1. 从一个真实困境说起：多模型调用的碎片化之痛

如果你正在做AI应用开发，大概率遇到过这样的场景：项目初期用某家云服务商的API跑通了原型，效果不错，但老板突然说"我们要支持国产模型，成本降下来"，或者产品经理跑来说"用户反馈某海外模型的回答质量更好，能不能加个切换按钮"。这时候你打开代码一看，每个模型的调用方式都不一样——有的用OpenAI的SDK，有的用自家封装的HTTP接口，参数命名五花八门，返回结构更是各说各话。改一处调用，可能要动三四个文件，测试一遍下来半天就没了。

这就是litellm要解决的核心问题。它是一个用Python写的开源库，目标非常直接：用一套统一的OpenAI格式接口，去调用市面上几乎所有主流的大语言模型。你只需要把原来代码里的openai.ChatCompletion.create换成litellm.completion，然后在参数里加一个model="某平台/某模型"，剩下的请求格式、响应解析、错误处理，它帮你全部抹平。

我第一次接触litellm是在一个需要同时对接四家模型供应商的内部工具项目上。当时团队评估过几种方案：自己写一层适配器、用LangChain的LLM抽象、或者直接在每个业务模块里硬编码不同SDK。自己写适配器工作量太大，LangChain又太重，最后选了litellm，原因很简单——它的接口设计几乎零学习成本，任何用过OpenAI SDK的人十分钟就能上手。

这篇文章适合三类人看：第一类是做AI应用开发、需要频繁切换或对比不同模型的工程师；第二类是想在自己的产品里给用户提供"模型选择"功能的开发者；第三类是对LLM应用架构感兴趣、想了解统一调用层设计思路的技术人。我会从litellm的核心机制讲起，拆解它的配置方式、路由策略、成本追踪、异常处理，再结合我实际踩过的坑，把那些官方文档里不会写的细节全部摊开来讲。

2. litellm到底做了什么：统一接口背后的映射逻辑

2.1 核心设计思路：把差异全部收进一个函数

litellm最核心的入口就是litellm.completion()这个函数。它的参数签名和OpenAI的ChatCompletion.create几乎一模一样——model、messages、temperature、max_tokens、stream，你原来怎么写的，现在基本不用改。区别在于model这个字段的写法：litellm用"供应商前缀/模型名"的格式来识别你要调用哪家的服务。

比如你要调用某海外平台的模型，写model="openai/gpt-4o"；要调用某国内平台的模型，写model="deepseek/deepseek-chat"；要调用本地部署的Ollama，写model="ollama/llama3"。litellm内部维护了一张巨大的映射表，把每个供应商的API端点、认证方式、请求格式、响应结构全部登记在案。当你传入model参数时，它做的第一件事就是解析前缀，找到对应的Provider配置，然后把你的统一请求翻译成该供应商能听懂的格式。

这个翻译过程比想象中复杂。不同供应商的差异不只是URL不同，还包括：认证头是Authorization: Bearer还是x-api-key；messages里的role字段是否支持system；temperature的取值范围是0到1还是0到2；流式返回的chunk结构是delta.content还是text；错误码的语义是否一致。litellm为每个Provider写了一个适配类，把这些差异全部封装在内部。你作为调用方，看到的永远是OpenAI格式的请求和响应。

2.2 支持的模型范围：从云端到本地，从文本到多模态

litellm目前支持的Provider数量已经超过100个，覆盖了几乎所有你能想到的模型服务。我把它大致分成几类，方便你快速判断自己的场景是否适用：

这个覆盖面意味着，你可以在不改动业务代码的前提下，把请求从一家切到另一家。我做过一个测试：同一个completion调用，只改model参数，分别打到四家不同的服务上，返回的响应结构完全一致，业务层的解析代码一行都不用动。这种"无感切换"的能力，在需要做模型对比评测或者灰度发布时特别有用。

2.3 安装与最小可用示例

安装litellm非常简单，一条pip命令搞定：

pip install litellm

如果你需要用到某些特定Provider的SDK（比如AWS Bedrock需要boto3），litellm会提示你安装对应的额外依赖。我建议一开始只装基础包，遇到报错再按提示补装，避免一次性引入太多不必要的依赖。

