当你同时接 OpenAI、Claude、DeepSeek、Gemini 时，最麻烦的往往不是选哪个模型，而是每个 SDK 的请求格式、Key 和计费口径都不一样。LiteLLM 就是为解决这件事而生的开源项目：它把多家模型统一成 OpenAI 兼容接口，并提供一个可以自建的网关。

本文讲清楚 LiteLLM 是什么、最小可用配置、路由与 Key 管理、部署方式，以及什么时候该自建、什么时候直接用托管网关。

说明：LiteLLM 是其权利人的开源项目，OpenAI、Anthropic、DeepSeek 等为各自权利人的商标。本文以 2026 年 10 月的常见版本为例，具体参数以官方文档为准。

一、LiteLLM 到底是什么

LiteLLM 有两个形态：

  • Python SDK：在代码里用统一的 completion 函数调用不同厂商的模型。
  • Proxy 网关：一个独立服务，暴露 OpenAI 兼容的 /v1/chat/completions，任何支持自定义 Base URL 的客户端都能接。

它解决的是协议适配、路由和记账三件事，不解决模型本身好不好用。换句话说，它是管道，不是模型。

核心能力包括：

能力 作用
统一协议 多厂商模型走 OpenAI 格式
路由与负载均衡 同一个模型名分发到多个部署
故障转移 主模型失败时切到备用模型
虚拟 Key 给团队或项目发独立 Key 和预算
用量与成本 记录请求、Token 和花费
日志回调 对接 Langfuse、OpenTelemetry 等系统

二、最小可用：pip 启动

先建虚拟环境，再安装带 proxy 的包：

python3 -m venv .venv
source .venv/bin/activate
pip install "litellm[proxy]"

写一个最小 config.yaml：

model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

litellm_settings:
  drop_params: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

启动：

export ANTHROPIC_API_KEY="sk-ant-你的密钥"
export DEEPSEEK_API_KEY="sk-你的密钥"
export LITELLM_MASTER_KEY="sk-litellm-本地管理密钥"
litellm --config config.yaml --port 4000

model_name 是对外暴露的名字，litellm_params.model 是真实的上游模型，格式通常是“厂商/模型名”。os.environ/XXX 表示从环境变量读取，不要把 Key 直接写进 yaml 再提交到仓库。

启动后用 OpenAI SDK 指向本地网关：

from openai import OpenAI

client = OpenAI(
    api_key="sk-litellm-本地管理密钥",
    base_url="http://127.0.0.1:4000",
)
resp = client.chat.completions.create(
    model="claude-sonnet",
    messages=[{"role": "user", "content": "只回复 OK"}],
)
print(resp.choices[0].message.content)

三、模型路由与故障转移

生产环境很少只挂一个上游。常见配置如下：

router_settings:
  routing_strategy: simple-shuffle
  num_retries: 2
  timeout: 600
  fallbacks:
    - claude-sonnet: ["deepseek-chat"]

几个参数的含义：

  • routing_strategy：多个同模型部署之间怎么选，simple-shuffle 是常见的起步选择。
  • num_retries：失败重试次数，注意每次重试都会产生真实费用。
  • timeout：单次请求超时，按业务最慢链路设置。
  • fallbacks：主模型不可用时切到备用模型。

故障转移不是免费的。备用模型的输出风格、上下文长度、工具调用能力可能不同，切过去之后业务侧要能接受。对格式要求严格的场景，宁可明确报错，也不要静默降级。

四、虚拟 Key 与预算

团队共用一把 master key 是运维事故的起点。正确做法是给每个项目发虚拟 Key，并限制可用模型和预算：

curl -X POST "http://127.0.0.1:4000/key/generate" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["claude-sonnet"],
    "max_budget": 20,
    "duration": "30d",
    "metadata": {"project": "demo"}
  }'

返回的 Key 交给业务方使用，master key 只留在运维手里。预算单位与币种以 LiteLLM 文档为准，这里只演示字段结构，不代表任何定价。

五、Docker 部署与上线检查

单机试用可以直接跑容器：

