接入大模型 API 的第一个月，我们组差点被一堆 provider SDK 给淹没。今天换这个厂商的鉴权，明天改那个平台的超时参数，后天又发现某个模型输出格式和别家不一样，整个开发进度全耗在“适配”上。后来我把核心网关换成了litellm这个开源项目，才真正体会到什么叫“接口只写一次，模型随便切”。这篇就结合我自己从零搭建到上生产的完整过程，聊聊 litellm 到底解决什么问题、怎么快速落地、以及那些文档里不会写但在实战里几乎必踩的坑。
这篇内容适合谁？如果你正在做 AI 应用开发、想给团队搭一个统一的模型接入层，或者手上已经接了多个模型服务商、被各自的 SDK 和计费方式搞得很烦，那这篇文章应该能帮你省下不少时间。
1. 为什么我会在自建 LLM 网关这件事上反复纠结
1.1 一开始我只是想少写几个 SDK
最早做内部工具的时候，我只需要接一个模型服务，代码非常简单：拿官方 SDK，填 key，调接口，解析返回。但业务一多起来情况就变了——有的场景需要更便宜的模型，有的场景需要响应更快的模型，有的场景需要支持长上下文的模型，于是就得同时接入好几家服务。
这时候麻烦来了。每个服务商的鉴权方式不一样，有的给 Bearer Token，有的要自定义 Header；每个服务商的流式返回格式也不一样，有的喂给前端能直接用，有的还得自己拼接；还有超时重试、错误码、限流策略，各家各有各的脾气。最后代码里充满了 if-else，每加一个新模型就要动业务代码，测试工作量成倍往上翻。
1.2 直到我把 litellm 当“协议转换器”来理解
后来我看到 litellm 的定位，突然意识到我一直在做一件很傻的事：业务代码根本不应该直接依赖任何一家模型服务商。正确做法是，在所有模型服务前面加一层网关，由网关来屏蔽所有的差异。
litellm 的核心能力就是做这件事：它对外提供一个 OpenAI 兼容的接口格式，你只需要像调 OpenAI 一样调它，至于后端到底是哪个模型、哪个供应商，都由 litellm 在服务端帮你转发。用大白话说，litellm 就像一个“翻译官”，把各家模型服务的方言全部翻译成同一种普通话，你的业务代码只需要会说这一种普通话就够了。
这一点想通之后，整个架构都清晰了：模型接入、路由、密钥管理、费用统计，全部下沉到网关层，业务代码只保留对“OpenAI 格式”的认知。
1.3 它到底适合谁：小团队、大团队、个人项目
我对 litellm 的适用范围做了个判断，不一定绝对准确，但可以提供给你参考：
- 个人开发者或小项目：直接用 litellm 的 Python 包，在代码里写
litellm.completion()统一调用，省去各家 SDK 的学习成本。 - 三五人的小团队：部署一个 litellm proxy 当作内部网关，让大家通过同一个入口调模型，统一 key 管理，其他人不用关心模型在哪配的。
- 中大型团队：配合虚拟密钥、预算配额、用量审计、Prometheus 监控等能力，把它当作公司内部 LLM 接入平台来用。
我实际落地的是第二种到第三种之间的场景，所以这篇文章会重点以“proxy 模式”为主线展开。
2. 10 分钟跑通第一个 litellm 代理：安装与请求转发
2.1 最小安装方式：pip 安装 litellm[proxy]
litellm 本身是一个 Python 包，安装非常简单，我建议在虚拟环境里装，避免污染系统 Python：
python3 -m venv .venv source .venv/bin/activate pip install 'litellm[proxy]'这里为什么要装[proxy]而不是普通版？因为基础版只有客户端调用能力，proxy这个 extra 会额外带上启动代理服务所需的依赖组件，包括 FastAPI、Pydantic 等。如果只是想在代码里调用模型，那pip install litellm就够；但要自建网关，必须装完整版。
装完之后可以先确认版本，顺便看看依赖是否都正常：
litellm --version2.2 用 CLI 直接启动一个在线模型
还没写任何配置，我先用最简单的方式验证链路。我把某个模型服务商的 API Key 配到环境变量里，然后执行：
export OPENAI_API_KEY=sk-xxxx litellm --model gpt-4o --port 8000这样 litellm 就起了一个监听在 8000 端口的代理服务，同时注册了一个gpt-4o模型。此时如果本地有 OpenAI SDK，只需要把 base_url 指向这个代理即可：
openai.base_url = "http://localhost:8000/v1"访问/v1/chat/completions的时候，litellm 会把请求转发到真正的模型服务。
第一次跑通这个流程时，我最大的感受是：接入一个模型居然可以不需要下载任何厂商 SDK，只需要一个环境变量。
2.3 用 config.yaml 管理多模型配置
CLI 启动方式适合验证，但没法配置多个模型。于是很快我就会切换到 config.yaml 这种方式。我的最小化配置长这样：
model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY然后启动：
litellm --config config.yaml --port 8000这里有个非常容易踩的坑：model_name只是你给外部使用者看的名字，可以随便起；而litellm_params.model必须写成供应商前缀/真实模型名的形式。比如openai/gpt-4o表示通过 openai 这个 provider 去请求gpt-4o这个模型，anthropic/claude-3-5-sonnet同理。如果直接在 litellm_params 里写gpt-4o，litellm 会根据默认映射去猜供应商，容易猜错，特别是模型名重叠时很麻烦。
除此之外，这个 YAML 里还可以针对每个模型单独设置 max_tokens、temperature 等参数。比如：
litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY temperature: 0.7 max_tokens: 1024这样调用方不用传也能拿到一个稳健的默认值。
2.4 从 OpenAI SDK 切过来的最小改动
对一个已经用 OpenAI SDK 写好的应用来说，迁移到 litellm proxy 几乎是无痛的。原来代码是：
from openai import OpenAI client = OpenAI(api_key="sk-xxxx") resp = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "你好"}], )迁移后只需要两处变化：
from openai import OpenAI client = OpenAI( api_key="sk-虚拟key", base_url="http://localhost:8000/v1", # 指向 litellm proxy ) resp = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "你好"}], )是的，就是把 base_url 指过去，其他代码全都复用。这就是 litellm 对外提供 OpenAI 兼容接口的最大价值：SDK 生态完全不用换。
3. 路由、重试与故障转移：把“换模型”变成配置问题
跑通基础代理之后，我开始研究更核心的能力：当有多个模型可用时，litellm 到底怎么决定把请求发给谁？如果某个模型挂了怎么办？这部分直接决定了网关的可用性。
3.1 路由策略：优先级、权重、简单轮询
litellm 的模型路由主要服务于两类场景。一类是“不同模型承担不同职责”，另一类是“多个同能力模型分摊流量”。前者靠调用方指定 model 名称，后者靠路由策略。
我配置多个高可用模型时是这样写的：
model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: completion supports_function_calling: true supports_vision: true - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY router_settings: routing_strategy: simple-shuffle fallbacks: []routing_strategy支持多种模式：simple-shuffle是带权重的随机轮询，适合把流量均匀散到多个模型上；priority会根据模型优先级顺序选择，只有高优先级不可用时才落到低优先级；还有usage-based-routing-v2这类更高级的策略，可以根据成本和延迟动态打分选路。
从我的实际经验来看，小团队用simple-shuffle配合 fallback 是最稳的组合，不建议一上来就追求复杂策略，因为你得先有足够多的历史流量数据才能调好权重。
3.2 fallback：主模型挂了，备选模型无缝顶上
我用一个场景来解释 fallback 为什么必要。有一次上游模型服务发生了区域性的高延迟，所有请求都要排队很久，如果当时没有 fallback 配置，整个业务就全部卡死了。配了 fallback 之后，litellm 会在主模型报错或超时后自动把同一请求发给备选模型，用户根本感知不到。
配置方式有两种。第一种是全局 fallback：
router_settings: fallbacks: [ {"gpt-4o": ["gpt-4o-mini"]}, {"claude-3-5-sonnet": ["gpt-4o"]} ]意思是：请求gpt-4o失败时，自动改发gpt-4o-mini；请求claude-3-5-sonnet失败时，自动改发gpt-4o。
第二种是单模型 fallback，写在 litellm_params 里：
- model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY fallbacks: ["gpt-4o-mini"]这两种方式可以混用，全局配兜底，单模型配定制。需要注意优先级：单模型级别的 fallback 优先于全局配置。
3.3 重试机制的“斧正”：生成类请求的安全边界
fallback 之外还有个很容易被忽略的点：重试。litellm 默认会对网络超时等部分错误做重试，这看起来是好事，但对 LLM 请求来说，重试有一个非常微妙的风险——生成类请求不幂等。
你的第一次请求可能已经消费了 token，模型也生成了内容，只是响应在返回途中超时了；如果此时直接重试同一个请求，用户可能要为同一段内容付两次钱。虽然可以用request_id一类的机制做去重，但在网关层很难完全保证。
所以我建议在配置时谨慎对待重试策略，尤其是那些会自动重跑的功能：
router_settings: allowed_fails: 3 cooldown_time: 30 timeout: 60allowed_fails表示模型连续失败多少次后会临时进入冷却期，cooldown_time控制冷却多久，timeout控制单次请求超时。这套组合拳比盲目开重试要安全得多。至少在我那个业务里，“失败后快速切换”比“失败后傻傻重试”带来的体验好得多。
4. 虚拟密钥、预算和用量追踪：让整个团队放心接模型
网关的价值不止在协议转换，密钥权限、预算控制、用量审计同样重要。这块如果没做好，团队里每个人直接拿着上游 API Key 到处用，轻则费用失控，重则泄露风险。
4.1 为什么需要虚拟密钥而不直接共享上游 key
真实场景下，团队里每个人、每个项目对模型的需求是不同的。有人要 GPT-4 这种贵模型，有人只需要便宜的模型做批量总结；有人一天调几千次，有人偶尔调一次。
如果大家都共享同一个上游 key，根本没法区分是谁在调用、哪个项目消耗了多少额度。而 litellm 的虚拟密钥机制，相当于在网关内部生成一把“子钥匙”，这把钥匙的权限范围、预算限制、速率限制都由你控制，并且完全独立于上游 key。
这样有几个好处：上游 key 永远只存在服务端，团队成员只接触虚拟 key；某个虚拟 key 泄露了，可以单独吊销，不影响全局；每个 key 的用量都有独立账单。
4.2 配置虚拟密钥：master key 和 generate_key
要生成虚拟密钥，首先得在 config.yaml 里定义一个总管理密钥：
general_settings: master_key: sk-master-123456这个 master key 用于管理 litellm 本身的 API，比如生成虚拟密钥、查看用量。启动之后可以用下面的命令生成一把新 key：
curl -X POST http://localhost:4000/key/generate \ -H "Authorization: Bearer sk-master-123456" \ -H "Content-Type: application/json" \ -d '{ "models": ["gpt-4o"], "max_budget": 50, "budget_duration": "30d", "max_parallel_requests": 10 }'响应里会返回类似sk-xxxxxx的虚拟 key。这个 key 就是给普通调用者用的，它只能访问你指定的gpt-4o模型，总体预算 50 美元，30 天窗口，并发上限 10。
4.3 预算与限流：按天/月/单次请求做控制
我对预算的理解经历了一个变化。最开始我只设置了 max_budget，以为总量控制就是够了。但后来发现，一次突发的流量高峰可能直接把 30 天预算在 5 分钟里打光。
所以现在我会推荐三层控制：
- 总量预算：
max_budget+budget_duration，控制周期总额度。 - 并发控制：
max_parallel_requests，防止某个脚本疯狂并发。 - 速率限制：通过
rate_limit参数，配合 litellm 的限流中间件，控制每秒请求数。
配置示例：
- user_id: project-a models: ["gpt-4o", "gpt-4o-mini"] max_budget: 100 budget_duration: "7d" rate_limit: 5这样每个项目按自己的配额走，互不挤占，超了也不影响别人。
4.4 用量追踪与可视化：数字比口头承诺更管用
预算控制之外，用量追踪是另一个让我觉得 litellm 值得长期用的原因。之前我们核经费全靠估算，现在 litellm 会记录每次请求的模型、token 数、费用，并汇总成维度丰富的统计数据。
通过接口可以查到消耗明细：
curl http://localhost:4000/spend/logs \ -H "Authorization: Bearer sk-master-123456"生产环境我还建议把 litellm 的 Prometheus 指标接进来，比如litellm_request_total、litellm_spend_total，放到现有的监控大盘上。这样每周开周会的时候，直接拉一个图表出来，哪个项目消耗了多少、哪个模型最费钱，一目了然。用数据说话，比在群里反复提醒“大家省着点用”有效得多。
5. 我在生产环境里踩过的几个真实坑
最后这部分是我最想写的，因为文档不会告诉你这些，但实际部署时几乎一定会遇到。
5.1 Docker 部署时的 config 文件挂载问题
我最早在本地运行一切正常，但一上 Docker 就发现 litellm 起不来。查了半天，问题是 config 文件没有正确挂载到容器里。
正确姿势是：
services: litellm: image: ghcr.io/berriai/litellm:main-latest ports: - "4000:4000" volumes: - ./litellm_config.yaml:/app/config.yaml command: ["--config", "/app/config.yaml", "--port", "4000"]需要注意的是：宿主机上 config 文件路径必须写对，容器内的路径建议固定为/app/config.yaml。另外如果配置里用了环境变量，例如os.environ/OPENAI_API_KEY，一定要在启动时通过environment传入，否则 litellm 读到的就是空值。
5.2 模型名映射的坑：model_name 和实际 provider model 不是一回事
有一次同事在代码里指定model="claude-3-5-sonnet"，结果网关一直报错找不到模型。我排查后发现，config.yaml 里他把 model_name 写成了 sonnet，请求里却写 claude-3-5-sonnet，两边对不上。
这是典型的“网关模型名”和“供应商模型名”混淆。在 litellm 里，调用方看到的model_name是你在 YAML 里自定义的别名，供应商模型名才是litellm_params.model里带前缀的那个。为了保证团队协作顺畅，最好在 YAML 里加注释，或者在内部文档里写清楚“请求时用的模型名 = model_name 这一列”，避免名字不一致。
5.3 日志炸屏与敏感信息脱敏
默认情况下 litellm 的日志非常啰嗦，尤其在 DEBUG 级别下，几乎每个请求的完整 response 都会被打印。这在开发环境问题不大，但在生产环境有两个风险：一是日志量太大，检索真正的问题时被淹没；二是如果请求和响应里含有用户隐私数据，直接落盘容易出问题。
我的做法是调整日志级别：
general_settings: logging: - level: INFO同时配合明文脱敏，确保 key 不会出现在日志里。跑了一段时间后，我深刻体会到：一个话痨的网关比一个安静的网关难维护得多。
5.4 缓存路由：给重复请求降本
最后分享一个成本优化技巧。litellm 支持响应缓存，对于相同请求，在缓存有效期内会直接返回缓存结果，不再真正调用模型。
配置很简单：
general_settings: cache: true cache_params: type: redis host: localhost port: 6379从节省成本的角度，这对 QA 批量测试、离线评估这类高重复请求的场景特别有用。但注意：如果你的 API 是给用户实时交互用的，强烈不建议开缓存，尤其是数据敏感的场景。不同请求虽然文本一样，但用户想表达的真实意图可能完全不同，盲目命中缓存反而会闹出笑话。
我个人现在只在内部评测和批量数据清洗时开这个能力，对外服务保持关闭状态。
最后再分享一点体会。litellm 对我来说最大的价值其实不是省掉了多少 SDK，而是它把“模型接入”从一次性的编码工作，变成了可持续运营的配置工作。今天换个模型、明天加个预算、后天接个新供应商，都不需要重新发版，只需要改配置重启，这种灵活性在 AI 技术更新那么快的当下特别重要。
如果你正准备搭自己的模型网关，我建议先从小处开始：一个代理、两个模型、一把虚拟 key，跑通链路之后再逐步加路由和预算控制。等一切稳定下来，你会发现它已经成为团队里那个最不起眼却最让人安心的基础设施。
