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 时，可以这样提问：

请使用 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，参数设为：

{"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 中配置环境变量：

GEMINI_API_KEY=你的实际密钥

如果当前网络环境访问 Gemini 需要代理，可以保留 docker-compose.yml 中的代理配置；如果不需要，应按实际环境修改或删除对应的代理地址。

启动方式

在项目根目录执行：

docker compose up -d

查看运行状态：

docker compose ps

查看日志：

docker compose logs -f

停止服务：

docker compose down

Windows 下使用 Python 直接运行

如果不想使用 Docker，也可以在 Windows 下通过 Python 分别启动 LiteLLM 和 Open WebUI。

建议环境：

• Windows 10 或 11
• Python 3.11
• PowerShell

1. 创建虚拟环境并安装依赖

在项目根目录打开 PowerShell，执行：

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install "litellm[proxy]" open-webui

如果 PowerShell 默认禁止脚本执行，可以先在当前会话临时放开：

Set-ExecutionPolicy -Scope Process Bypass

2. 启动 LiteLLM

在第一个 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 窗口中执行：

.\.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 中，切换到项目根目录执行：

cd 你的项目目录
Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1

安装成功后会自动启动两个服务，并输出访问地址。

5. 日常管理

# 查看服务状态
.\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 即可：

.\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 接口。

示例：

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 日志中是否有上游模型接口错误

可使用以下命令查看日志：

docker compose logs -f litellm
docker compose logs -f open-webui