# AI Stack

这个项目用 Docker Compose 组合了三个服务：

- LiteLLM：作为统一的模型代理层，对外提供 OpenAI 兼容接口
- Open WebUI：作为 Web 端聊天界面，直接连接 LiteLLM
- Jupyter：作为 Open WebUI Code Interpreter 的 Python 执行环境，用于生成 Excel 等文件

当前仓库的核心目标，是基于 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 文件，包含以下字段：姓名、部门、金额，并提供下载链接。
```

## 已配置模型

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
```