最小可用示例大概长这样：

import litellm response = litellm.completion( model="deepseek/deepseek-chat", messages=[ {"role": "system", "content": "你是一个简洁的助手。"}, {"role": "user", "content": "用一句话解释什么是统一调用层。"} ], api_key="你的API Key" ) print(response.choices[0].message.content)

注意api_key这个参数。litellm支持两种传法：一种是像上面这样直接传，适合快速测试；另一种是通过环境变量，比如DEEPSEEK_API_KEY、OPENAI_API_KEY，litellm会自动读取。生产环境我强烈建议用环境变量，避免Key硬编码在代码里。

提示：litellm的completion函数返回的对象结构和OpenAI SDK的返回完全一致，response.choices[0].message.content、response.usage.prompt_tokens这些字段都可以直接用。如果你原来代码里有基于OpenAI响应写的解析逻辑，迁移过来零成本。

3. 配置体系与路由策略：让多模型调用真正可控

3.1 环境变量与配置文件：两种管理方式的取舍

litellm的配置管理有两种模式，我分别说说适用场景。

第一种是纯环境变量。每个Provider对应一组环境变量，比如OPENAI_API_KEY、ANTHROPIC_API_KEY、AZURE_API_KEY加上AZURE_API_BASE和AZURE_API_VERSION。这种方式适合Provider数量少、部署环境简单的项目。优点是零配置文件，容器化部署时直接注入环境变量就行。缺点是当Provider超过五六个之后，环境变量列表会变得很长，而且不同环境的Key管理容易混乱。

第二种是配置文件加Router。litellm提供了一个Router类，你可以用一个YAML或JSON文件定义所有模型列表、路由策略、重试规则、预算限制。这种方式适合Provider多、需要精细控制的场景。配置文件大概长这样：

model_list: - model_name: "fast-model" litellm_params: model: "deepseek/deepseek-chat" api_key: "os.environ/DEEPSEEK_API_KEY" - model_name: "quality-model" litellm_params: model: "openai/gpt-4o" api_key: "os.environ/OPENAI_API_KEY" router_settings: routing_strategy: "latency-based-routing" num_retries: 3 timeout: 30

这里有个关键设计：model_name是你自己起的别名，业务代码里用这个别名调用，而不是直接写具体的Provider模型名。这样做的好处是，当你想把"fast-model"从DeepSeek换成另一个更便宜的模型时，只需要改配置文件，业务代码完全不动。我在项目里会把模型按用途分组，比如"fast-model"用于简单分类任务，"quality-model"用于复杂推理，"local-model"用于敏感数据处理，每个别名背后可以挂多个实际模型做负载均衡。

3.2 路由策略：延迟优先还是成本优先

Router支持多种路由策略，我重点讲三种最常用的。

延迟优先（latency-based-routing）：litellm会记录每个模型最近的响应时间，把请求优先发给当前最快的那个。这个策略适合对响应速度敏感的场景，比如实时对话。但要注意，延迟数据是滑动窗口统计的，如果某个模型突然变慢，需要几次请求之后才会被降权。

成本优先（cost-based-routing）：优先选择每Token成本最低的模型。适合大批量离线处理任务，比如批量摘要、数据清洗。我在一个日志分析项目里用这个策略，把大部分请求路由到了最便宜的模型上，只有检测到复杂内容时才升级到高质量模型，整体成本降了将近七成。

权重分配（weighted-routing）：你给每个模型配一个权重，litellm按权重随机分配。这个策略适合做A/B测试或者灰度发布。比如新模型上线，先给它10%的流量，观察一周没问题再逐步加量。

配置方式是在model_list里给同一个model_name配多个条目，然后设置routing_strategy。这里有个细节：如果你用的是延迟优先策略，litellm默认会做冷却处理——某个模型连续失败几次后，会被暂时移出候选列表，过一段时间再重新尝试。这个冷却时间可以通过cooldown_time参数调整，默认是60秒。我在实际使用中发现，对于偶尔抽风的API，这个机制能有效避免请求堆积在故障节点上。

3.3 回退与重试：让调用链更健壮

