简体中文 | English

LLM AIO Gateway - 多合一 LLM API 网关

LLM AIO Gateway 是一个基于 FastAPI 的统一 LLM API 网关，用一个服务代理多个 OpenAI 兼容和 Anthropic 兼容的上游提供商。它同时暴露 OpenAI Chat Completions、旧版 Completions、Anthropic Messages、OpenAI Responses 等接口，并提供路由规则、API Key 管理、reasoning 连续性、工具调用修复和视觉模型注入。

当前代理核心基于统一内部消息格式：所有客户端协议先转换为 InternalRequest / InternalMessage，再进入共享策略层。策略层会产出结构化 RoutingDecision，随后由上游适配器发送给 OpenAI/liteLLM 或 Anthropic 兼容接口，最后再渲染回客户端需要的协议格式。

功能特性

快速开始

环境要求

• Python 3.10+
• pip

手动安装

pip install -r requirements.txt
python main.py

默认服务地址为 http://localhost:8000。首次启动会自动创建 config.json 和 data.db。

Docker

docker compose up -d

首次配置

1. 打开 http://localhost:8000。
2. 创建第一个管理员账号。
3. 在管理面板添加上游提供商。
4. 刷新模型列表，或手动添加模型。
5. 创建普通用户并生成 API Key。
6. 使用 Authorization: Bearer sk-aio-... 调用网关。

提供商类型

模型 ID 支持 provider/model 和简单 model 两种形式。复合形式会直接定位到指定提供商；简单模型名会选择第一个启用且匹配的提供商模型。

API 端点

所有代理端点同时支持根路径和 /v1 前缀。

Chat Completions 示例

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-aio-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/model-name",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 1024
  }'

Completions 示例

curl http://localhost:8000/v1/completions \
  -H "Authorization: Bearer sk-aio-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/model-name",
    "prompt": "写一首关于春天的短诗。",
    "max_tokens": 200
  }'

Anthropic Messages 示例

curl http://localhost:8000/v1/messages \
  -H "Authorization: Bearer sk-aio-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/model-name",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": [{"type": "text", "text": "你好"}]}]
  }'

Responses 示例

curl http://localhost:8000/v1/responses \
  -H "Authorization: Bearer sk-aio-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/model-name",
    "input": "你好"
  }'

视觉模型注入

视觉模型注入用于让纯文本模型处理图片输入。为请求模型启用预处理器后，网关会将当前轮次图片交给配置的视觉模型描述，剥离原始图片数据，并把描述文本注入对话。

在 config.json 中配置预处理器：

{
  "preprocessors": {
    "my-vision": {
      "api_base": "http://127.0.0.1:8080/v1",
      "model": "MiniCPM-V-4.6",
      "api_key": "",
      "timeout": 60,
      "max_images": 20,
      "max_tokens": 1024,
      "prompt": "Please describe this image in detail.",
      "enabled": true
    }
  }
}

然后在管理面板为目标模型开启预处理器。是否预处理取决于用户请求的原始模型，而不是路由后的目标模型。

路由规则

路由规则可按用户名、API Key 子串、请求模型通配符透明重定向请求。第一条匹配规则生效。

路由发生在共享策略层，结果以 RoutingDecision 表达。日志会记录原始请求模型、解析后的模型、目标模型、目标提供商、命中规则和原因，便于排查“为什么请求去了这个上游”。

规则结构：

{
  "name": "route-example",
  "enabled": true,
  "username": "",
  "api_key_pattern": "",
  "match_model": "MiniMax-M2*",
  "target_model": "target-model",
  "target_provider": "target-provider"
}

Routing rules only describe active routing. Passive fallback is configured separately in fallback_policies: match the routed provider/model plus a failure trigger such as timeout, connection_error, http_429, or http_5xx, then try the configured fallback chain. The admin UI provides a dedicated fallback policy editor, so users do not need to write JSON in a routing rule.

The request pipeline is: ingress -> vision preprocessing based on the requested model -> active routing -> primary upstream call -> passive fallback on classified failure -> egress. Logs are emitted at each key stage (preprocess.*, routing, upstream.primary.*, fallback.*) so route and fallback decisions can be inspected after the fact.

管理接口提供 POST /admin/routing-rules/dry-run 用于检查某个用户、API Key 片段和请求模型会命中哪条主动路由规则。Fallback 已拆成独立策略，可通过 POST /admin/fallback-policies/dry-run 按 provider、model 和失败类型检查会使用哪条 fallback 链。提供商页面也提供健康检查入口，对 /models 可用性、延迟和模型数量做快速探测。

配置

config.json 保存服务级配置，修改后需要重启服务。

重要默认项：

架构摘要

客户端端点
  -> 协议入口
  -> 内部 IR
  -> 共享策略层（RoutingDecision、预处理、reasoning、工具修复）
  -> OpenAI/liteLLM 适配器或 direct Anthropic 适配器
  -> 内部输出
  -> 协议出口

端点特有的协议细节只保留在 ingress/egress。路由、预处理、reasoning 缓存、工具修复和适配器选择都基于统一内部格式运行。

主要代码边界：

测试

pytest tests/ -q

当前预期结果：334 passed。

真实烟测建议：

• Claude Code -> /messages
• Codex -> /responses
• OpenCode -> /chat/completions
• curl -> /completions
• 每类端点至少测一个 OpenAI 兼容提供商和一个 Anthropic 兼容提供商。

许可证

MIT。详见 LICENSE 文件。