409 lines
12 KiB
Markdown
409 lines
12 KiB
Markdown
# AI Stack
|
||
|
||
这个项目用 Docker Compose 组合了以下主要服务：
|
||
|
||
- LiteLLM：作为统一的模型代理层，对外提供 OpenAI 兼容接口
|
||
- Open WebUI：作为 Web 端聊天界面，直接连接 LiteLLM
|
||
- Jupyter：作为 Open WebUI Code Interpreter 的 Python 执行环境，用于生成 Excel 等文件
|
||
- Docling Serve：作为 Open WebUI 的内容提取引擎，负责文档 OCR、版面和表格解析
|
||
|
||
当前仓库的核心目标，是基于 Gemini 系列模型快速搭一套可本地运行的 AI 网关与聊天界面。
|
||
|
||
## 目录结构
|
||
|
||
- docker-compose.yml：服务编排文件
|
||
- litellm/config.yaml：LiteLLM 模型映射与回退策略配置
|
||
- .env：本地环境变量文件，至少需要配置 Gemini API Key
|
||
- app/：预留目录，当前未使用
|
||
- open_webui/：Open WebUI 的 Windows 服务配置目录
|
||
- install.ps1：Windows 服务安装/卸载/启停脚本（WinSW）
|
||
- litellm/litellm-service.xml：LiteLLM 的 WinSW 服务配置
|
||
- open_webui/openwebui-service.xml：Open WebUI 的 WinSW 服务配置
|
||
|
||
## 服务说明
|
||
|
||
### 1. LiteLLM
|
||
|
||
LiteLLM 容器暴露 4000 端口，对外提供 OpenAI 兼容接口。
|
||
|
||
当前配置特点：
|
||
|
||
- 通过环境变量 GEMINI_API_KEY 访问 Gemini 模型
|
||
- 读取 litellm/config.yaml 中定义的模型别名
|
||
- 为部分高阶模型配置了 fallback，当主模型不可用时自动降级到可用模型
|
||
- 容器内默认带有 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 配置，适合需要代理访问外网模型接口的环境
|
||
|
||
### 2. Open WebUI
|
||
|
||
Open WebUI 容器映射到本机 3000 端口。
|
||
|
||
当前配置特点：
|
||
|
||
- 通过 OPENAI_API_BASE_URL 指向 LiteLLM 的 OpenAI 兼容接口
|
||
- OPENAI_API_KEY 使用占位值 dummy，仅用于满足 Open WebUI 接口配置要求
|
||
- WEBUI_AUTH=false，默认关闭登录认证，适合内网或本地开发环境
|
||
- 使用 Docker Volume 持久化 WebUI 数据
|
||
- 已连接 Jupyter Code Interpreter，可让模型运行 Python 生成 .xlsx 等文件
|
||
|
||
### 3. Jupyter
|
||
|
||
Jupyter 只在 Docker 内网中提供给 Open WebUI 使用，不暴露到宿主机端口。
|
||
|
||
当前用途：
|
||
|
||
- 为 Open WebUI 的 Code Interpreter 提供 Python 执行环境
|
||
- 支持通过 pandas/openpyxl 等库生成 Excel 文件
|
||
- 使用 Docker Volume 持久化工作目录
|
||
|
||
在 Open WebUI 中导出 Excel 时，可以这样提问：
|
||
|
||
```text
|
||
请使用 Code Interpreter 生成一个 Excel 文件，包含以下字段：姓名、部门、金额，并提供下载链接。
|
||
```
|
||
|
||
### 4. Docling Serve
|
||
|
||
Docling Serve 使用 CPU 镜像运行，只在宿主机回环地址暴露 5001 端口，Open WebUI 通过 Docker 内部地址
|
||
`http://docling-serve:5001` 调用它。默认启用 OCR、`dlparse_v4` PDF 后端和准确表格解析，模型文件保存在
|
||
`docling-data` 卷中，避免容器重建后重复下载。
|
||
|
||
本地编排启动后可访问 <http://127.0.0.1:5001/ui>，线上编排使用 <http://127.0.0.1:18014/ui>。Open WebUI
|
||
与 Docling 位于同一 Docker 网络，服务间调用始终使用 `http://docling-serve:5001`，不能填写宿主机映射端口。
|
||
上传测试文档并确认能够返回 Markdown。首次处理文档时可能需要下载模型，耗时和内存占用会明显高于后续请求。
|
||
|
||
Open WebUI 的文档设置属于持久化配置。全新数据卷会读取 Compose 中的 Docling 环境变量；如果实例已经运行过，
|
||
数据库里的旧设置可能覆盖环境变量。此时进入 `设置 → 管理员设置 → 工具 → 文档`，将内容提取引擎设为
|
||
`Docling`，服务地址设为 `http://docling-serve:5001`，参数设为：
|
||
|
||
```json
|
||
{"do_ocr": true, "pdf_backend": "dlparse_v4", "table_mode": "accurate"}
|
||
```
|
||
|
||
## 已配置模型
|
||
|
||
LiteLLM 当前已配置以下 Gemini 模型别名：
|
||
|
||
- gemini-3-pro-preview
|
||
- gemini-3-flash-preview
|
||
- gemini-3.1-pro-preview
|
||
- gemini-3.1-flash-lite-preview
|
||
- gemini-2.5-pro
|
||
- gemini-2.5-flash
|
||
- gemini-2.5-flash-lite
|
||
- gemini-2.0-flash
|
||
- gemini-2.0-flash-001
|
||
- gemini-2.0-flash-lite
|
||
- gemini-flash-latest
|
||
- gemini-flash-lite-latest
|
||
- gemini-pro-latest
|
||
|
||
其中部分模型配置了自动回退策略：
|
||
|
||
- gemini-pro-latest 回退到 gemini-2.5-flash、gemini-flash-latest
|
||
- gemini-3.1-pro-preview 回退到 gemini-2.5-flash、gemini-flash-latest
|
||
- gemini-3-pro-preview 回退到 gemini-2.5-flash、gemini-flash-latest
|
||
|
||
## 运行前准备
|
||
|
||
需要具备以下环境：
|
||
|
||
- Docker
|
||
- Docker Compose
|
||
- 可用的 Gemini API Key
|
||
|
||
建议在 .env 中配置环境变量：
|
||
|
||
```env
|
||
GEMINI_API_KEY=你的实际密钥
|
||
```
|
||
|
||
如果当前网络环境访问 Gemini 需要代理，可以保留 docker-compose.yml 中的代理配置；如果不需要，应按实际环境修改或删除对应的代理地址。
|
||
|
||
## 启动方式
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
查看运行状态：
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
查看日志：
|
||
|
||
```bash
|
||
docker compose logs -f
|
||
```
|
||
|
||
停止服务：
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
## Windows 下使用 Python 直接运行
|
||
|
||
如果不想使用 Docker，也可以在 Windows 下通过 Python 分别启动 LiteLLM 和 Open WebUI。
|
||
|
||
建议环境：
|
||
|
||
- Windows 10 或 11
|
||
- Python 3.11
|
||
- PowerShell
|
||
|
||
### 1. 创建虚拟环境并安装依赖
|
||
|
||
在项目根目录打开 PowerShell，执行：
|
||
|
||
```powershell
|
||
py -3.11 -m venv .venv
|
||
.\.venv\Scripts\Activate.ps1
|
||
python -m pip install --upgrade pip
|
||
pip install "litellm[proxy]" open-webui
|
||
```
|
||
|
||
如果 PowerShell 默认禁止脚本执行，可以先在当前会话临时放开：
|
||
|
||
```powershell
|
||
Set-ExecutionPolicy -Scope Process Bypass
|
||
```
|
||
|
||
### 2. 启动 LiteLLM
|
||
|
||
在第一个 PowerShell 窗口中执行：
|
||
|
||
```powershell
|
||
.\.venv\Scripts\Activate.ps1
|
||
$env:GEMINI_API_KEY="你的实际密钥"
|
||
|
||
# 如果访问 Gemini 需要代理，可以按实际环境设置
|
||
$env:HTTP_PROXY="http://127.0.0.1:7890"
|
||
$env:HTTPS_PROXY="http://127.0.0.1:7890"
|
||
$env:ALL_PROXY="http://127.0.0.1:7890"
|
||
|
||
litellm --config .\litellm\config.yaml --port 4000
|
||
```
|
||
|
||
说明：
|
||
|
||
- litellm/config.yaml 可以直接复用当前仓库里的模型配置
|
||
- 如果本机不需要代理，可以删除上面的代理环境变量
|
||
- 启动成功后，LiteLLM 默认监听 <http://127.0.0.1:4000>
|
||
|
||
### 3. 启动 Open WebUI
|
||
|
||
在第二个 PowerShell 窗口中执行：
|
||
|
||
```powershell
|
||
.\.venv\Scripts\Activate.ps1
|
||
$env:OPENAI_API_BASE_URL="http://127.0.0.1:4000/v1"
|
||
$env:OPENAI_API_KEY="dummy"
|
||
$env:WEBUI_AUTH="false"
|
||
$env:DATA_DIR="$PWD\.data\open-webui"
|
||
$env:PORT="3000"
|
||
|
||
open-webui serve
|
||
```
|
||
|
||
说明：
|
||
|
||
- OPENAI_API_BASE_URL 指向本地启动的 LiteLLM
|
||
- OPENAI_API_KEY 保持 dummy 即可，主要用于兼容 OpenAI 风格配置
|
||
- DATA_DIR 用于持久化 Open WebUI 本地数据
|
||
- PORT 设置为 3000，这样和 Docker 方式下的访问地址保持一致
|
||
|
||
### 4. 访问服务
|
||
|
||
启动完成后可通过以下地址访问：
|
||
|
||
- Open WebUI：<http://127.0.0.1:3000>
|
||
- LiteLLM：<http://127.0.0.1:4000>
|
||
- LiteLLM OpenAI 兼容接口：<http://127.0.0.1:4000/v1>
|
||
|
||
### 5. 停止服务
|
||
|
||
分别在两个 PowerShell 窗口中按 Ctrl+C 即可停止。
|
||
|
||
### 6. 常见问题
|
||
|
||
- 如果 open-webui 命令不存在，先确认虚拟环境已激活，并重新执行依赖安装
|
||
- 如果 LiteLLM 启动失败，优先检查 GEMINI_API_KEY 和 config.yaml 路径是否正确
|
||
- 如果 Open WebUI 页面打开但没有模型，优先检查 LiteLLM 是否已在 4000 端口正常启动
|
||
|
||
## Windows 下使用 WinSW 注册为系统服务
|
||
|
||
适用于需要长期稳定运行的场景，解决命令窗口关掉就停止、异常不自动恢复的问题。
|
||
|
||
WinSW 把 LiteLLM 和 Open WebUI 注册为 Windows Service，具备以下能力：
|
||
|
||
- 开机自动启动
|
||
- 进程异常退出后自动重启
|
||
- 无需保持终端窗口
|
||
- 日志自动滚动，不占满磁盘
|
||
- 可以在服务管理器（services.msc）里统一查看和管理
|
||
|
||
### 1. 准备工作
|
||
|
||
确认以下条件已满足：
|
||
|
||
- Python 虚拟环境已经创建，litellm 和 open-webui 已安装
|
||
- Python 虚拟环境目录建议为项目根目录下的 `venv`（可按需调整）
|
||
- 用管理员权限打开 PowerShell
|
||
|
||
### 2. 下载 WinSW
|
||
|
||
从官方 GitHub 下载最新版：
|
||
|
||
<https://github.com/winsw/winsw/releases/latest>
|
||
|
||
下载 `WinSW-x64.exe`，重命名为 `WinSW.exe`，放到项目根目录（与 `install.ps1` 同级）。
|
||
|
||
### 3. 修改配置文件
|
||
|
||
按实际情况修改这两个文件：
|
||
|
||
- `litellm/litellm-service.xml`：修改 GEMINI_API_KEY
|
||
- `open_webui/openwebui-service.xml`：按需调整端口和数据目录
|
||
|
||
关键字段说明：
|
||
|
||
- `<executable>`：默认使用 `%BASE%` 相对路径（例如 `%BASE%\\..\\venv\\Scripts\\litellm.exe`），复制到任意目录仍可运行
|
||
- `<env name="GEMINI_API_KEY" value="..."/>`：填写实际密钥
|
||
- `<logpath>`：日志输出目录，目录不存在时安装脚本会自动创建
|
||
|
||
说明：`%BASE%` 是 WinSW 内置变量，表示当前 WinSW.exe 所在目录。
|
||
|
||
### 4. 安装服务
|
||
|
||
在管理员 PowerShell 中，切换到项目根目录执行：
|
||
|
||
```powershell
|
||
cd 你的项目目录
|
||
Set-ExecutionPolicy -Scope Process Bypass
|
||
.\install.ps1
|
||
```
|
||
|
||
安装成功后会自动启动两个服务，并输出访问地址。
|
||
|
||
### 5. 日常管理
|
||
|
||
```powershell
|
||
# 查看服务状态
|
||
.\install.ps1 -Status
|
||
|
||
# 停止服务
|
||
.\install.ps1 -Stop
|
||
|
||
# 启动服务
|
||
.\install.ps1 -Start
|
||
|
||
# 卸载服务
|
||
.\install.ps1 -Uninstall
|
||
```
|
||
|
||
也可以通过 Windows 服务管理器（`Win+R` 输入 `services.msc`）可视化管理，
|
||
服务名称分别为 `AI Stack - LiteLLM` 和 `AI Stack - Open WebUI`。
|
||
|
||
### 6. 日志位置
|
||
|
||
- LiteLLM 日志：`项目根目录\\logs\\litellm\\`
|
||
- Open WebUI 日志：`项目根目录\\logs\\openwebui\\`
|
||
|
||
日志文件为滚动模式，单文件超过 10MB 自动轮转，最多保留 5 个历史文件。
|
||
|
||
### 7. 修改配置后更新服务
|
||
|
||
修改 XML 文件后无需卸载重装，执行 refresh 即可：
|
||
|
||
```powershell
|
||
.\litellm\WinSW.exe refresh .\litellm\litellm-service.xml
|
||
.\open_webui\WinSW.exe refresh .\open_webui\openwebui-service.xml
|
||
```
|
||
|
||
## 访问入口
|
||
|
||
- Open WebUI：<http://localhost:3000>
|
||
- LiteLLM API：<http://localhost:4000>
|
||
- LiteLLM OpenAI 兼容接口前缀：<http://localhost:4000/v1>
|
||
|
||
## 使用方式
|
||
|
||
### 在 Open WebUI 中使用
|
||
|
||
启动后直接访问 Open WebUI 页面即可，通过 Web 界面选择 LiteLLM 暴露出来的模型进行对话。
|
||
|
||
### 通过 OpenAI 兼容接口调用
|
||
|
||
可以把 LiteLLM 当作 OpenAI 兼容网关使用，只需要把 Base URL 指向本机的 /v1 接口。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
curl http://localhost:4000/v1/chat/completions \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer dummy" \
|
||
-d '{
|
||
"model": "gemini-2.5-flash",
|
||
"messages": [
|
||
{"role": "user", "content": "你好"}
|
||
]
|
||
}'
|
||
```
|
||
|
||
说明：LiteLLM 实际调用 Gemini 时使用的是服务端环境变量中的 GEMINI_API_KEY；示例中的 Bearer dummy 只是为了满足 OpenAI 风格客户端的请求格式。
|
||
|
||
## 配置说明
|
||
|
||
### 模型配置
|
||
|
||
LiteLLM 的模型配置位于 litellm/config.yaml，可以按以下方式扩展：
|
||
|
||
- 新增或删除模型别名
|
||
- 调整别名对应的真实模型
|
||
- 配置 fallback 策略
|
||
|
||
### 服务配置
|
||
|
||
服务端口与环境变量位于 docker-compose.yml，可以根据部署环境调整：
|
||
|
||
- 端口映射
|
||
- 代理配置
|
||
- WebUI 认证开关
|
||
- 挂载目录和数据卷
|
||
|
||
## 注意事项
|
||
|
||
- 当前 WEBUI_AUTH=false，默认无登录认证，不建议直接暴露到公网
|
||
- .env 中包含真实密钥时，不应提交到公开仓库
|
||
- 如果代理地址不可用，LiteLLM 可能无法正常访问 Gemini 接口
|
||
- app/ 和 open_webui/ 目录当前未承载实际代码，主要运行逻辑集中在 docker-compose.yml 与 litellm/config.yaml
|
||
|
||
## 故障排查
|
||
|
||
### Open WebUI 无法加载模型
|
||
|
||
优先检查：
|
||
|
||
- LiteLLM 容器是否正常启动
|
||
- OPENAI_API_BASE_URL 是否仍然指向 <http://litellm:4000/v1>
|
||
- GEMINI_API_KEY 是否配置正确
|
||
|
||
### 模型调用失败
|
||
|
||
优先检查：
|
||
|
||
- 当前 API Key 是否有效
|
||
- 代理是否可用
|
||
- LiteLLM 日志中是否有上游模型接口错误
|
||
|
||
可使用以下命令查看日志：
|
||
|
||
```bash
|
||
docker compose logs -f litellm
|
||
docker compose logs -f open-webui
|
||
```
|