3 分钟把 100 个大模型塞进一个 API：用 LiteLLM 给公司搭一层 LLM 网关
一篇能让你下班前就把 LLM Gateway 最小 PoC 跑起来的实战指南。
配套封面提示词见文末。
一、先讲个真事
上个月，朋友公司技术总监找我倒苦水：
“我们刚接了豆包，领导又让对接 DeepSeek。CTO 说 Qwen 新模型出来后必须支持，海外业务还要上 Claude 和 GPT。我现在团队里 4 个工程师，每人维护一套 SDK、4 套鉴权、4 套日志、4 套计费报表……上周供应商接口升了个版本，老接口直接 502，半夜爬起来修。”
听完我只想说：
你们缺的不是更多的工程师，是一层 LLM 网关。
而这层网关最小 PoC 跑起来，真的可以非常快。
前提是：
- Docker 已经装好
- 网络正常
- API Key 已经准备好
- 不需要同时把所有生产能力一次性配齐
这篇文章就从一个最小可运行的 LiteLLM Gateway 开始，一路把模型、Virtual Key、Fallback、缓存、监控这些生产能力补上。
二、你公司可能正在踩的 3 个坑
如果你正在或打算接入多家大模型，下面这 3 个坑大概率会踩。
坑 1：每个厂商一套 SDK
OpenAI 用 openai，Anthropic 用 anthropic，Qwen 可能用 DashScope，其他供应商又有自己的 SDK。
业务代码最后很容易变成这样：
if provider == "openai":
...
elif provider == "qwen":
...
elif provider == "deepseek":
...
elif provider == "anthropic":
...
加一个新厂商，就要再改一次业务代码。
更麻烦的是，不同 SDK 的：
- 鉴权方式
- 错误处理
- Streaming
- Tool Calling
- 超时
- Retry
- 日志
都可能不一样。
坑 2：Key 满天飞，没法收回
开发把真实 API Key 硬编码进代码：
OPENAI_API_KEY = "sk-xxxxxxxx"
然后提交 Git。
或者把 Key：
- 塞进前端环境变量
- 发到群聊
- 写进 CI/CD
- 放进某个测试服务器
- 复制给多个业务团队
一旦泄露，最终账单可能直接把 CFO 气晕。
坑 3：用量黑洞
业务方说：
“我们用得不多。”
然后申请了一把 GPT / Claude / Qwen 的 Key。
到了月底：
“为什么这个月 API 账单这么高？”
你却不知道：
- 谁调用的
- 哪个团队调用的
- 哪个模型调用的
- 请求量多少
- Token 消耗多少
- 到底花了多少钱
三、LiteLLM 到底是什么？（大白话版）
LiteLLM 是一个面向多模型的统一 API Gateway / Proxy。
官方目前将 LiteLLM 定位为可以通过统一接口访问 100+ 个 LLM，并提供统一的 OpenAI 风格输入输出、认证授权、Virtual Key、成本统计、限流、Router、Retry / Fallback、缓存、Guardrails 等能力。
你只需要记住 3 件事：
1. 它是一层网关
架构非常简单：
业务系统
│
│ OpenAI Compatible API
▼
┌─────────────────────┐
│ LiteLLM │
│ Gateway │
│ │
│ Auth / Virtual Key │
│ Router / Fallback │
│ Rate Limit │
│ Logging / Cost │
│ Cache / Guardrails │
└─────────┬───────────┘
│
┌─────┼─────┬─────┐
▼ ▼ ▼ ▼
Qwen DeepSeek GPT Claude
业务方只需要知道：
http://your-litellm-gateway:4000
至于后面到底是：
- Qwen
- DeepSeek
- OpenAI
- Anthropic
- Azure
- Bedrock
- Vertex AI
- Ollama
由网关负责。
2. 它可以统一 OpenAI Compatible API
LiteLLM 官方支持通过统一接口访问大量 Provider，同时提供 Chat Completions、Responses、Embeddings、Images、Audio 等接口。
对于大量已经采用 OpenAI SDK 的业务系统来说，通常只需要修改：
base_url
api_key
底层模型可以换掉，业务调用逻辑基本不用跟着供应商一起改。
注意：
并不是所有供应商的所有高级能力都能做到 100% 无差异兼容。Provider 专属参数、新接口以及某些高级能力仍然需要单独验证。
3. 它不只是“转发器”
LiteLLM 真正有价值的地方，其实是网关层能力：
| 能力 | 解决什么问题 |
|---|---|
| 🔌 统一协议 | 业务统一使用 OpenAI Compatible API |
| 🔑 Virtual Key | 业务拿到的是网关 Key，真实 Provider Key 留在网关 |
| 📊 统一用量 | 按 Key / 用户 / 团队 / 项目 / 模型统计 |
| 📜 统一观测 | 请求、Token、延迟、错误等集中记录与分析 |
| 🛡️ Guardrails | 统一接入内容安全、PII 等护栏 |
| ⚡ 缓存 | 对重复请求较多的场景降低延迟和成本 |
| 🔀 Router / Fallback | 多 Deployment 路由、重试、故障转移 |
| 🚦 限流 / 配额 | 防止单个业务无限制消耗预算 |
这才是企业 LLM Gateway 的真正价值。
四、3 分钟跑起来（Docker Compose 路线）
适用场景：内网部署 / PoC 验证 / 小规模部署
环境要求：Linux + Docker Compose
本文的“3 分钟”指的是完成最小可运行 PoC，不是把所有生产能力一次性全部配置完成。
第 1 步：准备配置目录
mkdir -p ~/litellm-install
cd ~/litellm-install
curl -O https://raw.githubusercontent.com/BerriAI/litellm/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/BerriAI/litellm/main/prometheus.yml
curl -O https://raw.githubusercontent.com/BerriAI/litellm/main/.env.example
mv .env.example .env
LiteLLM 官方 Compose 当前包含：
- LiteLLM
- PostgreSQL
- Prometheus
但默认不包含 Grafana。
另外，生产环境建议固定 LiteLLM 版本，不要把 GitHub main 分支上的 Compose 与一个完全不同版本的镜像长期混用。
第 2 步：国内环境替换镜像
如果你的服务器直接拉 Docker Hub / GHCR 比较慢，可以使用你所在环境可访问的镜像代理或镜像仓库。
例如：
sed -i 's#docker.litellm.ai/berriai/litellm:main-stable#YOUR_REGISTRY/berriai/litellm:YOUR_VERSION#g' docker-compose.yml
sed -i 's#postgres:16#YOUR_REGISTRY/postgres:16#g' docker-compose.yml
sed -i 's#prom/prometheus#YOUR_REGISTRY/prom/prometheus:YOUR_VERSION#g' docker-compose.yml
这里特意没有把某个第三方镜像仓库写死。
原因很简单：
镜像代理的可用性、镜像同步时间、版本号和访问策略都可能变化。
生产环境建议使用自己信任的镜像仓库，并固定版本。
第 3 步：准备 .env
最小配置可以先这样：
cat > .env <<'EOF'
# LiteLLM 管理密钥
# 必须使用一个高强度随机值，示例仅用于演示
LITELLM_MASTER_KEY=sk-change-this-to-a-long-random-secret
# PostgreSQL
DATABASE_URL=postgresql://llmproxy:llmproxy@db:5432/litellm
# Provider API Keys
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx
EOF
注意：
不要在生产环境使用 sk-1234 这种示例 Key。
建议至少做到：
- 高随机性
- 不提交 Git
- 不写进业务代码
- 定期轮换
- 权限最小化
另外，如果你的 LiteLLM Compose 已经通过 environment / env_file 读取 DATABASE_URL，不要再为了“看起来完整”重复配置一套不同的数据库连接地址。
第 4 步：启动
现在 Docker 推荐使用 Compose Plugin：
docker compose up -d
查看状态：
docker compose ps
正常情况下，你应该至少看到：
litellm Up
db Up
prometheus Up
查看日志：
docker compose logs -f litellm
健康检查正常以后，可以访问：
http://your-server-ip:4000
管理后台的认证方式取决于你当前 LiteLLM 版本和认证配置，不建议把某个具体 UI 登录流程写死成“输入 master key 就一定能登录”。
五、3 种姿势给网关加模型
模型配置是 LiteLLM 日常使用中最频繁的事情。
通常有 3 种方式。
姿势 1：Web UI
适合：
- 开发调试
- 临时试模型
- PoC
- 少量模型人工维护
例如：
Provider: OpenAI Compatible
LiteLLM Model Name: qwen3.5-plus
Public Model Name: qwen3.5-plus
Model Mapping: qwen3.5-plus
UI 的具体菜单名称可能随着 LiteLLM 版本变化。
所以这里不建议把某一版 UI 的点击路径写死。
核心逻辑只有一个：
Provider
↓
真实模型 / Deployment
↓
LiteLLM Model Name
↓
业务侧调用名称
姿势 2：config.yaml（生产推荐）
生产环境更推荐把模型配置写进 Git 管理的配置文件。
例如：
model_list:
# 国内主力
- model_name: qwen3.5-plus
litellm_params:
model: openai/qwen3.5-plus
api_key: os.environ/DASHSCOPE_API_KEY
api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
# DeepSeek V4 Flash
- model_name: deepseek-v4-flash
litellm_params:
model: openai/deepseek-v4-flash
api_key: os.environ/DEEPSEEK_API_KEY
api_base: https://api.deepseek.com
# OpenAI
- model_name: gpt-5
litellm_params:
model: openai/gpt-5
api_key: os.environ/OPENAI_API_KEY
# Anthropic
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-sonnet-4-5-20250929
api_key: os.environ/ANTHROPIC_API_KEY
# LiteLLM 自身的核心设置
litellm_settings:
num_retries: 2
request_timeout: 30
# Proxy / 数据库相关设置
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
database_url: os.environ/DATABASE_URL
DeepSeek 这里特意使用：
deepseek-v4-flash
deepseek-v4-pro
而不是以前教程里常见的：
deepseek-chat
deepseek-reasoner
因为这两个旧模型名已经在 2026 年 7 月 24 日弃用。当前 DeepSeek 官方 API 使用 deepseek-v4-flash 和 deepseek-v4-pro，OpenAI Compatible Base URL 为：
https://api.deepseek.com
参考：
Fallback 怎么配？
真正生产环境里，比“配置一个模型”更重要的是：
一个模型挂了，业务不能一起挂。
例如：
model_list:
- model_name: coding-model
litellm_params:
model: openai/gpt-5
api_key: os.environ/OPENAI_API_KEY
- model_name: coding-model
litellm_params:
model: openai/qwen3.5-plus
api_key: os.environ/DASHSCOPE_API_KEY
api_base: https://dashscope.aliyuncs.com/compatible-mode/v1
litellm_settings:
num_retries: 2
request_timeout: 30
fallbacks:
- coding-model:
- qwen3.5-plus
LiteLLM Router 支持多 Deployment 的路由、Retry 和 Fallback。
生产环境可以进一步根据：
- 延迟
- 失败率
- 负载
- 成本
- 模型能力
设计更复杂的路由策略。
姿势 3：API
如果你自己在做 AI 中台 / 配置中心，也可以通过管理 API 动态管理模型。
例如：
GATEWAY="http://localhost:4000"
MASTER_KEY="sk-change-this-to-a-long-random-secret"
查看模型：
curl "$GATEWAY/models" \
-H "Authorization: Bearer $MASTER_KEY"
动态添加模型、删除模型等操作可以通过 LiteLLM 的管理 API 完成。
这适合：
配置中心
↓
LiteLLM Admin API
↓
Model Registry
也就是说：
模型配置不一定非要人工登录 UI 修改，也可以由企业自己的控制平面自动管理。
生产环境使用管理 API 时，要注意：
- Master Key 不能暴露给普通业务
- API 必须放在受保护的管理网络
- 需要做好权限和审计
- 删除模型等操作最好有审批机制
六、业务方怎么调用？（OpenAI Compatible）
这才是整个网关最爽的地方。
业务方原来可能是：
from openai import OpenAI
client = OpenAI(
api_key="sk-provider-key",
)
resp = client.chat.completions.create(
model="gpt-5",
messages=[
{"role": "user", "content": "用一句话介绍你自己"}
]
)
接入 LiteLLM 后：
from openai import OpenAI
client = OpenAI(
api_key="sk-business-virtual-key",
base_url="http://your-litellm-gateway:4000"
)
resp = client.chat.completions.create(
model="qwen3.5-plus",
messages=[
{"role": "user", "content": "用一句话介绍你自己"}
],
stream=True
)
for chunk in resp:
print(
chunk.choices[0].delta.content or "",
end="",
flush=True
)
注意这里：
sk-business-virtual-key
不是 Qwen / OpenAI / DeepSeek 的真实 API Key。
它是 LiteLLM 自己管理的 Virtual Key。
整个链路变成：
业务系统
│
│ Virtual Key
▼
LiteLLM
│
│ Real Provider API Key
▼
Qwen / DeepSeek / OpenAI / Claude
真实厂商 Key 永远留在网关侧。
七、生产级必备的 4 个能力
跑起来只是开始。
真正上线之前，我建议至少把下面 4 项补齐。
能力 1：Virtual Key + 用量配额
给每个业务系统发一个独立的 Virtual Key。
例如：
业务 A
Key: sk-virtual-a
Team: customer-service
Models: qwen3.5-plus
Budget: ¥5000 / month
业务 B
Key: sk-virtual-b
Team: coding
Models: gpt-5, claude-sonnet
Budget: ¥20000 / month
这样做之后：
Provider Key
│
▼
LiteLLM
│
┌────┼─────┐
▼ ▼ ▼
Key A Key B Key C
你就可以做到：
- 按业务隔离
- 按团队统计
- 按项目统计
- 按用户统计
- 设置预算
- 限制模型
- 密钥单独撤销
这就是企业里真正需要的“Key 管理”。
能力 2：Guardrails
Guardrails 的作用不是简单理解成“万能内容过滤器”。
例如使用 Presidio 这类方案，可以用于 PII 识别 / 脱敏：
guardrails:
- guardrail_name: block-pii
litellm_params:
guardrail: presidio
mode: pre_call
适合处理：
身份证
手机号
邮箱
地址
信用卡号
这类敏感信息。
但是：
超长 Prompt、高频调用、预算滥用，并不是 Presidio 的职责。
这些问题更适合通过：
- Token / Context 限制
- Rate Limit
- Budget
- Virtual Key
- Project Quota
来解决。
能力 3：Redis 缓存
对于重复请求很多的业务，缓存可以减少重复调用。
例如：
litellm_settings:
cache: true
cache_params:
type: redis
host: os.environ/REDIS_HOST
port: 6379
然后 .env：
REDIS_HOST=redis
需要注意：
LLM 缓存并不是“所有请求都能命中”。
是否命中取决于：
- 模型
- 请求内容
- 参数
- Cache Key
- TTL
- 缓存配置
所以缓存特别适合：
FAQ
知识库固定问答
重复 Prompt
固定模板
高重复率请求
而动态程度很高的聊天场景，缓存收益可能比较有限。
能力 4：Prometheus + Grafana
LiteLLM 可以暴露 Prometheus 相关指标。
但这里有一个很容易踩的坑：
LiteLLM 官方 Compose 默认带 Prometheus，不代表自动带 Grafana。
如果你还需要 Grafana，需要自己部署 Grafana，然后把 Prometheus 添加为数据源。
典型结构：
LiteLLM
│
│ Metrics
▼
Prometheus
│
│ Data Source
▼
Grafana
可以重点观察：
请求量
QPS
P50 / P95 / P99 延迟
错误率
模型调用情况
Provider 健康状态
而 Token / Cost / Team / Key 等更偏业务和费用维度的信息，则应该结合 LiteLLM 自身的 Spend / 管理能力以及数据库或其他观测系统一起看。
另外：
Grafana Dashboard ID 17346 是 Traefik 官方 Dashboard，不是 LiteLLM Dashboard。
千万不要把它直接当成 LiteLLM Dashboard 导入。
八、一个比较完整的企业架构
到这里，LiteLLM 在企业里的位置就非常清楚了。
┌────────────────────┐
│ 企业业务系统 │
│ Java / Python / Go │
│ Web / Agent / App │
└─────────┬──────────┘
│
OpenAI Compatible
│
▼
┌─────────────────────────┐
│ LiteLLM │
│ Gateway │
│ │
│ Authentication │
│ Virtual Key │
│ Model Routing │
│ Retry / Fallback │
│ Rate Limit │
│ Cost Tracking │
│ Guardrails │
│ Cache │
└───────┬─────┬─────┬──────┘
│ │ │
┌──────────────┘ │ └─────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ 国内模型 │ │ 海外模型 │ │ 私有模型 │
│ │ │ │ │ │
│ Qwen │ │ OpenAI │ │ Ollama │
│ DeepSeek │ │ Claude │ │ vLLM │
│ 豆包 │ │ Gemini │ │ SGLang │
└───────────┘ └───────────┘ └───────────┘
┌──────────────────┐
│ Observability │
│ │
│ PostgreSQL │
│ Prometheus │
│ Grafana │
│ Logs / Traces │
└──────────────────┘
这时候 LiteLLM 已经不再只是一个：
“帮我把 API 转发一下的工具。”
而是一层真正的：
企业 LLM Control Plane / Gateway
九、踩坑清单（这些我建议收藏）
| 现象 | 常见原因 | 解决思路 |
|---|---|---|
| 容器启动后不断重启 | 环境变量、数据库或配置错误 | docker compose logs -f litellm |
/v1/chat/completions 返回 401 | Virtual Key / Master Key 配置不对 | 检查当前认证配置和 Key |
修改 config.yaml 不生效 | 容器没有重新加载配置 | 重启 LiteLLM |
docker pull 卡很久 | Docker Registry 网络问题 | 使用可信镜像仓库 / 代理 |
| Redis Cache 一直不命中 | Cache Key / TTL / 请求差异 | 检查缓存配置和请求是否真正重复 |
| Prometheus 抓不到数据 | Prometheus 配置、网络或路径错误 | 检查 target 和 LiteLLM metrics |
| Grafana 页面打不开 | Compose 根本没启动 Grafana | 单独部署 Grafana |
| Fallback 没触发 | 没配置 fallback 或模型名不一致 | 检查 model_list 和 fallback 配置 |
| Provider Key 泄露 | Key 写进业务代码 | 业务只使用 Virtual Key |
| 月底账单失控 | 没做 Project / Team / Key Budget | 上线前先设置预算 |
| DeepSeek 示例跑不通 | 使用了旧模型名 | 使用 deepseek-v4-flash / deepseek-v4-pro |
十、生产环境别只部署一个 LiteLLM
PoC：
业务
│
▼
LiteLLM
│
├── PostgreSQL
└── Prometheus
完全可以。
但是生产环境更推荐：
┌──────────────┐
│ Load Balancer│
└──────┬───────┘
│
┌─────────┴─────────┐
▼ ▼
┌────────────┐ ┌────────────┐
│ LiteLLM #1 │ │ LiteLLM #2 │
└─────┬──────┘ └─────┬──────┘
│ │
└──────────┬─────────┘
▼
┌──────────────┐
│ PostgreSQL │
└──────────────┘
│
▼
┌──────────────┐
│ Redis │
└──────────────┘
这样才能真正做到：
- 网关高可用
- 多实例
- 共享状态
- 负载均衡
- 故障转移
- 高并发
所以：
2C4G 可以作为 PoC 起点，但不要把它理解成所有生产环境都只需要 2C4G。
生产容量最终还是取决于：
- QPS
- 并发
- Provider 数量
- 日志量
- PostgreSQL 数据量
- Redis 使用方式
- Prometheus 保留时间
- 是否多副本
十一、LiteLLM 和 OneAPI / Portkey / OpenRouter 怎么选？
LiteLLM 不是唯一选择。
大体可以这样理解：
| 方案 | 典型定位 |
|---|---|
| LiteLLM | 自建 LLM Gateway / Proxy / 多模型统一接入 |
| OneAPI | 国内比较常见的统一模型 API 中转网关 |
| Portkey | 更偏企业级 AI Gateway / Observability / Governance |
| OpenRouter | 更偏托管式、多模型统一 API 服务 |
如果你：
- 想自己部署
- 想自己掌握数据
- 有多个 Provider
- 需要 Virtual Key
- 需要预算和团队管理
- 想把 Gateway 放在公司内网
那么 LiteLLM 是一个非常值得研究的选择。
它目前已经是比较成熟、生态覆盖广、社区活跃的开源 LLM Gateway 方案之一。
十二、写在最后
回到开头那个技术总监的故事。
如果你们现在还是：
业务 A → OpenAI SDK
业务 B → Qwen SDK
业务 C → DeepSeek SDK
业务 D → Anthropic SDK
而且每套系统：
自己存 Key
自己做 Retry
自己统计 Token
自己算费用
自己做日志
自己处理 Provider 异常
那么继续堆 SDK，往往不是最优解。
真正应该抽出来的是：
┌─────────────────┐
业务系统 ──────────►│ LLM Gateway │
│ │
│ Auth │
│ Routing │
│ Fallback │
│ Rate Limit │
│ Cost │
│ Logging │
│ Guardrails │
│ Cache │
└───────┬─────────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
Qwen DeepSeek GPT
当这个 Gateway 建起来以后：
接一个新模型，不再意味着全公司改 SDK。
换一个 Provider，也不再意味着全公司重新发版。
某个供应商临时故障，也不一定意味着凌晨 3 点爬起来改业务代码。
从：
“每个业务自己接大模型”
变成：
“公司统一接入大模型，业务统一调用 Gateway”
这才是 LLM Gateway 真正的价值。
所以，如果你们公司已经开始同时使用 3 个、5 个甚至 10 个以上的大模型 API，那么现在就值得认真考虑：
是不是该在业务和模型之间，加这一层了？
官方文档
LiteLLM：
LiteLLM Providers：
https://docs.litellm.ai/docs/providers
LiteLLM Proxy：
https://docs.litellm.ai/docs/proxy/
DeepSeek API：
https://api-docs.deepseek.com/
Grafana Dashboard 17346：
https://grafana.com/grafana/dashboards/17346-traefik-official-standalone-dashboard/
注意：上面的 Grafana 17346 是 Traefik Dashboard，仅用于说明“不要误导入错 Dashboard”。