llm-proxy/README.md

大模型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次熔断，冷却期后自动恢复）
• 自动重试（失败切换到下一个托管同一模型的提供商，不改变用户请求的模型）

快速开始

安装依赖

pip install -r requirements.txt

启动服务

./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

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 可直接在对话中生成并展示图片。

列出模型（含能力标签）

curl http://localhost:16003/v1/models

流式响应

curl http://localhost:16003/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto-text",
    "messages": [{"role": "user", "content": "讲个笑话"}],
    "stream": true
  }'

图片生成

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（可在后台修改）：

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

模型别名

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 兼容）：

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 使用示例

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