多模型调用的一个核心价值就是容错。litellm的Router支持配置fallbacks，当主模型调用失败时，自动切换到备用模型。配置大概是这样：

router_settings: fallbacks: [{"fast-model": ["backup-model"]}] num_retries: 2 retry_after: 1

这段配置的意思是：当"fast-model"调用失败时，自动尝试"backup-model"；每个模型最多重试2次，重试间隔1秒。我建议把fallbacks设计成链式结构，比如主模型失败切到备用模型，备用模型再失败切到本地模型，形成三级保险。

但这里有个坑要注意：不是所有错误都适合重试。比如认证失败（401）或者请求格式错误（400），重试多少次都没用，反而浪费时间和配额。litellm默认会对所有异常做重试，你需要在代码里判断异常类型，对不可重试的错误直接抛出。我通常会在外层包一个try-except，捕获litellm.exceptions.AuthenticationError和litellm.exceptions.BadRequestError，这两类直接记录日志并告警，不走重试逻辑。

注意：回退机制会增加整体延迟。如果主模型的超时设置是30秒，回退模型也要30秒，最坏情况下用户要等60秒才能拿到结果。我的做法是把主模型超时设短一些（比如15秒），回退模型设长一些，同时在业务层加一个总超时控制。

4. 成本追踪与预算控制：把每一分钱都算清楚

4.1 Token计数与成本计算的内置逻辑

litellm内置了一个成本计算模块，每次调用完成后，它会根据返回的usage字段（包含prompt_tokens和completion_tokens）乘以对应模型的价格，算出这次调用的花费。价格数据维护在litellm的源码里，覆盖了大部分主流模型。你可以通过litellm.completion_cost(response)这个函数直接拿到本次调用的成本。

这个功能看起来简单，但实际用起来有几个细节值得注意。第一，流式调用的成本计算。流式模式下，usage字段可能不会在最后一个chunk里返回，litellm需要自己累计Token数量。我实测下来，大部分Provider的流式响应都能正确计算，但个别Provider的chunk里不带usage信息，这时候litellm会用一个估算值，准确度会打折扣。如果你对成本精度要求高，建议在流式场景下额外做一次非流式的Token计数校验。

第二，缓存命中的成本。有些Provider对缓存命中的Token收费更低，litellm的成本计算会区分cache_creation_input_tokens和cache_read_input_tokens，分别按不同单价计算。这个细节在官方文档里写得比较隐蔽，但如果你用到了Prompt Caching功能，一定要确认成本计算是否正确。

第三，自定义模型的价格。如果你用的是litellm官方价格表里没有的模型（比如自己微调后部署的模型），需要手动注册价格：

from litellm import register_model register_model({ "my-custom-model": { "input_cost_per_token": 0.000001, "output_cost_per_token": 0.000002, "litellm_provider": "openai", "mode": "chat" } })

注册之后，成本计算和预算控制就能正常工作了。

4.2 预算限制与告警：避免账单失控

litellm的Router支持给每个模型或每个用户设置预算上限。配置方式是在model_list里加max_budget参数，或者在Router初始化时设置budget_duration（比如"30d"表示30天）。当累计花费超过预算时，litellm会抛出BudgetExceededError，你可以捕获这个异常做降级处理。

我在一个面向内部团队的AI工具里用了这个功能。每个团队每月有固定的Token预算，超了之后自动切换到更便宜的模型，同时给管理员发告警。实现方式是在Router配置里给每个团队建一个虚拟Key，绑定预算和模型列表。litellm的虚拟Key机制支持细粒度的权限控制，比如限制只能调用某几个模型、限制每分钟请求数、限制总Token数。

这里有个经验：预算检查是在请求发出前做的，但成本是在请求完成后才计算的。这意味着如果预算刚好在边界上，可能会出现"最后一次调用超预算"的情况。对于预算敏感的场景，我建议把max_budget设得比实际预算低10%左右，留出缓冲空间。

4.3 成本数据的导出与分析

litellm支持把每次调用的成本数据写入回调函数，你可以对接自己的监控系统。常用的回调包括success_callback和failure_callback，前者在调用成功时触发，后者在失败时触发。回调函数接收完整的请求和响应对象，你可以从中提取模型名、Token数、成本、延迟等指标，写入数据库或时序数据库。

