如果你手里的业务要同时对接两三家大模型服务商你一定体会过那种“接口地狱”消息结构差不多、参数名差一点、流式事件的解析规则完全不同换一个模型等于重写一次接入层。我上个月就因为某个项目要增加本地私有化部署的模型翻遍文档写了三版适配代码后来同事 A 同学把 LiteLLM 丢给我说“你先试试这个能少写一半代码”。试完确实服气。LiteLLM 是一个把几十种模型服务的调用方式统一成同一套接口的开源组件可以当 Python 库直接用也可以起成独立网关服务。它不是那种花里胡哨的框架解决的就是接入层那些脏活累活。这篇文章我不会粘贴官方文档而是按我实际踩坑的顺序聊聊为什么需要它、客户端模式怎么用、什么时候该上网关、生产环境要注意什么。1. 先说说我为什么入坑多模型接入的混乱日常1.1 一次“换模型”引发的返工我参与过的内部知识库问答项目最开始只接了一家云端大模型官方 SDK 封装得不错调用起来很顺利。后来产品经理要求支持另一家新模型还要兼容公司内网的一台本地开源模型。问题一下就来了三套接口的消息结构大致相同但小节字段的命名和嵌套层级不一样。举个例子同样是把历史对话传给模型厂商 A 喜欢用messages里的content字段直接放字符串厂商 B 却要求把content换成数组里面再包一层type: text和text字段。如果模型要接收图片差异更明显有的要image_url有的要source。这些差异看着不大但代码里写起来就是一堆if分支。最痛苦的是测试用例。之前 mock 的数据全是按厂商 A 的格式造的换厂商 B 后全部失效。连“把上一轮回复拼到上下文里”这种基本操作都要写两份逻辑。当时我一度想做一个“万能适配层”把所有 SDK 的差异都收敛掉但越写越觉得不对这个适配层的复杂度会随着接入厂商数量线性增长而且每家的新功能你都要去追。1.2 统一封装不是把参数抄一遍那么简单市面上也有一些“统一 SDK”但我看了一圈核心就看两点第一是否覆盖我实际要用的厂商第二是否支持流式响应和工具调用。这两点缺一个后面准踩坑。厂商之间最典型的差异可以整理成这么一张表差异点厂商 A厂商 B本地私有化模型消息格式标准messages数组偏 content block 体系各家不一流式事件固定一类事件事件名不同结束标志不同有的甚至不标准工具调用arguments是 JSON 字符串结构化字段不同透传不稳定鉴权方式Header API Key额外版本头定期 Token超参命名temperature、top_p部分同义不同名未知字段直接报错这种差异意味着你没法靠写if-else优雅解决硬写出来的代码自己都不愿意维护。而且大多数厂商的接口都在快速迭代今天两个字段明天可能变成三个适配层永远在追版本。1.3 我的解法在应用和模型之间加一层适配折腾几轮之后我接受了“中间层”方案所有请求先发给一个适配层由适配层负责把统一格式转成各家模型需要的格式再把结果转回来。这个思路不算新鲜数据库驱动、消息队列客户端都是这么干的只是大模型接入的“方言”特别多适配层的工程量被放大了。LiteLLM 的好处是把这部分工程做完了。它对外暴露的接口刻意向主流的一类兼容协议靠拢这样你原有 SDK 的使用习惯几乎可以平移过来同时它允许你透传各家特有的参数不至于为了“统一”丢掉高级能力。选择它还有一个很实际的原因它既可以作为库嵌进你的应用也可以在以后需要时把同一套配置升级成独立网关不用推翻重来。2. 客户端用法先记住一个函数名2.1 安装与第一行代码引入成本很低一条命令搞定pip install litellm然后就能直接写import litellm response litellm.completion( modelopenai/gpt-4o-mini, messages[ {role: user, content: 用一句话解释为什么需要 API 网关} ], ) print(response.choices[0].message.content)代码和你平时接 OpenAI 风格接口几乎一样区别主要在model参数。LiteLLM 约定用服务商前缀/模型名的形式表示目标模型比如openai/gpt-4o-mini表示走这家服务商的同名模型。API Key 不一定要写在代码里它会自动从环境变量里找比如OPENAI_API_KEY、ANTHROPIC_API_KEY。当然你也可以显式传api_key参数这个后面本地模型会用到。第一次看到模型名要带斜杠的时候我愣了一下后来觉得这个设计其实很合理不同服务商可能都有同名模型或者同一个模型在不同平台的版本后缀不一样只有把“服务商”和“模型名”绑在一起路由逻辑才不容易搞混。2.2 流式、异步和工具调用的差异点生产环境很少用一次性的同步请求LiteLLM 支持异步和流式名字也特别好猜。异步response await litellm.acompletion( modelopenai/gpt-4o-mini, messages[{role: user, content: 你好}], )流式response litellm.completion( modelopenai/gpt-4o-mini, messages[{role: user, content: 写一段 200 字的故事}], streamTrue, ) for chunk in response: print(chunk.choices[0].delta.content or , end)真正值钱的是工具调用支持。现在做 Agent 类应用基本都要给模型挂工具不同服务商对工具调用的协议定义得五花八门。LiteLLM 允许你按主流风格直接传tools参数tools [ { type: function, function: { name: get_weather, description: 查询指定城市的实时天气, parameters: { type: object, properties: { city: {type: string, description: 城市名} }, required: [city], }, }, } ] response litellm.completion( modelopenai/gpt-4o-mini, messagesmessages, toolstools, )底层转换它替你做了。你只需要处理最终返回里的tool_calls字段逻辑和直接使用主流 SDK 差不多。这一下就把我原来手写转换适配的工作量省掉了。2.3 必须知道的模型命名约定客户端模式虽然简单但model参数的写法有讲究。我常用的几种目标大致如下目标model 参数写法说明官网通用模型openai/gpt-4o自动读取OPENAI_API_KEY另一家闭源模型anthropic/claude-3-5-sonnet-20241022自动读取ANTHROPIC_API_KEY某云平台已部署模型azure/我的部署名需要同时传api_base和api_version本地开源模型运行时ollama/qwen2.5:7b可省略api_base默认连本地端口任意兼容协议的自建服务openai/自定义模型名手动指定api_base可用任意合规服务这里最容易翻车的地方是服务商前缀。漏了前缀LiteLLM 会默认按某一种协议处理结果就是 401 或者格式错误。加了前缀但写错名字更麻烦因为很多报错信息不会直接告诉你“前缀不对”只会给你一个统一的模型不存在提示。我的习惯是先在文档页确认完整标识再本地跑一个最小请求验证。2.4 混搭本地与云端模型客户端模式最让我爽到的一个场景是同一套代码同时管理云端模型和本地私有化模型。内部知识库项目需要数据不出内网所以部分查询走本地模型但本地模型能力弱复杂总结又要走云端模型。以前这俩得维护两套调用代码用了 LiteLLM 之后后端只是拼接不同的model字符串model_name ollama/qwen2.5:7b if use_local else openai/gpt-4o剩下的请求逻辑、错误处理、重试全部复用。前端菜单里就是“快模型 / 强模型 / 私有模型”三个选项后端不关心底层是哪家的服务。这种“接入方式收敛为一次”的收益在项目初期可能看不出来等模型一多就非常明显。3. 进阶玩法把 LiteLLM 跑成独立网关服务3.1 什么时候需要网关而不是库客户端模式适合单个应用、场景单一的情况。但一旦你手里有多个服务都要接 LLM问题就来了上游密钥放在哪每个服务都存一份的话轮换密钥时你得改十几个地方不同团队怎么限额总不能靠口头约定模型故障时谁负责切换如果每个服务都自己实现回退逻辑代码风格会乱得没法维护。这时候就应该把 LiteLLM 跑成独立服务也就是网关模式。应用只跟网关通信网关负责背后的模型路由、密钥管理、重试回退和成本统计。从“每个应用自己接模型”变成“只有网关接模型”很多权限和治理问题就好办了。从库升级到网关代码改动并不大。因为网关提供的接口同样兼容主流的 Chat Completions 风格应用端换一个base_url就基本完事。这也是我当初敢选 LiteLLM 的原因先内嵌跑着等规模上来再拆出去。3.2 一份最小可用的网关配置网关模式的核心是一个 YAML 配置文件。先给你看一份能直接跑起来的最小配置model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: qwen-local litellm_params: model: ollama/qwen2.5:7b api_base: http://localhost:11434 general_settings: master_key: sk-换成你自己的主密钥启动命令litellm --config config.yaml --port 4000启动之后LiteLLM 会在本机 4000 端口提供一个 OpenAI 风格的网关端点路径是/v1/chat/completions。这里有两个概念要分清楚model_name是暴露给调用方的名字调用方只知道它叫gpt-4o或qwen-locallitellm_params.model才是真正上送给上游服务商的模型标识。你可以把任意上游模型映射成任意别名这在切换模型版本时特别有用调用方不用改任何代码。master_key是网关自己的主密钥调用方带着这个 Key 才能访问网关。后面你还可以为不同团队申请专用的虚拟 Key而不是直接把上游 Key 散出去。3.3 把现有 OpenAI SDK 客户端“骗”到网关网关模式最有意思的一点是你可以直接用现成的 OpenAI SDK 去连它因为它的接口本来就是兼容的。代码大概是这样的from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-换成你的主密钥, ) response client.chat.completions.create( modelqwen-local, messages[{role: user, content: 你好}], ) print(response.choices[0].message.content)你没看错model填的是网关里定义的model_name不是上游真实模型 ID。应用不知道也不关心上游到底是什么模型它只知道自己请求的是qwen-local。哪天你想把本地模型升级成更强版本只要改网关配置里的映射关系应用端一行代码都不用动。这种做法还带来了一个隐藏收益你可以用任何支持 OpenAI 风格调用的开源组件去对接网关。LangChain、LlamaIndex 这类框架甚至一些低代码工具只要允许自定义base_url就能直接连你的网关。等于说网关成了团队内部的“模型接入标准”上层工具生态基本上可以无缝接入。3.4 路由、重试和回退配置网关模式真正的能力在于路由治理。LiteLLM 支持把同一个模型的多个副本放在一组然后按策略分发请求也支持在一组模型失败时自动回退到另一组模型。配置上只要在router_settings里加几行router_settings: routing_strategy: usage-based-routing num_retries: 2 timeout: 30 fallbacks: - {gpt-4o: [qwen-local]}routing_strategy可以选“最少请求数”或者“基于用量路由”等策略。它的作用和负载均衡器差不多如果上游服务商某个 Key 已经接近速率上限网关会把请求发给另一组配置了相同模型但不同 Key 的节点从而摊平压力。fallbacks是故障转移。比如gpt-4o返回 429 或超时网关会尝试转给qwen-local。这个能力对可用性提升非常明显。我以前在应用里自己写回退逻辑来回试错、还要处理重试风暴现在网关统一做了规则也都在配置里团队其他人看一眼 YAML 就懂。4. 实际落地中的惊险时刻和我的解决套路4.1 模型名不一致会让请求静默失败我在客户端模式和网关模式都踩过同一个坑模型名不一致。网关暴露的model_name是一回事上游真实的模型 ID 是另一回事。如果你在网关里配了暴露名gpt-4o但上游模型实际叫gpt-4o-2024-11-20请求虽然到了上游却会收到一个“model not found”的 404。这类错误不太容易一眼看出原因因为它不是格式错误而是名字映射错了。我的排查套路是先直接用客户端模式调一次上游确认真实模型 ID 可用再检查网关配置里的litellm_params.model是否和客户端模式完全一致最后用/v1/models查看网关已经注册的模型列表确认暴露名没写错。这一套下来绝大多数问题都能定位。4.2 “厂商不接受的字段”是重大隐患各家模型对超参的宽容度不一样。主流服务商一般会忽略未知参数但某些自建模型服务对未知字段是直接报 400 的。比如同一套代码里你统一传了max_tokens和top_p结果目标模型只认max_completion_tokens请求就挂了。LiteLLM 给了两个处理方向。客户端模式可以在代码开头设置import litellm litellm.drop_params True网关模式则在配置里加litellm_settings: drop_params: true意思是当一个参数对目标模型不可用时LiteLLM 会在请求前自动丢掉它而不是硬着头皮传过去。这个开关对“一套代码兼容多种模型”特别重要强烈建议开启。但也要留个心眼某些参数被丢掉之后模型行为会有一点变化比如max_tokens丢了就可能导致回复长度不可控。所以生产环境关键请求还是要单独确认重要参数有没有被正确映射。4.3 工具调用和参数解析的双重序列化问题做 Agent 应用的朋友应该对工具调用的重放逻辑不陌生。有一次我写了一个对话回放系统把历史请求和响应都记录下来下次重放时直接把旧请求塞给模型。结果发现模型返回的工具参数被当成字符串又套了一层 JSON 转义整个调用链直接崩掉。原因很简单主流风格的tool_calls[].function.arguments字段规范上是一个 JSON 字符串不是对象。你在存储时如果又对它做了一次json.dumps就会出现“字符串里套字符串”的情况。正确做法是每层都严格按规范来传给模型时arguments必须是合法的 JSON 字符串拿到模型响应后arguments要做一次json.loads解析成字典再拼接业务逻辑回放时只传原始字典序列化后的字符串不要再做多余的嵌套。另外LiteLLM 在网关模式中会把工具调用转换成目标厂商的原生格式。转换后的返回字段可能与主流风格不同最好在测试环境里实际抓一次响应确认tool_calls的结构再写解析代码。我见过有人因为轻信文档里的示例没做真实打印结果解析逻辑错了一整天。4.4 成本统计经常对不上账面LiteLLM 自带一份常见模型的成本价格表方便你每次调用之后直接拿到cost字段。但这份表是社区维护的新模型发布时经常更新不及时冷门模型甚至根本没有收录。这时候你会发现调用结果里usage有 token 数但cost是 0或者价格明显不对。我的解决办法是在网关配置里对自定义模型手动补上价格信息model_list: - model_name: my-custom-model litellm_params: model: openai/xxx api_key: os.environ/OPENAI_API_KEY model_info: cost_per_1k_tokens: 0.002cost_per_1k_tokens表示每一千个 token 的成本。如果读写价格不一样还可以继续拆成input_cost_per_1k_tokens和output_cost_per_1k_tokens。把价格信息配准之后成本统计才有意义不然你后面做的预算控制全部建立在错误的数字上。4.5 流式请求的超时和长连接问题网关模式下还有一个容易被低估的问题流式请求的超时设置。模型生成很慢的时候连接会长时间保持打开如果网关的默认超时太短客户端会收到一个不完整的流而且没有明确的错误信息。我的建议是把超时调大同时设置重试次数而不是用默认值router_settings: timeout: 60 num_retries: 2 retry_after: 5对于我这边的情况60 秒足够覆盖绝大多数生成场景。如果模型经常超过 60 秒那问题可能不在超时而在模型选型或提示词设计上。另外如果同一时间并发请求很多要留意操作系统文件描述符限制和客户端连接池大小否则网关没有崩溃但连接池先被占满了。5. 生产环境下必须做的三件事5.1 密钥不能“裸奔”网关一旦上线它就是团队访问所有模型的总入口。这时候最忌讳的事情就是所有应用共用一个master_key或者更糟把上游密钥直接写在应用代码里。正确做法是用网关的虚拟 Key 机制为每个团队或每个应用生成独立的 Key并设置对应的权限范围。虚拟 Key 的生命周期可以控制某天某团队的项目下线了你只要吊销那个虚拟 Key不需要让所有应用跟着换密钥。上游 Key 只存在网关配置或环境变量里应用侧永远看不到。密钥轮换也只需要改网关一层不用再登录几十台服务器改配置。5.2 日志、追踪与可观测性网关模式上路以后最重要的就是看日志。LiteLLM 自带请求日志能看到每次请求的模型名、上游供应商、token 数、成本、响应延迟和错误码。别小看这些字段遇到问题的时候它们是第一手排查依据。我习惯把日志里的model、spend、response_time三个字段重点标记。model告诉你这个请求实际走了哪个上游spend告诉你成本response_time告诉你响应是否异常变慢。排查问题时先看延迟再看 token最后才看错误信息很多问题一眼就能定位。如果需要更细的追踪可以接入 OpenTelemetry 风格的指标或者把请求链路打到专门的追踪系统里。但对大部分团队来说先把基础请求日志收集起来比一开始就上复杂链路追踪更实际。5.3 预算和额度控制做 Agent 或内部工具最怕月底一看账单吓一跳。LiteLLM 的预算控制主要在网关层做可以按虚拟 Key 或团队设置额度比如“每个月最多消费 100 美元”超额之后网关自动拒绝新的请求。配置里一般是这样的逻辑general_settings: max_budget: 1000 budget_duration: 30d也可以为单个 Key 单独设置额度。我的经验是额度不要只设总额度还要注意单位时间的速率限制否则某个突发的请求高峰可能瞬间打爆月度预算。比如设置“每分钟最多 60 次请求”比单纯卡一个月总额更稳。5.4 一个值得养成的运维习惯最后说一个我自己的教训别一上来就把所有模型都塞进同一个网关。我踩过一次坑同时接入四个厂商后某个本地模型长时间无响应把整个网关的并发拖慢其他模型的请求也跟着遭殃。后来我把网关拆成两组一组承接关键生产任务只配置高可用模型另一组跑实验性模型允许失败和慢响应。两组之间不互相影响排障也简单很多。另外升级模型或新增厂商时先在网关配置里加一个“影子模型”用一小部分流量跑几天观察成本、延迟和错误率确认没问题再切换正式流量。直接全量切换的做法我试过一次某个模型连续报错导致所有回退流量打到另一个模型上预算直接飙升。有了影子验证和回退配额之后这类事故基本可以避免。如果问我想再分享什么那就是多模型接入这件事真正难的不是写代码而是把路由、成本、可观测这些“基础设施感”很重的事情提前想清楚。LiteLLM 帮我解决了最麻烦的接入层剩下的策略打磨反而成了乐趣。建议你在每个调用日志里都保留model和cost两个字段后面做成本归因会省下大量时间。