1. 项目概述与核心定位1.1 这个项目到底解决什么问题第一次接触 litellm 是在一个多模型混用的项目里。当时团队同时接入了好几家不同厂商的大模型服务每家的接口协议、鉴权方式、返回结构都不一样代码里到处是 if-else 分支维护起来非常痛苦。litellm 就是在这个背景下进入视野的——它本质上是一个统一的大模型调用中间层用一套 OpenAI 兼容的接口格式去对接市面上几十种不同的模型服务。说白了它的核心价值就一句话你只需要学会一套调用方式就能切换任意后端模型。不管是商业闭源模型、开源自部署模型还是本地推理服务litellm 都帮你把差异抹平了。这对需要做模型对比、成本优化、故障降级的场景来说价值非常大。它适合谁用我总结下来有三类人最需要一是做 AI 应用开发、需要灵活切换模型的工程师二是做模型评测、要批量跑不同模型对比效果的算法同学三是搭建内部 AI 网关、需要统一管理和计费的平台团队。哪怕你只是个人开发者想在自己的小工具里同时支持几个模型litellm 也能省掉大量适配代码。1.2 核心能力全景litellm 的能力可以分成几个层次来理解。最基础的是SDK 层也就是在 Python 代码里直接import litellm然后像调 OpenAI 一样调其他模型。往上是代理服务层也就是把 litellm 跑成一个 HTTP 服务对外暴露统一的 API 端点任何语言写的客户端都能用。再往上是管理与治理层包括密钥管理、用量统计、预算控制、限流、缓存这些生产环境必需的能力。我画个表把这几层能力对照一下方便你判断自己需要用到哪一层能力层次典型使用方式适用场景复杂度SDK 直调Python 代码内 import脚本、单机应用、快速验证低代理服务启动 HTTP 服务多语言客户端、团队共享中治理能力配置虚拟密钥、预算生产环境、多租户高理解这个分层很重要因为很多人一上来就想把所有能力都用上结果配置复杂到自己都理不清。我的建议是按需渐进先用 SDK 跑通再上代理最后才考虑治理。2. 核心设计思路拆解2.1 为什么选择 OpenAI 格式作为统一标准这是 litellm 最关键的一个设计决策值得单独说说。市面上模型服务那么多为什么偏偏选 OpenAI 的接口格式作为统一标准我的理解有三点原因。第一OpenAI 的接口格式事实上已经成了行业通用语言。绝大多数模型服务商在提供 API 时都会主动兼容 OpenAI 的格式因为这样迁移成本最低。litellm 顺着这个趋势走等于站在了生态的顺风位上。第二请求和响应的数据结构设计得足够通用。messages 数组、role 角色、content 内容这套结构能覆盖绝大多数对话场景扩展性也好。你可以在 content 里塞多模态内容可以用 tool_calls 做函数调用基本够用。第三降低用户的学习成本。开发者本来就会用 OpenAI 的 SDKlitellm 让你几乎不用改代码就能切换后端这个迁移成本几乎为零。我自己从纯 OpenAI 切到 litellm 的时候改动量就是加一行import和改一下模型名前缀。提示虽然 litellm 以 OpenAI 格式为主但它也支持其他格式的转换比如 Anthropic 的原生格式、Cohere 的格式等。不过实际用下来OpenAI 格式的兼容性最好建议优先用它。2.2 模型命名规则的设计逻辑litellm 用一套前缀命名规则来区分不同的模型提供方比如gpt-4走 OpenAIclaude-3-opus走 Anthropicollama/llama3走本地 Ollama。这个设计看起来简单但背后有讲究。前缀的作用是路由。litellm 拿到模型名后先解析前缀确定用哪个 provider 的适配器然后把统一的请求转换成该 provider 需要的格式发出去再把响应转回统一格式。整个过程对调用方透明。这种设计的好处是可扩展。新增一个 provider只要注册一个新的前缀和对应的适配器就行不影响已有逻辑。坏处是命名冲突比如不同厂商可能有同名模型这时候就得靠前缀区分。我踩过一次坑本地部署的模型名和某个商业模型重名了结果路由到了错误的后端排查了半天才发现是命名问题。2.3 配置驱动的治理能力litellm 的代理模式是配置驱动的一个 YAML 文件就能定义模型列表、路由策略、密钥、预算等。这种设计的好处是声明式、可版本化。你可以把配置文件纳入 Git 管理每次变更都有记录回滚也方便。我比较欣赏它的一点是配置和代码分离。模型列表、API 密钥这些经常变的东西放在配置里业务逻辑放在代码里职责清晰。生产环境里运维同学改配置就能调整模型路由不用动代码重新部署这个灵活性很实用。3. 核心细节与实操要点3.1 环境准备与安装安装本身很简单但有几个细节要注意。基础安装用pip install litellm就够了但如果你要用代理模式建议装带 proxy 的完整版pip install litellm[proxy]。这个 extras 会把 FastAPI、Uvicorn 这些依赖一起装上。Python 版本建议 3.9 以上我实测 3.8 也能跑但有些新特性用不了。另外如果你要用本地模型可能还需要装对应的推理框架客户端比如 Ollama 的 Python 包。注意litellm 迭代很快不同版本之间 API 可能有细微差异。生产环境建议锁定版本号别用 latest否则某天自动升级可能出问题。我就遇到过升级后某个参数默认值变了导致行为不一致的情况。3.2 SDK 直调的关键参数SDK 直调是最简单的用法核心就是completion函数。但有几个参数值得展开说。model参数决定路由前面说了前缀规则。messages是对话历史格式和 OpenAI 一致。api_key可以显式传也可以走环境变量。我建议用环境变量管理密钥别硬编码在代码里这是基本的安全习惯。temperature、max_tokens、top_p这些采样参数litellm 会尽量透传给后端。但要注意不是所有后端都支持所有参数。比如某些开源模型不支持top_p传了会被忽略或报错。我一般会先查一下目标模型的文档确认支持哪些参数。还有一个容易被忽略的是timeout和max_retries。生产环境一定要设否则某个后端卡住会拖垮整个请求链路。我一般设 timeout 30 秒retries 2 次配合降级策略使用。3.3 代理服务的配置结构代理模式的配置文件是核心我拆解一下典型结构。顶层一般有model_list、general_settings、litellm_settings这几块。model_list定义可用模型每个条目包含model_name对外暴露的名字和litellm_params实际路由参数。这里有个技巧同一个实际模型可以注册多个 model_name用于不同的路由策略或配额。general_settings管的是服务级配置比如 master key、数据库连接。litellm_settings管的是行为配置比如缓存、降级、回调。我建议配置文件的组织方式是按环境分文件dev、staging、prod 各一份公共部分用 YAML 锚点复用。这样既清晰又不容易出错。3.4 密钥与预算管理生产环境里密钥管理是个绕不开的话题。litellm 支持虚拟密钥也就是给每个调用方发一个虚拟 key背后映射到真实的后端密钥。这样做的好处是真实密钥不暴露给调用方可以随时吊销虚拟 key还能给每个 key 设预算和限流。预算控制是按虚拟 key 维度统计用量的可以设日预算、月预算。超了之后请求会被拒绝。这个功能对多租户场景特别有用能防止某个调用方把额度用光。提示虚拟密钥功能依赖数据库存储用量数据所以要先配好数据库连接。SQLite 适合小规模生产建议用 PostgreSQL。4. 实操过程与核心环节4.1 从零跑通 SDK 调用我带你走一遍完整流程。第一步装包pip install litellm。第二步设环境变量比如OPENAI_API_KEY、ANTHROPIC_API_KEY这些litellm 会自动读取。第三步写代码import litellm response litellm.completion( modelgpt-4, messages[{role: user, content: 你好}], temperature0.7, max_tokens100 ) print(response.choices[0].message.content)这段代码跑通后把model改成claude-3-opus只要对应的环境变量设了就能直接调 Anthropic 的模型代码其他部分不用动。这就是 litellm 的核心体验。4.2 搭建代理服务的完整步骤代理服务稍微复杂点。第一步准备配置文件config.yamlmodel_list: - model_name: gpt-4 litellm_params: model: gpt-4 api_key: os.environ/OPENAI_API_KEY - model_name: claude litellm_params: model: claude-3-opus api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-my-master-key第二步启动服务litellm --config config.yaml --port 4000。第三步用任意 HTTP 客户端调用端点是http://localhost:4000/chat/completions请求格式和 OpenAI 完全一致只是把 base_url 指过来。我实测下来这个流程十分钟能跑通。但生产部署要考虑进程管理、日志、监控这些建议用容器化方式配合健康检查端点。4.3 多模型路由与降级配置降级是 litellm 很实用的一个能力。配置里可以定义 fallbacks比如主模型调用失败时自动切到备用模型litellm_settings: fallbacks: [{gpt-4: [claude, ollama/llama3]}]这个配置的意思是gpt-4 失败时依次尝试 claude 和本地 llama3。实际用下来这个机制能显著提升可用性尤其是依赖外部服务的时候。但要注意降级不是万能的。不同模型的能力差异可能很大降级后返回的结果质量可能下降。我的做法是降级只用于非关键场景关键场景宁可报错让上层处理。4.4 缓存配置与效果验证缓存能省钱也能提速。litellm 支持内存缓存和 Redis 缓存。配置litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379开启后相同的请求会命中缓存直接返回不消耗后端额度。我实测在重复查询场景下命中率能到 40% 以上成本下降明显。但缓存有个坑语义相同但措辞不同的请求不会命中。比如你好和您好是两个不同的 key。所以缓存对精确重复的请求有效对语义相似的不行。如果需要语义缓存得额外接向量检索那是另一套方案了。5. 常见问题与排查技巧5.1 典型报错速查我把踩过的坑整理成表方便你对照排查报错信息常见原因解决思路AuthenticationError密钥没设或设错检查环境变量名是否匹配NotFoundError模型名或前缀写错核对 provider 前缀和模型名RateLimitError触发后端限流配置重试和降级Timeout后端响应慢调大 timeout 或换后端ContextWindowExceeded输入超长截断或换长上下文模型5.2 密钥读取的坑litellm 读环境变量的规则是os.environ/VAR_NAME注意这个写法。我一开始直接写$VAR_NAME结果不生效排查了好久。另外不同 provider 的环境变量名不一样OpenAI 是OPENAI_API_KEYAnthropic 是ANTHROPIC_API_KEY别搞混。还有一个隐蔽的坑环境变量在服务启动时读取。如果你启动后再改环境变量服务不会感知。所以改完密钥要重启服务。5.3 流式输出的处理流式输出streaming在 litellm 里是支持的但处理方式和普通请求不同。返回的是一个迭代器要逐块读取。我见过有人直接把流式响应当普通响应用结果拿到的是空内容。处理流式的正确姿势是遍历迭代器累积 content 片段。另外流式模式下有些统计信息比如 token 用量可能拿不到需要额外配置。5.4 用量统计的准确性用量统计依赖后端返回的 usage 字段。但不是所有后端都返回准确的 usage有些开源模型返回的是估算值甚至不返回。这会导致统计偏差。我的做法是对统计准确性要求高的场景用支持精确 usage 的后端对准确性要求不高的接受估算值。另外litellm 支持自定义回调可以把用量数据推到自己的监控系统做二次校验。6. 生产环境部署经验6.1 性能与并发调优代理服务的性能瓶颈通常在网络 IO 和后端响应速度上。litellm 本身是异步的用 Uvicorn 跑多 worker 能提升并发。我一般设 worker 数为 CPU 核数的 2 倍左右。但要注意worker 多了之后内存缓存不共享。如果用了内存缓存每个 worker 各存各的命中率会下降。这种情况建议用 Redis 做共享缓存。6.2 监控与告警生产环境一定要有监控。litellm 支持多种回调可以把请求日志、用量、延迟推到监控系统。我一般关注几个指标请求成功率、P99 延迟、各模型用量占比、缓存命中率。告警阈值我设的是成功率低于 95% 告警P99 延迟超过 10 秒告警。这两个指标能覆盖大部分异常情况。6.3 安全加固要点安全方面有几个必做的点。第一master key 一定要强别用默认值。第二虚拟密钥要设预算和限流防止滥用。第三代理服务不要直接暴露公网放在内网或加一层网关。第四日志里不要记录完整密钥脱敏处理。我见过有人把代理服务直接暴露公网结果被扫到后疯狂调用账单爆炸。这个教训很深刻安全配置不能省。7. 扩展玩法与个人体会7.1 结合本地模型的混合部署litellm 一个很实用的玩法是混合部署简单请求走本地小模型复杂请求走云端大模型。这样既能控制成本又能保证效果。配置上就是注册两个模型然后在业务层做路由判断。我实测下来把 60% 的简单请求分流到本地模型后云端成本下降了近一半而用户体验基本没受影响。这个策略对成本敏感的场景很值得试。7.2 作为模型评测的基础设施做模型评测的时候litellm 能省很多事。同一套评测代码换个模型名就能跑不同模型结果格式统一方便对比。我一般会写个脚本遍历模型列表批量跑评测集最后汇总成表格。这个用法对算法同学特别友好不用为每个模型写适配代码专注在评测逻辑上就行。7.3 我踩过的几个印象深刻的坑最后分享几个我踩过的坑帮你少走弯路。第一个是模型名前缀遗漏直接写llama3而不是ollama/llama3结果路由失败。第二个是配置文件缩进错误YAML 对缩进敏感一个空格错位就解析失败。第三个是版本升级导致的参数默认值变化升级前一定要看 changelog。这些坑都不难解决但不知道的时候确实会卡很久。希望这些经验能帮你节省时间。litellm 这个工具用熟了之后确实能大幅提升多模型场景的开发效率值得花时间深入掌握。