1. 从一个真实困境说起多模型调用的碎片化之痛如果你正在做AI应用开发大概率遇到过这样的场景项目初期用OpenAI的接口跑通了原型效果不错上线后老板说“能不能换成国产模型降降成本”你打开代码一看发现业务逻辑里到处散落着openai.ChatCompletion.create的调用参数格式、返回结构、错误码全是绑死的。换一个模型供应商几乎等于把整个调用层重写一遍。更麻烦的是当你想同时接入多家模型做对比测试、做降级容灾、或者根据任务类型路由到不同模型时每家的SDK认证方式不同、请求体结构不同、流式输出的chunk格式不同、甚至同一个概念比如“系统提示词”在不同API里的字段名都不一样。这种碎片化带来的维护成本在项目规模稍微大一点之后就会指数级上升。LiteLLM就是冲着这个痛点来的。它的核心定位可以用一句话概括用一套OpenAI格式的接口调用市面上几乎所有主流大模型服务。你写一次调用代码改一个字符串参数就能切换模型供应商不用改业务逻辑不用重新学一套SDK。这篇文章我会从实际使用的角度把LiteLLM的安装配置、核心用法、代理服务部署、成本追踪、踩坑经验完整讲一遍适合已经有一定Python基础、正在做AI应用开发、被多模型调用折磨过的朋友。2. LiteLLM到底解决了什么问题统一接口的底层逻辑2.1 它不是一个模型而是一层翻译中间件很多人第一次看到LiteLLM的名字会误以为它是一个新的大模型其实完全不是。LiteLLM是一个Python库加一个可选的代理服务它做的事情是在你的代码和各家模型API之间加了一层适配层。你调用LiteLLM的函数LiteLLM负责把你的请求翻译成对应供应商能理解的格式发出去拿到响应后再翻译回OpenAI格式返回给你。这个设计思路和数据库领域的ORM对象关系映射非常像。你用SQLAlchemy写代码的时候不需要关心底层是MySQL还是PostgreSQLLiteLLM让你不需要关心底层是GPT还是Claude还是通义千问。这个类比我觉得是最容易理解的。2.2 统一接口带来的三个直接收益第一个收益是代码可移植性。你的业务代码只依赖LiteLLM的接口模型供应商变成一个配置项。今天用A模型明天想换成B模型做A/B测试改一行model参数就行。第二个收益是降级容灾变得简单。LiteLLM内置了fallback机制你可以配置一个模型列表当主模型调用失败超时、限流、服务不可用时自动切换到备用模型。这个在线上环境非常实用我自己就遇到过某家服务在高峰期频繁超时的情况有了fallback至少保证业务不中断。第三个收益是成本追踪和预算控制。LiteLLM会自动计算每次调用的token消耗和对应费用支持设置预算上限超出后自动拒绝请求。对于需要控制AI调用成本的项目来说这个功能省去了自己搭建计费系统的麻烦。2.3 支持范围与版本选择建议LiteLLM支持的模型供应商数量一直在增长目前覆盖了OpenAI、Anthropic、Google Gemini、Cohere、Mistral、Meta Llama系列通过各托管平台、以及国内多家主流模型服务。具体支持列表建议直接看官方文档的providers页面因为更新频率很高我这里列出来很快就会过时。版本选择上我的建议是如果你只是想在Python项目里用统一接口调模型装litellm基础包就够了如果你需要部署一个统一的API网关给多个项目或团队用那需要用到litellm[proxy]它会额外安装FastAPI、Uvicorn等依赖。Python版本建议3.9以上3.11体验最好。3. 环境搭建与最小可用示例十分钟跑通第一个调用3.1 安装与密钥配置的几种方式安装本身很简单pip install litellm如果你要用代理模式pip install litellm[proxy]密钥配置是新手最容易卡住的地方。LiteLLM读取密钥的方式遵循各家SDK的环境变量约定比如OpenAI的密钥读OPENAI_API_KEYAnthropic的读ANTHROPIC_API_KEY。你可以直接在shell里export也可以用.env文件配合python-dotenv加载。注意不要把密钥硬编码在代码里然后提交到代码仓库。我见过不止一个项目因为这事导致密钥泄露被刷爆额度。用环境变量或者密钥管理服务这是底线。如果你用的是国内模型服务很多也兼容OpenAI的接口格式这种情况下可以通过设置api_base参数指向对应的服务地址密钥用OPENAI_API_KEY这个环境变量名传入即可。具体每个供应商的环境变量名官方文档有对照表。3.2 第一个调用从OpenAI格式到多模型切换最基础的调用长这样from litellm import completion import os os.environ[OPENAI_API_KEY] your-key-here response completion( modelgpt-4o, messages[ {role: user, content: 用一句话解释什么是统一接口} ] ) print(response.choices[0].message.content)看到没有这个调用格式和OpenAI官方SDK几乎一模一样。现在关键来了如果你想换成Clauderesponse completion( modelclaude-3-5-sonnet-20241022, messages[ {role: user, content: 用一句话解释什么是统一接口} ] )只改了model参数其他代码一行没动。这就是LiteLLM的核心价值。模型命名规则一般是provider/model-name的格式但OpenAI的模型可以省略provider前缀直接写模型名。3.3 流式输出与异步调用的写法差异流式输出是现在AI应用的标配LiteLLM的流式写法和OpenAI一致response completion( modelgpt-4o, messages[{role: user, content: 写一首关于编程的短诗}], streamTrue ) for chunk in response: content chunk.choices[0].delta.content if content: print(content, end, flushTrue)异步版本用acompletion配合asyncio使用。这里有个实际经验如果你在做Web服务强烈建议用异步版本否则每个请求都阻塞一个线程并发量稍微上来就扛不住。异步版本的流式处理需要用async for来迭代。4. 代理模式部署实战把统一接口变成团队共享服务4.1 什么时候需要上代理模式如果你只是个人项目或者单个Python应用直接用SDK就够了。但如果你面临以下情况代理模式就值得上了多个项目/多个语言的技术栈都需要调模型不想每个项目都配一遍密钥和适配逻辑需要统一的密钥管理和访问控制不想把真实密钥散落在各个项目里需要集中查看所有项目的调用量和成本。代理模式本质上是LiteLLM帮你起了一个FastAPI服务对外暴露OpenAI兼容的HTTP接口。任何能用OpenAI SDK的客户端把base_url指向这个代理服务就能用。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-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: qwen-plus litellm_params: model: openai/qwen-plus api_base: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: os.environ/DASHSCOPE_API_KEY litellm_settings: drop_params: true set_verbose: false general_settings: master_key: sk-your-master-key database_url: postgresql://user:passlocalhost:5432/litellm这里有几个字段值得展开说。model_name是对外暴露的名称客户端调用时用这个名称litellm_params.model是实际路由到的模型格式是provider/model。drop_params: true这个设置很实用它的作用是当某个供应商不支持你传入的某个参数时自动丢弃而不是报错。比如你传了OpenAI特有的参数给一个不支持的模型没有这个设置会直接报错。master_key是代理服务的管理密钥客户端调用时需要带上。database_url是可选的配了之后才能使用预算控制、用量统计等需要持久化的功能。4.3 启动服务与客户端接入验证启动命令litellm --config config.yaml --port 4000启动后用curl验证一下curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-master-key \ -d { model: gpt-4o, messages: [{role: user, content: 测试一下}] }Python客户端接入from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-your-master-key ) response client.chat.completions.create( modelclaude-sonnet, messages[{role: user, content: 你好}] )注意这里用的是OpenAI官方SDK只是把base_url改了。这意味着你现有的基于OpenAI SDK的代码几乎不用改就能接入。提示生产环境部署时代理服务前面建议加一层反向代理处理HTTPS和限流。LiteLLM本身也支持配置多个worker通过--num_workers参数指定。5. 成本追踪、预算控制与降级策略的落地细节5.1 费用是怎么算出来的LiteLLM内置了一个模型价格表每次调用后根据输入输出token数乘以对应单价算出费用。这个价格表会随官方更新但如果你用的是自定义部署的模型或者价格表里没有的模型需要手动配置价格。手动配置的方式是在litellm_params里加input_cost_per_token和output_cost_per_token- model_name: my-custom-model litellm_params: model: openai/my-model api_base: http://my-endpoint/v1 input_cost_per_token: 0.000001 output_cost_per_token: 0.000002费用数据会记录在数据库里可以通过代理的/spend/logs接口查询也可以在管理UI里看。管理UI的地址是http://localhost:4000/ui用master_key登录。5.2 给不同团队或项目设置预算上限这是代理模式相比直接用SDK的一个明显优势。你可以创建多个虚拟密钥每个密钥绑定不同的预算curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o, claude-sonnet], max_budget: 100, budget_duration: 30d, key_alias: team-a-key }这个接口会返回一个新的密钥团队A用这个密钥调用30天内累计消费超过100美元后就会被拒绝。models字段限制了这把密钥能访问哪些模型避免越权调用贵的模型。5.3 fallback配置主模型挂了怎么办fallback的配置在litellm_settings里litellm_settings: fallbacks: [{gpt-4o: [claude-sonnet, qwen-plus]}]这个配置的意思是当gpt-4o调用失败时依次尝试claude-sonnet和qwen-plus。触发fallback的条件包括超时、限流、服务端错误等。我自己的经验是fallback的备用模型最好选不同供应商的否则同一家服务整体故障时备用也没用。另外要注意fallback会增加响应延迟因为要等主模型失败才会切换所以超时时间不要设太长一般10-30秒比较合理。6. 踩坑实录那些文档里不会写的实际问题6.1 参数兼容性drop_params不是万能的前面提到drop_params: true可以自动丢弃不支持的参数但实际用下来发现它只对部分参数有效。比如你把OpenAI的response_format传给一个不支持的模型即使开了drop_params也可能报错。我的做法是在业务层做参数适配根据目标模型的能力决定传哪些参数而不是完全依赖LiteLLM的自动处理。另一个常见问题是temperature的取值范围。OpenAI是0到2但有些模型只支持0到1。传了超出范围的值有的供应商会报错有的会静默截断。这个没有统一解法只能在使用新模型前先做一轮参数测试。6.2 流式输出中token计数不准的情况流式模式下LiteLLM默认可能拿不到完整的usage信息因为很多供应商在流式响应里不返回token统计。这会导致费用计算偏低甚至为零。解决办法是开启stream_optionsresponse completion( modelgpt-4o, messages[...], streamTrue, stream_options{include_usage: True} )但注意不是所有供应商都支持这个参数。对于不支持的LiteLLM会尝试用tiktoken在本地估算token数估算结果和实际会有偏差做成本核算时心里要有数。6.3 超时设置与重试策略的平衡LiteLLM支持配置超时和重试response completion( modelgpt-4o, messages[...], timeout30, num_retries2 )这里有个坑重试和fallback叠加使用时总等待时间可能很长。比如超时30秒、重试2次、再fallback到另一个模型又超时30秒重试2次最坏情况下用户要等两分钟。我的建议是重试次数不要超过1次把更多精力放在fallback的模型选择上让备用模型尽快接管。6.4 国内模型接入时的api_base陷阱国内很多模型服务兼容OpenAI接口但兼容程度参差不齐。最常见的问题是api_base的路径。有的服务要求写完整的/v1/chat/completions路径有的只需要写到/v1LiteLLM会自动补全。如果调用报404先检查这个路径。还有一个问题是SSL证书验证。部分自建或私有部署的模型服务用的是自签名证书Python的requests库默认会拒绝。可以通过设置环境变量REQUESTS_CA_BUNDLE指向证书文件或者在LiteLLM参数里传ssl_verifyFalse仅限内网可信环境使用。7. 把LiteLLM用好的几个进阶思路7.1 基于任务类型的模型路由LiteLLM代理支持根据请求内容路由到不同模型。比如简单的分类任务路由到便宜的小模型复杂的推理任务路由到贵的大模型。这个可以通过自定义路由逻辑实现在配置文件里用model_name做别名然后在业务层根据任务类型选择不同的别名。我自己的做法是在业务代码里封装一个get_model_for_task(task_type)函数返回对应的模型别名这样路由逻辑集中在一处调整起来方便。7.2 缓存层减少重复调用LiteLLM支持Redis缓存相同的请求在一定时间内直接返回缓存结果不重复调用模型。对于问答类、客服类场景用户问的问题重复率其实不低缓存能省下可观的费用。配置方式是在litellm_settings里加litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379 ttl: 3600ttl是缓存过期时间单位秒。设太长会导致答案过时设太短起不到省钱效果一般1小时是个折中。7.3 日志与可观测性接入代理模式支持把调用日志推送到各种可观测性平台。即使不接外部平台至少要把日志落到数据库方便出问题时排查。database_url配好之后所有请求的详细信息模型、token数、费用、延迟、状态都会记录。我建议额外记录请求的业务标识比如用户ID、会话ID这样排查问题时能快速定位到具体是哪个用户的哪次调用出了问题。这个可以通过在请求的metadata里传自定义字段实现。7.4 版本升级的注意事项LiteLLM迭代很快几乎每周都有新版本。升级前一定要看changelog特别关注breaking changes。我遇到过升级后配置文件字段改名导致服务起不来的情况。建议的做法是在测试环境先升级验证确认没问题再上生产。另外锁定版本号在requirements里写litellmx.y.z比用litellmx.y.z更稳妥避免某天自动升级后出问题。8. 一些实际使用中的体会用LiteLLM有一段时间了最大的感受是它确实把多模型调用的复杂度从业务层抽离出来了。以前每接一个新模型都要翻文档、对参数、写适配代码现在大部分情况下改个配置就行。代理模式对于团队协作的价值也很明显密钥不用到处发用量和成本一目了然。但它也不是银弹。参数兼容性、流式token计数、国内服务的接口差异这些问题该踩的坑一个不少。我的建议是先用SDK模式在小项目里跑通熟悉了它的行为模式之后再上代理模式。配置项不要一次开太多drop_params、fallback、缓存这些功能逐个加上去每加一个都验证一下行为是否符合预期出问题时也容易定位是哪个配置导致的。最后分享一个小技巧LiteLLM的completion函数支持传metadata参数你可以把业务相关的信息塞进去这些信息会出现在日志里。排查线上问题时这个字段能帮你快速把一次模型调用和具体的业务请求关联起来比翻时间戳对日志高效得多。 1. 从一个真实困境说起多模型调用的碎片化之痛如果你正在做AI应用开发大概率遇到过这样的场景项目初期用OpenAI的接口跑通了原型效果不错上线后老板说“能不能换成国产模型降降成本”你打开代码一看发现业务逻辑里到处散落着openai.ChatCompletion.create的调用参数格式、返回结构、错误码全是绑死的。换一个模型供应商几乎等于把整个调用层重写一遍。更麻烦的是当你想同时接入多家模型做对比测试、做降级容灾、或者根据任务类型路由到不同模型时每家的SDK认证方式不同、请求体结构不同、流式输出的chunk格式不同、甚至同一个概念比如“系统提示词”在不同API里的字段名都不一样。这种碎片化带来的维护成本在项目规模稍微大一点之后就会指数级上升。LiteLLM就是冲着这个痛点来的。它的核心定位可以用一句话概括用一套OpenAI格式的接口调用市面上几乎所有主流大模型服务。你写一次调用代码改一个字符串参数就能切换模型供应商不用改业务逻辑不用重新学一套SDK。这篇文章我会从实际使用的角度把LiteLLM的安装配置、核心用法、代理服务部署、成本追踪、踩坑经验完整讲一遍适合已经有一定Python基础、正在做AI应用开发、被多模型调用折磨过的朋友。2. LiteLLM到底解决了什么问题统一接口的底层逻辑2.1 它不是一个模型而是一层翻译中间件很多人第一次看到LiteLLM的名字会误以为它是一个新的大模型其实完全不是。LiteLLM是一个Python库加一个可选的代理服务它做的事情是在你的代码和各家模型API之间加了一层适配层。你调用LiteLLM的函数LiteLLM负责把你的请求翻译成对应供应商能理解的格式发出去拿到响应后再翻译回OpenAI格式返回给你。这个设计思路和数据库领域的ORM对象关系映射非常像。你用SQLAlchemy写代码的时候不需要关心底层是MySQL还是PostgreSQLLiteLLM让你不需要关心底层是GPT还是Claude还是通义千问。这个类比我觉得是最容易理解的。2.2 统一接口带来的三个直接收益第一个收益是代码可移植性。你的业务代码只依赖LiteLLM的接口模型供应商变成一个配置项。今天用A模型明天想换成B模型做A/B测试改一行model参数就行。第二个收益是降级容灾变得简单。LiteLLM内置了fallback机制你可以配置一个模型列表当主模型调用失败超时、限流、服务不可用时自动切换到备用模型。这个在线上环境非常实用我自己就遇到过某家服务在高峰期频繁超时的情况有了fallback至少保证业务不中断。第三个收益是成本追踪和预算控制。LiteLLM会自动计算每次调用的token消耗和对应费用支持设置预算上限超出后自动拒绝请求。对于需要控制AI调用成本的项目来说这个功能省去了自己搭建计费系统的麻烦。2.3 支持范围与版本选择建议LiteLLM支持的模型供应商数量一直在增长目前覆盖了OpenAI、Anthropic、Google Gemini、Cohere、Mistral、Meta Llama系列通过各托管平台、以及国内多家主流模型服务。具体支持列表建议直接看官方文档的providers页面因为更新频率很高我这里列出来很快就会过时。版本选择上我的建议是如果你只是想在Python项目里用统一接口调模型装litellm基础包就够了如果你需要部署一个统一的API网关给多个项目或团队用那需要用到litellm[proxy]它会额外安装FastAPI、Uvicorn等依赖。Python版本建议3.9以上3.11体验最好。3. 环境搭建与最小可用示例十分钟跑通第一个调用3.1 安装与密钥配置的几种方式安装本身很简单pip install litellm如果你要用代理模式pip install litellm[proxy]密钥配置是新手最容易卡住的地方。LiteLLM读取密钥的方式遵循各家SDK的环境变量约定比如OpenAI的密钥读OPENAI_API_KEYAnthropic的读ANTHROPIC_API_KEY。你可以直接在shell里export也可以用.env文件配合python-dotenv加载。注意不要把密钥硬编码在代码里然后提交到代码仓库。我见过不止一个项目因为这事导致密钥泄露被刷爆额度。用环境变量或者密钥管理服务这是底线。如果你用的是国内模型服务很多也兼容OpenAI的接口格式这种情况下可以通过设置api_base参数指向对应的服务地址密钥用OPENAI_API_KEY这个环境变量名传入即可。具体每个供应商的环境变量名官方文档有对照表。3.2 第一个调用从OpenAI格式到多模型切换最基础的调用长这样from litellm import completion import os os.environ[OPENAI_API_KEY] your-key-here response completion( modelgpt-4o, messages[ {role: user, content: 用一句话解释什么是统一接口} ] ) print(response.choices[0].message.content)看到没有这个调用格式和OpenAI官方SDK几乎一模一样。现在关键来了如果你想换成Clauderesponse completion( modelclaude-3-5-sonnet-20241022, messages[ {role: user, content: 用一句话解释什么是统一接口} ] )只改了model参数其他代码一行没动。这就是LiteLLM的核心价值。模型命名规则一般是provider/model-name的格式但OpenAI的模型可以省略provider前缀直接写模型名。3.3 流式输出与异步调用的写法差异流式输出是现在AI应用的标配LiteLLM的流式写法和OpenAI一致response completion( modelgpt-4o, messages[{role: user, content: 写一首关于编程的短诗}], streamTrue ) for chunk in response: content chunk.choices[0].delta.content if content: print(content, end, flushTrue)异步版本用acompletion配合asyncio使用。这里有个实际经验如果你在做Web服务强烈建议用异步版本否则每个请求都阻塞一个线程并发量稍微上来就扛不住。异步版本的流式处理需要用async for来迭代。4. 代理模式部署实战把统一接口变成团队共享服务4.1 什么时候需要上代理模式如果你只是个人项目或者单个Python应用直接用SDK就够了。但如果你面临以下情况代理模式就值得上了多个项目/多个语言的技术栈都需要调模型不想每个项目都配一遍密钥和适配逻辑需要统一的密钥管理和访问控制不想把真实密钥散落在各个项目里需要集中查看所有项目的调用量和成本。代理模式本质上是LiteLLM帮你起了一个FastAPI服务对外暴露OpenAI兼容的HTTP接口。任何能用OpenAI SDK的客户端把base_url指向这个代理服务就能用。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-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: qwen-plus litellm_params: model: openai/qwen-plus api_base: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: os.environ/DASHSCOPE_API_KEY litellm_settings: drop_params: true set_verbose: false general_settings: master_key: sk-your-master-key database_url: postgresql://user:passlocalhost:5432/litellm这里有几个字段值得展开说。model_name是对外暴露的名称客户端调用时用这个名称litellm_params.model是实际路由到的模型格式是provider/model。drop_params: true这个设置很实用它的作用是当某个供应商不支持你传入的某个参数时自动丢弃而不是报错。比如你传了OpenAI特有的参数给一个不支持的模型没有这个设置会直接报错。master_key是代理服务的管理密钥客户端调用时需要带上。database_url是可选的配了之后才能使用预算控制、用量统计等需要持久化的功能。4.3 启动服务与客户端接入验证启动命令litellm --config config.yaml --port 4000启动后用curl验证一下curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-master-key \ -d { model: gpt-4o, messages: [{role: user, content: 测试一下}] }Python客户端接入from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-your-master-key ) response client.chat.completions.create( modelclaude-sonnet, messages[{role: user, content: 你好}] )注意这里用的是OpenAI官方SDK只是把base_url改了。这意味着你现有的基于OpenAI SDK的代码几乎不用改就能接入。提示生产环境部署时代理服务前面建议加一层反向代理处理HTTPS和限流。LiteLLM本身也支持配置多个worker通过--num_workers参数指定。5. 成本追踪、预算控制与降级策略的落地细节5.1 费用是怎么算出来的LiteLLM内置了一个模型价格表每次调用后根据输入输出token数乘以对应单价算出费用。这个价格表会随官方更新但如果你用的是自定义部署的模型或者价格表里没有的模型需要手动配置价格。手动配置的方式是在litellm_params里加input_cost_per_token和output_cost_per_token- model_name: my-custom-model litellm_params: model: openai/my-model api_base: http://my-endpoint/v1 input_cost_per_token: 0.000001 output_cost_per_token: 0.000002费用数据会记录在数据库里可以通过代理的/spend/logs接口查询也可以在管理UI里看。管理UI的地址是http://localhost:4000/ui用master_key登录。5.2 给不同团队或项目设置预算上限这是代理模式相比直接用SDK的一个明显优势。你可以创建多个虚拟密钥每个密钥绑定不同的预算curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o, claude-sonnet], max_budget: 100, budget_duration: 30d, key_alias: team-a-key }这个接口会返回一个新的密钥团队A用这个密钥调用30天内累计消费超过100美元后就会被拒绝。models字段限制了这把密钥能访问哪些模型避免越权调用贵的模型。5.3 fallback配置主模型挂了怎么办fallback的配置在litellm_settings里litellm_settings: fallbacks: [{gpt-4o: [claude-sonnet, qwen-plus]}]这个配置的意思是当gpt-4o调用失败时依次尝试claude-sonnet和qwen-plus。触发fallback的条件包括超时、限流、服务端错误等。我自己的经验是fallback的备用模型最好选不同供应商的否则同一家服务整体故障时备用也没用。另外要注意fallback会增加响应延迟因为要等主模型失败才会切换所以超时时间不要设太长一般10-30秒比较合理。6. 踩坑实录那些文档里不会写的实际问题6.1 参数兼容性drop_params不是万能的前面提到drop_params: true可以自动丢弃不支持的参数但实际用下来发现它只对部分参数有效。比如你把OpenAI的response_format传给一个不支持的模型即使开了drop_params也可能报错。我的做法是在业务层做参数适配根据目标模型的能力决定传哪些参数而不是完全依赖LiteLLM的自动处理。另一个常见问题是temperature的取值范围。OpenAI是0到2但有些模型只支持0到1。传了超出范围的值有的供应商会报错有的会静默截断。这个没有统一解法只能在使用新模型前先做一轮参数测试。6.2 流式输出中token计数不准的情况流式模式下LiteLLM默认可能拿不到完整的usage信息因为很多供应商在流式响应里不返回token统计。这会导致费用计算偏低甚至为零。解决办法是开启stream_optionsresponse completion( modelgpt-4o, messages[...], streamTrue, stream_options{include_usage: True} )但注意不是所有供应商都支持这个参数。对于不支持的LiteLLM会尝试用tiktoken在本地估算token数估算结果和实际会有偏差做成本核算时心里要有数。6.3 超时设置与重试策略的平衡LiteLLM支持配置超时和重试response completion( modelgpt-4o, messages[...], timeout30, num_retries2 )这里有个坑重试和fallback叠加使用时总等待时间可能很长。比如超时30秒、重试2次、再fallback到另一个模型又超时30秒重试2次最坏情况下用户要等两分钟。我的建议是重试次数不要超过1次把更多精力放在fallback的模型选择上让备用模型尽快接管。6.4 国内模型接入时的api_base陷阱国内很多模型服务兼容OpenAI接口但兼容程度参差不齐。最常见的问题是api_base的路径。有的服务要求写完整的/v1/chat/completions路径有的只需要写到/v1LiteLLM会自动补全。如果调用报404先检查这个路径。还有一个问题是SSL证书验证。部分自建或私有部署的模型服务用的是自签名证书Python的requests库默认会拒绝。可以通过设置环境变量REQUESTS_CA_BUNDLE指向证书文件或者在LiteLLM参数里传ssl_verifyFalse仅限内网可信环境使用。7. 把LiteLLM用好的几个进阶思路7.1 基于任务类型的模型路由LiteLLM代理支持根据请求内容路由到不同模型。比如简单的分类任务路由到便宜的小模型复杂的推理任务路由到贵的大模型。这个可以通过自定义路由逻辑实现在配置文件里用model_name做别名然后在业务层根据任务类型选择不同的别名。我自己的做法是在业务代码里封装一个get_model_for_task(task_type)函数返回对应的模型别名这样路由逻辑集中在一处调整起来方便。7.2 缓存层减少重复调用LiteLLM支持Redis缓存相同的请求在一定时间内直接返回缓存结果不重复调用模型。对于问答类、客服类场景用户问的问题重复率其实不低缓存能省下可观的费用。配置方式是在litellm_settings里加litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379 ttl: 3600ttl是缓存过期时间单位秒。设太长会导致答案过时设太短起不到省钱效果一般1小时是个折中。7.3 日志与可观测性接入代理模式支持把调用日志推送到各种可观测性平台。即使不接外部平台至少要把日志落到数据库方便出问题时排查。database_url配好之后所有请求的详细信息模型、token数、费用、延迟、状态都会记录。我建议额外记录请求的业务标识比如用户ID、会话ID这样排查问题时能快速定位到具体是哪个用户的哪次调用出了问题。这个可以通过在请求的metadata里传自定义字段实现。7.4 版本升级的注意事项LiteLLM迭代很快几乎每周都有新版本。升级前一定要看changelog特别关注breaking changes。我遇到过升级后配置文件字段改名导致服务起不来的情况。建议的做法是在测试环境先升级验证确认没问题再上生产。另外锁定版本号在requirements里写litellmx.y.z比用litellmx.y.z更稳妥避免某天自动升级后出问题。8. 一些实际使用中的体会用LiteLLM有一段时间了最大的感受是它确实把多模型调用的复杂度从业务层抽离出来了。以前每接一个新模型都要翻文档、对参数、写适配代码现在大部分情况下改个配置就行。代理模式对于团队协作的价值也很明显密钥不用到处发用量和成本一目了然。但它也不是银弹。参数兼容性、流式token计数、国内服务的接口差异这些问题该踩的坑一个不少。我的建议是先用SDK模式在小项目里跑通熟悉了它的行为模式之后再上代理模式。配置项不要一次开太多drop_params、fallback、缓存这些功能逐个加上去每加一个都验证一下行为是否符合预期出问题时也容易定位是哪个配置导致的。最后分享一个小技巧LiteLLM的completion函数支持传metadata参数你可以把业务相关的信息塞进去这些信息会出现在日志里。排查线上问题时这个字段能帮你快速把一次模型调用和具体的业务请求关联起来比翻时间戳对日志高效得多。