我自己的做法是用success_callback把数据写到本地的SQLite里，然后用一个简单的看板做可视化。关键指标包括：每个模型的日均调用次数、平均延迟、平均成本、错误率。这些数据对于后续的模型选型和路由策略调整非常有价值。比如我发现某个模型虽然单价便宜，但错误率高导致重试成本反而更贵，就把它从主路由里移除了。

5. 流式输出与异步调用：性能优化的关键细节

5.1 流式响应的统一处理

流式输出是对话类应用的标配，litellm对流的支持做得比较到位。你只需要在completion里加stream=True，返回的就是一个生成器，每次迭代拿到一个chunk。chunk的结构和OpenAI一致，chunk.choices[0].delta.content就是增量文本。

但不同Provider的流式实现差异很大。有的Provider会在第一个chunk里返回role字段，有的不会；有的Provider的结束标志是finish_reason="stop"，有的是[DONE]标记；有的Provider在流式模式下不返回usage信息。litellm在内部做了归一化处理，把大部分差异抹平了，但我在实际使用中还是遇到过两个问题。

第一个问题是流式模式下的错误处理。如果请求发出后、流开始之前就出错了（比如认证失败），litellm会直接抛异常，这个好处理。但如果流已经开始、中途出错（比如网络中断），异常会在迭代过程中抛出，你需要用try-except包住整个迭代循环。我建议在流式场景下加一个"心跳检测"——如果超过N秒没有收到新chunk，就主动断开并触发回退。

第二个问题是流式模式下的Token计数。前面提到过，部分Provider不返回usage，litellm会用估算值。如果你需要精确的Token计数，可以在流结束后用litellm.token_counter函数重新计算一遍。这个函数支持传入model和messages，返回精确的Token数。虽然多了一次计算，但对于成本敏感的场景是值得的。

5.2 异步并发：用acompletion提升吞吐

litellm提供了异步版本的acompletion，配合asyncio可以大幅提升并发吞吐。我做过一个对比测试：同样的100个请求，同步串行执行耗时约120秒，用asyncio.gather并发执行（并发数20）耗时不到8秒，提升非常明显。

异步调用的代码结构大概是这样：

import asyncio import litellm async def call_model(prompt): response = await litellm.acompletion( model="deepseek/deepseek-chat", messages=[{"role": "user", "content": prompt}] ) return response.choices[0].message.content async def main(): prompts = ["问题1", "问题2", "问题3"] tasks = [call_model(p) for p in prompts] results = await asyncio.gather(*tasks) return results asyncio.run(main())

这里有个坑：并发数不是越高越好。大部分Provider都有速率限制（Rate Limit），并发太高会触发429错误。litellm的Router支持配置rpm（每分钟请求数）和tpm（每分钟Token数）限制，超过限制的请求会自动排队。我建议根据Provider的实际限制来设置并发数，一般从10开始试，逐步往上加，观察错误率。

另外，异步模式下如果某个请求失败，asyncio.gather默认会抛出异常并取消其他任务。如果你希望部分失败不影响整体，可以加return_exceptions=True参数，这样失败的请求会返回异常对象而不是抛出。我在批量处理场景下会用这个模式，最后统一统计成功和失败的数量。

5.3 超时与重试的配合策略

超时设置是异步调用里最容易出问题的地方。litellm的completion和acompletion都支持timeout参数，单位是秒。但要注意，这个超时是单次请求的超时，如果配置了重试，总耗时可能是timeout × (num_retries + 1)。

我的经验是分两层设置超时：第一层是litellm的timeout，设得短一些（比如15秒），让快速失败的请求尽快触发重试或回退；第二层是业务层的总超时，用asyncio.wait_for包住整个调用链，设得长一些（比如45秒），防止无限等待。这样既能快速响应故障，又能给重试留出空间。

还有一个细节：流式调用的超时行为和非流式不同。非流式调用是在整个响应返回后判断超时，流式调用是在每个chunk之间判断。这意味着如果模型生成很慢但一直在输出，流式调用不会超时，而非流式调用可能已经超时了。对于长文本生成场景，流式调用在超时控制上更友好。

6. 踩坑实录：那些文档里不会写的细节