docker run -d --name litellm \
  -p 4000:4000 \
  -v "$(pwd)/config.yaml:/app/config.yaml" \
  -e ANTHROPIC_API_KEY \
  -e DEEPSEEK_API_KEY \
  -e LITELLM_MASTER_KEY \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml

上线前至少检查这几项：

  1. 网关不要直接暴露公网，前面放 Nginx 或 Caddy 做 TLS 和访问控制。
  2. master key 用强随机值，不写进代码仓库。
  3. 需要用量入库时接 PostgreSQL，否则重启后部分统计会丢。
  4. 配好日志轮转和磁盘告警，请求日志增长很快。
  5. 留一条健康检查：curl http://127.0.0.1:4000/health。
  6. 升级前先看 changelog，镜像固定版本标签，不要长期用 latest。

还有一点容易被忽略：网关是新的单点。它挂了，所有模型都挂。至少要做进程守护、自动重启和一条独立的告警链路。

六、日志与成本：别等账单来了才发现

网关的一个隐性价值是把调用记录下来。LiteLLM 可以记录每次请求的模型、Token、延迟和花费，并按 Key、团队、标签聚合。要把这件事做完整，需要三步：

  1. 配置数据库，让花费记录持久化，而不是只存在内存里。
  2. 给请求打标签，例如在 metadata 里写项目名，否则月底无法按项目拆分。
  3. 接一个可观测后端，把链路追踪和日志集中起来。

示例配置：

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]

general_settings:
  database_url: os.environ/DATABASE_URL

注意两点：第一，回调服务自己也要高可用，回调阻塞可能拖慢主请求；第二，日志里可能包含用户原文，保留期限和访问权限要提前定好，不要把生产日志永久保存。

成本上，网关只能让你看见花费，不能自动让花费变少。真正省钱的动作还是选对模型、压缩上下文、控制重试次数。

七、自建还是用托管网关

维度 自建 LiteLLM 托管 AI 网关
数据路径 完全自己控制 经过服务商
初始成本 低，装完就能跑 注册即用
长期运维 升级、备份、监控都归你 服务商负责
计费与发票 自己对接上游 统一人民币账单
灵活性 高，可改源码和路由 受平台能力边界
故障责任 自己兜底 按服务条款

一个实用的判断：

  • 有运维、有合规要求、需要深度定制路由，选自建。
  • 团队小、只想统一 Key 和账单、不想半夜修容器，选托管。
  • 也可以先用托管跑通业务，等调用量稳定后再评估自建。

国内团队还要额外考虑网络。自建网关本身不解决上游可达性，上游访问不稳定时，网关只会把失败放大。这时“自建加国内可达的上游”或“直接使用托管网关”更现实。

如果你不需要改源码，只是想要一个 OpenAI 兼容入口、统一 Key 和人民币账单，托管网关通常注册当天就能跑通；LiteLLM 更适合作为需要长期维护的基础设施。两者也可以并存：内部用 LiteLLM 做路由，对外统一走托管入口。

八、常见问题

LiteLLM 是免费的吗？

开源部分可以自行部署，但上游模型的调用费用照常产生；企业版功能和托管服务的价格以官方为准。

它和 One API、New API 有什么区别？

One API 和 New API 更偏多用户额度分发，LiteLLM 更偏多模型路由和 SDK 统一。两者都能做 OpenAI 兼容入口，选型看你要的是计费分发还是路由能力。

支持 Claude 的原生工具调用吗？

支持程度取决于版本和上游适配。复杂工具调用、缓存等能力建议用真实请求验证，不要只看文档。

自建网关能省钱吗？

不一定。省下的是平台服务费，付出的是服务器、运维和故障时间。调用量很小时，托管通常更划算。

生产环境最少要配什么？

TLS、master key、虚拟 Key、预算上限、日志、数据库备份、健康检查，这几样缺一不可。

下一步

如果你想先验证多模型调用、又不想自己维护容器，可以 注册中商起航 AI 网关，用 OpenAI 兼容入口跑通第一条请求；模型与价格以 模型价格 为准。等调用量和合规要求明确后，再决定是否自建 LiteLLM。

相关阅读：