最近半年接的 AI 应用项目几乎没有一个不用接多模型。客户的诉求也都很一致想用 GPT-4 的代码能力又惦记 Claude 的上下文长度还点名让支持开源模型的本地化部署。如果按老思路给每家 API 单独写一个 SDK 接入模块光维护模型参数映射就能把人逼疯。后来我把整套架构切换到了 LiteLLM 这一层代理上问题一下就简单了。这篇文章不是给你抄官方 README而是说说我在多模型接入实战里怎么选型、怎么埋坑、怎么把预算和频率限制管起来的。如果你正在处理多模型接入或者打算统一公司内部的模型调用入口这里的经验可以直接照搬。1. 为什么我决定用 LiteLLM而不是继续堆各家 SDK1.1 直接替换代码结构的核心收益先说结论LiteLLM 最大的价值不是多一个中间件而是把 100 多种大模型 API 的请求格式、鉴权方式、返回结构全部归一化成 OpenAI 的格式。这话听起来很简单但实际换过来之后收益是革命性的。以前项目里引了 OpenAI、Anthropic、Google 三家的官方 SDK再加上一套接入某开源模型的内部模块总共四套不同的要求路径。每套请求体结构不同返回结构也不同。OpenAI 的response.choices[0].message.content、Anthropic 的response.content[0].text每次都要在业务代码里单独写适配层。Model 层写了一大堆 if-else逻辑乱成一锅粥。换成 LiteLLM 之后所有模型调用统一走acompletion或completion方法传入的模型名只是加了一个前缀比如anthropic/claude-3-opus-20240229、openai/gpt-4o、ollama/llama3。不同模型的差异被前缀剥离了代码里的 if-else 跟着一起消失。注意LiteLLM 的前缀是硬编码的 provider 标识不要自己发明缩写。写错的后果是请求直接 throw 一个ModelNotFoundError排查起来会误伤业务逻辑。1.2 那些容易忽略的兼容性细节真实项目里有个很容易踩的坑官方 API 里有些参数是某家模型独有不是所有模型通用的。比如 Anthropic 的top_p、OpenAI 的logprobs、本地模型的num_predict。如果直接把这些参数塞进 LiteLLM 的请求体它默认会直接透传给后端模型结果部分模型会拒绝执行。我的做法是定义一套通用参数子集给所有模型只支持 temperature、max_tokens、top_p、stream、stop 这几个标准字段。凡是跟具体模型绑定的参数放到additional_args里单独传只有执行特定模型时才去填充。这套参数白名单机制帮我规避了大量请求失败的问题。1.3 什么时候不该选 LiteLLM客观讲如果项目永远只调用一家模型 API用原生 SDK 完全没问题。LiteLLM 的价值在多模型、多租户、需要集中管理配额和预算的场景才会充分放大。团队很小、没有运维人力、只接一个公开 API 的话加一层代理还要多维护一个服务反而加重负担。我在一个模拟项目X里做过测试同一套调用逻辑原生 SDK 比 LiteLLM 快 10% 左右但这个差距主要体现在小请求上。流式输出场景下用户体感几乎无差别。所以别再纠结有没有 10% 的中间层性能损耗了多花点时间省掉几百行模型适配代码才是真划算。2. 配置文件的加载顺序与密钥管理的几层细节2.1 环境变量、config.yaml 与运行时动态配置的优先级LiteLLM 允许三种方式配置 API 密钥环境变量、config.yaml、运行时自定义传参。三者混用的时候实际上存在一套隐性的优先级逻辑。它在底层用get_secret()解析 key最优先读运行时传入的api_key字段其次才去读环境中用模型名映射的 key。比如OPENAI_API_KEY和ANTHROPIC_API_KEY是环境变量方式最靠后的才是 yaml 里的配置。这个细节决定了一件很重要的事情哪一层能兜底。我当时因为想快速上线把 key 直接写在 config.yaml 里然后代码里没有显式传 key一切正常。后来测试环境要接一个专门测试账号我需要临时覆盖线上 key发现怎么传都不生效。后来查了源码才发现运行时传参优先级最高但只有请求发起对象的代码里显式声明了api_key才会触发覆盖。2.2 master_key 的两层作用访问令牌与虚拟 API key 鉴权如果只把 LiteLLM 当 SDK 用不开代理模式master_key就没那么关键。一旦打开config.yaml里的general_settings.master_keyLiteLLM 会立刻切进代理模式所有进来的请求都要带一个有效的 API key。这个 master_key 可以生成多个虚拟 key每个虚拟 key 可以绑定不同的预算、速率限制和模型白名单。这一点在需要在多个团队之间共享网关的时候特别重要。我在某公司的内部平台里给每个业务线发了不同的虚拟 keyA 团队只有openai/*的权限B 团队只能用anthropic/*某一天某个业务的日志量异常上涨直接定位到是哪把虚拟 key 出的问题不用去挨个翻 Kubernetes 集群里的 Pod 日志。2.3 配置加密与团队协作的约定配置文件很容易变成一个秘钥大杂烩。我的建议是 config.yaml 里只写占位符如${OPENAI_API_KEY}真正的 key 放到部署环境的环境变量里。这样 config 文件才能放心提交到 Git也能避免 key 泄露后需要全量轮换的尴尬。团队协作里也需要约定一个命名格式。项目里统一用LLM_前缀定义环境变量比如LLM_OPENAI_KEY、LLM_ANTHROPIC_KEY。LiteLLM 在解析model: openai/gpt-4o时会默认寻找OPENAI_API_KEY这样的 key 名所以我们需要自定义映射。from litellm import completion os.environ[OPENAI_API_KEY] os.environ.get(LLM_OPENAI_KEY, ) os.environ[ANTHROPIC_API_KEY] os.environ.get(LLM_ANTHROPIC_KEY, )这样写之后不管 yaml 里怎么设置代码里的映射关系都清晰。后来接手这个项目的同事说这是配置里最省心的一部分。3. 流式输出与多模态请求的落地细节3.1 流式是指渲染而非等待全量返回一些刚接手 LLM 项目的同学对流式的理解有误区。流式带来的不是首字延迟变低而是让用户不用等待全量内容生成完才看到文字。LiteLLM 对流式的处理是透传机制的streamTrue打开后返回一个迭代器每取一段就往客户端推一段。需要特别说明的是LiteLLM 返回的流式数据在不同 provider 之间结构不一致。OpenAI 的 chunk 里是delta.contentAnthropic 的 chunk 里是delta.text。LiteLLM 在做统一的时候是把所有 provider 的 chunk 都改成了 OpenAI delta 格式。response litellm.completion( modelclaude-3-5-sonnet-20241022, messagesmessages, streamTrue ) for chunk in response: # chunk[choices][0][delta][content] 已经统一 yield chunk[choices][0][delta][content]但如果自己直接遍历response拿到是自定义对象不是标准的 dict。我实际测试时发现直接对迭代对象做json.dumps()会报错需要先转 dict 或者直接访问属性。这一点和原生 OpenAI SDK 的返回结构不一致属于 LiteLLM 为了兼容性做了一层封装带来的副作用。3.2 多模态请求的图像输入格式多模态图片文本请求在做统一接入时也有几个坑。LiteLLM 遵循 OpenAI 的 message 格式图像内容要放在 content 数组里用type: image_url去标识然后 image_url 里嵌套url字段。OpenAI 的接口远高于通用标准但 Anthropic 的图像格式是 base64 的 source 类型。实测下来LiteLLM 在转换图像时主要是把 Anthropic 格式的图片字节转成 OpenAI 需要的 data URL。这个时代最方便的方式是直接把本机文件转成标准 base64 字符串Python 端唯一需要注意的就是 base64 字符串前面要加data:image/jpeg;base64,前缀。如果图像是远程 URL并且该 URL 需要鉴权头直接传 URL 会 401。这种情况就必须先把图片下载到内存里转 base64 再传。网络图片的格式转换正确但缓存策略没做会导致每次请求都去拉一次原图token 成本没涨但延迟和网络带宽会明显增加。3.3 超时与重试机制的坑LLM API 的响应时间不像传统接口那样稳定特别是长上下文请求可能 30 秒甚至 60 秒才返回。设置超时要根据具体模型来确定我在 CLI 工具类项目里设置为 120 秒而 Web 端交互项目里则采用首字超时 流式超时的组合策略。litellm.completion( modelopenai/gpt-4o, messagesmessages, timeout60, num_retries2 )LiteLLM 默认重试机制比较简单遇到超时、429 限流、5xx 错误时重试且重试遵循指数退避。但有个细节容易踩坑读取超时和连接超时区分的阈值不同代理模式下connect_timeout只有 10 秒默认值后端某一瞬间无法响应代理日志不会立刻报错客户端会等等到读超时才拿到异常表现为调用变慢而非彻底失败。4. 一种特殊的使用场景离线模型与私有化网关4.1 Ollama 与 vLLM 的接入方式差异LiteLLM 不只是连接云厂商的 API它对本地模型的支持也很完善。通过 Ollama 启动一个本地模型LiteLLM 里直接指定模型名为ollama/llama3.1:8b就能转发请求不需要额外做端口转发。但这里要注意Ollama 的模型在本地是流式返回 tokenLiteLLM 默认会开启stream模式如果业务后端没有处理流式响应本地模型会被认为有 bug。vLLM 这种起 OpenAI 兼容服务的框架更直接LiteLLM 识别到 base_url 后直接把原请求转发到对应端点。注意如果自己搭的 vLLM 服务没有/v1路径前缀需要显式在 base_url 里避开空格不然 404 会非常难排查。### 4.2 混合云架构里的路由策略 我的项目里经常出现这样的需求某些敏感数据必须走私有化模型其他常规内容走云端大模型。LiteLLM 支持在 config.yaml 里配置 router_settings将不同的 model 命名路由到不同的 deployment 里。而且它比想象中智能的一点是这个路由策略不仅匹配模型名还支持根据权重分发流量。model_list:model_name: gpt-4o-special litellm_params: model: openai/gpt-4o api_base: https://internal-gateway.example.com/v1 api_key: os.environ/LLM_OPENAI_KEY model_info: mode: completionmodel_name: local-llama litellm_params: model: ollama/llama3.1:8b这里 model_name 是暴露给业务方的名字litellm_params.model 是实际发给后端的模型名。我们团队内部引入这个别名机制之后业务方不再需要感知底层到底是哪个模型后端切换模型时只需要改配置不需要业务方动代码。 ### 4.3 本地模型的 token 计数与限流拦截 本地模型和云端模型在 token 计数上不一致这一点经常被忽略。云端 API 通常会在返回体里附带 usage 字段本地模型有的实现并没有。LiteLLM 提供一个 set_token_counter 接口来自定义计数逻辑。不自定义的话日志里的 usage 为 0模型限流策略会失效。 我踩过一次坑某个内部工具用本地量化模型跑批量任务结果并发一高直接把机器内存打满。查了半天发现是 token 数统计不准本地服务自己的 context 已经快接近上限但 LiteLLM 层没感知到依然放行新请求进来。最后在 router 里加了自定义 token 计数按请求阻塞的并发数做了限制服务才稳定下来。 ## 5. 预算控制的几个关键配置与真实业务场景 ### 5.1 按 key 限额、按模型限价与按用户限速的关系 预算控制是 LiteLLM 在真实企业场景里很常见的诉求。它不是简单的设置一个总额度而是可以做到多维度的组合控制按 API key 设置单日最大消费、按模型设置单次调用最大成本上限比如单次请求价格超过 0.1 美元直接拒绝、按用户维度设置 RPM每分钟请求数和 TPM每分钟 token 数。 这个配置意味着什么你可以给研发环境单独开一个每天 5 美元的 key给外墙机器人开一个每分钟 60 次请求的配额。我之前搭建的一个客服系统里就是通过 max_budget 防止某个异常 bug 把账户余额打光又通过设置 rpm_limit10 避免了某位同事写了一个死循环脚本在后台疯狂调用。general_settings: master_key: sk-your-master-key database_url: postgresql://... litellm_settings: max_budget: 1000 budget_duration: 30d注意配了 database_url 之后LiteLLM 会将 key 使用量和预算信息持久化到数据库。这个步骤不要省。没有数据库的话一旦代理重启预算计数全部清零等于限额形同虚设。用 SQLite 做 demo 没问题生产环境老老实实上 PostgreSQL。 ### 5.2 用 Redis 缓存避免重复扣费难题 预算与速率的实时控制在多实例部署时非常依赖分布式锁和共享计数。LiteLLM 支持通过 Redis 缓存保证多副本之间的配额数据一致。这里我把踩过的坑说明白当 LiteLLM 代理在 Kubernetes 里跑 3 个副本没有配置 Redis 的情况下每个副本各自维护一套速率计数器理论的 tpm 限制会变成实际的三倍等于限流失效。 配置 Redis 的字段是 cache 下的 type: redis。而且不只是限流数据里面还能存请求日志和 token 统计。代价是每次请求会多一次网络往返但换来的是数据一致性这个性能消耗可以接受。 ### 5.3 异常日志的格式化与追踪信息 最后提一下可观测性。LiteLLM 的日志在默认配置下不太适合直接接入企业级日志平台它的 call_logging 功能可以把每次请求的详细信息交给回调函数。我通常会把 model、messages 长度、response.cost 等关键字段挑出来主动发送到 Sentry 或者写入 ClickHouse。async def log_success_async(kwargs, response_obj, start_time, end_time): cost response_obj.get(cost, 0) model kwargs.get(model) # 写入自己的日志系统litellm.success_callback [log_success_async] litellm.failure_callback [sentry]这里的 cost 字段非常重要特别是未来需要做计费报表的时候。LiteLLM 会基于自己的定价表计算成本所以如果使用自定义的 api_base务必检查模型定价是否匹配。我就遇到过一次接入某内部模型返回的 cost 是 0原因就是它找不到对应模型的定价表默认按 0 处理。修改 model_info.custom_llm_provider 和 model_info.max_tokens 也解决不了必须补充 model_cost 字典。 ## 6. 我在三个真实场景里跑的完整链路复盘 ### 6.1 某个智能客服项目里的稳定运行 为了让你更直观感受这套东西怎么落地我拿一个实际开发过的客服系统举例。这个项目的需求是使用 GPT-4o 做语义理解使用 Claude 3.5 Sonnet 做最后的回复润色底层接的是某私有化部署的向量模型做意图识别分类。 集成完成后收到的最明显收益是代码量少了一大半。以前需要分别对接三个模型的 SDK各自写异常处理、超时重试和返回格式解析。现在业务代码只需要一个 async def chat(messages): 函数内部通过 litellm.acompletion 统一处理日志层面也在代理侧统一记录 token 消耗。 运行期间遇到的最大的风险是模型切换。有一次 GPT-4o 出现连续错误我们在没有改一行业务代码的情况下仅通过修改 config.yaml 里的 model_name 映射就把流量切到了 Claude 3.5 上。整个过程不超过 5 分钟对线上用户没有影响。这在之前的架构里是完全做不到的至少需要重新发布业务服务。 ### 6.2 单个慢请求拖垮整个 Batch 任务的排查 另一个值得记录的案例是批量数据处理任务。某次在跑大规模摘要任务时整体耗时突然从 30 分钟飙升到 2 小时而且大量任务报超时。排查时先看业务代码发现批处理并发数、超时都正常接着看 LiteLLM 日志发现大量请求耗时为 60 秒以上。 最终定位是某一个模型在特定上下文长度下响应特别慢但它没有触发超时重试所有请求都压在代理层等待。解决方案是把该模型的 timeout 降为 45 秒并开启 num_retries1同时设置 allowed_fails 指标。如果同一个模型连续失败 3 次直接触发熔断不再调用该模型转而走备用模型。 ### 6.3 多租户场景下的防跑路机制设计 最后一个案例是关于逃单的。某平台对外开放了 50 个租户每个租户都拿自己的 key 接入。如果没有配额任何一个租户写个死循环都能把预算打穿。当时我们做了三层防护 第一层是按 key 限流给普通租户设置 rpm60, tpm100000第二层是按租户维度设置 max_budget50 美元第三层是给所有租户的总调用量设置一个总预算。这三层数据全部落到 PostgreSQL出现异常时可以直接在管理后台看到到底是哪个 key 的消耗量暴增。 ## 7. 关于模型兼容性你必须接受的三个不保证 ### 7.1 参数映射不是 100% 无损 LiteLLM 文档里明确写着它exposes OpenAI format但这不是逐字逐句的转发。部分 OpenAI 参数在转成其他家格式时会被丢掉例如 OpenAI 的 frequency_penalty 在转 Anthropic 时只能映射到 top_p 和 temperature 做近似处理。所以如果要使用某家模型的强项能力如 Anthropic 的 thinking 模式就必须在请求模型名前加 anthropic/ 前缀然后使用 Anthropic 原生格式去构造请求。 ### 7.2 工具调用Function Calling的格式差异 Function Calling 是很多 agent 应用的核心能力。OpenAI 的 tool 结构在 Anthropic 下需要用 tools tool_choice 字段去适配。LiteLLM 的兼容层识别 OpenAI 格式的 tools自动转成 Anthropic 能识别的结构。但实际转换里有个比较隐晦的点OpenAI 的 function 定义里 parameters 要求是 JSON Schema 格式Anthropic 额外要求 input_schema 并把顶层定义为 object 类型。如果代码里构造的 JSON Schema 不规范在 OpenAI 下能跑切到 Anthropic 就会报 400。 我的对策是给工具定义写一个独立校验函数在发起请求前先用 jsonschema 库校验一遍。这个校验函数帮我在早期就拦截了很多低级拼写错误。 ### 7.3 embedding 模型同样适用但成本要单独统计 不是只有 chat 模型能过 LiteLLMtext-embedding-3-small 这类 embedding 模型同样支持。Embedding 请求的 token 消耗在 usage 里返回的就是实际 token 数和 chat 模型算法一致。但 embedding 一般调用量都巨大成本统计必须单独看。我在成本报表里把 embedding 的消耗和 chat 消耗拆开统计不然一个批次任务里可能因为 embedding 费用占比过高导致对整个项目的利润率判断出现偏差。 ## 8. 部署方式的选择建议与监控配套 ### 8.1 Docker 单机部署还是 K8s 多副本 LiteLLM 官方镜像很小CPU 模式下跑起来几乎没有资源压力至少 1 核 1G 就能带动一个中高并发网关。单机部署适合小团队和实验项目部署起来就是一个 docker run 的事情。多副本部署则必须考虑配置同步问题。 K8s 多副本部署时不建议用默认的 Deployment 直连一定要把 database_url 指向共享 PostgreSQL否则不同 Pod 之间的配置不同步虚拟 key 校验时会出现时灵时不灵的问题。LiteLLM 会自动检测 config 是否有变化但自己手动 kubectl scale 的时候新 Pod 并不会主动去拉取远端数据库里的最新配置需要滚动重启一次才会加载。这个坑曾经浪费了我整整一个下午。 ### 8.2 健康检查与优雅停机 对代理服务做健康检查至关重要因为它要承接所有模型的流量。如果代理是单点它一挂整个系统就无法调用模型了。在 Kubernetes 里需要配置存活探针和就绪探针LiteLLM 默认暴露了 /health/liveliness 和 /health/readiness 两个端点直接配到 Deployment 里即可。 此外需要考虑优雅停机。当 Pod 被滚动更新时正在处理的流式请求会被强制中断。这时需要为 Pod 设置 terminationGracePeriodSeconds 大于最长模型响应时间否则客户端会看到流式输出突然中断且没有任何错误提示。 ### 8.3 日志采集与告警 日志方面LiteLLM 默认输出 JSON 格式日志里面含有 request id、model、response time 等关键信息。建议在收集端直接按 model 字段做索引排除掉健康检查的干扰项。同时按 response time 做出一个基础告警如果平均响应时间连续 5 分钟超过 30 秒立即告警。 告警阈值不能一刀切需要按不同模型分开设置。比如某开源大模型本地部署的平均响应在 8 秒左右OpenAI 在 1.5 秒左右。统一用 5 秒阈值会导致本地模型的监控频繁误报。后来我把模型分了三档快速档 5s、普通档 20s、慢速档 60s每个档位单独设置告警。 ## 9. 从零到一搭建一套可接入多模型的工程化骨架 ### 9.1 最小可运行骨架一个函数适配所有模型 如果你是从 0 开始把 LiteLLM 集成到项目里最稳妥的路线是先跑通一个函数适配所有模型的最小骨架。代码只要几行import litellm import osos.environ[OPENAI_API_KEY] your-keydef llm_chat(model: str, messages: list, **kwargs): try: resp litellm.completion( modelmodel, messagesmessages, **kwargs ) return resp.choices[0].message.content except Exception as e: raise RuntimeError(fLLM call failed: {e})调用的时候llm_chat(openai/gpt-4o, messages) 和 llm_chat(anthropic/claude-3-5-sonnet-20241022, messages) 都会走同一个函数。把 model 参数从配置文件里读出来就能做到不改代码任意切换底层模型。 python ### 9.2 企业级骨架还需要加的东西 但工程化不能止步于此。我实际落地时会在这个最小函数上再叠加四层 - 第一层是重试机制单独封装一个 retry_with_backoff 装饰器覆盖网络抖动和 429 限流。 - 第二层是缓存层对相同 system prompt user prompt 的请求用 Redis 做个短时缓存缓存时间设置为 5 分钟同时提供一个手动清缓存的开关防止业务侧需要实时数据时拿到脏缓存。 - 第三层是审计日志把每次调用的用户 ID、模型名、token 数、成本、响应时间写入数据库这个数据对后面的成本分摊和模型效果评估都很有价值。 - 第四层是模型切换开关用一个远程配置中心控制比如某个模型连续错误率达到 5%自动把流量切换到备用模型。 这四层加完一套完整的 LLM 网关就不仅仅是一个代理了而是变成了整个团队的基础设施。我见过很多项目初期只接一个模型运行了几个月后想接第二个模型结果发现所有调用都散落在业务代码里硬编码了模型名和 API key改造起来极其痛苦。如果你的项目也存在这种隐患用一个独立网关层来收敛所有 LLM 调用是非常值得的投资。 ### 9.3 成本与收益的简单计算 最后给一个直观的成本参考。假设公司现在有 5 个业务系统在使用 LLM每个系统平均支持 2 种模型直接接入的成本是维护 10 个模型适配模块以及每个开发者都看不同的 API 文档。用 LiteLLM 统一之后维护成本变为维护 1 个代理网关和 1 套配置。 部署成本不高一台 2 核 4G 的服务器完全可以扛住中小规模团队的全部调用量。省下来的人力成本非常可观而它带来的多模型容灾能力是直接在业务层面提升了可用性。我个人的体会是LiteLLM 不是一项需要造轮子的技术它本身就是轮子。你要做的只是把它推到该在的位置然后在轮子周围铺好你专属的监控、预算和审批流程。 如果你决定试用建议第一步不要追求花哨的 fallback 策略和复杂的路由规则先把最简单的一个模型通过代理跑通再逐步接入第二、第三个。每个模型的接入都要留出半天的回归测试时间特别是流式响应和工具调用这两个场景。跨模型切换做到无感再放开线上流量。这样一步步走比一开始就把所有模型都接进来然后遇到问题手忙脚乱要舒服得多。