最近在捣鼓AI应用接模型的时候我几乎逢人就推荐一个工具litellm。可能很多同学第一次看到这个名字会以为它是某个大模型的新版本其实它是一个Python库。它的核心功能就一句话让你用一套代码、一套调用格式接入几乎所有主流的大模型服务商包括OpenAI、Anthropic、Google Gemini、阿里、智谱等等。同时它还自带代理服务、限流、重试、成本统计、密钥管理这些功能相当于给团队或项目加了一层“模型网关”。我第一次用litellm的场景特别朴素项目里原先只接了OpenAI后来要接Claude代码里得写两套请求逻辑还要处理完全不同的返回结构改得头大。后来在网上看到有人提到litellm说可以把不同厂商的模型统一成OpenAI格式来调用我当时就试了一下结果发现不只是“统一格式”这么简单它把重试、降级、负载均衡、甚至价格预算统计都一起做掉了完全超出预期。这篇博文我就把自己从接触到深度使用litellm的过程、踩过的坑、以及一些配置细节完整写出来希望对正在做多模型接入或者想搭一个内部AI网关的同学有帮助。1. 为什么需要统一接口从“模型混乱期”聊聊背景1.1 各家API的真实痛点现在大模型市场早就不是OpenAI一家独大了。Anthropic有Claude系列、Google有Gemini、国内有各种开源的Qwen、DeepSeek等等。单看每一家的API文档都写得很清楚但一旦你需要在同一个应用里接入两家以上问题就来了。首先接口格式不统一。OpenAI用的是messages数组里面放role和contentClaude在某个版本里也是类似的格式但参数细节不同比如max_tokens和max_tokens_to_sample这种命名的差异Gemini又有自己的一套管法。更麻烦的是同样一个“让模型写一段Python代码”的请求在不同服务商那边可能需要不同的顶层字段去控制温度、随机性、流式输出等参数。其次是返回结构不统一。OpenAI返回choices[0].message.contentClaude返回content[0].textGemini可能又是另一个字段路径。这意味着你的业务代码里得写大量的解析兼容逻辑。我见过一个项目光是一个“提取模型回复内容”的函数就写了十来个if...else因为可能要接的服务商太多了。第三是每个服务商的错误处理逻辑不一样限流返回的状态码不同、超时策略不同、鉴权方式也不同。这些“脏活累活”都堆在业务代码里维护成本极高。1.2 litellm的定位与核心思路litellm的解法很聪明。它不搞自己的模型也不替代任何一家服务商它就做一个“中间层”。你按照OpenAI的格式把请求发给它它负责把请求翻译成目标服务商能理解的样子然后发出去等目标服务商返回之后它再统一转成OpenAI的格式还给你。这样你的业务代码从头到尾只认识一种接口。它还有一个Agent叫Proxy Server也就是代理模式。你可以把litellm当作一个小型的API网关独立跑起来业务服务只需要配置一个base_url指向它然后用OpenAI的SDK去调用剩下的事情litellm全部接管。这种设计的价值在于业务开发不用关心底下的模型是哪一家只关心模型名。比如你今天用的gpt-4o明天想换claude-3-5-sonnet在你的代码里只需要改一个字符串甚至不改也可以通过配置中心动态切换。同时服务的稳定性提升了一个层级因为重试、降级这些策略都在网关层完成了。2. 环境准备与基础接入2.1 安装与环境检查litellm的安装很简单直接用pippip install litellm如果你的项目对包大小敏感它依赖的东西也不多核心调用只需要httpx和pydantic这一类的库。安装完之后我建议先做一次快速验证。我需要确认Python版本在3.8以上我在3.9、3.10、3.11都跑过没遇到兼容性问题。然后设置环境变量。如果你要调OpenAI的模型export OPENAI_API_KEYsk-xxxx如果要调Anthropic就设置ANTHROPIC_API_KEYGemini就设置GEMINI_API_KEY。litellm通过读取这些环境变量来找密钥。注意如果你的Key是存在本地的.env文件里记得在使用litellm之前先加载。我习惯用一个很小的工具库python-dotenv来做这件事。2.2 一次调用从OpenAI格式到全模型兼容接下来写最简单的一次调用。在litellm里核心函数是completion基本用法长这样import litellm response litellm.completion( modelgpt-4o, messages[ {role: user, content: 给我讲一个三句话的笑话} ], temperature0.7 ) print(response.choices[0].message.content)这个写法跟OpenAI官方SDK几乎一样因为litellm就是故意保持这个格式的。但神奇的地方在这里我把model参数换成下面任意一个上面的代码都不用改modelclaude-3-5-sonnet-20241022 modelgemini-1.5-pro modelanthropic/claude-3-opus modelollama_chat/llama3.1它会根据你传入的模型名自动判断要调用哪一家服务商自动切换鉴权方式、接口格式、返回解析。如果你在model前面加上服务商前缀比如anthropic/或者openai/可以强制指定走某条路线这在某些场景下很有用可以避免模型名冲突。我实测最顺手的用法是直接把环境变量配置好然后用统一格式调通再慢慢试各种模型。说句实话第一眼看到response对象的时候我心里想的是“这不就是把OpenAI的response结构抄了一遍嘛”但后来发现它里面对不同供应商的“方言”处理是真的到位。3. 核心功能拆解路由、重试与观测3.1 模型路由与负载均衡单模型调用只是入门litellm真正有价值的是“模型路由”能力。你可以把多个模型组成一组让litellm自动选择用哪个模型来处理请求。这在两种场景下特别有用一是想省钱优先用便宜的模型二是想保稳定主模型挂了自动切备用模型。我经常写的一个路由配置长这样import litellm router litellm.Router(model[gpt-4o, claude-3-5-sonnet, gemini-1.5-pro]) response router.completion( modelgpt-4o, messages[{role: user, content: 你好}], fallback_models[claude-3-5-sonnet, gemini-1.5-pro] )这里有两个重点值得展开。第一个是Router可以通过routing_strategy参数指定策略比如simple-shuffle是随机挑一个least-busy是挑当前负载最低的usage-based-routing是根据模型成本去选。第二个是fallback_models它定义了主模型失败后的降级名单。litellm如果发现主模型因为限流、超时或5xx报错会自动按顺序去试备用模型业务方几乎无感。3.2 重试与降级的参数设计重试参数方面litellm的默认行为我觉得对大多数场景是合理的遇到网络抖动、500错误、429限流会自动重试默认最多重试2次。但我建议你在生产环境显式配置一下因为默认策略不一定适合所有供应商。response litellm.completion( modelgpt-4o, messages[{role: user, content: 你好}], num_retries3, retry_after5, fallback_models[claude-3-5-sonnet], )num_retries是最大重试次数retry_after是重试前等待的秒数这个等待时间我一般设成5秒起步。注意如果对方服务商返回的是400这种客户端错误重试也没用litellm会直接放弃它主要对429、5xx和网络异常做重试。降级时要关注模型的能力差异如果主模型是gpt-4o备用模型至少也得是同等级的推理能力否则业务结果质量会有明显下降。3.3 可观测性与日志AI网关最重要的就是能看清楚“谁在什么时候用了哪个模型花了多少钱”。litellm自带了日志记录和成本估算功能。它有几种日志输出方式控制台日志、写入文件、甚至回调到自定义函数。我常用的是把调用记录打进日志文件简单配置就行import litellm litellm.success_callback [my_logging_function] litellm.failure_callback [my_error_logging_function]然后在自己的回调里可以取到kwargs里的模型名称、提示词长度、输出长度、花费的钱数。这里有一个细节litellm计算成本用的价格表来源于litellm/model_prices_and_context_window.json它会定期更新。如果你接的是私有化部署模型或极新的模型价格可能查不到此时返回的cost字段会是0或者空。别慌可以手动维护价格或者忽略成本字段。提示在生产项目里我把litellm的日志和公司内部的监控系统打通了每次调用的延迟、token消耗、成本都会记录到数据表里。这样月底跟财务对账的时候特别方便不用再从各个平台单独拉账单。4. 实操搭建一个本地AI网关4.1 快速启动代理服务如果你想在团队内部搭建一个“所有模型统一入口”的API服务litellm提供了Proxy模式这也是它最强大的用法之一。启动方式非常简单在命令行里执行litellm --model gpt-4o --port 8000这样会在本地8000端口起一个类似OpenAI的API服务支持/chat/completions、/completions、/models这些端点。业务侧只要把OpenAI SDK的base_url指过来就行from openai import OpenAI client OpenAI( api_keysk-anything, # 代理模式下这个Key不校验也可以 base_urlhttp://localhost:8000 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)注意这里有点小坑代理模式下如果api_key随便填是能过去的但如果你在后面加了虚拟密钥功能api_key就要填你自己生成的虚拟Key不能随便写了。这一点我在后面会重点讲。4.2 接入多个提供商并配置限流命令行启动适合快速测试生产环境肯定不能这么裸奔而是用配置文件来管理。我一般用一个config.yaml里面定义好可用的模型列表、每个模型的限流参数、以及密钥信息model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY rpm: 100 tpm: 100000 - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY rpm: 80 tpm: 80000 - model_name: gemini-1.5-pro litellm_params: model: gemini/gemini-1.5-pro api_key: os.environ/GEMINI_API_KEY rpm: 50 tpm: 50000然后启动litellm --config config.yaml --port 8000model_name是外部暴露的名字litellm_params.model是真实要调用的远端模型名rpm是每分钟请求数上限tpm是每分钟token数上限。限流参数设置好之后当请求频率超出阈值litellm会返回429错误给调用方但不会去疯狂打上游服务商。如果配了重试和降级它还有可能自动换一个没有超限的模型来响应。4.3 密钥管理与权限控制前面提到虚拟密钥这是litellm做的很好用的一个点。在生产环境我们不应该把OpenAI的原始Key下发给每个服务或每个开发者。litellm支持在代理服务上生成虚拟Keycurl http://localhost:8000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d {models: [gpt-4o]}返回结果里会带上一个新的sk-开头的Key。这个Key是litellm自己生成的背后映射到真实的模型调用。这样即使某个服务的Key泄露了你也可以在litellm这边一键吊销而不需要去上游服务商那边重新生成密钥。只有持有Master Key的人才能管理这些虚拟Key。安全提示Master Key默认是sk-master-key如果不改会很危险。建议启动时用环境变量LITELLM_MASTER_KEY指定一个强密码。我第一次部署时忘了改结果内网里所有人都能创建虚拟Key虽然不会直接看到上游Key但也能调接口烧钱后来老老实实加了权限控制。5. 常见问题与排查技巧实录5.1 模型名传错导致调用失败最常碰到的问题就是模型名字对不上。比如你在供应商那边用的是claude-3-5-sonnet-20241022结果在litellm里只写了claude-3-5-sonnet有些时候它能正确解析有些时候会报找不到。解决方法是查询litellm支持的模型列表我习惯用代码列出import litellm all_models litellm.model_list print([m for m in all_models if claude in m])也可以直接看官方文档里的model map。如果你接的是自定义的模型在model参数里直接写完整路径会更稳妥。注意在config.yaml里配置模型时litellm_params.model尽量写全名不要偷懒。5.2 上游限流与并发突刺429错误是家常便饭尤其是多个服务共用一个上游Key的时候。litellm的重试机制能解决一部分问题但如果并发实在太高光靠重试反而会加剧限流。我在配置里会这样处理第一给每个模型设置合理的rpm/tpm第二启用cooldown_time当某个模型连续报错时litellm可以自动把该模型拉入“冷却期”暂时不用直接走备用模型从而保护上游。router_settings: cooldown_time: 30 routing_strategy: usage-based-routing5.3 成本统计与实际账单对不上这个坑很多人会遇到。litellm的成本估算是通过它内置的价格表完成的但价格表更新有延迟。比如某家供应商大规模调价之后litellm可能还没来得及更新导致它预估的费用和真实账单差距很大。解决思路如下一是手动覆盖价格在代码里改litellm.model_cost_map。二是在做对账时以供应商后台账单为准litellm的成本只做参考。三是把litellm的每次调用日志记录下来用日志里的token数去乘价格表这样可以自己重算。建议不要完全依赖litellm的cost字段特别是在用了新模型或高端模型的时候。5.4 日志乱码与编码问题在使用OpenAI兼容接口返回内容时如果响应里的中文出现乱码多半是项目本身没有设置UTF-8编码。litellm本身对编码处理是没问题的但如果你在Windows控制台跑可能会因为默认编码是GBK而看到乱码。我的建议是代码文件开头声明# -*- coding: utf-8 -*-或者在运行环境中设置PYTHONIOENCODINGutf-8。这类问题不算大但排查起来很烦人。5.5 排查综合技巧litellm支持一个Debug模式打开后它会打印出内部的请求和响应细节这比猜错因高效得多import litellm litellm.set_verbose(True)还有一个很实用的方法开启litellm.suppress_debug_info False能看到它实际发送给上游服务商的请求体长什么样。当你怀疑某家供应商大模型返回内容被截断或请求参数没传全时用这个办法一眼就能看出来。6. 进阶玩法与生态整合6.1 与主流框架结合现在很多AI应用都用LangChain或LlamaIndex这类框架做编排。litellm在这些框架里的定位是把“模型调用”这层完全替换。比如在LangChain里你可以直接用ChatLiteLLM模块接入只要配置好model_name即可from langchain_community.chat_models import ChatLiteLLM from langchain_core.messages import HumanMessage chat ChatLiteLLM(modelgpt-4o, temperature0.7) resp chat([HumanMessage(content你好)]) print(resp.content)在LlamaIndex里也可以用LiteLLM作为LLM后端。这样原本基于OpenAI开发的应用只需要替换类名和微调参数就能切换到litellm极其顺畅。6.2 自定义模型接入与扩展如果你用的是开源模型自己部署想接入litellm也很方便。它的设计本来就支持第三方兼容端点。比如你本地跑着一个Ollama上的模型可以通过ollama_chat/llama3.1这样的前缀来指定走Ollama通道。如果你接的是某企业内部系统只要它提供OpenAI兼容接口你也可以直接通过自定义api_base接进来。以下是我用过的一个简单自定义配置例子import litellm litellm.openai_settings[MY_CUSTOM_SERVICE] { api_base: https://my-internal-service.example.com/v1, api_key: os.environ[MY_SERVICE_KEY] } resp litellm.completion( modelopenai/gpt-4o, # 这里只是占位真实服务由api_base接管 messages[{role: user, content: test}], api_basehttps://my-internal-service.example.com/v1 )6.3 多节点部署的可能性litellm的代理模式是支持多节点横向扩展的这意味着你可以做一个小型的高可用网关集群。多个litellm实例共享同一套配置与虚拟密钥存储存储在Redis或数据库里上游负载被分散到多个网关节点上。这也是它被很多创业公司拿来当作内部AI基础设施的原因之一。如果需要做多节点我建议把配置文件和密钥存储外部化再用容器编排工具管理litellm实例的生命周期。实例本身是无状态的可以随意增减。不过这一块牵扯到运维非必要不折腾单节点对你的小型项目完全够了。我的几点总结性体会用litellm大半年下来我最深的感觉是“它把多模型接入这件事从噩梦变成了日常”。以前我接新模型平均要花半天到一天去读文档、调参数、写适配代码现在用litellm只需要在配置里加一行模型名跑一下回归测试基本就能上线。特别是把代理模式跑起来之后连业务方的SDK都不用改这种体验相当爽。如果你还没有试过litellm我的建议是从最简单的completion调用开始把它当作一个“兼容性工具”来用。跑通之后再逐步加上路由、重试、降级和虚拟密钥。不要一上来就搭完整网关那样容易淹没在配置细节里。litellm的文档我建议优先看“Proxy”那部分那才是它在生产环境发挥真正价值的地方。另外litellm的版本更新比较快如果你用的是旧版本有些新模型可能查不到升级前记得看一下官方变更记录。做好版本锁定是长期使用最省心的方式。