1. 项目概述与核心定位litellm 这个项目第一次接触是在一个多模型混用的场景里。当时团队需要同时对接好几家不同厂商的大模型接口每家的 SDK、鉴权方式、请求格式、返回结构都不一样代码里到处是 if-else 分支维护成本高得离谱。后来有人推荐了 litellm用下来确实解决了不少痛点。简单说litellm 是一个统一的大模型调用层它把不同厂商的 API 抽象成一套标准的 OpenAI 兼容格式让你用同一套代码就能调用多种模型。这个项目能做什么核心就一件事抹平不同大模型服务商之间的接口差异。你不需要为每个厂商单独写适配代码也不需要记住每家的参数命名规则。litellm 提供了一层代理和 SDK对外暴露统一的接口对内帮你转发到实际的后端模型。它解决的问题很明确——多模型切换成本高、代码耦合严重、迁移困难。适合谁来参考如果你正在做 AI 应用开发尤其是需要对比不同模型效果、做 A/B 测试、或者给用户提供多模型选择的场景litellm 值得花时间研究。哪怕你只是想在本地快速切换几个模型跑跑实验它也能省掉大量重复劳动。对于刚接触大模型开发的新手litellm 也是一个不错的切入点因为它把复杂的多厂商适配逻辑封装掉了你只需要关注业务本身。我个人的使用感受是litellm 最大的价值不在于它支持了多少家模型而在于它把“调用大模型”这件事标准化了。就像 JDBC 之于数据库你不需要关心底层是 MySQL 还是 PostgreSQL只要用统一的接口就行。这种抽象层的价值在项目初期可能不明显但一旦模型数量超过三个优势就非常突出了。2. 核心架构与设计思路拆解2.1 为什么需要统一调用层在没有 litellm 这类工具之前多模型调用的典型做法是为每个厂商写一个封装类然后在业务代码里根据配置选择不同的类。这种做法的问题在于每接入一个新模型就要新增一个封装类还要修改业务代码的分支逻辑。时间一长代码里全是厂商相关的硬编码想换模型就得改代码、重新测试、重新部署。litellm 的设计思路是面向接口编程的典型实践。它定义了一套标准的请求和响应格式所有厂商的差异都被收敛到适配层内部。业务代码只依赖标准接口不依赖具体实现。这样带来的好处是新增模型只需要在 litellm 的配置里加一条记录业务代码完全不用动。模型切换变成了配置变更而不是代码变更。另一个设计考量是兼容性优先。litellm 选择 OpenAI 的 API 格式作为标准而不是自己发明一套。这个决策很聪明因为 OpenAI 的接口格式已经成为事实上的行业标准大量现有代码和工具都基于这套格式。选择兼容 OpenAI意味着用户可以无缝迁移现有的 OpenAI 代码学习成本几乎为零。2.2 代理模式与 SDK 模式的双轨设计litellm 提供了两种使用方式一种是作为 Python SDK 直接集成到代码里另一种是作为独立代理服务运行。这两种模式针对的是不同的使用场景。SDK 模式适合开发阶段或者单机应用。你直接在 Python 代码里 import litellm然后调用 completion 函数传入模型名称和消息列表就行。这种方式简单直接不需要额外部署服务适合快速验证和原型开发。代理模式适合生产环境或者多语言场景。你启动一个 litellm 代理服务它对外暴露 OpenAI 兼容的 HTTP 接口。任何能调用 OpenAI 接口的客户端只需要把 base_url 指向代理地址就能调用所有后端模型。这种方式的好处是语言无关Java、Go、Node.js 都能用而且可以在代理层统一做鉴权、限流、日志、缓存等横切关注点。我实际用下来代理模式在团队协作中优势明显。因为代理服务是独立部署的模型配置、API Key 管理、访问控制都集中在服务端客户端不需要关心这些细节。而且代理层可以做请求日志和用量统计方便做成本核算和问题排查。2.3 模型路由与回退机制litellm 的模型路由功能是我觉得最实用的特性之一。它支持根据模型名称自动路由到对应的厂商也支持配置回退策略。比如你可以设置主模型和备用模型当主模型调用失败时自动切换到备用模型。这个机制在网络不稳定或者某个厂商服务抖动的时候特别有用。回退策略的配置逻辑是定义一个模型组组内按优先级排列多个模型。请求进来时先尝试第一个失败则尝试第二个以此类推。失败判断包括网络错误、超时、返回错误码等情况。这个功能在需要高可用性的生产环境里几乎是必备的。还有一个细节值得提litellm 支持基于权重的负载均衡。你可以给同一个模型组里的多个部署实例分配不同的权重请求会按权重比例分发。这对于多实例部署或者多账号轮询的场景很实用可以充分利用配额避免单个账号被限流。3. 核心功能与实操要点解析3.1 安装与基础配置litellm 的安装很简单用 pip 就行。如果你只需要 SDK 功能安装基础包即可如果需要代理服务建议安装带代理依赖的完整版本。pip install litellm pip install litellm[proxy]安装完成后第一步是配置 API Key。litellm 支持通过环境变量读取各厂商的密钥命名规则是厂商名大写加_API_KEY。比如 OpenAI 的密钥环境变量是 OPENAI_API_KEYAnthropic 的是 ANTHROPIC_API_KEY。这种设计的好处是密钥不硬编码在代码里符合安全最佳实践。注意环境变量的命名必须严格按照 litellm 的约定否则它会找不到密钥。我刚开始用的时候把 ANTHROPIC_API_KEY 写成了 CLAUDE_API_KEY结果一直报鉴权失败排查了半天才发现是命名问题。配置好密钥后最简单的调用方式是这样from litellm import completion response completion( modelgpt-4o, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)这段代码和直接调用 OpenAI SDK 几乎一样区别只在于 model 参数可以换成其他厂商的模型名称。litellm 会根据模型名称的前缀自动判断厂商比如 claude- 开头走 Anthropicgemini- 开头走 Google。3.2 多模型切换与参数映射litellm 最核心的能力是参数映射。不同厂商的 API 参数名称和取值范围都不一样litellm 在内部做了一层转换。比如 temperature 这个参数OpenAI 的范围是 0 到 2Anthropic 的范围是 0 到 1litellm 会自动做归一化处理。支持的通用参数包括参数名说明注意事项model模型名称决定路由到哪个厂商messages消息列表格式统一为 role/contenttemperature随机性不同厂商范围不同litellm 自动转换max_tokens最大输出长度部分厂商叫 max_output_tokenstop_p核采样通用支持stream流式输出统一支持stop停止词格式略有差异litellm 统一处理实际使用中我建议尽量只用通用参数避免使用厂商特有的参数。因为一旦用了特有参数代码就和特定厂商绑定了失去了 litellm 的跨模型优势。如果确实需要用到某个厂商的特有能力litellm 也支持通过 extra_body 参数透传但这部分就不具备可移植性了。3.3 代理服务的部署与配置代理模式的部署稍微复杂一些但收益也更大。首先需要准备一个配置文件通常叫 config.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-sonnet-4-20250514 api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-123456 database_url: postgresql://user:passlocalhost:5432/litellm配置文件里 model_name 是对外暴露的名称客户端调用时用这个名称。litellm_params 里的 model 是实际的后端模型标识格式是厂商前缀加模型名。api_key 可以用 os.environ/ 语法引用环境变量避免明文写在配置文件里。启动代理服务的命令是litellm --config config.yaml --port 4000启动后代理服务监听 4000 端口对外提供 OpenAI 兼容的接口。客户端只需要把 base_url 改成 http://localhost:4000api_key 改成配置文件里设置的 master_key就能像调用 OpenAI 一样调用所有配置的模型。提示生产环境建议配合 PostgreSQL 使用因为 litellm 需要数据库来存储虚拟密钥、用量记录、团队信息等。如果只是本地测试可以不加 database_url但功能会受限。3.4 虚拟密钥与访问控制litellm 的虚拟密钥功能解决了一个实际问题如何在不暴露真实 API Key 的前提下给不同用户或团队分配访问权限。你可以创建虚拟密钥设置预算上限、模型访问范围、过期时间等。创建虚拟密钥的方式有两种通过 API 调用或者通过管理界面。API 方式适合自动化管理管理界面适合手动操作。虚拟密钥的格式通常以 sk- 开头和 OpenAI 的密钥格式一致方便客户端兼容。预算控制是虚拟密钥的一个重要特性。你可以给每个密钥设置最大花费额度当累计用量超过额度时litellm 会自动拒绝后续请求。这个功能对于控制成本非常有用尤其是在多人共用一个模型账号的场景下可以避免某个人不小心跑出天价账单。4. 实操过程与核心环节实现4.1 从零搭建一个多模型代理服务我以实际搭建过程为例完整走一遍流程。假设我们需要搭建一个代理服务支持 OpenAI 和 Anthropic 两家模型并且要能通过虚拟密钥控制访问。第一步准备环境。需要 Python 3.8 以上版本以及一个 PostgreSQL 数据库可选但推荐。先安装 litellm 和代理依赖pip install litellm[proxy] pip install psycopg2-binary第二步创建配置文件。在项目目录下新建 config.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-sonnet-4-20250514 api_key: os.environ/ANTHROPIC_API_KEY general_settings: master_key: sk-my-master-key database_url: postgresql://litellm:passwordlocalhost:5432/litellm第三步设置环境变量。在终端里导出两个真实密钥export OPENAI_API_KEYsk-xxxx export ANTHROPIC_API_KEYsk-ant-xxxx第四步启动服务litellm --config config.yaml --port 4000 --detailed_debug--detailed_debug 参数会输出详细的请求日志方便排查问题。生产环境可以去掉这个参数减少日志量。第五步验证服务。用 curl 发一个测试请求curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-my-master-key \ -d { model: gpt-4o, messages: [{role: user, content: 测试}] }如果返回正常的响应说明服务搭建成功。然后把 model 换成 claude-sonnet再测一次验证多模型路由是否正常。4.2 虚拟密钥的创建与预算设置服务跑起来之后下一步是创建虚拟密钥。通过 API 创建的方式如下curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-my-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o, claude-sonnet], max_budget: 10.0, budget_duration: 30d, key_alias: team-a-key }这个请求会创建一个虚拟密钥限制只能访问 gpt-4o 和 claude-sonnet 两个模型30 天内最多花费 10 美元。返回结果里会包含生成的密钥字符串把这个密钥发给团队成员即可。预算设置的粒度可以很细。max_budget 是总预算budget_duration 是预算重置周期。还可以设置 rpm_limit每分钟请求数和 tpm_limit每分钟 token 数来做限流。这些参数组合起来可以实现相当精细的访问控制。注意虚拟密钥的预算统计是基于 litellm 内部的计费逻辑它需要知道每个模型的单价。litellm 内置了主流模型的定价表但如果你用的是自定义模型或者私有部署模型需要手动在配置文件里指定 input_cost_per_token 和 output_cost_per_token否则预算统计会不准确。4.3 流式输出与异步调用litellm 对流式输出的支持很完善。SDK 模式下只需要设置 streamTrue返回的就是一个生成器可以逐块读取内容from litellm import completion response completion( modelclaude-sonnet, messages[{role: user, content: 写一段话}], streamTrue ) for chunk in response: content chunk.choices[0].delta.content if content: print(content, end, flushTrue)异步调用用 acompletion 函数配合 asyncio 使用。异步模式在高并发场景下性能优势明显因为大模型调用是 IO 密集型操作异步可以充分利用等待时间处理其他请求。import asyncio from litellm import acompletion async def call_model(): response await acompletion( modelgpt-4o, messages[{role: user, content: 你好}] ) return response.choices[0].message.content result asyncio.run(call_model())实测下来异步模式在批量处理任务时吞吐量比同步模式高出好几倍。如果你需要同时调用多个模型做对比异步加 gather 的方式效率最高。4.4 回退策略与重试配置回退策略的配置在代理模式下通过 config.yaml 实现。可以定义 fallbacks 列表指定主模型和备用模型的对应关系litellm_settings: fallbacks: [{gpt-4o: [claude-sonnet]}] num_retries: 2 request_timeout: 30这段配置的意思是当 gpt-4o 调用失败时自动回退到 claude-sonnet每个请求最多重试 2 次单次请求超时时间为 30 秒。回退触发条件包括网络错误、超时、返回 5xx 错误码等。重试策略需要根据实际场景调整。如果是因为限流导致的失败重试往往能成功如果是因为参数错误导致的失败重试没有意义反而浪费时间和配额。litellm 默认只对可重试的错误进行重试这个逻辑是合理的。我踩过的一个坑是回退链太长会导致请求延迟很高。比如主模型超时 30 秒回退模型又超时 30 秒用户要等 60 秒才能拿到结果。后来我把超时时间调短到 15 秒并且限制回退链最多两层体验好了很多。5. 常见问题与排查技巧实录5.1 鉴权失败与密钥配置问题鉴权失败是最常见的问题表现是返回 401 错误。排查思路按以下顺序进行首先确认环境变量是否设置正确。litellm 读取环境变量的时机是进程启动时如果你在启动服务之后才 export 环境变量服务是读不到的。正确做法是先 export 再启动或者在配置文件里用 os.environ/ 语法引用。其次确认密钥格式是否正确。不同厂商的密钥格式不同OpenAI 的以 sk- 开头Anthropic 的以 sk-ant- 开头。如果密钥格式不对litellm 可能在路由阶段就判断错误。最后确认虚拟密钥是否有权限访问目标模型。虚拟密钥创建时如果限制了 models 列表调用不在列表里的模型会返回 403 错误。这个错误和 401 容易混淆需要看具体的错误信息。错误码可能原因排查方法401密钥无效或未设置检查环境变量和配置文件403虚拟密钥无权限检查密钥的 models 限制404模型名称错误检查 model_name 是否在配置中429触发限流检查 rpm/tpm 限制和厂商配额500后端服务异常查看 litellm 日志和厂商状态5.2 模型路由不生效的排查模型路由不生效的表现是明明配置了多个模型但请求总是走到同一个后端。这个问题通常有几个原因。一是模型名称匹配规则问题。litellm 的路由是基于模型名称的精确匹配或前缀匹配。如果你配置的 model_name 是 gpt-4o但请求里传的是 gpt-4o-mini两者不匹配litellm 会尝试用默认路由规则处理可能走到意料之外的后端。二是配置文件没有重新加载。litellm 代理服务启动后修改配置文件不会自动生效需要重启服务。如果你用的是容器部署需要重新构建镜像或者重启容器。三是环境变量覆盖了配置文件。litellm 的配置优先级是环境变量高于配置文件。如果你在环境变量里设置了 OPENAI_API_KEY又在配置文件里指定了不同的密钥实际生效的是环境变量里的。提示排查路由问题时启动服务时加上 --detailed_debug 参数日志里会打印每个请求的路由决策过程非常直观。5.3 流式输出中断与超时处理流式输出中断的表现是内容输出到一半突然停止没有报错也没有结束标记。这个问题在长文本生成场景下比较常见。主要原因通常是超时设置不合理。流式输出的超时判断和普通请求不同它需要判断的是两个 chunk 之间的间隔时间而不是整个请求的总时长。如果模型生成速度慢chunk 间隔超过超时阈值连接就会被断开。解决方法是在配置文件里调整 stream_timeout 参数把它设置得比普通请求超时更长。另外网络中间设备如负载均衡器、反向代理也可能有超时限制需要一并检查。还有一个容易忽略的点是客户端读取超时。有些 HTTP 客户端默认读取超时是 30 秒流式输出如果超过这个时间没有新数据客户端会主动断开。需要在客户端也设置合理的超时时间。5.4 用量统计与成本核算的准确性用量统计不准确是另一个高频问题。litellm 的用量统计依赖于厂商返回的 token 计数但不同厂商的计数方式有差异。比如有些厂商把输入和输出 token 分开计费有些厂商合并计算。litellm 会尽量归一化但无法做到 100% 准确。如果你发现统计结果和厂商账单对不上先检查模型的定价配置是否正确。litellm 内置的定价表可能不是最新的厂商调价后需要手动更新。在配置文件里可以覆盖默认定价model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY input_cost_per_token: 0.0000025 output_cost_per_token: 0.00001另外缓存命中的请求是否计入用量也需要确认。litellm 支持响应缓存缓存命中的请求不会调用后端模型但默认会计入用量统计。如果你不希望缓存命中计入预算需要在配置里关闭这个行为。5.5 性能调优与并发控制代理服务在高并发场景下可能成为瓶颈。litellm 本身是异步框架单实例可以支撑相当高的并发但有几个参数需要调整。worker 数量决定了进程数默认是 1。在多核服务器上可以适当增加 worker 数量但不要超过 CPU 核心数。因为大模型调用是 IO 密集型worker 太多反而会增加上下文切换开销。连接池大小影响与后端厂商的并发连接数。如果连接池太小请求会排队等待如果太大可能触发厂商的并发限制。建议根据厂商的配额来设置一般 20 到 50 之间比较合适。还有一个容易被忽略的点是日志级别。debug 级别的日志会记录完整的请求和响应内容在高并发下会产生大量 IO严重影响性能。生产环境建议用 info 或 warning 级别。6. 进阶用法与扩展场景6.1 自定义模型接入litellm 支持接入自定义模型只要该模型提供 OpenAI 兼容的接口。这在私有部署场景下很实用。配置方式是在 model_list 里指定 api_basemodel_list: - model_name: my-local-model litellm_params: model: openai/my-model api_base: http://localhost:8000/v1 api_key: dummy-key这里的 model 字段用 openai/ 前缀表示用 OpenAI 兼容协议通信。api_base 指向自定义服务的地址。api_key 如果服务不需要鉴权随便填一个占位符即可。这种配置方式的好处是私有模型和公有模型可以混用对外暴露统一的接口。客户端不需要知道哪个模型是本地部署的哪个是云端的调用方式完全一致。6.2 缓存策略与成本优化litellm 支持多种缓存后端包括内存缓存、Redis 缓存等。缓存的作用是对于相同的请求直接返回缓存结果不调用后端模型从而节省成本和延迟。缓存的配置在 litellm_settings 里litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379 ttl: 3600ttl 是缓存过期时间单位秒。对于事实性问答场景缓存命中率可能很高成本节省效果明显。但对于创意生成场景相同请求每次都应该返回不同结果缓存反而会降低体验需要根据场景决定是否开启。注意缓存键是基于请求内容的哈希值如果请求里包含随机种子或者时间戳缓存永远不会命中。使用缓存时要注意请求参数的稳定性。6.3 可观测性与监控集成生产环境需要监控代理服务的运行状态。litellm 支持多种可观测性集成包括日志、指标、追踪等。日志方面litellm 可以输出结构化的 JSON 日志方便接入日志收集系统。指标方面可以暴露 Prometheus 格式的指标包括请求数、延迟、错误率、token 用量等。追踪方面支持 OpenTelemetry 标准可以接入分布式追踪系统。我实际用下来最实用的监控指标是请求延迟的 P95 和 P99 分位数以及各模型的错误率。这两个指标能快速反映服务质量的变化。token 用量指标则用于成本监控设置告警阈值当用量异常增长时及时发现问题。6.4 团队协作与多租户管理litellm 的团队功能支持多租户场景。你可以创建团队给团队分配预算和模型权限然后在团队下创建成员密钥。这样不同团队之间的用量和预算相互隔离便于管理。团队管理的 API 包括创建团队、添加成员、设置团队预算等。团队预算和成员预算可以叠加使用成员预算不能超过团队预算。这种层级结构适合中大型组织的管理需求。对于个人开发者或者小团队可能用不到这么复杂的功能。但如果你在公司内部推广 litellm团队功能能帮你更好地控制成本和权限。我建议一开始就用虚拟密钥而不是直接暴露 master key养成好习惯后续扩展会顺利很多。7. 实操心得与避坑指南7.1 配置文件管理的经验配置文件是 litellm 代理服务的核心管理好配置文件能避免很多问题。我的做法是把配置文件纳入版本控制但敏感信息用环境变量引用不直接写在文件里。这样配置文件可以安全地提交到代码仓库密钥通过部署环境注入。另外建议为不同环境准备不同的配置文件比如 config.dev.yaml、config.prod.yaml。开发环境可以开启 debug 日志和详细错误信息生产环境则关闭这些减少信息泄露风险。配置变更的流程也要规范。修改配置文件后先在一个实例上验证确认无误再滚动更新其他实例。litellm 支持优雅重启重启过程中不会丢失正在处理的请求。7.2 密钥轮换与安全管理API Key 的安全管理是个持续性的工作。我踩过的坑是早期为了图方便把真实密钥直接写在配置文件里后来配置文件被不小心提交到了公开仓库导致密钥泄露。虽然及时发现并更换了密钥但这个过程很惊险。正确的做法是所有密钥都通过环境变量注入配置文件里只写 os.environ/ 引用。定期轮换密钥尤其是在团队成员变动时。使用虚拟密钥而不是真实密钥对外提供服务这样即使虚拟密钥泄露影响范围也可控。litellm 的虚拟密钥支持设置过期时间建议给临时用途的密钥设置较短的过期时间用完即废。长期使用的密钥也要定期更换不要一个密钥用到底。7.3 版本升级的注意事项litellm 迭代速度很快新版本可能引入不兼容的变更。升级前一定要看 changelog了解有哪些 breaking changes。我遇到过升级后配置文件格式变化的情况导致服务启动失败。建议的升级流程是先在测试环境升级跑一遍核心功能的回归测试确认没问题再升级生产环境。升级时保留旧版本的配置文件备份万一出问题可以快速回滚。另外litellm 的依赖比较多升级时可能会连带升级其他包引发依赖冲突。建议用虚拟环境隔离升级前先冻结当前依赖版本出问题时可以对照排查。7.4 成本控制的实战技巧成本控制是使用大模型服务时绕不开的话题。litellm 提供了多种成本控制手段组合使用效果最好。第一层是虚拟密钥的预算限制这是硬性上限超过就拒绝请求。第二层是缓存减少重复请求。第三层是模型路由把简单任务路由到便宜的小模型复杂任务才用大模型。第四层是限流防止突发流量导致成本失控。我实际用下来缓存和模型路由对成本的影响最大。很多场景下用户的问题有大量重复缓存命中率能达到 30% 以上。模型路由则需要根据业务特点设计规则比如意图识别用便宜模型内容生成用贵模型。还有一个技巧是设置预算告警。litellm 支持在预算使用到一定比例时发送告警比如用到 80% 时发通知这样你有时间调整策略而不是等到预算耗尽才发现。7.5 与其他工具的配合使用litellm 不是孤立的工具它可以和很多其他工具配合使用形成完整的工作流。和 LangChain 配合时litellm 可以作为 LangChain 的 LLM 后端利用 LangChain 的链式调用能力同时享受 litellm 的多模型支持。和 FastAPI 配合时litellm 代理可以作为 FastAPI 应用的一个路由统一鉴权和日志。和 Docker 配合时litellm 代理可以容器化部署方便扩缩容。我个人的习惯是把 litellm 代理作为基础设施层上层应用通过标准 OpenAI 接口调用。这样上层应用不需要关心模型细节专注于业务逻辑。基础设施层则统一处理鉴权、限流、日志、监控等横切关注点。这种分层架构在项目规模扩大后维护成本优势非常明显。内容已经覆盖了 litellm 的核心功能、实操步骤、问题排查和进阶用法。如果你正在做多模型应用开发建议先从 SDK 模式入手熟悉基本调用方式后再尝试代理模式。代理模式虽然配置稍复杂但带来的管理便利性和扩展性在项目进入生产阶段后会体现得淋漓尽致。