hz4th_coder
86198e83c5
- API Key鉴权: /v1/* 与 /mcp 接口支持 Bearer 鉴权(OpenAI兼容), 系统配置页可启停/增删Key (GET/PUT /api/admin/apikeys, key脱敏显示; /health /status 不受限; 内部自调用自动带key) - Function Calling: tools/tool_calls 全透传上游, 实测 GLM-5.3-flash 返回 tool_calls(get_weather) - MCP Server: /mcp 端点(Streamable HTTP + SSE兼容), 暴露 text_complete/vision_complete/image_generate 工具 (initialize/ping/tools/list/tools/call/prompts.list/resources.list; 实测生图返回图片URL) - 默认生成 API Key: sk-hz4th-<hex>
269 lines
8.7 KiB
Markdown
269 lines
8.7 KiB
Markdown
# 大模型API中转系统 (LLM Proxy)
|
||
|
||
> 兼容OpenAI API格式的多提供商代理系统，支持能力(Capability)路由、优先级自动切换
|
||
|
||
**版本：v2.2.0**
|
||
|
||
## 功能特点
|
||
|
||
### 🔄 多提供商支持
|
||
- 支持配置多个上游大模型提供商
|
||
- 按优先级自动选择可用提供商
|
||
- 故障自动切换到备用提供商
|
||
|
||
### 🎯 能力路由（v2.1.0 新增）
|
||
每个模型可标记**能力标签**，AUTO配置**固定绑定一个功能类型**并自动筛选具备该能力的模型：
|
||
|
||
| 能力 | 说明 | 端点 |
|
||
|------|------|------|
|
||
| `text` 文本推理 | 纯文本对话 | `/v1/chat/completions` |
|
||
| `vision` 视觉能力 | 多模态图像理解 | `/v1/chat/completions`（消息含图片自动路由） |
|
||
| `audio_out` 语音输出 | TTS 语音合成 | `/v1/audio/speech` |
|
||
| `audio_in` 语音输入 | ASR 语音识别 | `/v1/audio/transcriptions` |
|
||
| `image_gen` 图片生成 | 文生图 | `/v1/images/generations` |
|
||
| `video_gen` 视频生成 | 文生视频 | `/v1/video/generations` |
|
||
|
||
### 📡 OpenAI API 兼容
|
||
- 完全兼容 OpenAI API 格式（Chat / Embeddings / Images / Audio）
|
||
- 支持流式和非流式响应
|
||
- 支持模型别名映射
|
||
|
||
### 🛡️ 高可用
|
||
- 自动健康检查
|
||
- 错误计数与熔断（连续失败3次熔断，**冷却期后自动恢复**）
|
||
- 自动重试（失败切换到下一个托管同一模型的提供商，**不改变用户请求的模型**）
|
||
|
||
## 快速开始
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
./start.sh # 后台启动（PID 管理）
|
||
./start.sh stop # 停止
|
||
./start.sh status # 状态
|
||
# 或前台运行
|
||
python app.py
|
||
```
|
||
|
||
### 访问地址
|
||
|
||
```
|
||
前台API: http://localhost:16003/v1/chat/completions
|
||
后台管理: http://localhost:16003/admin
|
||
```
|
||
|
||
## API 使用
|
||
|
||
### Chat Completions
|
||
|
||
```bash
|
||
curl http://localhost:16003/v1/chat/completions \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer ***" \
|
||
-d '{
|
||
"model": "auto",
|
||
"messages": [{"role": "user", "content": "Hello!"}],
|
||
"stream": false
|
||
}'
|
||
```
|
||
|
||
后台「对话」页选择 `auto-image` 或 `Qwen-Image` 可直接在对话中生成并展示图片。
|
||
|
||
### 列出模型（含能力标签）
|
||
|
||
```bash
|
||
curl http://localhost:16003/v1/models
|
||
```
|
||
|
||
### 流式响应
|
||
|
||
```bash
|
||
curl http://localhost:16003/v1/chat/completions \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "auto-text",
|
||
"messages": [{"role": "user", "content": "讲个笑话"}],
|
||
"stream": true
|
||
}'
|
||
```
|
||
|
||
### 图片生成
|
||
|
||
```bash
|
||
curl http://localhost:16003/v1/images/generations \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "auto-image",
|
||
"prompt": "a cute cat, cartoon style",
|
||
"size": "1024x1024"
|
||
}'
|
||
```
|
||
|
||
## Auto 配置（按能力固定功能 + 具体模型排序）
|
||
|
||
每个 Auto 配置固定一个**功能类型**，内部是一个**有序的具体模型列表**（可在后台拖动排序），请求时按序选择第一个可用模型。调用时 `model="配置名称"`：
|
||
|
||
| 配置名称 | 功能 | 说明 |
|
||
|----------|------|------|
|
||
| `auto` | 文本推理 | 默认，按模型列表顺序自动选择 |
|
||
| `auto-text` | 文本推理 | 纯文本模型 |
|
||
| `auto-vision` | 视觉能力 | 多模态视觉模型 |
|
||
| `auto-image` | 图片生成 | 生图模型 |
|
||
| `auto-voice-out` | 语音输出 | TTS 模型 |
|
||
| `auto-voice-in` | 语音输入 | ASR 模型 |
|
||
| `auto-video` | 视频生成 | 视频模型 |
|
||
|
||
在后台「Auto配置」页可**拖动具体模型**调整优先级（粒度是模型，不是提供商），勾选参与自动选择。
|
||
|
||
## 历史上下文缓存（可配置）
|
||
|
||
带历史上下文的 `auto` 请求会**优先复用上次使用的模型**（按首条消息识别会话），命中上游前缀缓存、节省成本。可在「系统配置」页开关：
|
||
|
||
- `prefer_cache_model`：是否启用（默认开）
|
||
- `cache_ttl_seconds`：记忆有效期（默认 3600 秒）
|
||
|
||
## 模型管理
|
||
|
||
后台「模型管理」页：
|
||
- 每个模型可配置能力标签（文本/视觉/语音/生图/生视频）
|
||
- 支持添加/编辑/删除模型、设置默认模型
|
||
- 支持模型别名管理（`qwen`→`unsloth/Qwen3.8-27B-Q6_K` 等）
|
||
|
||
## 配置说明
|
||
|
||
默认配置在 `config/settings.py`，运行时配置存于 `data/config.json`（可在后台修改）：
|
||
|
||
```python
|
||
UPSTREAM_PROVIDERS = [
|
||
{
|
||
"name": "provider-name",
|
||
"priority": 1, # 优先级，数字越小越高
|
||
"base_url": "https://api.example.com/v1",
|
||
"api_key": "sk-xxx",
|
||
"capabilities": ["text", "vision"], # 提供商能力（新模型默认继承）
|
||
"models": [
|
||
{"name": "model-1", "capabilities": ["text"]},
|
||
{"name": "model-2", "capabilities": ["text", "vision"]},
|
||
],
|
||
"default_model": "model-1",
|
||
"timeout": 180,
|
||
"enabled": True,
|
||
},
|
||
]
|
||
```
|
||
|
||
### 内置提供商
|
||
|
||
| 提供商 | 能力 | 模型 |
|
||
|--------|------|------|
|
||
| Local Qwen | 文本+视觉 | `unsloth/Qwen3.8-27B-Q6_K`, `unsloth/Qwen3.8-27B-Q4_K_M` |
|
||
| SiliconFlow LLM | 文本 | `deepseek-ai/DeepSeek-V4-Flash`, `meituan-longcat/LongCat-2.0` |
|
||
| Autodl | 文本+视觉 | `qwen3.6-plus`, `GLM-5.3-flash` |
|
||
| Autodl Image | 图片生成 | `Qwen-Image` |
|
||
|
||
### 模型别名
|
||
|
||
```python
|
||
MODEL_ALIASES = {
|
||
"auto": "auto",
|
||
"qwen": "unsloth/Qwen3.8-27B-Q6_K",
|
||
"deepseek": "deepseek-ai/DeepSeek-V4-Flash",
|
||
...
|
||
}
|
||
```
|
||
|
||
## 端点
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/` | GET | 服务信息 |
|
||
| `/v1/chat/completions` | POST | 聊天完成 |
|
||
| `/v1/embeddings` | POST | 文本嵌入 |
|
||
| `/v1/images/generations` | POST | 图片生成 |
|
||
| `/v1/audio/speech` | POST | 语音合成 |
|
||
| `/v1/audio/transcriptions` | POST | 语音识别 |
|
||
| `/v1/video/generations` | POST | 视频生成 |
|
||
| `/v1/models` | GET | 模型列表 |
|
||
| `/health` | GET | 健康检查 |
|
||
| `/status` | GET | 详细状态 |
|
||
| `/admin` | GET | 后台管理 |
|
||
|
||
## 优先级与熔断机制
|
||
|
||
当使用 `model="auto"` 系列时：
|
||
1. 按配置的优先级顺序选择提供商
|
||
2. 跳过不可用/不具备对应能力的提供商
|
||
3. 请求失败自动切换到下一个托管同一模型的提供商（保持请求模型不变）
|
||
4. 连续失败3次的提供商被熔断，冷却期（默认60秒）后自动半开恢复
|
||
|
||
## 邮件通知（auto 调用全部失败时）
|
||
|
||
某个 auto 配置被调用后所有提供商都失败（如全部熔断/停用），自动发邮件通知，方便及时处理。
|
||
|
||
- **配置入口**：后台「系统配置」页 → 邮件通知（SMTP 服务器/账号/密码/收件人/加密方式，均可在网页配置）
|
||
- **防轰炸**：默认最小间隔 300 秒，短时间内连续失败只发一封
|
||
- **测试**：配置页有「发送测试邮件」按钮
|
||
- **端点**：`/api/admin/email`（GET/PUT）、`/api/admin/email/test`（POST）
|
||
- **默认配置**：`mail.tphai.com:587`（plain）、收件人 `wlq@tphai.com`
|
||
|
||
## 接口认证（API Key）
|
||
|
||
为 `/v1/*` 与 `/mcp` 接口启用 Bearer 鉴权（OpenAI 兼容）：
|
||
|
||
```bash
|
||
curl http://<IP>:16003/v1/chat/completions \
|
||
-H "Authorization: Bearer sk-hz4th-xxxx" \
|
||
...
|
||
```
|
||
|
||
- **配置入口**：后台「系统配置」页 → 接口认证（API Key），可启停鉴权、增删多个 Key
|
||
- **管理接口**：`/api/admin/apikeys`（GET/PUT）
|
||
- `/health`、`/status` 不受鉴权影响
|
||
|
||
## 标准接口
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| OpenAI 兼容 | `/v1/chat/completions` 等，支持流式、`tools`/function calling 透传 |
|
||
| Function Calling | 请求体带 `tools` 数组即透传上游，返回 `tool_calls`（实测 GLM/DeepSeek 正常） |
|
||
| MCP Server | 连接 `http://<IP>:16003/mcp`（Streamable HTTP + SSE），工具：`text_complete` / `vision_complete` / `image_generate` |
|
||
|
||
### MCP 使用示例
|
||
|
||
```bash
|
||
curl http://<IP>:16003/mcp \
|
||
-H "Authorization: Bearer sk-hz4th-xxxx" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'
|
||
|
||
# 调用文本模型
|
||
curl http://<IP>:16003/mcp -H "Authorization: Bearer sk-hz4th-xxxx" -H "Content-Type: application/json" \
|
||
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"text_complete","arguments":{"model":"auto-text","prompt":"你好"}}}'
|
||
```
|
||
|
||
Claude Desktop / Cursor 等支持 MCP 的客户端可直接将 `http://<IP>:16003/mcp` 配为 MCP Server。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
llm-proxy/
|
||
├── app.py # 主程序（前台API + 后台管理，单端口）
|
||
├── start.sh # 启动/停止脚本
|
||
├── requirements.txt # 依赖
|
||
├── config/
|
||
│ └── settings.py # 默认配置（提供商/能力/别名/auto）
|
||
├── data/ # 运行时配置与数据（config.json/stats.json/chats.json）
|
||
├── logs/ # 日志目录
|
||
└── templates/ # 后台管理页面
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|