6.1 模型名映射的隐藏规则

litellm的模型名解析有一套隐藏规则，官方文档没有完整列出，但实际使用中经常遇到。比如model="gpt-4o"不带前缀时，litellm会默认按OpenAI处理；model="claude-3-sonnet"不带前缀时，会按Anthropic处理。这个"默认推断"机制在简单场景下很方便，但在多Provider环境下容易出问题。

我遇到过一个典型案例：项目里同时用了某国内平台的模型和某海外平台的模型，两个模型的名称恰好有重叠。不带前缀调用时，litellm推断错了Provider，导致认证失败。排查了半天才发现是模型名解析的问题。从那以后，我要求团队里所有litellm调用必须带Provider前缀，不允许依赖默认推断。这个规则写进了代码规范，虽然多打几个字符，但避免了大量隐性Bug。

另一个相关问题是模型名的版本后缀。有些Provider的模型名带日期后缀（比如gpt-4-0613），有些带版本号（比如claude-3-5-sonnet-20241022）。litellm的价格表和能力表是按具体版本维护的，如果你用的版本号不在表里，成本计算和能力判断可能会出错。我的做法是定期检查litellm的版本更新，新模型发布后及时升级库版本。

6.2 认证信息的传递陷阱

litellm支持多种认证方式，但不同Provider的认证参数名不一样。OpenAI用api_key，Azure用api_key加api_base和api_version，AWS Bedrock用aws_access_key_id和aws_secret_access_key。这些参数可以直接传给completion函数，也可以通过环境变量。

我踩过的一个坑是环境变量名冲突。项目里同时用了OpenAI和Azure OpenAI，两者都需要api_key，但环境变量名不同（OPENAI_API_KEY和AZURE_API_KEY）。litellm在解析时会根据model前缀选择对应的环境变量，这个逻辑本身没问题。但有一次我在代码里手动传了api_key参数，litellm优先使用了手动传的值，导致Azure的请求用了OpenAI的Key，报了个莫名其妙的认证错误。排查了很久才定位到是参数覆盖的问题。

经验总结：手动传参和环境变量不要混用。要么全部走环境变量，要么全部手动传，保持一致。如果确实需要混用，一定要在代码注释里写清楚每个参数的来源，避免后续维护时踩坑。

6.3 流式与非流式返回结构的差异

虽然litellm尽力统一了返回结构，但流式和非流式之间还是有一些细微差异。非流式返回的response.choices[0].message是一个完整的消息对象，包含content、role、tool_calls等字段。流式返回的每个chunk里，delta对象可能只包含部分字段——第一个chunk可能有role，中间的chunk只有content，最后一个chunk有finish_reason。

如果你写的解析代码假设每个chunk都有完整字段，就会出问题。我见过有开发者用chunk.choices[0].delta.content直接拼接，结果遇到第一个chunk（只有role没有content）时报NoneType错误。正确的做法是用getattr或者判断字段是否存在：

for chunk in response: delta = chunk.choices[0].delta if hasattr(delta, "content") and delta.content: print(delta.content, end="")

还有一个差异是工具调用（Function Calling）的流式返回。非流式模式下，tool_calls是一个完整的数组；流式模式下，tool_calls是分片返回的，需要自己拼接。litellm提供了一个辅助函数litellm.stream_chunk_builder来简化这个拼接过程，但我在实际使用中发现它对某些Provider的兼容性不够好，最后还是自己写了一个拼接逻辑。

6.4 错误码的跨Provider差异

不同Provider的错误码语义不完全一致。比如同样是429，OpenAI表示速率限制，某国内平台可能表示配额耗尽。litellm在内部做了一层错误码映射，把常见的错误归类为RateLimitError、AuthenticationError、BadRequestError等。但这个映射不是100%准确，个别Provider的特殊错误码可能被归类到APIError这个通用类别里。

我的处理策略是：对litellm的标准异常做通用处理，对未识别的异常做兜底处理。具体来说，捕获RateLimitError时做退避重试，捕获AuthenticationError时告警并停止重试，捕获APIError时记录完整的错误信息（包括原始响应体），方便后续分析。litellm的异常对象里有一个original_exception属性，可以拿到Provider返回的原始错误信息，这个在排查问题时非常有用。

