我大概是从一个有点烦躁的下午开始接触 LiteLLM 的当时项目里要同时对接三家模型厂商的接口OpenAI 的 SDK 要写一套Claude 那边又是另一套切到其他家的模型时还要重新处理鉴权、重试、超时代码里到处是 if-else 和 try-catch。后来有同行扔给我一个词——“litellm”说你可以用这个把事情简化掉。抱着试一试的心态用了一个下午之后它就成了我几乎所有 LLM 项目的默认入口。这篇文章不打算做成文档翻译我会从“为什么需要它”讲起再拆解它的核心能力、部署网关的完整步骤以及我在真实项目里怎么把它和 vLLM、LangChain、RAG 这些常见组件搭配起来用。最后会分享几个踩过之后才注意到的坑和配置经验。如果你是做应用开发、接模型接口接得头大的人或者正准备在公司内部组一个多模型网关这篇文章应该能给你不少可以直接用的东西。1. 为什么大家都在谈 LiteLLM大模型 API 接入的碎片化困局1.1 模型一多SDK 就变成灾难现场这两年大模型的格局基本就是“百花齐放各玩各的”OpenAI 的 ChatGPT 系列是一套调用方式Anthropic 的 Claude 是另一套Google Gemini 又是自己的一套国内各家开源模型部署起来还要考虑 vLLM、Ollama 这些推理框架各自的接口规范。最痛苦的不是“接口不同”而是“差异藏在细节里”。比如同样一个“要求模型输出 JSON”的需求OpenAI 那边可以传 response_format到了 Claude 那边就得用另一个参数控制输出格式再比如消息历史里 system prompt 和 user 消息的写法各家也有细微差别。一开始我只接了两家模型代码里还能靠 if-else 兜住到第三家、第四家的时候维护成本肉眼可见地飙升。每次换模型供应商产品逻辑没改多少底层调用代码倒是改了一整天。1.2 SDK 迁移这件事远比想象中麻烦网上经常有人在问“OpenAI 的 SDK 能不能直接用来调其他家的模型”严格说答案是“部分可以”。因为很多模型服务商为了兼容生态会主动模仿 OpenAI 的接口格式你只需要修改 base_url 和 api_key 就能跑通基础对话。但一旦涉及到流式输出、工具调用function calling、超时重试、上下文缓存这些高级特性各家实现经常不一致比如有些服务把流式响应拆成多行 JSON 输出有些则用数据帧层级包装导致你那套“标准处理逻辑”未必能通用。我当时看到热搜里“OpenAI API → 其他模型免费(SDK迁移技巧)”这种话题特别有共鸣——很多人以为换个 base_url 就万事大吉结果在项目里被流式解析、错误码兼容这些边角问题反复折磨。LiteLLM 解决的就是这个“最后一公里”的问题你不需要自己去抹平各家 SDK 的差异它在你和模型厂商之间做了一层标准适配。1.3 LiteLLM 的核心定位一个库、一个网关、而不是一个模型LiteLLM 本身不训练模型、不托管模型它只是一个 Python 库也可以作为一个独立的代理服务LiteLLM Proxy运行。它做的事情可以一句话概括让你用同一个 OpenAI 风格的接口格式去调用一百多个不同厂商的模型同时把鉴权、重试、限流、预算、负载均衡、日志这些“脏活”收归到一层统一处理。打个比方它相当于 LLM 世界的“万能转接头”。一边是 USB-C一边是各种奇奇怪怪的接口LiteLLM 帮你把针脚定义全部对齐了。你不需要关心对面是 OpenAI 还是本地 vLLM 拉起来的开源模型你只需要在配置文件里写清楚每个“模型名”对应哪个“实际服务地址”然后业务代码里始终用同一套方式去请求。2. 从“套一层皮”到全家桶LiteLLM 的核心能力到底有哪些2.1 统一接口真·一套代码到处跑LiteLLM 最基础的用法就是一个 completion 函数。你不安装 OpenAI SDK也不安装 Anthropic SDK只要设置好对应的环境变量然后这样写from litellm import completion response completion( modelclaude-3-5-sonnet-20241022, messages[{role: user, content: 用一句话介绍你自己}], ) print(response.choices[0].message.content)关键在于model 参数可以是任何 LiteLLM 支持的模型标识。你想切到 gpt-4o就把 model 换成 gpt-4o再把 OPENAI_API_KEY 配好你想切到 Gemini就换成 gemini/gemini-1.5-pro配好 GEMINI_API_KEY。业务层的消息结构、返回值结构基本不变因为 LiteLLM 做了大量输出格式适配把各家返回的字段映射成统一的 OpenAI 风格对象。这意味着什么意味着你的上层应用可以不用关心“现在背后是哪个模型”。今天用 Claude 效果好明天改成某个国产模型来降本代码层面可能只是一行配置的变化而不是重写整个调用层。2.2 Fallback、重试、超时稳定性是这样兜底的单模型调用的最大风险是“上游抖动”。某家模型服务高峰期经常 429或者响应特别慢一旦你的应用没有做容错用户只会看到一个转圈然后报错。LiteLLM 内置了模型级的路由和 Fallback 机制你可以在请求里指定response completion( modelgpt-4o, messagesmessages, fallbacks[claude-3-5-sonnet-20241022, bedrock/anthropic.claude-3-5-sonnet-v2], )这样当第一个模型失败、超时、或者返回 5xx 时LiteLLM 会自动尝试下一个模型。这个机制在我们的生产项目里很实用尤其是做客服机器人的时候用户的求助消息不能因为单一模型故障就丢掉。当然这里有个细节值得注意Fallback 只对“请求失败”生效如果模型返回了内容但内容质量很低LiteLLM 本身没法判断所以 Fallback 更适合解决可用性问题而不是质量问题。另外还可以设置 num_retries、timeout 这些参数LiteLLM 会按照指数退避的方式重试避免一失败就立刻疯狂请求把上游打挂。这个细节我后来才在日志里体会到价值高峰期做促销活动上游偶发抖动如果没有退避重试网关自己就会变成新的故障源。2.3 成本追踪、用量统计财务视角的好帮手公司里用模型最怕的不是模型不好用而是月末账单对不上账。几个人共用一个 API Key调用了多少次、花了多少钱完全是一笔糊涂账。LiteLLM Proxy 天然带着一套用量记录和成本估算体系它会按你配置的模型单价或者根据厂商的实时价格信息计算每次请求的成本并把请求日志落到数据库里。你可以在管理页面上按 API Key、按模型、按团队维度看统计数据甚至可以设置月度预算上限。哪个业务线烧钱最猛看两个图就一目了然。我们之前有一个“为了测试开了接口给前端同学直接用”的场景结果月底发现测试环境产生了上千美金的调用量——后来给那个 Key 设了 50 美金的月预算到顶就自动拒绝新请求这类问题才彻底堵住。3. 从零部署 LiteLLM Proxy 网关一次完整的实操记录3.1 准备工作安装与启动LiteLLM 有两条路可以走一是直接在业务代码里作为 Python 库调用二是以独立服务的形式部署一套 Proxy业务方通过 HTTP 请求它。我强烈建议只要你的场景超过“一个人自己写脚本玩”就尽早从“直接 import”切换到“独立 Proxy”模式。安装非常简单pip install litellm[proxy]启动也更简单litellm --config config.yaml --port 4000它底层基于 FastAPI 实现所以启动后你会看到一个默认的交互式文档页面可以当做一个调试工具用也可以让前端同事照着文档写请求比什么手写说明都直观。3.2 写一份最小可用的 config.yaml以下是我实际项目里一份很典型的配置文件做过去敏处理model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-code litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llama litellm_params: model: openai/llama3.1-8b-instruct api_base: http://localhost:8000/v1 api_key: fake-key litellm_settings: num_retries: 3 request_timeout: 30 fallbacks: - [gpt-4o, claude-code]这里有几个概念需要解释清楚。model_list 里每一组配置包含两部分model_name 是“对外暴露的逻辑名”业务方请求的时候用自己的逻辑名即可litellm_params 则是“真实调用细节”包括真正要请求的模型标识符、API 地址、密钥来源。比如我本地用 vLLM 拉起了一个 Llama 3.1 模型对外叫 local-llama实际上只不过是一个把请求转发到 localhost:8000 的入口。业务方完全不用知道这后面到底是openai/gpt-4o还是本地部署。配置文件还可以通过环境变量引用密钥比如api_key: os.environ/ANTHROPIC_API_KEY这样密钥不会硬编码进仓库安全层面上干净很多。3.3 用 OpenAI SDK 直接对接代理这是最让人舒适的一点当你需要从业务代码发起请求时完全不必引入一个叫 litellm 的 SDK直接用标准的 OpenAI SDK 就可以from openai import OpenAI client OpenAI( api_keysk-litellm-virtual-key, base_urlhttp://你的网关地址:4000/v1, ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)因为 LiteLLM 暴露的接口本身就是 OpenAI 兼容的所以你已经写好、已经在用的 SDK 根本不需要换。这对老项目来说特别友好不需要大改代码只要把 base_url 指过来然后统一换一个由网关签发的虚拟 Key就能把流量纳管到网关层。这也是我建议所有团队都尽快切换 Proxy 模式的原因你用 Python SDK 没问题用 Node.js SDK、Java SDK、甚至写 curl 也没问题全部通过标准的 OpenAI 风格协议与网关通信网关再去适配各家真正的协议。技术栈异构的团队终于能在“模型接入”这件事上达成一致了。3.4 为什么我更推荐用 Proxy 而不是只用库直接调用litellm.completion()在个人脚本里很方便但它在多服务、多团队的架构下有一个绕不开的问题每个服务都要自己处理密钥、自己配置模型列表、自己实现重试策略配置分散在 N 个服务的环境变量里一旦要换模型你得挨个去改。而 Proxy 模式把所有“模型侧”的配置收敛到一个地方服务方只面对一个“API 网关”。这带来的好处包括安全隔离业务团队不直接接触上游厂商的 API Key统一使用网关签发的虚拟 Key出问题可以单独吊销。配置热更新设置好 proxy 的配置文件后重启服务即可生效不需要每个业务服务跟着改代码。可视化监控所有请求都经过网关所以日志、延迟、成本都能在同一处查看解决问题时有全局视角。基于这些原因我现在接手任何团队项目第一步都是问“你们现在有没有一个统一的模型接入层”答案是没有我就会推荐搭一套 LiteLLM Proxy。4. 真实场景组合LiteLLM 和 vLLM、LangChain、RAG 一起用4.1 接入 vLLM 拉起的本地模型开源模型部署这一块vLLM 是现在绕不开的框架。它吞吐高、显存管理好尤其适合那种内部知识库、私有化部署的场景。vLLM 默认也提供 OpenAI 兼容的接口所以接入 LiteLLM 几乎零成本只需要在 model_list 里加一项配置文件- model_name: internal-llama3 litellm_params: model: openai/meta-llama/Meta-Llama-3-8B-Instruct api_base: http://192.168.1.50:8000/v1 api_key: dummy这里 model_name 是业务侧看到的逻辑名内部的openai/前缀只是告诉 LiteLLM“这个服务商的接口协议是 OpenAI 风格”而 api_base 指向 vLLM 实际监听地址。这样做的直接价值是业务代码里如果想用“私有化的 Llama”还是“云上的 GPT-4o”根本不改代码只改 model 名。我做过一个内部问答系统早期全部调用云端模型后来公司要求数据不出内网于是把纯内部数据类的问题路由到 vLLM 本地模型其余开放问题才走云端模型。前端看到的是同一个 API 入口体验没有任何变化。4.2 LangChain 生态下的无缝切换LangChain 是很多人搭 LLM 应用时第一个接触的框架它本身有一套庞大的组件生态。LiteLLM 在 LangChain 里的集成方式也值得注意。最直接的用法是直接把 LiteLLM 的模型类接进去from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o, openai_api_basehttp://你的网关地址:4000/v1, openai_api_keysk-litellm-virtual-key, )看到没有还是那条路只要改 base_url 和 key你的 LangChain 工作流就已经接入第三方模型了。这个思路可以扩展到几乎所有“接受 OpenAI 兼容配置”的前端框架。对于团队已有的 LangChain 项目迁移成本低到“改配置”而不是“改代码”。4.3 RAG 场景里的模型路由配置我最近维护的一个知识库问答系统就是典型 RAG 架构先用向量数据库做召回再把召回片段塞给大模型做生成。这个场景里对于“总结性”问题用哪家模型差异不大对于“要引用文档原话”的问题就需要准确性和上下文长度都很好的强模型对于一些模板化的“标题生成”任务用小模型足够。在 LiteLLM Proxy 里这个需求可以通过定义多个 model_name 实现model_list: - model_name: rag-summary litellm_params: model: openai/gpt-4o-mini - model_name: rag-heavy litellm_params: model: anthropic/claude-3-5-sonnet-20241022 - model_name: rag-embed litellm_params: model: openai/text-embedding-3-small业务代码里根据问题类型直接请求不同 model_name网关帮你做真实路由。价格和效果之间的平衡被配置化产品经理想调策略只需要说一句“把 rag-summary 换成 claude 的小模型”你改一行 YAML 就行。在这种架构下向量数据库、LangChain、模型网关各司其职向量库管“召回”LangChain 管“流程编排”LiteLLM 管“模型适配和治理”。整条链路清晰了好多。4.4 微调后的模型如何统一暴露另一类常见需求是模型微调。你用某模型服务商的微调接口训练了一个垂直模型训练完之后业务方想用这个专用模型但又不想把微调 API Key 暴露给前端。LiteLLM 同样可以做这层包装。以 OpenAI 微调为例配置大概这样- model_name: finance-qa litellm_params: model: openai/ft:gpt-3.5-turbo-0125:your-org::your-finetuned-id api_key: os.environ/OPENAI_API_KEY业务侧只需要知道一个逻辑名 finance-qa 就可以了模型 ID、密钥、计费规则都在网关层管理。将来微调版本迭代把模型 ID 换成新版本业务代码一行都不动。这一点对于算法和业务分离的团队特别有价值。5. 配置与运维中的踩坑记录这些细节文档里未必写清楚5.1 虚拟密钥和真实 Key别搞混了边界LiteLLM Proxy 在生成 API Key 时默认产出的是一种“虚拟密钥”它并不等同于上游厂商的密钥而是网关内部签发的一个令牌。业务方拿这个令牌请求网关网关再“代持”真实 Key 去请求上游。这个设计天然规避了密钥分发问题但坑也在这里如果某个业务方绕过网关、直接拿真实 Key 去请求上游那么你的预算控制、审计日志在那一部分流量上就形同虚设。所以我在团队里定了两条纪律第一所有上游厂商 Key 只允许出现在网关所在服务器和密钥管理系统里第二代码评审时凡是看到直接调用 OpenAI SDK 并填入真实 Key 的一律打回改造。这不是技术问题是治理问题。一旦某一天一个 Key 泄露你能很快定位到是谁的 Key、是哪个环节流出去的而不是整个账号一起陪葬。5.2 预算控不住多半是单位没对齐LiteLLM 的预算配置支持按 Key、按 User、按 Team 维度设置 max_budget我见过很多次“明明设了预算为什么还是超了”的疑问查下来多半是单位或者时间窗口理解错了。比如 max_budget 是以美元为单位budget_duration 可以是 1d、30d、1mo 这样的字符串如果你期望“自然月”而配置的是“滚动30天”月底可能会看到一个你不太理解的超支记录。另一个容易忽略的点是预算周期内即使请求被拒绝请求本身可能已经到达上游产生了费用。预算控制更像一个“主动刹车”但不等于“欠费后一分钱不再花”。我在生产环境测试时发现从预算触发到真正拒绝新请求通常有极小延迟所以不要把预算上限设成金额上限的 100%留 20% 的缓冲更稳妥。5.3 缓存要区分流式与非流式否则会踩逻辑坑LiteLLM 支持语义缓存和精确缓存我一开始图省事给 RAG 问答接口直接开了缓存结果出现了一个诡异问题同样的问题前一个人问到了“今天天气不错”的答案第二个人在非流式接口下拿到的是完全一致的历史缓存但在流式接口下某些时候会拿到一个“残缺开头”或者超时降级后的不完整内容。后来研究了一下这个现象简单说流式请求的缓存处理和普通响应的缓存处理并不完全一样而且缓存键的设计会影响命中粒度。我的建议是如果业务对时效性敏感比如行情、资讯类问答先把缓存关掉或者明确设置较短的缓存过期时间如果缓存只用于高重复度的 FAQ打开缓存前先想清楚“哪些数据可以被缓存”不要全量一把梭。5.4 高峰期连接池和最大并发踩过的另一个坑代理模式还有一个容易被低估的问题是“并发能力”。我在一个大促活动前做过一次压力测试直接拿 locust 压网关发现网关本身没挂倒是上游某个模型厂商先开始疯狂 429。查日志后发现是网关层把同一上游的并发请求放得太猛触发了对方限流策略。这个事情提醒了我两个配置维度一是网关层要为每个上游设置合适的最大并发数比如通过配置控制同一模型的并发请求数二是要分层做限流而不是把全部压力原封不动转发给上游。LiteLLM 手册里有很多参数不同版本的字段名会有差异动手前记得先看清楚自己版本的配置说明别照着几个月前的博客抄。结尾两个我踩了多次之后非常上头的经验最后再分享两个我实际操作中感受很深的点。第一个是把“模型名”当作你的接口协议来设计而不是把“具体某个模型”当作协议的一部分。所有业务代码里不要出现具体的供应商模型标识统一用自定的逻辑名比如 “default-chat”“long-context-summary”“cheap-embedding”。这样你将来无论是因为成本、效果、合规原因换模型都只是一次配置变更而不是一次代码重构。LiteLLM 的 model_name 设计天然就是为了支持这件事别浪费了它。第二个是一定把日志成本算进你的架构里。LiteLLM 默认会把请求日志写到 SQLite但生产环境数据量一大SQLite 扛不住太久。我第一次直接在生产跑默认配置两周后日志写入延迟明显拖慢了接口响应。后来我把日志切到独立数据库或者干脆把持久化关掉只保留一星期以内的统计输出另外用外部系统收集网关日志性能马上恢复了。如果你正在为“多模型接入”这件事头疼我的建议是别在业务代码里手动适配各家 SDK直接花半天时间把 LiteLLM Proxy 搭起来试试。先把两三个常用的云端模型和本地 vLLM 模型通过网关暴露出来业务侧完全用 OpenAI 风格的 SDK 调用不了多长时间你就能感受到“模型成为可替换组件”这件事有多舒服。