1. 项目概述与核心定位litellm 这个项目最早是我在做一个多模型路由网关时被同事安利的。当时我们的业务需要同时对接好几家不同厂商的大模型接口每家的 SDK、鉴权方式、请求参数、返回结构都不一样代码里到处是 if-else 分支维护起来非常痛苦。litellm 的出现基本解决了这个痛点——它用一套统一的 OpenAI 格式接口把不同厂商的大模型调用统一封装起来你只需要改一个模型名称字符串就能在多个模型之间切换。简单来说litellm 是一个轻量级的 Python 库同时也可以作为一个代理服务部署。它的核心价值在于统一接口层不管你底层用的是哪家的模型上层业务代码只需要按照 OpenAI 的格式来写剩下的适配工作交给 litellm 处理。这对于需要做模型对比、成本优化、故障降级的团队来说实用性非常高。适合谁来参考这篇内容如果你正在做以下事情litellm 值得花时间研究一是需要在多个大模型之间做动态切换或 A/B 测试二是想统一管理多个厂商的 API Key 和调用配额三是希望在不改动业务代码的前提下快速接入新模型四是需要一套统一的成本追踪和日志记录方案。哪怕你只是个人开发者想在自己的小项目里灵活切换模型litellm 也能帮你省掉大量适配代码。2. 核心架构与设计思路拆解2.1 为什么需要统一接口层在没有 litellm 这类工具之前多模型接入的典型做法是每个厂商写一个适配器类然后在业务层根据配置去选择调用哪个适配器。这种做法的问题在于每接入一个新模型就要新增一个适配器业务层的选择逻辑也要跟着改。更麻烦的是不同厂商的返回结构差异很大有的返回choices[0].message.content有的返回output.text有的甚至直接返回一个字符串。业务层如果直接依赖这些结构后续换模型时改动量会非常大。litellm 的设计思路是在业务代码和厂商 SDK 之间插入一个标准化层。这个层做的事情包括把统一的 OpenAI 格式请求翻译成各厂商的实际请求格式把各厂商的返回结果翻译回 OpenAI 格式统一处理鉴权、重试、超时、错误码映射等横切关注点。这样一来业务代码只需要面向 OpenAI 格式编程底层的差异被完全屏蔽。这个思路其实和数据库领域的 ORM 很像。你写 SQL 的时候不需要关心底层是 MySQL 还是 PostgreSQLORM 帮你做方言转换。litellm 就是大模型调用领域的“ORM”只不过它转换的不是 SQL 方言而是各家 API 的请求和响应格式。2.2 核心模块拆解litellm 的代码结构不算复杂核心模块可以分成几块来理解。第一块是completion 入口。这是最常用的功能对应litellm.completion()方法。你传入模型名称和消息列表它返回一个标准化的响应对象。模型名称的格式通常是厂商前缀/模型标识比如openai/gpt-4o、anthropic/claude-3-5-sonnet、deepseek/deepseek-chat这样的形式。litellm 根据前缀去路由到对应的适配器。第二块是provider 适配器。每个厂商对应一个适配器模块负责把标准请求转换成该厂商的实际请求。适配器里会处理该厂商特有的参数映射比如某些厂商不支持temperature参数适配器就会在转换时忽略或做替代处理。适配器还负责把厂商的返回结果标准化包括 token 用量统计、finish_reason 映射等。第三块是router 路由层。这是 litellm 作为代理服务时的核心组件。Router 支持多种路由策略比如按权重分配、按成本最低优先、按延迟最低优先、按可用性降级等。你可以配置多个部署实例Router 会根据策略自动选择。这个功能在生产环境中非常实用比如你可以配置主模型和备用模型主模型调用失败时自动切换到备用模型。第四块是成本追踪与日志。litellm 内置了成本计算功能会根据模型名称和 token 用量自动计算本次调用的费用。它还支持回调机制可以把调用日志推送到各种可观测性平台。对于需要做成本核算的团队来说这个功能省去了自己维护价格表的麻烦。2.3 部署形态的选择litellm 有两种使用方式选择哪种取决于你的场景。第一种是作为 Python 库直接调用。适合单体应用或者脚本场景你直接在代码里import litellm然后调用completion()方法。这种方式最简单不需要额外部署服务但缺点是每个调用方都需要自己管理 API Key 和配置。第二种是作为代理服务部署。litellm 提供了一个 proxy server你可以把它部署成一个独立的 HTTP 服务所有业务方通过这个代理来调用模型。代理层统一管理 API Key、做访问控制、记录日志、执行路由策略。这种方式适合多团队共用的场景业务方不需要关心底层用的是哪家模型只需要调用代理的统一接口。我个人的建议是如果是个人项目或者小团队直接用库的方式就够了没必要引入额外的服务部署复杂度。如果是公司级别的多团队共用或者需要做精细的成本管控和访问审计那就上代理服务。3. 核心细节解析与实操要点3.1 模型名称的命名规则litellm 的模型名称格式是provider/model_name这个命名规则是整个库的路由基础理解清楚很重要。常见的 provider 前缀包括openai、anthropic、azure、bedrock、vertex_ai、deepseek、mistral、cohere、ollama等。每个前缀对应一个适配器实现。如果你用的是 OpenAI 兼容的第三方服务比如某些国内厂商提供的 OpenAI 兼容接口可以用openai/前缀然后通过api_base参数指定实际的服务地址。这里有个容易踩的坑不同 provider 对模型名称的写法要求不一样。比如 Azure OpenAI 的模型名称需要包含部署名格式是azure/你的部署名而不是直接用模型本身的名称。再比如 Bedrock 的模型名称需要包含区域前缀和版本号格式类似bedrock/anthropic.claude-3-sonnet-20240229-v1:0。这些细节在官方文档里都有说明但第一次配置时很容易搞错。提示如果你不确定某个模型的正确名称格式可以用litellm.model_list查看当前版本支持的所有模型列表或者在代码里调用litellm.get_model_info(模型名称)来验证。3.2 API Key 的配置方式litellm 读取 API Key 的方式遵循环境变量优先的原则。每个 provider 对应一个或多个环境变量名称比如 OpenAI 对应OPENAI_API_KEYAnthropic 对应ANTHROPIC_API_KEYAzure 对应AZURE_API_KEY加上AZURE_API_BASE和AZURE_API_VERSION。你也可以在代码里显式传入比如litellm.completion(modelopenai/gpt-4o, api_keysk-xxx, ...)。但显式传入的方式不利于密钥管理生产环境建议用环境变量或者密钥管理服务。对于代理服务模式litellm 支持在配置文件里定义多个模型和对应的密钥代理层会根据请求中的模型名称自动选择对应的密钥。配置文件通常是一个 YAML 文件结构大致如下model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o 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这种配置方式的好处是业务方只需要知道gpt-4o或claude-sonnet这样的别名不需要关心底层的实际模型名称和密钥。密钥轮换时也只需要改配置文件不需要通知所有业务方。3.3 请求参数的标准化处理litellm 会把 OpenAI 格式的请求参数翻译成各厂商的实际参数。大部分参数是直接映射的比如temperature、max_tokens、top_p这些通用参数。但有些参数在不同厂商之间差异较大需要特别注意。比如max_tokens在 OpenAI 里表示生成的最大 token 数但在某些厂商的接口里叫max_output_tokens或者max_new_tokens。litellm 的适配器会做名称转换你只需要按 OpenAI 的写法传max_tokens就行。再比如stop参数OpenAI 支持传一个字符串或字符串列表但有些厂商只支持单个字符串。litellm 会在适配器里做兼容处理如果厂商只支持单个字符串它会取列表的第一个元素。还有一个容易忽略的点是多模态输入。OpenAI 的格式是用content数组来表示文本和图片的混合输入每个元素有type字段。litellm 会把这种格式转换成各厂商支持的多模态格式。但不同厂商对图片的格式要求不一样有的要求传 URL有的要求传 base64 编码有的对图片尺寸有限制。这些细节在跨厂商切换时容易出问题建议在切换模型前先用小规模请求做验证。3.4 流式输出的处理流式输出是大模型应用中很常见的需求litellm 对流式的支持比较完善。你只需要在调用时传streamTrue返回的就是一个迭代器每次 yield 一个 chunk。但这里有个细节需要注意不同厂商的流式返回格式差异很大。OpenAI 的流式返回是 SSE 格式每个 chunk 是一个 JSON 对象包含choices[0].delta.content。Anthropic 的流式返回格式不同事件类型更多有message_start、content_block_delta、message_stop等多种事件。litellm 会把这些差异统一成 OpenAI 的流式格式你拿到的 chunk 结构是一致的。不过统一格式也意味着某些厂商特有的信息可能会丢失。比如 Anthropic 的流式返回里会包含usage信息但 OpenAI 的流式格式默认不包含 usage。litellm 在转换时会尽量保留这些信息但如果你依赖某些厂商特有的字段建议先测试确认。注意流式模式下litellm 的某些功能比如自动重试可能不会生效因为流式请求一旦开始返回就很难在中途重试。如果你的场景对可靠性要求很高建议在流式外层自己做重试逻辑。4. 实操过程与核心环节实现4.1 环境准备与安装安装 litellm 很简单一条 pip 命令搞定pip install litellm如果你需要用到代理服务功能还需要安装额外的依赖pip install litellm[proxy]安装完成后建议先设置好环境变量。以 OpenAI 和 Anthropic 为例export OPENAI_API_KEY你的密钥 export ANTHROPIC_API_KEY你的密钥如果你用的是其他厂商参考官方文档设置对应的环境变量。环境变量设置好之后可以先跑一个最简单的测试import litellm response litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: 你好请用一句话介绍你自己}] ) print(response.choices[0].message.content)如果这一步能正常返回说明基础环境没问题。如果报错大概率是 API Key 没设置对或者模型名称写错了。4.2 多模型切换的实操演示假设你有一个业务场景需要根据用户的问题类型选择不同的模型。简单问题用便宜的小模型复杂问题用能力强的大模型。用 litellm 实现起来很直接import litellm def ask(question, complexitysimple): if complexity simple: model openai/gpt-4o-mini else: model anthropic/claude-3-5-sonnet-20241022 response litellm.completion( modelmodel, messages[{role: user, content: question}], temperature0.7, max_tokens1024 ) return response.choices[0].message.content这段代码里切换模型只需要改一个字符串。如果你后续想换成 DeepSeek 或者别的模型也只需要改model参数的值其他代码完全不用动。这就是统一接口层的价值。4.3 代理服务的部署与配置如果你决定用代理服务模式部署流程也不复杂。首先创建一个配置文件config.yamlmodel_list: - model_name: fast-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: strong-model litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db然后启动代理服务litellm --config config.yaml --port 4000启动后你就可以像调用 OpenAI 接口一样调用这个代理from openai import OpenAI client OpenAI( api_keysk-your-master-key, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelfast-model, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)注意这里用的是标准的 OpenAI SDK只是把base_url指向了 litellm 代理。业务方完全不需要安装 litellm也不需要知道底层用的是哪家模型。这种解耦程度对于多团队协作来说非常友好。4.4 路由策略的配置litellm 的 Router 支持多种路由策略配置方式是在litellm_params里指定routing_strategy。常见的策略包括策略名称含义适用场景simple-shuffle随机选择多实例负载均衡least-busy选择当前请求数最少的实例避免单实例过载usage-based-routing根据 token 用量选择成本敏感场景latency-based-routing根据历史延迟选择延迟敏感场景cost-based-routing根据成本选择成本优化场景配置示例model_list: - model_name: smart-route litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: smart-route litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY router_settings: routing_strategy: latency-based-routing这个配置定义了两个部署实例都叫smart-route。当业务方请求smart-route时Router 会根据延迟策略选择当前延迟较低的实例。如果某个实例调用失败Router 会自动重试另一个实例。这种配置在生产环境中很实用可以在不中断服务的情况下做模型切换和灰度发布。4.5 成本追踪的实操litellm 内置了成本计算功能每次调用后可以通过response._hidden_params或者回调函数获取本次调用的成本。更常用的方式是在代理服务里开启成本追踪然后在数据库里查看统计。配置文件中开启成本追踪general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db cost_tracking: true开启后每次调用的 token 用量和费用都会记录到数据库。你可以通过代理的管理接口查询统计信息也可以直接查数据库。对于需要做成本分摊的团队来说这个功能可以省去自己维护价格表和计算逻辑的工作量。提示litellm 的成本计算依赖内置的价格表如果某个模型的价格有变动或者你用的是自定义价格的模型需要手动更新价格配置。建议定期检查成本统计的准确性。5. 常见问题与排查技巧实录5.1 模型名称报错怎么排查最常见的报错是litellm.exceptions.BadRequestError或者Invalid model name。遇到这种报错按以下顺序排查第一步确认模型名称格式是否正确。必须是provider/model_name的形式provider 前缀要在 litellm 支持的列表里。你可以用litellm.model_list查看支持的模型列表。第二步确认该 provider 的 API Key 是否设置。如果环境变量没设置litellm 会报鉴权错误。你可以用litellm.get_model_info(模型名称)来验证模型信息是否能正常获取。第三步如果是 Azure 或 Bedrock 这类需要额外配置的 provider确认api_base、api_version、region等参数是否设置正确。这些 provider 的配置项比较多容易遗漏。5.2 超时和重试的配置litellm 默认的超时时间可能不适合所有场景。你可以在调用时传timeout参数也可以在全局设置里配置import litellm litellm.request_timeout 60 # 全局超时60秒 litellm.num_retries 3 # 全局重试3次对于代理服务模式可以在配置文件里设置litellm_settings: request_timeout: 60 num_retries: 3 retry_after: 5这里有个经验重试次数不是越多越好。如果某个模型服务本身不可用重试太多次只会增加延迟。建议根据业务场景设置合理的重试次数一般 2 到 3 次就够了。另外对于流式请求重试可能不会生效需要在业务层自己做处理。5.3 常见报错速查表报错信息可能原因解决方法AuthenticationErrorAPI Key 未设置或错误检查环境变量或配置文件中的密钥BadRequestError模型名称格式错误或参数不合法检查模型名称格式确认参数在支持范围内RateLimitError触发厂商的速率限制降低请求频率或配置多个部署实例做负载均衡Timeout请求超时增加 timeout 配置或检查网络连接ContextWindowExceeded输入 token 超过模型上限截断输入或换用上下文窗口更大的模型ContentPolicyViolation内容触发了厂商的安全策略调整输入内容或换用策略更宽松的模型5.4 几个容易踩的坑第一个坑是环境变量命名不一致。不同 provider 的环境变量名称不一样有的用_API_KEY后缀有的用_KEY后缀有的还需要额外的_BASE和_VERSION。建议在项目里统一用.env文件管理避免手动设置时遗漏。第二个坑是代理服务的数据库迁移。litellm 代理服务用数据库存储配置和日志版本升级时可能需要做数据库迁移。建议在升级前先备份数据库并查看官方文档的升级说明。第三个坑是流式模式下的 usage 统计。某些 provider 在流式模式下不返回 usage 信息导致成本统计不准确。如果成本统计对你很重要建议在流式请求结束后额外发一个非流式请求来获取 usage或者使用 provider 提供的 usage 查询接口。第四个坑是多模态输入的格式兼容。不同厂商对图片输入的格式要求不同有的要求 URL有的要求 base64有的对图片格式和尺寸有限制。在跨厂商切换时建议先用小规模请求验证多模态输入是否能正常工作。5.5 性能优化的几个方向如果你发现 litellm 的调用延迟比较高可以从几个方向优化。一是连接复用。litellm 底层用的是 HTTP 客户端默认会复用连接。但如果你在代码里频繁创建新的客户端实例连接复用可能不会生效。建议在应用启动时创建一个全局的客户端实例后续调用都复用这个实例。二是并发控制。litellm 支持异步调用用acompletion()方法可以在异步框架里并发调用多个模型。但要注意控制并发数避免触发厂商的速率限制。三是缓存。litellm 支持缓存功能可以把相同请求的响应缓存起来避免重复调用。对于某些确定性较高的场景比如 temperature 设为 0缓存可以显著降低成本和延迟。配置方式是在调用时传cachingTrue或者全局开启缓存。import litellm litellm.cache litellm.Cache(typelocal) response litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}], cachingTrue )缓存虽然好用但要注意缓存的失效策略。如果模型更新了或者你的 prompt 模板变了缓存可能会导致返回旧结果。建议在关键场景下谨慎使用缓存或者设置合理的缓存过期时间。6. 扩展玩法与进阶思路6.1 自定义 Provider 适配器litellm 虽然支持很多 provider但总有一些小众的或者自建的模型服务不在支持列表里。这种情况下你可以自己写一个适配器。litellm 的适配器接口比较清晰核心是实现请求转换和响应转换两个方法。自定义适配器的基本步骤是继承BaseLLM类实现completion()方法在里面处理请求转换和响应标准化。然后在litellm的 provider 注册表里注册你的适配器。这样你就可以用custom/your-model这样的名称来调用自建服务了。这个功能对于有自建模型服务的团队来说很实用。你可以把自建服务和第三方模型统一到同一个接口下业务方不需要区分调用的是哪个。6.2 与可观测性平台的集成litellm 支持多种回调机制可以把调用日志推送到各种可观测性平台。常见的集成方式包括推送到日志服务、推送到指标监控系统、推送到链路追踪系统。配置方式是在litellm_settings里设置success_callback和failure_callbacklitellm_settings: success_callback: [custom_callback] failure_callback: [custom_callback]你也可以自己写回调函数在函数里做自定义的日志处理。比如记录每次调用的模型名称、token 用量、延迟、成本等信息然后推送到你的监控系统。这对于做模型性能对比和成本分析很有帮助。6.3 多租户场景下的权限控制如果你用 litellm 代理服务给多个团队或客户提供服务权限控制是一个需要考虑的问题。litellm 支持基于 API Key 的权限控制你可以为每个租户分配不同的 Key并限制他们可以访问的模型和调用配额。配置方式是在数据库里创建虚拟 Key并设置models和max_budget等字段。这样每个租户只能访问被授权的模型超出配额后会被拒绝。对于 SaaS 类产品来说这个功能可以省去自己实现权限系统的工作量。6.4 模型降级与故障转移生产环境中最怕的就是某个模型服务突然不可用。litellm 的 Router 支持故障转移配置你可以设置主模型和备用模型主模型调用失败时自动切换到备用模型。配置示例model_list: - model_name: primary litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: fallback litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY router_settings: fallbacks: [{primary: [fallback]}]这个配置表示当primary调用失败时自动降级到fallback。对于可用性要求高的场景这种配置可以显著降低服务中断的风险。不过要注意不同模型的能力和输出风格可能不同降级后的结果可能和主模型有差异需要在业务层做兼容处理。6.5 本地模型与云端模型的统一调用litellm 也支持本地部署的模型比如通过 Ollama 或者 vLLM 部署的模型。你只需要把 provider 前缀设为ollama或openaivLLM 兼容 OpenAI 接口然后指定api_base为本地服务地址即可。这样一来你就可以在同一个接口下同时调用本地模型和云端模型。对于某些对数据隐私要求高的场景可以把敏感请求路由到本地模型非敏感请求路由到云端模型。这种混合部署的方式在成本和合规之间找到了一个平衡点。# 调用本地 Ollama 模型 response litellm.completion( modelollama/llama3, messages[{role: user, content: 你好}], api_basehttp://localhost:11434 ) # 调用云端模型 response litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}] )两种调用的代码结构完全一致只是模型名称和api_base不同。这种统一性对于需要灵活切换部署方式的团队来说非常方便。6.6 批量请求与异步处理如果你的场景需要批量调用模型比如对一批文档做摘要或者分类litellm 的异步接口可以显著提升效率。用acompletion()配合asyncio.gather()可以并发处理多个请求。import asyncio import litellm async def process_one(text): response await litellm.acompletion( modelopenai/gpt-4o-mini, messages[{role: user, content: f请摘要{text}}] ) return response.choices[0].message.content async def process_batch(texts): tasks [process_one(t) for t in texts] results await asyncio.gather(*tasks) return results这种方式的效率比串行调用高很多但要注意控制并发数。如果并发太高可能会触发厂商的速率限制。建议用asyncio.Semaphore来控制并发数或者用 litellm 内置的批量接口。提示批量请求时建议开启重试和错误处理避免单个请求失败导致整个批次中断。litellm 的acompletion()支持num_retries参数可以在请求失败时自动重试。7. 个人实操体会与建议我在多个项目里用过 litellm踩过一些坑也总结了一些经验。最大的体会是litellm 的价值不在于它支持多少模型而在于它把多模型调用的复杂度收敛到了一个统一的接口层。在没有它之前每接一个新模型都要写适配代码、改业务逻辑、重新测试。有了它之后接入新模型的成本从“天”级别降到了“分钟”级别。另一个体会是代理服务模式虽然功能强大但不要为了用而用。如果你的场景只是单应用调用几个模型直接用库的方式就够了。代理服务引入了额外的部署复杂度和运维成本只有在多团队共用、需要精细权限控制和成本审计的场景下才值得上。还有一个建议是在生产环境使用前一定要做充分的测试。不同厂商的模型在参数支持、返回格式、错误码、速率限制等方面都有差异litellm 虽然做了统一但不可能覆盖所有边界情况。建议在切换模型或升级 litellm 版本前先用小规模流量做验证确认没有兼容性问题后再全量切换。最后分享一个小技巧如果你不确定某个模型是否支持某个参数可以在调用时传drop_paramsTruelitellm 会自动忽略该模型不支持的参数而不是报错。这个参数在跨模型切换时特别有用可以避免因为参数不兼容导致的调用失败。response litellm.completion( modelanthropic/claude-3-5-sonnet-20241022, messages[{role: user, content: 你好}], temperature0.7, drop_paramsTrue # 自动忽略不支持的参数 )这个参数虽然方便但也要注意忽略参数可能会导致模型行为和你预期的不一致。比如某个模型不支持temperature忽略后它会用默认值可能和你想要的效果有差异。所以建议在开发阶段先确认参数支持情况生产环境再决定是否开启drop_params。
1. 项目概述与核心定位litellm 这个项目最早是我在做一个多模型路由网关时被同事安利的。当时我们的业务需要同时对接好几家不同厂商的大模型接口每家的 SDK、鉴权方式、请求参数、返回结构都不一样代码里到处是 if-else 分支维护起来非常痛苦。litellm 的出现基本解决了这个痛点——它用一套统一的 OpenAI 格式接口把不同厂商的大模型调用统一封装起来你只需要改一个模型名称字符串就能在多个模型之间切换。简单来说litellm 是一个轻量级的 Python 库同时也可以作为一个代理服务部署。它的核心价值在于统一接口层不管你底层用的是哪家的模型上层业务代码只需要按照 OpenAI 的格式来写剩下的适配工作交给 litellm 处理。这对于需要做模型对比、成本优化、故障降级的团队来说实用性非常高。适合谁来参考这篇内容如果你正在做以下事情litellm 值得花时间研究一是需要在多个大模型之间做动态切换或 A/B 测试二是想统一管理多个厂商的 API Key 和调用配额三是希望在不改动业务代码的前提下快速接入新模型四是需要一套统一的成本追踪和日志记录方案。哪怕你只是个人开发者想在自己的小项目里灵活切换模型litellm 也能帮你省掉大量适配代码。2. 核心架构与设计思路拆解2.1 为什么需要统一接口层在没有 litellm 这类工具之前多模型接入的典型做法是每个厂商写一个适配器类然后在业务层根据配置去选择调用哪个适配器。这种做法的问题在于每接入一个新模型就要新增一个适配器业务层的选择逻辑也要跟着改。更麻烦的是不同厂商的返回结构差异很大有的返回choices[0].message.content有的返回output.text有的甚至直接返回一个字符串。业务层如果直接依赖这些结构后续换模型时改动量会非常大。litellm 的设计思路是在业务代码和厂商 SDK 之间插入一个标准化层。这个层做的事情包括把统一的 OpenAI 格式请求翻译成各厂商的实际请求格式把各厂商的返回结果翻译回 OpenAI 格式统一处理鉴权、重试、超时、错误码映射等横切关注点。这样一来业务代码只需要面向 OpenAI 格式编程底层的差异被完全屏蔽。这个思路其实和数据库领域的 ORM 很像。你写 SQL 的时候不需要关心底层是 MySQL 还是 PostgreSQLORM 帮你做方言转换。litellm 就是大模型调用领域的“ORM”只不过它转换的不是 SQL 方言而是各家 API 的请求和响应格式。2.2 核心模块拆解litellm 的代码结构不算复杂核心模块可以分成几块来理解。第一块是completion 入口。这是最常用的功能对应litellm.completion()方法。你传入模型名称和消息列表它返回一个标准化的响应对象。模型名称的格式通常是厂商前缀/模型标识比如openai/gpt-4o、anthropic/claude-3-5-sonnet、deepseek/deepseek-chat这样的形式。litellm 根据前缀去路由到对应的适配器。第二块是provider 适配器。每个厂商对应一个适配器模块负责把标准请求转换成该厂商的实际请求。适配器里会处理该厂商特有的参数映射比如某些厂商不支持temperature参数适配器就会在转换时忽略或做替代处理。适配器还负责把厂商的返回结果标准化包括 token 用量统计、finish_reason 映射等。第三块是router 路由层。这是 litellm 作为代理服务时的核心组件。Router 支持多种路由策略比如按权重分配、按成本最低优先、按延迟最低优先、按可用性降级等。你可以配置多个部署实例Router 会根据策略自动选择。这个功能在生产环境中非常实用比如你可以配置主模型和备用模型主模型调用失败时自动切换到备用模型。第四块是成本追踪与日志。litellm 内置了成本计算功能会根据模型名称和 token 用量自动计算本次调用的费用。它还支持回调机制可以把调用日志推送到各种可观测性平台。对于需要做成本核算的团队来说这个功能省去了自己维护价格表的麻烦。2.3 部署形态的选择litellm 有两种使用方式选择哪种取决于你的场景。第一种是作为 Python 库直接调用。适合单体应用或者脚本场景你直接在代码里import litellm然后调用completion()方法。这种方式最简单不需要额外部署服务但缺点是每个调用方都需要自己管理 API Key 和配置。第二种是作为代理服务部署。litellm 提供了一个 proxy server你可以把它部署成一个独立的 HTTP 服务所有业务方通过这个代理来调用模型。代理层统一管理 API Key、做访问控制、记录日志、执行路由策略。这种方式适合多团队共用的场景业务方不需要关心底层用的是哪家模型只需要调用代理的统一接口。我个人的建议是如果是个人项目或者小团队直接用库的方式就够了没必要引入额外的服务部署复杂度。如果是公司级别的多团队共用或者需要做精细的成本管控和访问审计那就上代理服务。3. 核心细节解析与实操要点3.1 模型名称的命名规则litellm 的模型名称格式是provider/model_name这个命名规则是整个库的路由基础理解清楚很重要。常见的 provider 前缀包括openai、anthropic、azure、bedrock、vertex_ai、deepseek、mistral、cohere、ollama等。每个前缀对应一个适配器实现。如果你用的是 OpenAI 兼容的第三方服务比如某些国内厂商提供的 OpenAI 兼容接口可以用openai/前缀然后通过api_base参数指定实际的服务地址。这里有个容易踩的坑不同 provider 对模型名称的写法要求不一样。比如 Azure OpenAI 的模型名称需要包含部署名格式是azure/你的部署名而不是直接用模型本身的名称。再比如 Bedrock 的模型名称需要包含区域前缀和版本号格式类似bedrock/anthropic.claude-3-sonnet-20240229-v1:0。这些细节在官方文档里都有说明但第一次配置时很容易搞错。提示如果你不确定某个模型的正确名称格式可以用litellm.model_list查看当前版本支持的所有模型列表或者在代码里调用litellm.get_model_info(模型名称)来验证。3.2 API Key 的配置方式litellm 读取 API Key 的方式遵循环境变量优先的原则。每个 provider 对应一个或多个环境变量名称比如 OpenAI 对应OPENAI_API_KEYAnthropic 对应ANTHROPIC_API_KEYAzure 对应AZURE_API_KEY加上AZURE_API_BASE和AZURE_API_VERSION。你也可以在代码里显式传入比如litellm.completion(modelopenai/gpt-4o, api_keysk-xxx, ...)。但显式传入的方式不利于密钥管理生产环境建议用环境变量或者密钥管理服务。对于代理服务模式litellm 支持在配置文件里定义多个模型和对应的密钥代理层会根据请求中的模型名称自动选择对应的密钥。配置文件通常是一个 YAML 文件结构大致如下model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o 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这种配置方式的好处是业务方只需要知道gpt-4o或claude-sonnet这样的别名不需要关心底层的实际模型名称和密钥。密钥轮换时也只需要改配置文件不需要通知所有业务方。3.3 请求参数的标准化处理litellm 会把 OpenAI 格式的请求参数翻译成各厂商的实际参数。大部分参数是直接映射的比如temperature、max_tokens、top_p这些通用参数。但有些参数在不同厂商之间差异较大需要特别注意。比如max_tokens在 OpenAI 里表示生成的最大 token 数但在某些厂商的接口里叫max_output_tokens或者max_new_tokens。litellm 的适配器会做名称转换你只需要按 OpenAI 的写法传max_tokens就行。再比如stop参数OpenAI 支持传一个字符串或字符串列表但有些厂商只支持单个字符串。litellm 会在适配器里做兼容处理如果厂商只支持单个字符串它会取列表的第一个元素。还有一个容易忽略的点是多模态输入。OpenAI 的格式是用content数组来表示文本和图片的混合输入每个元素有type字段。litellm 会把这种格式转换成各厂商支持的多模态格式。但不同厂商对图片的格式要求不一样有的要求传 URL有的要求传 base64 编码有的对图片尺寸有限制。这些细节在跨厂商切换时容易出问题建议在切换模型前先用小规模请求做验证。3.4 流式输出的处理流式输出是大模型应用中很常见的需求litellm 对流式的支持比较完善。你只需要在调用时传streamTrue返回的就是一个迭代器每次 yield 一个 chunk。但这里有个细节需要注意不同厂商的流式返回格式差异很大。OpenAI 的流式返回是 SSE 格式每个 chunk 是一个 JSON 对象包含choices[0].delta.content。Anthropic 的流式返回格式不同事件类型更多有message_start、content_block_delta、message_stop等多种事件。litellm 会把这些差异统一成 OpenAI 的流式格式你拿到的 chunk 结构是一致的。不过统一格式也意味着某些厂商特有的信息可能会丢失。比如 Anthropic 的流式返回里会包含usage信息但 OpenAI 的流式格式默认不包含 usage。litellm 在转换时会尽量保留这些信息但如果你依赖某些厂商特有的字段建议先测试确认。注意流式模式下litellm 的某些功能比如自动重试可能不会生效因为流式请求一旦开始返回就很难在中途重试。如果你的场景对可靠性要求很高建议在流式外层自己做重试逻辑。4. 实操过程与核心环节实现4.1 环境准备与安装安装 litellm 很简单一条 pip 命令搞定pip install litellm如果你需要用到代理服务功能还需要安装额外的依赖pip install litellm[proxy]安装完成后建议先设置好环境变量。以 OpenAI 和 Anthropic 为例export OPENAI_API_KEY你的密钥 export ANTHROPIC_API_KEY你的密钥如果你用的是其他厂商参考官方文档设置对应的环境变量。环境变量设置好之后可以先跑一个最简单的测试import litellm response litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: 你好请用一句话介绍你自己}] ) print(response.choices[0].message.content)如果这一步能正常返回说明基础环境没问题。如果报错大概率是 API Key 没设置对或者模型名称写错了。4.2 多模型切换的实操演示假设你有一个业务场景需要根据用户的问题类型选择不同的模型。简单问题用便宜的小模型复杂问题用能力强的大模型。用 litellm 实现起来很直接import litellm def ask(question, complexitysimple): if complexity simple: model openai/gpt-4o-mini else: model anthropic/claude-3-5-sonnet-20241022 response litellm.completion( modelmodel, messages[{role: user, content: question}], temperature0.7, max_tokens1024 ) return response.choices[0].message.content这段代码里切换模型只需要改一个字符串。如果你后续想换成 DeepSeek 或者别的模型也只需要改model参数的值其他代码完全不用动。这就是统一接口层的价值。4.3 代理服务的部署与配置如果你决定用代理服务模式部署流程也不复杂。首先创建一个配置文件config.yamlmodel_list: - model_name: fast-model litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: strong-model litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db然后启动代理服务litellm --config config.yaml --port 4000启动后你就可以像调用 OpenAI 接口一样调用这个代理from openai import OpenAI client OpenAI( api_keysk-your-master-key, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelfast-model, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)注意这里用的是标准的 OpenAI SDK只是把base_url指向了 litellm 代理。业务方完全不需要安装 litellm也不需要知道底层用的是哪家模型。这种解耦程度对于多团队协作来说非常友好。4.4 路由策略的配置litellm 的 Router 支持多种路由策略配置方式是在litellm_params里指定routing_strategy。常见的策略包括策略名称含义适用场景simple-shuffle随机选择多实例负载均衡least-busy选择当前请求数最少的实例避免单实例过载usage-based-routing根据 token 用量选择成本敏感场景latency-based-routing根据历史延迟选择延迟敏感场景cost-based-routing根据成本选择成本优化场景配置示例model_list: - model_name: smart-route litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: smart-route litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY router_settings: routing_strategy: latency-based-routing这个配置定义了两个部署实例都叫smart-route。当业务方请求smart-route时Router 会根据延迟策略选择当前延迟较低的实例。如果某个实例调用失败Router 会自动重试另一个实例。这种配置在生产环境中很实用可以在不中断服务的情况下做模型切换和灰度发布。4.5 成本追踪的实操litellm 内置了成本计算功能每次调用后可以通过response._hidden_params或者回调函数获取本次调用的成本。更常用的方式是在代理服务里开启成本追踪然后在数据库里查看统计。配置文件中开启成本追踪general_settings: master_key: sk-your-master-key database_url: sqlite:///litellm.db cost_tracking: true开启后每次调用的 token 用量和费用都会记录到数据库。你可以通过代理的管理接口查询统计信息也可以直接查数据库。对于需要做成本分摊的团队来说这个功能可以省去自己维护价格表和计算逻辑的工作量。提示litellm 的成本计算依赖内置的价格表如果某个模型的价格有变动或者你用的是自定义价格的模型需要手动更新价格配置。建议定期检查成本统计的准确性。5. 常见问题与排查技巧实录5.1 模型名称报错怎么排查最常见的报错是litellm.exceptions.BadRequestError或者Invalid model name。遇到这种报错按以下顺序排查第一步确认模型名称格式是否正确。必须是provider/model_name的形式provider 前缀要在 litellm 支持的列表里。你可以用litellm.model_list查看支持的模型列表。第二步确认该 provider 的 API Key 是否设置。如果环境变量没设置litellm 会报鉴权错误。你可以用litellm.get_model_info(模型名称)来验证模型信息是否能正常获取。第三步如果是 Azure 或 Bedrock 这类需要额外配置的 provider确认api_base、api_version、region等参数是否设置正确。这些 provider 的配置项比较多容易遗漏。5.2 超时和重试的配置litellm 默认的超时时间可能不适合所有场景。你可以在调用时传timeout参数也可以在全局设置里配置import litellm litellm.request_timeout 60 # 全局超时60秒 litellm.num_retries 3 # 全局重试3次对于代理服务模式可以在配置文件里设置litellm_settings: request_timeout: 60 num_retries: 3 retry_after: 5这里有个经验重试次数不是越多越好。如果某个模型服务本身不可用重试太多次只会增加延迟。建议根据业务场景设置合理的重试次数一般 2 到 3 次就够了。另外对于流式请求重试可能不会生效需要在业务层自己做处理。5.3 常见报错速查表报错信息可能原因解决方法AuthenticationErrorAPI Key 未设置或错误检查环境变量或配置文件中的密钥BadRequestError模型名称格式错误或参数不合法检查模型名称格式确认参数在支持范围内RateLimitError触发厂商的速率限制降低请求频率或配置多个部署实例做负载均衡Timeout请求超时增加 timeout 配置或检查网络连接ContextWindowExceeded输入 token 超过模型上限截断输入或换用上下文窗口更大的模型ContentPolicyViolation内容触发了厂商的安全策略调整输入内容或换用策略更宽松的模型5.4 几个容易踩的坑第一个坑是环境变量命名不一致。不同 provider 的环境变量名称不一样有的用_API_KEY后缀有的用_KEY后缀有的还需要额外的_BASE和_VERSION。建议在项目里统一用.env文件管理避免手动设置时遗漏。第二个坑是代理服务的数据库迁移。litellm 代理服务用数据库存储配置和日志版本升级时可能需要做数据库迁移。建议在升级前先备份数据库并查看官方文档的升级说明。第三个坑是流式模式下的 usage 统计。某些 provider 在流式模式下不返回 usage 信息导致成本统计不准确。如果成本统计对你很重要建议在流式请求结束后额外发一个非流式请求来获取 usage或者使用 provider 提供的 usage 查询接口。第四个坑是多模态输入的格式兼容。不同厂商对图片输入的格式要求不同有的要求 URL有的要求 base64有的对图片格式和尺寸有限制。在跨厂商切换时建议先用小规模请求验证多模态输入是否能正常工作。5.5 性能优化的几个方向如果你发现 litellm 的调用延迟比较高可以从几个方向优化。一是连接复用。litellm 底层用的是 HTTP 客户端默认会复用连接。但如果你在代码里频繁创建新的客户端实例连接复用可能不会生效。建议在应用启动时创建一个全局的客户端实例后续调用都复用这个实例。二是并发控制。litellm 支持异步调用用acompletion()方法可以在异步框架里并发调用多个模型。但要注意控制并发数避免触发厂商的速率限制。三是缓存。litellm 支持缓存功能可以把相同请求的响应缓存起来避免重复调用。对于某些确定性较高的场景比如 temperature 设为 0缓存可以显著降低成本和延迟。配置方式是在调用时传cachingTrue或者全局开启缓存。import litellm litellm.cache litellm.Cache(typelocal) response litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}], cachingTrue )缓存虽然好用但要注意缓存的失效策略。如果模型更新了或者你的 prompt 模板变了缓存可能会导致返回旧结果。建议在关键场景下谨慎使用缓存或者设置合理的缓存过期时间。6. 扩展玩法与进阶思路6.1 自定义 Provider 适配器litellm 虽然支持很多 provider但总有一些小众的或者自建的模型服务不在支持列表里。这种情况下你可以自己写一个适配器。litellm 的适配器接口比较清晰核心是实现请求转换和响应转换两个方法。自定义适配器的基本步骤是继承BaseLLM类实现completion()方法在里面处理请求转换和响应标准化。然后在litellm的 provider 注册表里注册你的适配器。这样你就可以用custom/your-model这样的名称来调用自建服务了。这个功能对于有自建模型服务的团队来说很实用。你可以把自建服务和第三方模型统一到同一个接口下业务方不需要区分调用的是哪个。6.2 与可观测性平台的集成litellm 支持多种回调机制可以把调用日志推送到各种可观测性平台。常见的集成方式包括推送到日志服务、推送到指标监控系统、推送到链路追踪系统。配置方式是在litellm_settings里设置success_callback和failure_callbacklitellm_settings: success_callback: [custom_callback] failure_callback: [custom_callback]你也可以自己写回调函数在函数里做自定义的日志处理。比如记录每次调用的模型名称、token 用量、延迟、成本等信息然后推送到你的监控系统。这对于做模型性能对比和成本分析很有帮助。6.3 多租户场景下的权限控制如果你用 litellm 代理服务给多个团队或客户提供服务权限控制是一个需要考虑的问题。litellm 支持基于 API Key 的权限控制你可以为每个租户分配不同的 Key并限制他们可以访问的模型和调用配额。配置方式是在数据库里创建虚拟 Key并设置models和max_budget等字段。这样每个租户只能访问被授权的模型超出配额后会被拒绝。对于 SaaS 类产品来说这个功能可以省去自己实现权限系统的工作量。6.4 模型降级与故障转移生产环境中最怕的就是某个模型服务突然不可用。litellm 的 Router 支持故障转移配置你可以设置主模型和备用模型主模型调用失败时自动切换到备用模型。配置示例model_list: - model_name: primary litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: fallback litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY router_settings: fallbacks: [{primary: [fallback]}]这个配置表示当primary调用失败时自动降级到fallback。对于可用性要求高的场景这种配置可以显著降低服务中断的风险。不过要注意不同模型的能力和输出风格可能不同降级后的结果可能和主模型有差异需要在业务层做兼容处理。6.5 本地模型与云端模型的统一调用litellm 也支持本地部署的模型比如通过 Ollama 或者 vLLM 部署的模型。你只需要把 provider 前缀设为ollama或openaivLLM 兼容 OpenAI 接口然后指定api_base为本地服务地址即可。这样一来你就可以在同一个接口下同时调用本地模型和云端模型。对于某些对数据隐私要求高的场景可以把敏感请求路由到本地模型非敏感请求路由到云端模型。这种混合部署的方式在成本和合规之间找到了一个平衡点。# 调用本地 Ollama 模型 response litellm.completion( modelollama/llama3, messages[{role: user, content: 你好}], api_basehttp://localhost:11434 ) # 调用云端模型 response litellm.completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}] )两种调用的代码结构完全一致只是模型名称和api_base不同。这种统一性对于需要灵活切换部署方式的团队来说非常方便。6.6 批量请求与异步处理如果你的场景需要批量调用模型比如对一批文档做摘要或者分类litellm 的异步接口可以显著提升效率。用acompletion()配合asyncio.gather()可以并发处理多个请求。import asyncio import litellm async def process_one(text): response await litellm.acompletion( modelopenai/gpt-4o-mini, messages[{role: user, content: f请摘要{text}}] ) return response.choices[0].message.content async def process_batch(texts): tasks [process_one(t) for t in texts] results await asyncio.gather(*tasks) return results这种方式的效率比串行调用高很多但要注意控制并发数。如果并发太高可能会触发厂商的速率限制。建议用asyncio.Semaphore来控制并发数或者用 litellm 内置的批量接口。提示批量请求时建议开启重试和错误处理避免单个请求失败导致整个批次中断。litellm 的acompletion()支持num_retries参数可以在请求失败时自动重试。7. 个人实操体会与建议我在多个项目里用过 litellm踩过一些坑也总结了一些经验。最大的体会是litellm 的价值不在于它支持多少模型而在于它把多模型调用的复杂度收敛到了一个统一的接口层。在没有它之前每接一个新模型都要写适配代码、改业务逻辑、重新测试。有了它之后接入新模型的成本从“天”级别降到了“分钟”级别。另一个体会是代理服务模式虽然功能强大但不要为了用而用。如果你的场景只是单应用调用几个模型直接用库的方式就够了。代理服务引入了额外的部署复杂度和运维成本只有在多团队共用、需要精细权限控制和成本审计的场景下才值得上。还有一个建议是在生产环境使用前一定要做充分的测试。不同厂商的模型在参数支持、返回格式、错误码、速率限制等方面都有差异litellm 虽然做了统一但不可能覆盖所有边界情况。建议在切换模型或升级 litellm 版本前先用小规模流量做验证确认没有兼容性问题后再全量切换。最后分享一个小技巧如果你不确定某个模型是否支持某个参数可以在调用时传drop_paramsTruelitellm 会自动忽略该模型不支持的参数而不是报错。这个参数在跨模型切换时特别有用可以避免因为参数不兼容导致的调用失败。response litellm.completion( modelanthropic/claude-3-5-sonnet-20241022, messages[{role: user, content: 你好}], temperature0.7, drop_paramsTrue # 自动忽略不支持的参数 )这个参数虽然方便但也要注意忽略参数可能会导致模型行为和你预期的不一致。比如某个模型不支持temperature忽略后它会用默认值可能和你想要的效果有差异。所以建议在开发阶段先确认参数支持情况生产环境再决定是否开启drop_params。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