7. 生产环境部署的几点实战建议

7.1 代理模式：把litellm做成独立服务

litellm除了作为Python库使用，还提供了一个代理服务器模式。你可以用一条命令启动一个HTTP服务，对外暴露OpenAI兼容的接口，所有请求由这个服务转发到后端的不同Provider。这个模式适合多语言技术栈的团队——比如你的主业务是Java写的，不想为了调用LLM专门引入Python依赖，就可以用litellm代理做中间层。

启动命令大概是这样：

litellm --config config.yaml --port 8000

启动后，任何支持OpenAI接口的客户端都可以把base_url指向这个服务。代理模式还自带了一个管理界面，可以查看调用日志、成本统计、模型状态。我在一个多团队协作的项目里用了这个模式，每个团队用自己的虚拟Key调用，管理员在界面上统一管理预算和权限，省去了很多沟通成本。

代理模式的性能开销不大，我实测下来单次请求的额外延迟在5到10毫秒左右，对于大部分应用来说可以忽略。但如果你的QPS很高（比如上千），建议做水平扩展，用Nginx做负载均衡。

7.2 日志与可观测性

生产环境一定要打开litellm的日志功能。litellm支持设置litellm.set_verbose = True来输出详细日志，但这个日志量很大，只适合调试时用。生产环境建议用回调机制，把关键指标写到自己的监控系统。

我关注的指标包括：每个模型的P50/P95/P99延迟、错误率、每分钟Token消耗量、成本趋势。这些指标可以帮助你判断：某个模型是否在退化、路由策略是否需要调整、预算是否要重新分配。litellm的回调函数是异步执行的，不会阻塞主请求，但要注意回调函数本身不要做太重的操作，否则会拖慢整体性能。

还有一个细节：日志里不要记录完整的请求和响应内容。LLM的请求和响应可能包含敏感信息，记录到日志里有合规风险。我通常只记录Token数、模型名、延迟、状态码这些元数据，内容本身不落盘。

7.3 版本升级的注意事项

litellm的迭代速度很快，几乎每周都有新版本。新版本会加入新模型支持、修复Bug、调整价格表，但也可能引入不兼容的变更。我的升级策略是：小版本跟紧，大版本谨慎。比如从1.30升级到1.31，一般可以直接升；从1.x升级到2.x，先看Changelog里有没有Breaking Change，然后在测试环境跑一遍回归测试。

升级后重点检查三件事：模型价格表是否更新（影响成本计算）、异常类型是否有变化（影响错误处理逻辑）、返回结构是否有调整（影响解析代码）。我一般会在升级后跑一个包含各种边界情况的测试用例集，确认没问题再上生产。

8. 一些个人体会

litellm这个库我用了快一年，最大的感受是它把"多模型调用"这件事的复杂度从业务层转移到了基础设施层。以前每接一个新模型，都要写一套适配代码、测一遍边界情况；现在只需要在配置里加一行，业务代码完全不动。这种"一次接入、随处切换"的能力，在模型快速迭代的当下特别有价值。

但它也不是银弹。litellm的统一接口是"最大公约数"，某些Provider的独有功能（比如某家特有的结构化输出格式、某家特有的缓存机制）可能无法通过litellm直接使用。遇到这种情况，我的做法是：通用功能走litellm，独有功能直接调原生SDK，两者共存。不要为了追求"全部统一"而放弃Provider的独有能力。

另外，litellm的文档虽然覆盖面广，但细节深度不够，很多参数的实际行为需要看源码或者自己测试才能确认。我建议在使用前先花半天时间把核心模块的源码翻一遍，特别是litellm/main.py和litellm/router.py这两个文件，看完之后对它的工作机制会有更清晰的认识，遇到问题也能更快定位。

最后分享一个小技巧：如果你不确定某个模型是否被litellm支持，可以用litellm.get_supported_openai_params(model="模型名")这个函数查一下。它会返回该模型支持的OpenAI参数列表，如果返回空列表或者报错，说明litellm还没有适配这个模型，需要自己写Provider适配或者等社区更新。这个函数在选型阶段特别有用，能帮你快速判断技术可行性。