1. 先搞清楚 litellm 到底解决了什么问题1.1 多模型接入时最折磨人的不是模型本身而是接口差异最近我一直在维护一个带多模型路由的应用服务说实话真正让人头疼的不是模型效果而是接口格式差异。OpenAI 的对话补全用messages数组有一部分服务商把对话字段叫input有的返回里choices在顶层有的塞在responses里流式格式更是五花八门有的是 Server-Sent Events有的是 JSON 数组还有的干脆要求单独走一条 WebSocket。为了接第三四个模型我又得照着官方文档重写一遍客户端逻辑。做过类似工作的人应该能理解那种“适配器地狱”的感觉。模型本身是黑盒但接口差异成了直接成本每换一家供应商就要改代码、改测试、改监控。后来我开始用 litellm一个用 Python 写的统一模型接入层才慢慢把这部分工作收敛住对外统一成一套 OpenAI 风格接口底层想接哪家就接哪家业务代码基本不用动。本文不会复读官方文档我会结合我在实际项目里整理的思路聊清楚 litellm 的设计定位、上手路径、代理部署方式以及那些文档之外容易踩的坑。如果你正在给团队搭统一模型入口或者想减少业务代码和模型供应商之间的耦合这篇应该能帮上不少忙。1.2 litellm 的定位一层很薄的适配器而不是重框架初次接触 litellm 的人容易误以为它是一个完整框架得先引入一堆概念才能用。实际上它的设计非常克制核心就两件事格式转换和请求转发。在 SDK 模式下你写出来的代码和直接调 OpenAI SDK 差不多只是把模型名换成anthropic/claude-3-5-sonnet这种格式。在代理模式下litellm 变成独立服务对外暴露 OpenAI 兼容接口内部把请求转到真实供应商再把结果原样返回。这种“薄层”设计有个很大的好处迁移成本低。业务代码里只需要把base_url指向 litellm 代理或者把openai客户端换成 litellm 的completion就能跑起来。排查问题时也不用在一个复杂的抽象层里翻来翻去跟着日志走就能定位到具体请求。同时litellm 也内置了生产环境常见的高级能力比如 fallback、限流、重试、token 成本统计、缓存。它默认保持简单复杂能力是可选配置这对小团队和大团队来说都比较友好。1.3 用了 litellm 不等于一劳永逸先想清楚边界这里我想先把丑话说在前面。litellm 适合“多供应商、频繁切换、需要统一管理”的场景但有些情况不值得引入。如果项目只用一家供应商、且确定未来不会换直接用官方 SDK 更轻。如果你需要深度依赖某家特有的最新功能通常官方 SDK 更新最快代理层会有几天滞后。还有代理部署会带来额外一跳网络开销如果你对请求延迟极度敏感需要先做性能评估再决定要不要用。这些不是 litellm 的缺陷而是任何抽象层都会有的取舍。搞清楚边界比盲目引入更重要。下面我会按实操顺序展开把具体怎么装、怎么配、怎么排查都讲透。2. 从零上手安装、鉴权与第一次模型调用2.1 安装很简单但依赖选择要留意litellm 的安装是常规的 pip 操作直接执行pip install litellm这样装的是纯 SDK 模式适合在代码里做统一调用。如果你需要把 litellm 跑成代理服务也就是 proxy 模式建议安装带 proxy 依赖的版本pip install litellm[proxy]这里有个容易忽略的细节litellm 本身依赖很多第三方 provider 的 SDK所以安装包体积不小。如果你只在 Docker 容器里跑单模型代理完全够用但如果是给团队内部多环境安装建议用虚拟环境或者容器锁版本避免依赖冲突。实际经验里我遇到最多的问题不是安装失败而是升版本之后某个 provider 的依赖行为变了导致同样的代码结果不一致。所以日常使用我习惯把版本号固定住测试通过之后不轻易升。安装完成后可以用一行命令验证环境python -c import litellm; print(litellm.__version__)能输出版本号就说明基本环境没问题了。2.2 环境变量和模型命名规则直接决定后面省不省心litellm 读取各家供应商的鉴权信息标准做法是放到环境变量里。OpenAI 对应export OPENAI_API_KEYsk-...各家服务都有自己对应的环境变量名比如 Anthropic 的ANTHROPIC_API_KEYAzure 则还需要AZURE_API_KEY、AZURE_API_BASE等。建议统一在.env文件里维护而不是写死在代码中。这一点听起来是基础常识但实际项目里经常见到 key 明文出现在配置里一旦仓库泄露损失会很大。模型名称的写法是 litellm 的特色格式大致是供应商前缀/具体模型名例如openai/gpt-4oanthropic/claude-3-5-sonnetazure/gpt-4ogemini/gemini-1.5-pro如果省略前缀只写gpt-4olitellm 会默认当成 OpenAI 模型。统一格式之后切换模型时只需要改字符串里的前缀。我们内部以前写死各家 SDK 的 import后来统一成这种命名方式确实省了很多维护成本。2.3 第一个 completion 请求验证链路是否通SDK 模式的最小调用非常简单下面这段代码就是一次完整的对话请求from litellm import completion response completion( modelopenai/gpt-4o, messages[ {role: user, content: 用一句话解释什么是适配器模式} ] ) print(response[choices][0][message][content])返回结构是 OpenAI 风格用过 OpenAI SDK 的开发者几乎零成本上手。想切换模型时把model参数改成anthropic/claude-3-5-sonnet其他代码不用动litellm 会自动处理消息格式转换。这里我想提醒一个容易踩的细节响应对象本身是自定义对象同时支持属性访问和字典式访问。直接打印整段 response 信息量很大初学者容易看花眼。想快速取内容用字典式写法最顺手但前提是调用成功。第一次跑通后我建议先固定一个模型确认网络、key、模型名都没问题再往后叠加复杂配置。3. 把 litellm 当代理服务跑起来给团队统一基座3.1 一条命令启动本地网关背后发生了什么SDK 模式解决的是单机代码里的统一调用但团队里如果每个服务都装一套 litellm就不太合适了。这时可以用代理模式把 litellm 跑成独立服务对外暴露 OpenAI 兼容接口。启动方式很直观。先准备一个最简单的配置文件config.yamlmodel_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY然后启动litellm --config config.yaml --port 4000服务起来后它会暴露类似/v1/models、/v1/chat/completions、/v1/embeddings这样的端点。客户端只需要把base_url改成http://localhost:4000/v1API key 随便填一个非空值即可因为鉴权实际上由 litellm 转发时处理。“API key 随便填”这个点很反直觉我第一次用时也觉得奇怪。原因在于 litellm 代理默认不做鉴权校验它只是把请求转发给真实供应商。只有你在代理层开启了自定义 key 管理时这个字段才会被校验。所以团队内部用的时候建议在代理前面加一层网关或者至少设置虚拟 key避免裸奔。3.2 用 OpenAI SDK 调用代理业务代码几乎零改动代理服务启动后客户端侧接入可以用标准 OpenAI SDK 实现from openai import OpenAI client OpenAI( api_keydummy-key, base_urlhttp://localhost:4000/v1 ) response client.chat.completions.create( modelgpt-4o, messages[ {role: user, content: 你好} ] ) print(response.choices[0].message.content)这段代码和平时调用 OpenAI 官方接口唯一的区别就是base_url和api_key。也就是说如果项目里已经写好了基于 OpenAI 客户端的逻辑切换只是改配置不用改代码。这一点对已有系统接入统一网关非常关键。除了聊天补全代理也支持 embeddings、图像生成等端点。如果你需要统一做向量化同样可以通过代理接入多个嵌入模型客户端无需感知底层切换。3.3 配置多个模型与自定义别名把路由规则前置单一模型代理只是入门真正有价值的是多模型配置。可以在config.yaml里定义多个模型并给它们设置对外别名。下面是一个配置示例model_list: - model_name: my-chat-model litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: my-chat-model litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY这里两个条目都叫my-chat-model这是 litellm 支持的负载均衡用法同一对外模型名下可以挂多个底层模型默认按权重轮询分发。客户端请求my-chat-model时代理会挑一个可用后端。这种“对外别名 多后端”的设计让调用方不必关心底层是哪家模型。今天把my-chat-model全切到某个系列明天再切部分流量给另一家都只改代理配置业务侧完全无感知。我们在项目里把不同环境的模型别名固定住内部联调和生产切换都很顺畅。3.4 fallback、重试与超时生产环境必配的三件套配置多模型之后如果不设置降级策略仅靠轮询并不能保证稳定性。litellm 在config.yaml的litellm_settings里提供了几个关键参数litellm_settings: num_retries: 2 request_timeout: 30 fallbacks: [ {my-chat-model: [my-chat-model-fallback]} ]num_retries表示请求失败后的重试次数。重试对幂等请求很友好但如果是非幂等操作还按默认次数重试会放大副作用建议结合业务类型评估。request_timeout是单次请求超时时间单位是秒。大模型生成本身慢超时设太短容易被误杀设太长又容易拖垮线程池30 秒对大多数文本生成场景比较折中。fallbacks是降级列表当主模型返回限流、超时、服务不可用等错误时代理会自动尝试备选模型。这些配置合在一起能给团队层面的稳定性提供基本保障。实际运维中我发现fallback 触发条件默认比较保守只对明确的 429、500、超时这类失败生效如果供应商返回 200 但内容异常它不会感知这一点不要过度依赖代理兜底。4. 进阶玩法缓存、函数调用与 Embedding 统一入口4.1 缓存策略能省的不只是钱litellm 支持对相同请求做语义缓存也就是根据消息内容计算出 key下次相同输入直接返回之前的结果。在config.yaml里开启很简单litellm_settings: cache: true缓存生效后最直接的好处是降本。有些场景每天有大量重复的问题比如客服预检、固定格式的摘要缓存命中后不再调用上游模型token 费用直接归零。另一个好处是响应速度变快因为省掉了外部网络请求P95 延迟能明显下降。不过缓存要慎用。如果业务依赖模型生成结果的随机性或者需要实时性很高的信息开启缓存会让用户收到旧答案。我自己的做法是只在确定性较强的接口上开并且通过请求参数里的no-cache之类标识绕开缓存。litellm 也支持 Redis 作为缓存后端多实例部署时能共享缓存数据单机内存缓存只适合开发和测试。4.2 函数调用与流式输出代理怎么透传现在很多业务会用到 function calling。好消息是因为 litellm 走的是 OpenAI 兼容协议tools参数可以直接透传到后端模型返回结构也保持一致。当后端是 Anthropic 或 Gemini 时litellm 会在中间做一次工具调用格式转换。有一件事需要留意不同供应商对 function calling 的支持程度不一样参数细节也有差异。比如某家要求tool_choice必须显式声明另一家默认就支持。如果发现代理层转换后工具调用不生效先把litellm --debug打开看日志通常能看到格式转换前后的完整信息。流式输出在代理场景下也经常用到。客户端传streamTrue后代理会把上游的流式块转发给客户端整体体验和直连供应商基本一致。中间多一层网络会让断线概率稍高生产环境建议客户端侧加上超时重连机制下面第 6 节会展开说。4.3 Embedding 模型统一接入顺手解决向量化入口问题litellm 不只是做对话补全Embedding 也可以统一接入。代理暴露/v1/embeddings端点客户端用标准 OpenAI SDK 就能调用result client.embeddings.create( modelmy-embedding-model, input需要向量化的文本 ) print(result.data[0].embedding)配置端同样在model_list里声明例如- model_name: my-embedding-model litellm_params: model: openai/text-embedding-3-small api_key: os.environ/OPENAI_API_KEY这个能力对检索项目很有用。如果我们希望向量化逻辑在应用层不绑定某一家的 Embedding 服务那么统一入口就是合理的抽象位置。后续想从一个小模型换成更大更贵的模型只需要改代理配置不需要动整个检索链路。5. 成本统计、预算控制与生产部署的落地经验5.1 内置 token 统计与成本计算让你看清每笔请求花在哪里用代理模式之后成本数据天然集中。每次请求的返回里都带 token 用量代理日志也会记录模型名、输入输出 token 数和预估费用。我通常在配置里开启详细日志配合一个简单的采集脚本按天、按模型、按调用方汇总。这里有一个需要谨慎看待的点litellm 计算成本用的是内置的价格表但各家供应商调价之后这个价格表可能滞后。如果账目要求精确建议拿到原始 token 用量后用自己的价格文件重新计算。对大多数场景来说内置估算已经能反映趋势精确定价可以用在报表导出等环节。5.2 虚拟 key 与预算管理给多团队提供入口代理模式下litellm 支持创建虚拟 key。每个 key 可以绑定预算、关联用户或团队并且设置过期时间。这样即使所有请求都指向同一个代理也能做到按调用方隔离。如果一个团队或者一个项目组被分配了固定预算可以在 key 上直接做限制超出配额后代理会拒绝请求。这个能力相当于用配置代替了一部分限流代码对资源管控很有用。需要注意虚拟 key 的鉴权是代理自己实现的不像真实供应商 key 那样在源头加密传输。内网部署时建议把代理放在内网或加一层网关避免虚拟 key 暴露在外网环境。这个细节如果忽略等于把统一入口的访问控制建立在很弱的基础上。5.3 容器化部署与资源分配别小看一台代理机器的规格落地到生产环境时我一般用 Docker 跑代理。一个基础命令如下docker run -d \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ --env-file .env \ --name litellm-proxy \ ghcr.io/berriai/litellm:main-stable这里把 config.yaml 直接挂载进去环境变量从.env读取启动后服务监听 4000 端口。资源方面代理本身主要是转发和格式转换CPU 消耗不高但并发能力受 Python 异步能力影响比较大。建议给足连接池配置同时把上游请求超时和并发数控制在合理范围避免突发流量把连接全部占满。另外如果代理需要长时间稳定运行日志轮转要记得配置。litellm 日志在请求量大的时候增长非常快不轮转的话磁盘满只是时间问题。这个坑在文档里不太显眼但线上出过一次问题之后我就每次都主动处理了。6. 常见问题排查与避坑记录6.1 鉴权失败和 key 找不到先别急着怀疑代码代理转发时报 401绝大多数情况不是代理逻辑出错而是环境变量没传到进程里。常见原因有两个.env文件没有实际加载或者模型配置里写了os.environ/OPENAI_API_KEY但当前 shell 环境里没有这个变量。排查顺序我建议这样先手动执行echo $OPENAI_API_KEY看变量是否存在再用litellm --debug启动代理看日志。只要日志里出现了实际请求的供应商地址和鉴权头就能很快确认是环境问题还是转发链路问题。很多次排查到最后只是 export 少写了一个变量。6.2 上下文长度和模型映射混乱理解“别名”是突破口代理模式下特别常见的一类问题是客户端传了模型名my-chat-model但代理后端实际是另一个模型导致业务侧误判上下文长度。比如某后端上下文是 128k另一个备选只有 8k请求文本稍微长一点就触发超限。解决办法是在config.yaml里给每个模型显式声明max_input_tokens和max_output_tokens让路由层在选模型前先做长度检查。litellm 内置了一些模型的信息但自定义别名或较新模型未必能自动识别人工补充元数据最稳。6.3 流式输出、超时与重试循环容易拖垮客户端流式场景下因为中间多了一层代理断线和超时几率会比直连稍高。客户端如果没做好超时处理可能一直挂在等待状态。经验是客户端侧也要设置合理的流式读取超时不要把代理的超时时间当成唯一防线。重试还有一个隐蔽问题如果 fallback 列表里包含同一个底层模型而上游正在大规模限流那么重试多少次都是白搭反而增加上游压力。我建议 fallback 配置时优先选择不同供应商的模型同时把num_retries控制在一两次避免重试风暴。6.4 本地模型和私有模型接入别漏掉 base_url 参数litellm 也能接本地部署的模型服务比如基于 vLLM 或 Ollama 起的服务。配置方式是在litellm_params里带上api_basemodel_list: - model_name: local-model litellm_params: model: openai/llama-3.1-8b-instruct api_base: http://localhost:8000/v1这里model前缀写成openai/是因为本地服务暴露的是 OpenAI 兼容接口litellm 会按这个协议去解析。如果本地服务的接口格式不标准对接时需要做额外的格式转换配置。这个细节我见过不少人踩坑请求报 404 就先怀疑代理结果发现是api_base写成了服务首页地址而正确的路径是/v1后缀。改完之后立刻通了。7. 最后一点个人体会和落地清单7.1 把 litellm 放在架构的哪个位置真正值钱的不是工具本身而是你把它放在架构的哪个位置。我自己的做法是无论项目当前是否有多模型需求都会在业务代码和模型供应商之间留一层薄的抽象。litellm 是实现这个抽象的一个顺手工具而不是让业务逻辑直接依赖它。如果只是图一时方便把供应商模型名写满整个项目后面想换模型照样会经历一遍大改。反过来如果为了抽象而引入很重的框架都团队学习和维护成本也会上升。litellm 的“薄”和“标准接口”正好卡在一个比较舒服的位置。7.2 几条可以直接抄走的落地清单我整理了几个从实战里沉淀下来的清单给第一次上手的朋友参考。第一统一用模型别名不要在业务代码各处维护真实供应商模型名。第二所有供应商 key 放进环境变量配置里用os.environ引用绝不硬编码。第三先跑通单模型再上 fallback否则问题定位成本很高。第四生产环境开启成本日志先从一个简单的汇总脚本开始看得见支出之后再做优化。如果你现在就想试我的建议是搭一个只有两个模型的小代理打开 fallback然后用压测工具打一遍流量。跑通了再决定要不要扩大到全团队。实际用下来litellm 确实让“换模型”这件事变得不再可怕但前提是你愿意花点时间把架构里的位置想清楚。我到现在一直保持着一个习惯新项目第一次接模型之前先问自己一句这层抽象到底是为了谁而写的。 
长河君 · 2026/10/21 4:11:52 · 阅读 1.2k litellm详解：统一大模型接入层，让多模型调用更简单
1. 先搞清楚 litellm 到底解决了什么问题1.1 多模型接入时最折磨人的不是模型本身而是接口差异最近我一直在维护一个带多模型路由的应用服务说实话真正让人头疼的不是模型效果而是接口格式差异。OpenAI 的对话补全用messages数组有一部分服务商把对话字段叫input有的返回里choices在顶层有的塞在responses里流式格式更是五花八门有的是 Server-Sent Events有的是 JSON 数组还有的干脆要求单独走一条 WebSocket。为了接第三四个模型我又得照着官方文档重写一遍客户端逻辑。做过类似工作的人应该能理解那种“适配器地狱”的感觉。模型本身是黑盒但接口差异成了直接成本每换一家供应商就要改代码、改测试、改监控。后来我开始用 litellm一个用 Python 写的统一模型接入层才慢慢把这部分工作收敛住对外统一成一套 OpenAI 风格接口底层想接哪家就接哪家业务代码基本不用动。本文不会复读官方文档我会结合我在实际项目里整理的思路聊清楚 litellm 的设计定位、上手路径、代理部署方式以及那些文档之外容易踩的坑。如果你正在给团队搭统一模型入口或者想减少业务代码和模型供应商之间的耦合这篇应该能帮上不少忙。1.2 litellm 的定位一层很薄的适配器而不是重框架初次接触 litellm 的人容易误以为它是一个完整框架得先引入一堆概念才能用。实际上它的设计非常克制核心就两件事格式转换和请求转发。在 SDK 模式下你写出来的代码和直接调 OpenAI SDK 差不多只是把模型名换成anthropic/claude-3-5-sonnet这种格式。在代理模式下litellm 变成独立服务对外暴露 OpenAI 兼容接口内部把请求转到真实供应商再把结果原样返回。这种“薄层”设计有个很大的好处迁移成本低。业务代码里只需要把base_url指向 litellm 代理或者把openai客户端换成 litellm 的completion就能跑起来。排查问题时也不用在一个复杂的抽象层里翻来翻去跟着日志走就能定位到具体请求。同时litellm 也内置了生产环境常见的高级能力比如 fallback、限流、重试、token 成本统计、缓存。它默认保持简单复杂能力是可选配置这对小团队和大团队来说都比较友好。1.3 用了 litellm 不等于一劳永逸先想清楚边界这里我想先把丑话说在前面。litellm 适合“多供应商、频繁切换、需要统一管理”的场景但有些情况不值得引入。如果项目只用一家供应商、且确定未来不会换直接用官方 SDK 更轻。如果你需要深度依赖某家特有的最新功能通常官方 SDK 更新最快代理层会有几天滞后。还有代理部署会带来额外一跳网络开销如果你对请求延迟极度敏感需要先做性能评估再决定要不要用。这些不是 litellm 的缺陷而是任何抽象层都会有的取舍。搞清楚边界比盲目引入更重要。下面我会按实操顺序展开把具体怎么装、怎么配、怎么排查都讲透。2. 从零上手安装、鉴权与第一次模型调用2.1 安装很简单但依赖选择要留意litellm 的安装是常规的 pip 操作直接执行pip install litellm这样装的是纯 SDK 模式适合在代码里做统一调用。如果你需要把 litellm 跑成代理服务也就是 proxy 模式建议安装带 proxy 依赖的版本pip install litellm[proxy]这里有个容易忽略的细节litellm 本身依赖很多第三方 provider 的 SDK所以安装包体积不小。如果你只在 Docker 容器里跑单模型代理完全够用但如果是给团队内部多环境安装建议用虚拟环境或者容器锁版本避免依赖冲突。实际经验里我遇到最多的问题不是安装失败而是升版本之后某个 provider 的依赖行为变了导致同样的代码结果不一致。所以日常使用我习惯把版本号固定住测试通过之后不轻易升。安装完成后可以用一行命令验证环境python -c import litellm; print(litellm.__version__)能输出版本号就说明基本环境没问题了。2.2 环境变量和模型命名规则直接决定后面省不省心litellm 读取各家供应商的鉴权信息标准做法是放到环境变量里。OpenAI 对应export OPENAI_API_KEYsk-...各家服务都有自己对应的环境变量名比如 Anthropic 的ANTHROPIC_API_KEYAzure 则还需要AZURE_API_KEY、AZURE_API_BASE等。建议统一在.env文件里维护而不是写死在代码中。这一点听起来是基础常识但实际项目里经常见到 key 明文出现在配置里一旦仓库泄露损失会很大。模型名称的写法是 litellm 的特色格式大致是供应商前缀/具体模型名例如openai/gpt-4oanthropic/claude-3-5-sonnetazure/gpt-4ogemini/gemini-1.5-pro如果省略前缀只写gpt-4olitellm 会默认当成 OpenAI 模型。统一格式之后切换模型时只需要改字符串里的前缀。我们内部以前写死各家 SDK 的 import后来统一成这种命名方式确实省了很多维护成本。2.3 第一个 completion 请求验证链路是否通SDK 模式的最小调用非常简单下面这段代码就是一次完整的对话请求from litellm import completion response completion( modelopenai/gpt-4o, messages[ {role: user, content: 用一句话解释什么是适配器模式} ] ) print(response[choices][0][message][content])返回结构是 OpenAI 风格用过 OpenAI SDK 的开发者几乎零成本上手。想切换模型时把model参数改成anthropic/claude-3-5-sonnet其他代码不用动litellm 会自动处理消息格式转换。这里我想提醒一个容易踩的细节响应对象本身是自定义对象同时支持属性访问和字典式访问。直接打印整段 response 信息量很大初学者容易看花眼。想快速取内容用字典式写法最顺手但前提是调用成功。第一次跑通后我建议先固定一个模型确认网络、key、模型名都没问题再往后叠加复杂配置。3. 把 litellm 当代理服务跑起来给团队统一基座3.1 一条命令启动本地网关背后发生了什么SDK 模式解决的是单机代码里的统一调用但团队里如果每个服务都装一套 litellm就不太合适了。这时可以用代理模式把 litellm 跑成独立服务对外暴露 OpenAI 兼容接口。启动方式很直观。先准备一个最简单的配置文件config.yamlmodel_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY然后启动litellm --config config.yaml --port 4000服务起来后它会暴露类似/v1/models、/v1/chat/completions、/v1/embeddings这样的端点。客户端只需要把base_url改成http://localhost:4000/v1API key 随便填一个非空值即可因为鉴权实际上由 litellm 转发时处理。“API key 随便填”这个点很反直觉我第一次用时也觉得奇怪。原因在于 litellm 代理默认不做鉴权校验它只是把请求转发给真实供应商。只有你在代理层开启了自定义 key 管理时这个字段才会被校验。所以团队内部用的时候建议在代理前面加一层网关或者至少设置虚拟 key避免裸奔。3.2 用 OpenAI SDK 调用代理业务代码几乎零改动代理服务启动后客户端侧接入可以用标准 OpenAI SDK 实现from openai import OpenAI client OpenAI( api_keydummy-key, base_urlhttp://localhost:4000/v1 ) response client.chat.completions.create( modelgpt-4o, messages[ {role: user, content: 你好} ] ) print(response.choices[0].message.content)这段代码和平时调用 OpenAI 官方接口唯一的区别就是base_url和api_key。也就是说如果项目里已经写好了基于 OpenAI 客户端的逻辑切换只是改配置不用改代码。这一点对已有系统接入统一网关非常关键。除了聊天补全代理也支持 embeddings、图像生成等端点。如果你需要统一做向量化同样可以通过代理接入多个嵌入模型客户端无需感知底层切换。3.3 配置多个模型与自定义别名把路由规则前置单一模型代理只是入门真正有价值的是多模型配置。可以在config.yaml里定义多个模型并给它们设置对外别名。下面是一个配置示例model_list: - model_name: my-chat-model litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: my-chat-model litellm_params: model: anthropic/claude-3-5-sonnet api_key: os.environ/ANTHROPIC_API_KEY这里两个条目都叫my-chat-model这是 litellm 支持的负载均衡用法同一对外模型名下可以挂多个底层模型默认按权重轮询分发。客户端请求my-chat-model时代理会挑一个可用后端。这种“对外别名 多后端”的设计让调用方不必关心底层是哪家模型。今天把my-chat-model全切到某个系列明天再切部分流量给另一家都只改代理配置业务侧完全无感知。我们在项目里把不同环境的模型别名固定住内部联调和生产切换都很顺畅。3.4 fallback、重试与超时生产环境必配的三件套配置多模型之后如果不设置降级策略仅靠轮询并不能保证稳定性。litellm 在config.yaml的litellm_settings里提供了几个关键参数litellm_settings: num_retries: 2 request_timeout: 30 fallbacks: [ {my-chat-model: [my-chat-model-fallback]} ]num_retries表示请求失败后的重试次数。重试对幂等请求很友好但如果是非幂等操作还按默认次数重试会放大副作用建议结合业务类型评估。request_timeout是单次请求超时时间单位是秒。大模型生成本身慢超时设太短容易被误杀设太长又容易拖垮线程池30 秒对大多数文本生成场景比较折中。fallbacks是降级列表当主模型返回限流、超时、服务不可用等错误时代理会自动尝试备选模型。这些配置合在一起能给团队层面的稳定性提供基本保障。实际运维中我发现fallback 触发条件默认比较保守只对明确的 429、500、超时这类失败生效如果供应商返回 200 但内容异常它不会感知这一点不要过度依赖代理兜底。4. 进阶玩法缓存、函数调用与 Embedding 统一入口4.1 缓存策略能省的不只是钱litellm 支持对相同请求做语义缓存也就是根据消息内容计算出 key下次相同输入直接返回之前的结果。在config.yaml里开启很简单litellm_settings: cache: true缓存生效后最直接的好处是降本。有些场景每天有大量重复的问题比如客服预检、固定格式的摘要缓存命中后不再调用上游模型token 费用直接归零。另一个好处是响应速度变快因为省掉了外部网络请求P95 延迟能明显下降。不过缓存要慎用。如果业务依赖模型生成结果的随机性或者需要实时性很高的信息开启缓存会让用户收到旧答案。我自己的做法是只在确定性较强的接口上开并且通过请求参数里的no-cache之类标识绕开缓存。litellm 也支持 Redis 作为缓存后端多实例部署时能共享缓存数据单机内存缓存只适合开发和测试。4.2 函数调用与流式输出代理怎么透传现在很多业务会用到 function calling。好消息是因为 litellm 走的是 OpenAI 兼容协议tools参数可以直接透传到后端模型返回结构也保持一致。当后端是 Anthropic 或 Gemini 时litellm 会在中间做一次工具调用格式转换。有一件事需要留意不同供应商对 function calling 的支持程度不一样参数细节也有差异。比如某家要求tool_choice必须显式声明另一家默认就支持。如果发现代理层转换后工具调用不生效先把litellm --debug打开看日志通常能看到格式转换前后的完整信息。流式输出在代理场景下也经常用到。客户端传streamTrue后代理会把上游的流式块转发给客户端整体体验和直连供应商基本一致。中间多一层网络会让断线概率稍高生产环境建议客户端侧加上超时重连机制下面第 6 节会展开说。4.3 Embedding 模型统一接入顺手解决向量化入口问题litellm 不只是做对话补全Embedding 也可以统一接入。代理暴露/v1/embeddings端点客户端用标准 OpenAI SDK 就能调用result client.embeddings.create( modelmy-embedding-model, input需要向量化的文本 ) print(result.data[0].embedding)配置端同样在model_list里声明例如- model_name: my-embedding-model litellm_params: model: openai/text-embedding-3-small api_key: os.environ/OPENAI_API_KEY这个能力对检索项目很有用。如果我们希望向量化逻辑在应用层不绑定某一家的 Embedding 服务那么统一入口就是合理的抽象位置。后续想从一个小模型换成更大更贵的模型只需要改代理配置不需要动整个检索链路。5. 成本统计、预算控制与生产部署的落地经验5.1 内置 token 统计与成本计算让你看清每笔请求花在哪里用代理模式之后成本数据天然集中。每次请求的返回里都带 token 用量代理日志也会记录模型名、输入输出 token 数和预估费用。我通常在配置里开启详细日志配合一个简单的采集脚本按天、按模型、按调用方汇总。这里有一个需要谨慎看待的点litellm 计算成本用的是内置的价格表但各家供应商调价之后这个价格表可能滞后。如果账目要求精确建议拿到原始 token 用量后用自己的价格文件重新计算。对大多数场景来说内置估算已经能反映趋势精确定价可以用在报表导出等环节。5.2 虚拟 key 与预算管理给多团队提供入口代理模式下litellm 支持创建虚拟 key。每个 key 可以绑定预算、关联用户或团队并且设置过期时间。这样即使所有请求都指向同一个代理也能做到按调用方隔离。如果一个团队或者一个项目组被分配了固定预算可以在 key 上直接做限制超出配额后代理会拒绝请求。这个能力相当于用配置代替了一部分限流代码对资源管控很有用。需要注意虚拟 key 的鉴权是代理自己实现的不像真实供应商 key 那样在源头加密传输。内网部署时建议把代理放在内网或加一层网关避免虚拟 key 暴露在外网环境。这个细节如果忽略等于把统一入口的访问控制建立在很弱的基础上。5.3 容器化部署与资源分配别小看一台代理机器的规格落地到生产环境时我一般用 Docker 跑代理。一个基础命令如下docker run -d \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ --env-file .env \ --name litellm-proxy \ ghcr.io/berriai/litellm:main-stable这里把 config.yaml 直接挂载进去环境变量从.env读取启动后服务监听 4000 端口。资源方面代理本身主要是转发和格式转换CPU 消耗不高但并发能力受 Python 异步能力影响比较大。建议给足连接池配置同时把上游请求超时和并发数控制在合理范围避免突发流量把连接全部占满。另外如果代理需要长时间稳定运行日志轮转要记得配置。litellm 日志在请求量大的时候增长非常快不轮转的话磁盘满只是时间问题。这个坑在文档里不太显眼但线上出过一次问题之后我就每次都主动处理了。6. 常见问题排查与避坑记录6.1 鉴权失败和 key 找不到先别急着怀疑代码代理转发时报 401绝大多数情况不是代理逻辑出错而是环境变量没传到进程里。常见原因有两个.env文件没有实际加载或者模型配置里写了os.environ/OPENAI_API_KEY但当前 shell 环境里没有这个变量。排查顺序我建议这样先手动执行echo $OPENAI_API_KEY看变量是否存在再用litellm --debug启动代理看日志。只要日志里出现了实际请求的供应商地址和鉴权头就能很快确认是环境问题还是转发链路问题。很多次排查到最后只是 export 少写了一个变量。6.2 上下文长度和模型映射混乱理解“别名”是突破口代理模式下特别常见的一类问题是客户端传了模型名my-chat-model但代理后端实际是另一个模型导致业务侧误判上下文长度。比如某后端上下文是 128k另一个备选只有 8k请求文本稍微长一点就触发超限。解决办法是在config.yaml里给每个模型显式声明max_input_tokens和max_output_tokens让路由层在选模型前先做长度检查。litellm 内置了一些模型的信息但自定义别名或较新模型未必能自动识别人工补充元数据最稳。6.3 流式输出、超时与重试循环容易拖垮客户端流式场景下因为中间多了一层代理断线和超时几率会比直连稍高。客户端如果没做好超时处理可能一直挂在等待状态。经验是客户端侧也要设置合理的流式读取超时不要把代理的超时时间当成唯一防线。重试还有一个隐蔽问题如果 fallback 列表里包含同一个底层模型而上游正在大规模限流那么重试多少次都是白搭反而增加上游压力。我建议 fallback 配置时优先选择不同供应商的模型同时把num_retries控制在一两次避免重试风暴。6.4 本地模型和私有模型接入别漏掉 base_url 参数litellm 也能接本地部署的模型服务比如基于 vLLM 或 Ollama 起的服务。配置方式是在litellm_params里带上api_basemodel_list: - model_name: local-model litellm_params: model: openai/llama-3.1-8b-instruct api_base: http://localhost:8000/v1这里model前缀写成openai/是因为本地服务暴露的是 OpenAI 兼容接口litellm 会按这个协议去解析。如果本地服务的接口格式不标准对接时需要做额外的格式转换配置。这个细节我见过不少人踩坑请求报 404 就先怀疑代理结果发现是api_base写成了服务首页地址而正确的路径是/v1后缀。改完之后立刻通了。7. 最后一点个人体会和落地清单7.1 把 litellm 放在架构的哪个位置真正值钱的不是工具本身而是你把它放在架构的哪个位置。我自己的做法是无论项目当前是否有多模型需求都会在业务代码和模型供应商之间留一层薄的抽象。litellm 是实现这个抽象的一个顺手工具而不是让业务逻辑直接依赖它。如果只是图一时方便把供应商模型名写满整个项目后面想换模型照样会经历一遍大改。反过来如果为了抽象而引入很重的框架都团队学习和维护成本也会上升。litellm 的“薄”和“标准接口”正好卡在一个比较舒服的位置。7.2 几条可以直接抄走的落地清单我整理了几个从实战里沉淀下来的清单给第一次上手的朋友参考。第一统一用模型别名不要在业务代码各处维护真实供应商模型名。第二所有供应商 key 放进环境变量配置里用os.environ引用绝不硬编码。第三先跑通单模型再上 fallback否则问题定位成本很高。第四生产环境开启成本日志先从一个简单的汇总脚本开始看得见支出之后再做优化。如果你现在就想试我的建议是搭一个只有两个模型的小代理打开 fallback然后用压测工具打一遍流量。跑通了再决定要不要扩大到全团队。实际用下来litellm 确实让“换模型”这件事变得不再可怕但前提是你愿意花点时间把架构里的位置想清楚。我到现在一直保持着一个习惯新项目第一次接模型之前先问自己一句这层抽象到底是为了谁而写的。