1. 从一个真实困境说起多模型调用为什么让人头疼如果你正在做AI应用开发大概率遇到过这样的场景产品需要同时接入好几个不同厂商的大模型有的擅长长文本理解有的在代码生成上表现突出还有的性价比高适合做批量任务。于是你的代码里开始出现各种SDK的初始化逻辑、不同的鉴权方式、五花八门的请求参数格式、各不相同的返回结构。每接一个新模型就要翻一遍文档、改一遍调用层、测一遍异常处理。更麻烦的是当你想把某个任务从A模型切换到B模型做效果对比时发现两者的调用方式完全不兼容光是适配层就得写半天。如果团队里还有其他人维护同一套代码风格不统一带来的沟通成本更是雪上加霜。这就是litellm要解决的核心问题。它本质上是一个统一的大模型调用中间层用一套OpenAI风格的接口去调用市面上几乎所有主流模型服务。你不需要为每个厂商单独写适配代码只需要改一个模型名称字符串就能在多个模型之间自由切换。对于需要做模型对比、多模型路由、成本优化的团队来说这个价值非常直接。这篇文章我会从实际使用角度出发把litellm的安装配置、核心用法、代理服务部署、成本追踪、踩坑经验完整讲一遍。不管你是刚接触大模型API调用的新手还是已经在生产环境里维护多模型接入的老手应该都能找到有用的东西。2. litellm到底做了什么统一接口的底层逻辑2.1 它解决的不是调用问题而是适配问题很多人第一次看到litellm的介绍会觉得不就是个封装库吗。但真正用起来才发现它做的事情比简单封装要深得多。大模型API调用看起来简单——发个HTTP请求传几个参数拿回结果。但实际工程中不同厂商之间的差异远比想象中大。举几个例子OpenAI的对话接口用messages数组某些厂商用prompt字符串OpenAI的返回结构里内容在choices[0].message.content有的厂商放在output.text流式返回的SSE格式各家也不完全一致函数调用Function Calling的参数定义方式更是千差万别。litellm的做法是在中间做一层标准化映射。它定义了一套统一的输入输出格式基本对齐OpenAI的规范然后在内部为每个支持的模型服务实现对应的转换逻辑。你传入统一格式的请求它负责翻译成目标厂商需要的格式拿到响应后再翻译回统一格式返回给你。这意味着你的业务代码只需要面向一套接口编程新增模型支持时只需要改配置不需要动业务逻辑。这个设计思路在工程上叫做适配器模式但litellm把它做到了足够广的覆盖面。2.2 支持的模型范围与调用方式litellm目前支持的模型服务商覆盖了国内外主流选择包括OpenAI系列、Anthropic系列、Google系列、Meta系列、Mistral系列以及国内多家厂商的模型服务。此外它还支持通过Ollama调用本地部署的模型通过HuggingFace接入开源模型。调用方式极其简洁。核心就是completion函数from litellm import completion response completion( modelgpt-4o, messages[{role: user, content: 用一句话解释什么是递归}] ) print(response.choices[0].message.content)如果要切换到另一个模型只需要改model参数response completion( modelclaude-sonnet-4-20250514, messages[{role: user, content: 用一句话解释什么是递归}] )代码结构完全不变。这就是litellm最核心的价值——用字符串切换模型用统一接口屏蔽差异。2.3 模型命名规则与自动路由litellm的模型命名有一套约定provider/model-name的格式。比如openai/gpt-4o、anthropic/claude-sonnet-4-20250514、ollama/llama3。如果你只写模型名不写前缀litellm会根据内置的映射表自动推断服务商。这个自动推断在大多数情况下够用但在一些边界场景下可能猜错。我的建议是始终显式写全前缀避免因为模型名冲突导致路由到错误的服务商。比如某些厂商的模型名称和OpenAI的很像不写前缀就容易出问题。另外litellm支持通过环境变量配置各家的API Key。比如OPENAI_API_KEY、ANTHROPIC_API_KEY等它会自动读取。这样你就不需要在代码里硬编码密钥部署时通过环境变量注入即可。3. 环境搭建与基础调用从零跑通第一个请求3.1 安装与依赖管理litellm的安装非常轻量pip install litellm如果你需要用到代理服务功能后面会详细讲可以安装带proxy的完整版pip install litellm[proxy]需要注意的是litellm本身依赖不算多但它会按需引入各厂商的SDK。如果你只用OpenAI不会安装Anthropic的包。这种按需加载的设计对部署体积比较友好。我建议在虚拟环境里安装避免和系统Python环境里的其他包产生版本冲突。特别是如果你同时用着其他AI框架依赖冲突的概率不低。3.2 API Key配置的几种方式配置密钥有三种常见方式各有适用场景第一种是环境变量适合本地开发和容器化部署export OPENAI_API_KEYyour-key-here export ANTHROPIC_API_KEYyour-key-here第二种是代码里直接传参适合快速测试response completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}], api_keyyour-key-here )第三种是通过配置文件适合代理服务模式。这个后面讲代理部署时再展开。注意无论用哪种方式都不要把密钥硬编码到提交到代码仓库的文件里。我见过太多因为密钥泄露导致账单暴涨的案例这个坑一定要避开。3.3 第一个完整调用示例跑通一个最小可用示例需要确认三件事模型名写对、密钥配好、网络能通。下面是一个完整的测试脚本import os from litellm import completion os.environ[OPENAI_API_KEY] your-key-here try: response completion( modelopenai/gpt-4o, messages[ {role: system, content: 你是一个简洁的助手}, {role: user, content: 用三句话介绍Python的装饰器} ], temperature0.7, max_tokens500 ) print(response.choices[0].message.content) print(f本次消耗token: {response.usage.total_tokens}) except Exception as e: print(f调用失败: {e})这段代码里几个关键点值得说明。temperature控制输出的随机性0.7适合大多数对话场景max_tokens限制输出长度防止意外产生超长响应导致费用失控response.usage里包含了token消耗统计这是做成本追踪的基础数据。3.4 流式输出的处理方式对话类应用通常需要流式输出让用户看到逐字生成的效果。litellm的流式调用也很直接response completion( modelopenai/gpt-4o, messages[{role: user, content: 写一首关于秋天的短诗}], streamTrue ) for chunk in response: content chunk.choices[0].delta.content if content: print(content, end, flushTrue)这里有个细节要注意流式返回的每个chunk里delta.content可能是None比如第一个chunk通常只包含role信息。不做判空处理会报错。另外流式模式下usage统计默认不返回需要显式设置stream_options{include_usage: True}才能拿到token消耗数据。4. 代理服务模式把litellm变成团队共用的网关4.1 为什么需要代理模式如果你只是个人项目里用litellm直接import调用就够了。但如果是团队协作场景代理模式的价值就体现出来了。代理模式是把litellm跑成一个独立的HTTP服务对外暴露OpenAI兼容的API接口。团队成员不需要在各自的项目里安装litellm、配置各家密钥只需要把请求指向这个代理服务就行。密钥统一在服务端管理调用日志统一记录成本统一追踪模型列表统一维护。这个架构特别适合以下场景多个项目共用多个模型服务、需要统一管控API密钥、需要做调用审计和成本分摊、需要在不改业务代码的前提下切换底层模型。4.2 配置文件的结构与关键字段代理服务的核心是一个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 - model_name: local-llama litellm_params: model: ollama/llama3 api_base: http://localhost:11434 general_settings: master_key: sk-your-master-key database_url: os.environ/DATABASE_URLmodel_list定义了对外暴露的模型名称和实际路由目标。注意model_name是对外名称客户端请求时用的就是这个litellm_params.model是实际的服务商标识。两者可以不同这给了你一层抽象——客户端看到的是gpt-4o你可以在后端随时把它指向不同的实际模型。general_settings里的master_key是代理服务的访问密钥客户端需要带上这个key才能调用。database_url用于持久化调用日志和成本数据支持PostgreSQL等数据库。4.3 启动服务与客户端接入启动代理服务litellm --config config.yaml --port 4000启动后代理服务监听4000端口提供OpenAI兼容的接口。客户端调用方式from openai import OpenAI client OpenAI( api_keysk-your-master-key, base_urlhttp://localhost:4000 ) response client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] )注意这里用的是标准OpenAI SDK只是把base_url指向了代理服务。这意味着任何已经用OpenAI SDK的项目只需要改一个base_url就能接入迁移成本几乎为零。4.4 多实例部署与负载均衡生产环境下单个代理实例可能扛不住高并发。litellm支持在配置里为同一个model_name配置多个后端实例自动做负载均衡model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_1 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_2两个配置项的model_name相同litellm会自动在它们之间轮询。这既能分摊并发压力也能在某一个key触发限流时自动切换到另一个。实操心得负载均衡策略可以通过router_settings调整支持轮询、加权、最低延迟等多种模式。如果你的多个后端延迟差异大用最低延迟模式体验会好很多。5. 成本追踪与预算控制让每一分钱都花得明白5.1 token统计的获取方式成本控制的前提是能准确统计消耗。litellm在每次调用的响应里都会返回usage信息response completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}] ) print(response.usage.prompt_tokens) # 输入token数 print(response.usage.completion_tokens) # 输出token数 print(response.usage.total_tokens) # 总token数对于流式调用需要显式开启usage统计response completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}], streamTrue, stream_options{include_usage: True} )最后一个chunk里会包含完整的usage数据。这个细节很容易被忽略导致流式场景下成本统计缺失。5.2 内置成本计算与自定义价格litellm内置了主流模型的价格表可以自动把token消耗换算成费用from litellm import completion_cost response completion( modelopenai/gpt-4o, messages[{role: user, content: 你好}] ) cost completion_cost(completion_responseresponse) print(f本次调用费用: ${cost:.6f})如果你用的是自定义部署的模型或者内置价格表没有覆盖的模型可以在配置里手动指定价格model_list: - model_name: my-custom-model litellm_params: model: openai/my-model input_cost_per_token: 0.000001 output_cost_per_token: 0.000002这个功能在做成本对比时特别有用。你可以用同一批请求跑不同模型直接对比费用差异为选型提供数据支撑。5.3 预算限制与告警配置代理模式下可以设置预算上限超过阈值自动拒绝请求general_settings: max_budget: 100 budget_duration: 30d这表示30天内总预算100美元超出后拒绝新请求。对于团队共用场景还可以按用户或按key设置独立预算避免某个项目把整体额度用光。注意预算控制是硬限制触发后请求会直接失败。生产环境建议配合告警使用在接近阈值时提前通知而不是等到请求被拒才发现。6. 踩坑实录那些文档里不会写的细节6.1 模型名称写错导致的诡异报错最常见的问题就是模型名写错。litellm的报错信息有时候不够直观比如你把anthropic/claude-sonnet-4-20250514写成了anthropic/claude-sonnet-4可能得到一个model not found的错误但不会告诉你正确的名称是什么。我的做法是先用litellm提供的模型列表接口确认可用名称from litellm import model_list print(model_list)或者在代理模式下访问/models接口获取完整列表。养成先查再写的习惯能省下不少排查时间。6.2 超时与重试的默认行为litellm默认有重试机制但默认参数不一定适合所有场景。我遇到过因为默认超时太短长文本生成任务频繁失败的情况。解决办法是显式设置超时和重试次数response completion( modelopenai/gpt-4o, messages[{role: user, content: 写一篇2000字的文章}], timeout120, num_retries3 )timeout单位是秒长文本任务建议设大一些。num_retries控制失败重试次数但要注意重试会重复计费对于已经产生部分输出的请求要谨慎。6.3 不同模型对参数的支持差异虽然litellm做了统一接口但不同模型对参数的支持程度不同。比如某些模型不支持temperature某些不支持top_p某些对max_tokens有上限要求。传入不支持的参数时有的厂商会报错有的会静默忽略。litellm的做法是尽量做参数映射但无法保证100%兼容。我的经验是先用最小参数集跑通再逐步添加参数测试。如果某个参数在切换模型后报错先去掉它确认问题来源。6.4 代理模式下的并发瓶颈代理服务默认是单进程运行的。在高并发场景下可能会成为瓶颈。解决办法是用多worker模式启动litellm --config config.yaml --port 4000 --num_workers 4或者用gunicorn等WSGI服务器托管。具体worker数量根据CPU核心数和请求特征调整。IO密集型的场景可以多开一些CPU密集型的则要控制数量避免上下文切换开销。7. 进阶玩法路由策略、缓存与可观测性7.1 基于规则的路由策略litellm支持根据请求内容自动路由到不同模型。比如根据问题长度、关键词、用户等级等条件选择模型。这个功能在成本优化上很有价值——简单问题用便宜模型复杂问题用强模型。配置方式是在model_list里定义路由规则或者在代码里用Router类做更灵活的控制。实际使用中我建议先从简单的场景开始比如按token长度分流验证效果后再逐步细化规则。7.2 响应缓存减少重复调用对于重复性高的请求比如相同的FAQ问答开启缓存可以显著降低成本。litellm支持内存缓存和Redis缓存两种模式litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379缓存命中时直接返回历史结果不产生API调用费用。但要注意缓存的有效期设置——对于时效性强的场景比如查询实时数据缓存时间要设短一些。7.3 调用日志与可观测性代理模式下所有调用都会记录到数据库。可以查询每次调用的模型、token消耗、费用、延迟、状态等信息。这些数据对于排查问题、优化成本、分析使用模式都很有价值。如果团队有现成的可观测性平台litellm也支持把日志推送到外部系统。具体集成方式参考官方文档的callback配置部分。8. 我个人的使用建议用litellm有一段时间了最大的感受是它确实解决了多模型接入的痛点但也不是银弹。几点体会分享出来第一不要为了统一而统一。如果你的项目只用一家模型服务直接用它官方SDK可能更简单。litellm的价值在多模型场景下才体现得明显。第二代理模式适合团队直调模式适合个人。团队协作时代理模式的统一管理优势很大但个人项目直接import更轻量。第三成本追踪要尽早做。很多人是等到账单出来才发现费用超预期。litellm的usage统计和成本计算功能用起来不复杂建议一开始就接上。第四版本升级要谨慎。litellm迭代很快新版本可能引入不兼容变更。生产环境升级前先在测试环境验证确认关键功能正常再上线。第五配置文件要纳入版本管理。代理模式的YAML配置是核心资产模型列表、路由规则、预算设置都在里面。用Git管理起来变更可追溯回滚也方便。最后说一个实际使用中的小技巧如果你需要频繁在多个模型之间做效果对比可以写一个简单的批量测试脚本用同一组prompt跑不同模型把结果和成本数据汇总成表格。这个脚本用litellm实现起来非常快对于选型决策帮助很大。
