1. 为什么一个接口层能成为多模型调用的关键枢纽第一次接触 litellm 是在一个需要同时对接多家大模型服务的项目里。当时团队面临一个很现实的问题业务代码里散落着各种 SDK 调用OpenAI 一套写法、某云厂商一套写法、本地部署的模型又是另一套写法每换一个模型就要改一遍业务逻辑测试成本高得离谱。litellm 这个项目就是冲着这个痛点来的——它用统一的 OpenAI 格式接口把不同厂商、不同协议的模型调用全部抹平让业务层只写一次代码就能切换任意后端。说白了litellm 是一个LLM API 的统一代理层和 SDK。它能做什么一句话概括你用它提供的completion()函数传入modelopenai/gpt-4o或者modelanthropic/claude-3-5-sonnet或者modelollama/llama3剩下的协议转换、鉴权、参数映射、流式处理它全帮你搞定。解决了什么问题解决了多模型时代最烦人的适配碎片化问题。适合谁看如果你正在做 AI 应用、需要对比多个模型效果、或者要给团队搭一套统一的模型网关这个项目值得花时间研究。我写这篇东西的出发点很简单官方文档虽然全但很多实战中的坑和取舍逻辑它不会告诉你。下面我把自己从零搭一套 litellm 调用体系的过程完整拆一遍包括选型理由、配置细节、踩过的坑以及那些文档里不会写的经验。2. litellm 的整体设计与核心思路拆解2.1 它到底解决了什么架构层面的问题在没有 litellm 之前一个典型的多模型项目代码大概长这样业务层里到处是if model_provider openai: ... elif model_provider anthropic: ...这样的分支。每接一家新厂商就要新增一个分支、新增一套异常处理、新增一套重试逻辑。代码越堆越厚维护成本指数级上升。litellm 的思路是把这层适配逻辑抽出来做成一个中间层。它的核心设计有三个关键点第一接口标准化。它完全对齐 OpenAI 的 ChatCompletion 接口格式包括 messages 结构、参数命名、返回体结构。这意味着你原来写 OpenAI 的代码几乎不用改只要把openai.ChatCompletion.create换成litellm.completion再改一下 model 名字就行。第二模型路由与映射。它内部维护了一张巨大的模型映射表把gpt-4o、claude-3-5-sonnet、gemini-1.5-pro这些名字映射到对应的厂商 SDK 和调用参数。你只需要在 model 字段里加个前缀如openai/、anthropic/它就知道该走哪条路。第三代理模式与 SDK 模式双形态。你可以把它当 Python 库直接 import 用也可以把它起成一个 HTTP 服务Proxy Server让任何语言的项目通过 HTTP 调用。这个设计非常关键后面会展开讲。2.2 为什么选择统一到 OpenAI 格式而不是自创格式这是 litellm 最聪明的一个决策。市面上已经有无数的工具、框架、客户端是围绕 OpenAI 格式写的——各种聊天界面、各种 Agent 框架、各种评测工具。如果 litellm 自创一套格式那这些生态工具全都用不了它自己就得重新造一遍轮子。而选择对齐 OpenAI 格式意味着 litellm 天然兼容整个 OpenAI 生态。你可以把 litellm 的代理地址填到任何支持自定义 API Base 的工具里瞬间让那个工具支持几十种模型。这个杠杆效应是巨大的。我实测下来很多只支持 OpenAI 的客户端改一个 base_url 就能直接跑 Claude 和本地模型体验非常顺滑。2.3 SDK 模式和代理模式该怎么选这是新手最容易纠结的地方。我的经验是分场景场景推荐模式理由单人 Python 项目快速验证SDK 模式零部署成本import 即用多语言团队协作代理模式任何语言都能通过 HTTP 调用需要统一管理密钥代理模式密钥集中在服务端不下发到客户端需要做限流、计费、日志代理模式中间层可以统一拦截需要精细控制每次调用SDK 模式直接拿到原始对象调试方便我自己的做法是开发阶段用 SDK 模式快速迭代上线前切到代理模式做统一治理。两者可以共存代理服务内部也是用 SDK 实现的。3. 核心细节解析与实操要点3.1 模型命名规则那个斜杠不是随便加的litellm 的 model 字段命名有个固定套路provider/model-name。比如openai/gpt-4o、anthropic/claude-3-5-sonnet-20241022、ollama/llama3.1。这个斜杠前面的 provider 决定了它去调哪家的 SDK。这里有个坑我踩过如果你只写gpt-4o不带前缀litellm 会尝试自动推断但推断逻辑并不总是准确尤其是当模型名字有歧义的时候。所以我的建议是永远显式写全前缀别偷懒。显式写还有一个好处代码可读性强别人一眼就知道你在调哪家。另外不同 provider 的模型名格式不一样。OpenAI 系的一般是gpt-4o、gpt-4o-miniAnthropic 系带日期后缀如claude-3-5-sonnet-20241022本地 ollama 的就是你ollama pull下来的名字。这些细节在切换模型时特别容易搞错建议维护一个自己的模型清单表。3.2 环境变量与密钥管理litellm 读取密钥的方式遵循各家 SDK 的惯例。OpenAI 读OPENAI_API_KEYAnthropic 读ANTHROPIC_API_KEY以此类推。你可以在代码里显式传也可以靠环境变量。我的实操建议是本地开发用 .env 文件生产环境用密钥管理服务。千万别把密钥硬编码在代码里这个不用多说。litellm 支持在调用时传api_key参数也支持在代理配置里集中管理。代理模式下密钥管理更集中。你可以在 config.yaml 里给每个模型配好 key客户端调用时完全不需要知道密钥。这对团队协作特别友好——前端同学不需要拿到任何厂商密钥就能调模型。3.3 参数映射那些不兼容的参数怎么处理不同厂商的参数并不完全一致。比如 OpenAI 有response_formatAnthropic 早期没有Anthropic 有top_kOpenAI 没有。litellm 做了一层参数映射把通用的参数翻译成各家能理解的格式。但映射不是万能的。我遇到过的情况是某些厂商特有的参数litellm 会直接透传或者忽略。这时候你需要查文档确认。我的经验是先用最通用的参数集model、messages、temperature、max_tokens、stream跑通再逐步加厂商特有参数。一上来就堆一堆参数出错了很难定位是哪家不认。还有一个细节max_tokens这个参数在不同厂商的默认值和上限都不一样。有些模型默认输出很短你不显式设置就会截断。我一般会显式设置一个合理的值比如 4096避免输出被莫名截断。3.4 流式输出的处理差异流式输出streamTrue是多模型调用里最容易出问题的地方。虽然 litellm 统一了返回格式但底层各家的流式协议差异很大。OpenAI 是 SSE 格式的 chunkAnthropic 是另一种事件流本地模型的流式实现又各不相同。litellm 把这些都归一化成了 OpenAI 风格的 chunk 对象。你拿到的每个 chunk 都有choices[0].delta.content。这个统一非常省事。但要注意流式模式下错误处理更复杂。如果流到一半底层报错litellm 会抛异常你需要用 try/except 包住整个迭代过程。我踩过的一个坑是某些模型在流式模式下不支持某些参数比如response_format会直接报错。所以流式和非流式最好分开测试别假设它们行为一致。4. 实操过程与核心环节实现4.1 从零搭一个最小可用的 SDK 调用先装包pip install litellm然后写一个最小的调用脚本import litellm import os os.environ[OPENAI_API_KEY] your-key-here response litellm.completion( modelopenai/gpt-4o-mini, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释什么是统一接口层。} ], temperature0.7, max_tokens256 ) print(response.choices[0].message.content)这段代码跑通说明基础环境没问题。注意返回体结构和 OpenAI 完全一致response.choices[0].message.content就是答案。response.usage里还有 token 统计这个后面做成本核算很有用。4.2 切换到不同厂商模型把 model 换掉就行其他代码不动# 切到 Anthropic response litellm.completion( modelanthropic/claude-3-5-sonnet-20241022, messages[{role: user, content: 你好}] ) # 切到本地 ollama response litellm.completion( modelollama/llama3.1, messages[{role: user, content: 你好}], api_basehttp://localhost:11434 )本地模型需要指定api_base指向你本地服务的地址。这个地址根据你的部署方式不同而不同常见的是 11434 端口。实测下来本地模型首次调用会有加载延迟后续就快了。4.3 搭建代理服务代理模式是我更推荐的团队方案。先装带代理功能的版本pip install litellm[proxy]然后写一个 config.yamlmodel_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llama litellm_params: model: ollama/llama3.1 api_base: http://localhost:11434 general_settings: master_key: sk-your-master-key启动服务litellm --config config.yaml --port 4000启动后任何支持 OpenAI 格式的客户端把 base_url 指向http://localhost:4000api_key 填 master_key就能调用上面配置的所有模型。model 字段填gpt-4o-mini、claude-sonnet、local-llama这些你自定义的名字。这个设计的妙处在于模型名和实际后端解耦了。你可以在 config 里把gpt-4o-mini映射到任何后端客户端代码完全不用改。哪天想换模型改 config 重启就行。4.4 参数计算与成本核算做多模型应用成本核算绕不开。litellm 的返回体里有usage字段包含prompt_tokens、completion_tokens、total_tokens。你可以基于这些数据做成本统计。成本计算公式很简单单次成本 prompt_tokens × 输入单价 completion_tokens × 输出单价不同模型单价差异巨大。我一般会在代码里维护一张单价表每次调用后累加。代理模式下litellm 还支持回调callback可以在每次调用后自动记录日志和成本这个功能做监控特别有用。要注意的是流式模式下 usage 可能拿不到。有些厂商在流式返回里不包含 token 统计litellm 会尽量补全但不保证。如果需要精确计费建议非流式调用或者用 litellm 的 token 计数工具单独算。4.5 重试与降级策略生产环境必须考虑容错。litellm 内置了重试机制可以在调用时传num_retriesresponse litellm.completion( modelopenai/gpt-4o-mini, messages[...], num_retries3, timeout30 )num_retries3表示失败后重试 3 次timeout30表示 30 秒超时。这两个参数我建议永远显式设置默认值不一定适合你的场景。更高级的玩法是降级fallback主模型挂了自动切备用模型。litellm 支持在代理配置里设置 fallback 列表。比如主用 GPT-4o挂了自动切 Claude再挂了切本地模型。这个在 config.yaml 里配置客户端无感知。5. 常见问题与排查技巧实录5.1 报错排查速查表报错信息可能原因解决方法AuthenticationError密钥没配或配错检查环境变量名是否正确密钥是否过期NotFoundError模型名写错确认 provider 前缀和模型名拼写RateLimitError触发限流加 num_retries或降低并发ContextWindowExceeded输入超长截断历史消息或换长上下文模型APIConnectionError网络或 api_base 错检查本地服务是否启动地址端口对不对BadRequestError参数不兼容去掉厂商特有参数用通用参数集5.2 那些文档不会写的坑第一个坑环境变量名容易记混。OpenAI 是OPENAI_API_KEYAnthropic 是ANTHROPIC_API_KEY但有些厂商的变量名不直观。我建议在项目里统一用一个 .env 文件管理别靠记忆。第二个坑本地模型的 api_base 必须带协议头。写localhost:11434不行必须写http://localhost:11434。这个细节坑过我好几次。第三个坑代理服务的 master_key 别用默认值。默认的 master_key 是公开的生产环境必须改。而且 master_key 和厂商密钥是两回事别搞混。第四个坑流式输出的异常捕获。流式迭代过程中如果底层报错异常会在迭代时抛出不是在调用时。所以 try/except 要包住整个 for 循环不能只包调用那一行。第五个坑模型名大小写敏感。有些 provider 的模型名是大小写敏感的GPT-4o和gpt-4o可能不一样。统一用小写最保险。5.3 性能优化的几个实操心得并发调用时litellm 本身是同步的但你可以配合 asyncio 用它的异步接口acompletion。实测下来异步版本在高并发场景下吞吐量提升明显。另外代理服务可以开多个 worker 进程来提升并发能力。启动时加--num_workers 4之类的参数。但要注意worker 多了内存占用也上去了根据机器配置权衡。还有一个容易被忽略的点连接复用。频繁调用时底层 HTTP 连接复用能省不少握手开销。litellm 内部用的是 requests 或 httpx默认会复用连接但如果你自己包了一层可能破坏复用。这个在压测时能明显看出来。5.4 日志与可观测性生产环境一定要开日志。litellm 支持多种回调可以把每次调用的模型、耗时、token 数、成本都记录下来。我一般会接一个简单的日志系统把数据存下来做分析。代理模式下--detailed_debug参数可以打印详细日志排查问题时很有用。但生产环境别开日志量太大。我自己的做法是开发环境开详细日志生产环境只记录关键指标模型、耗时、token、成功失败。这样既能排查问题又不会淹没在日志里。6. 进阶玩法与扩展思路6.1 自定义模型接入litellm 支持接入任何兼容 OpenAI 格式的自定义服务。如果你的模型服务暴露的是 OpenAI 兼容接口可以直接用openai/前缀加自定义 api_base 接入。这个能力让 litellm 的适用范围大大扩展——只要你的服务说 OpenAI 的话litellm 就能管。6.2 与 Agent 框架配合很多 Agent 框架底层是调 OpenAI 的。把 litellm 代理地址填进去Agent 瞬间支持多模型。我试过把几个主流 Agent 框架接到 litellm 代理上切换模型只需要改一个配置非常省事。6.3 做模型评测的基座如果你要做模型对比评测litellm 是很好的基座。同一套测试用例循环切换 model 字段就能跑遍所有模型。返回体格式统一评测脚本不用为每个模型写适配。这个用法我在做模型选型时用得最多。6.4 密钥轮换与负载均衡代理模式下同一个模型可以配多个密钥litellm 会自动轮换。这个在密钥有配额限制时特别有用。配置方式是在 model_list 里给同一个 model_name 配多条记录litellm 会做负载均衡。我实测下来这个轮换机制在密钥配额用尽时能自动切到下一个配合重试机制稳定性提升明显。但要注意轮换是随机的还是轮询的取决于配置需要根据场景选择。7. 我个人的一些使用体会用 litellm 这一年多最大的感受是它把多模型调用的复杂度真正降下来了。以前接一个新模型要半天现在改一行配置就行。但工具再好也有边界有几个点我想强调一下。第一别把它当银弹。litellm 抹平的是接口层差异但模型本身的能力差异、参数语义差异、输出风格差异它管不了。切换模型后效果变化那是模型的事不是 litellm 的事。第二代理模式的生产部署要认真对待。它是个服务就有服务的运维要求——进程管理、日志、监控、重启策略一个都不能少。别把它当个脚本随便跑。第三版本升级要谨慎。litellm 迭代很快新版本可能改了行为或参数。升级前先在测试环境验证别直接上生产。最后分享一个小技巧维护一个自己的模型清单文件记录每个模型的 provider 前缀、完整模型名、单价、上下文长度、特殊参数。切换模型时查这个表比翻文档快得多。这个习惯帮我省了大量试错时间。