LiteLLM生产部署，替换One‑API做多模型路由
LiteLLM 是一个开源的大模型网关，可以把 OpenAI、Anthropic、Azure 等不同接口统一成 OpenAI 兼容格式。
相比 One-API，它在生产环境里更强调路由策略和失败重试，适合需要高可用多模型调度的场景。
本文基于 Docker 演示 LiteLLM 生产部署，替换 One-API 后的核心配置与验证方法，零基础可照做。
LiteLLM 能替代 One-API 的哪些能力
One-API 适合快速聚合多个渠道，LiteLLM 则把“模型路由”“自动重试”“预算控制”这类运维能力做成配置项。
替换时不需要改业务代码，因为 LiteLLM 同样兼容 OpenAI 的 /v1/chat/completions 接口。
生产环境迁移的关键不是安装，而是把模型列表、密钥、失败策略重新梳理成一份 config.yaml。
部署前需要准备什么
- 一台能访问外网的 Linux 服务器，建议 2 核 4G 以上。
- 已安装 Docker 和 Docker Compose。
- 准备上游模型的 API Key，例如 OpenAI、Anthropic 或国内模型厂商的 Key。
- 确认业务侧原来调用 One-API 的地址和模型名，后续要映射到 LiteLLM。
用 Docker Compose 搭建 LiteLLM 服务
创建目录：
mkdir -p /opt/litellm && cd /opt/litellm创建 docker-compose.yml：
version: "3.9"
services:
litellm:
image: ghcr.io/berriai/litellm:main-latest
ports:
- "4000:4000"
volumes:
- ./config.yaml:/app/config.yaml
environment:
- OPENAI_API_KEY=sk-xxx
- ANTHROPIC_API_KEY=sk-ant-xxx
command: ["--config", "/app/config.yaml", "--port", "4000"]启动服务：
docker compose up -d看到日志出现 Uvicorn running 表示服务已启动。
建议固定一个可用的镜像 tag，不要长期跟随 main-latest 变动，具体以官方镜像仓库显示为准。
配置多模型路由与失败自动重试
在 /opt/litellm/config.yaml 中定义模型列表和重试策略。
以下是最小可用配置：
model_list:
- model_name: chat-model
litellm_params:
model: openai/gpt-4o-mini
api_key: os.environ/OPENAI_API_KEY
- model_name: chat-model
litellm_params:
model: anthropic/claude-3-haiku-20240307
api_key: os.environ/ANTHROPIC_API_KEY
router_settings:
retry_policy:
TimeoutError: 3
APIError: 2
fallbacks:
- chat-model: ["anthropic/claude-3-haiku-20240307"]这里把两个上游模型都映射到同一个 model_name，LiteLLM 会按负载或顺序路由；
某个模型报错或超时后，自动重试并切换到备用模型。
保存后重启容器：
docker compose restart密钥通过环境变量注入，config.yaml 里不要写明文。
验证路由和重试是否生效
先验证基础调用：
curl http://localhost:4000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"chat-model","messages":[{"role":"user","content":"你好"}]}'能正常返回内容，说明网关路由已生效。
要验证失败自动重试，可以临时把 config.yaml 中第一个模型的 api_key 改成错误值，再请求一次。
观察日志会看到第一次请求失败后自动尝试第二个模型，最终返回成功结果。
常见坑位提醒
- One-API 的渠道和令牌配置不会自动迁移，需要重新在
config.yaml中声明模型和密钥。 - 容器重启后环境变量不生效，检查
docker-compose.yml中的environment是否配置正确。 - 排查重试问题时，可以加
--detailed_debug启动参数，但生产环境不建议长期开启。 - 上游模型的限流和计费策略不同，重试次数设置过大会增加成本，建议按 2-3 次起步观察。
如果你正在考虑 LiteLLM 生产部署并替换 One-API，建议先用本文配置跑通一个模型，再逐步扩展模型列表和重试策略。
遇到异常时优先查看容器日志和 config.yaml 格式，多数失败都出在这两个地方。
