做AI应用开发这一年多我花在“接API”上的时间比花在调参上的时间还多。今天想聊的LiteLLM就是专门解决这个问题的开源工具——它能把国内外主流大模型服务商千奇百怪的接口格式统一成同一种调用方式。不管你是想快速对比各家模型效果还是想把大模型能力封装成一个稳定、可审计、可计费的内部服务这个项目都能帮你省掉一大片适配代码。下面是我从零接入LiteLLM的完整过程包含环境搭建、核心功能拆解、网关部署和一堆实战中踩过的坑希望对正在折腾多模型接入的朋友有参考价值。1. 先搞清楚LiteLLM到底解决了什么问题在写第一行代码之前我建议先理解这个项目存在的理由。因为如果你只是随便调一个模型LiteLLM带来的额外抽象层反而可能成为负担。只有当你同时面对多家服务商、多种协议、多套密钥的时候它才会体现出真正的价值。1.1 大模型API的“方言”困境每家服务商的API都有自己的“方言”。有的用conversation参数有的用prompt参数有的把系统提示词放在独立字段里有的要求你统一塞进messages数组工具调用有的叫functions有的叫tools里面的参数结构又不一样。就连最基础的鉴权方式有的用请求头带密钥有的用额外参数传递还有的必须走特定的签名流程。我这边的实际经历是当时做一个模拟项目X需要同时接三家服务商的API做模型效果A/B评测。每家都要写一套独立的请求封装包含鉴权、参数拼装、响应解析、错误码映射、重试策略。光这一层适配代码我写了六七百行。最崩溃的是三家对限流的反馈方式完全不同——一个返回429一个返回503还有一个在响应体里塞了一段JSON错误信息错误处理逻辑根本没法复用。这种“方言”问题在团队里还会放大每来一个新同事都要重新学一遍不同API的调用习惯代码仓库里到处是风格各异的HTTP客户端封装。1.2 LiteLLM给出的核心思路做一层统一的API翻译层LiteLLM的思路一点都不玄乎它充当一个“翻译层”把所有服务商接口统一成同一套格式。你在代码里只需要写一种调用方式指定模型名和常规参数剩下的格式转换、鉴权、响应解析全部由LiteLLM在内部完成。你可以把它理解为大模型世界的“万能电源转换头”。不管插座是两脚、三脚还是圆脚你手头只需要一个标准插头。LiteLLM内部维护了大量适配规则知道某服务商的消息格式长什么样、参数名对应什么、返回的数据结构怎么映射回统一格式。对你来说调用的大模型服务商只是model字符串里的一个前缀而已。更重要的一点是LiteLLM不只是做格式转换。它还集成了生产环境需要的配套设施密钥管理、成本统计、重试机制、熔断策略、负载均衡、虚拟Key和多租户支持。换句话说你装好它之后等于顺手拥有了一套轻量级的AI网关而不是一个只能“翻译格式”的小工具。1.3 什么时候你才需要LiteLLM我见过不少团队把LiteLLM当成万能钥匙所有项目都强行套一层其实没必要。我梳理一下真正适合接入它的场景你需要在多个模型之间做效果对比和选型评测希望切换模型时不改业务代码。你的产品要根据用户等级、请求类型动态路由到不同模型。比如简单问题走便宜的小模型复杂推理才用贵的大模型。公司里多个团队、多个项目都在调用大模型API需要一个统一入口来管理密钥、配额和审计日志。你要把大模型能力封装成内部服务给前端页面或其他后端系统调用但不想把服务商密钥暴露到各个角落。反过来如果你的业务只依赖某一家的模型短期内完全不会切换而且对网络延迟极其敏感那直接调官方SDK可能更干净。LiteLLM的抽象层是有代价的——多一层封装就意味着多一次转发和一层可能的故障点。方案选型不能只看“有没有用”还要看“值不值得”。2. 从零跑通第一个请求环境准备与基础接入这一节我按最简路径走先让你在10分钟内发出第一个请求。工程上我们追求“最小可运行闭环”先把链路跑通再逐层加功能。2.1 安装环境避免踩Python版本和依赖的坑LiteLLM是基于Python的官方要求Python 3.8及以上建议直接用3.10或3.11省得遇到一些老版本的类型语法兼容问题。安装命令很简单pip install litellm[proxy]如果只是想在自己项目里当SDK用不打算起代理服务可以只装pip install litellm。但既然要长期用我推荐直接带上proxy扩展后面部署网关模式会用到。我的习惯是用虚拟环境安装无论你用venv还是poetry不要让LiteLLM直接污染系统Python环境。曾经有位同事把LiteLLM直接装进系统环境后面又装了一个依赖pydantic旧版本的项目两者冲突排查了半天。虚拟环境隔离成本极低别在这个环节偷懒。2.2 第一个调用统一格式的请求长什么样装完之后核心用法是这样import os from litellm import completion os.environ[OPENAI_API_KEY] 你的密钥 response completion( modelgpt-4o-mini, messages[ {role: system, content: 你是一个简洁的助手}, {role: user, content: 帮我用一句话介绍量子计算}, ], temperature0.7, ) print(response.choices[0].message.content)注意看不管背后的服务商是哪一家你写的参数结构始终是这套model、messages、temperature。LiteLLM会根据model字符串里的前缀自动判断该把请求发给谁。比如gpt-4o-mini默认走某家官方接口openai/前缀可以显式指定走这家anthropic/claude-3-5-sonnet则是另一家如果你本地自建了兼容通用格式的模型服务还可以用openai/custom-model并配一个api_base指向本地地址。这里有个小细节messages里的角色到底是system还是assistant还是user各家理解基本一致但有些服务商对system消息的处理方式不同。LiteLLM会做一定程度的兼容但如果模型本身对系统提示词的遵循程度很低那不是LiteLLM能解决的事应用层还是要自己控制提示词的写法。2.3 密钥管理别再把服务商密钥硬编码到代码里很多初学者喜欢把密钥直接写在Python文件里甚至不小心把代码推向公开仓库。我的习惯是配合环境变量文件.env来管理OPENAI_API_KEYsk-xxx ANTHROPIC_API_KEYsk-yyy COHERE_API_KEYsk-zzzLiteLLM会自动读取.env文件里的变量。你在代码里只需要确保环境变量存在其他不用管。团队协作时密钥应当收敛到服务器或网关端而不是每个开发者的本地配置。测试环境、预发环境、生产环境的密钥最好分开这样就算某个环境的密钥泄露也能快速定位和轮换。3. 核心功能逐个拆解路由、重试、成本与流式跑通基础调用之后重点来了。LiteLLM之所以在圈内受欢迎是因为它把大模型接入的“脏活累活”都标准化了。这里挑几个我用得最频繁、也最能提升效率的功能展开讲。3.1 多模型路由与故障切换让业务代码不再绑定单一服务商如果你只想固定用一个模型那LiteLLM的优势还不明显。但一旦你想实现“OpenAI挂了自动切别的”或者“不同请求走不同模型”它的路由能力就派上用场了。在代理模式下你可以通过配置文件声明一个model_list把多个后端模型映射到同一个对外名称model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet - model_name: gpt-4o-mini litellm_params: model: azure/chatgpt-v4o-mini api_base: https://your-resource.openai.azure.com/ api_key: os.environ/AZURE_API_KEY这个例子里有个很实用的玩法你对外统一暴露gpt-4o-mini这个名字内部却配了两个后端实例。当第一个后端返回限流错误或者超时LiteLLM会自动把请求转到第二个后端业务层完全无感知。相当于给服务商做了热备。路由策略上LiteLLM支持按优先级顺序调用也支持按权重分发还可以根据延迟做动态选择。我实际使用时的偏好是默认主备模式主服务商承担绝大多数流量备服务商平时可以切到小流量灰度一旦主链路抖动自动切备份。这种方案对可用性要求高的线上服务非常友好。3.2 重试、超时与限流生产环境最容易被忽视的一环大模型API没有不超时的。网络抖动、服务商过载、并发限流每一条都可能让你的请求直接失败。LiteLLM内置了重试机制你只需要设置几个全局变量import litellm litellm.max_retries 3 litellm.request_timeout 30重试策略默认带指数退避也就是第一次失败后等一会儿再试第二次等待时间更长避免在服务商已经过载的情况下继续猛撞。这个设计符合常规的限流退避原则。为什么必须用指数退避而不是固定间隔因为限流往往是服务商整体过载的信号如果所有客户端都用固定间隔重试很容易造成“重试风暴”把服务商彻底压垮。我建议把max_retries设置为2到3次就好不要贪多。超过3次的重试在大模型场景里意义不大——很多错误是请求本身的问题比如提示词超长重试多少次都不会成功。而且每次重试都意味着额外的时间成本和费用成本。对延迟敏感的业务你可以把request_timeout调到10秒以内对离线批处理任务可以放宽到60秒甚至更久。3.3 成本追踪与用量统计别等到月底账单才发现超支接入多家模型之后成本是一个绕不开的问题。LiteLLM提供了成本计算能力和明细日志这一点在代理模式下尤其突出。在SDK模式下你可以这样估算单次请求成本from litellm import completion_cost response completion(...) cost completion_cost(completion_responseresponse)它会根据模型、输入token数和输出token数按服务商的公开价格标准算出一个估算值。需要注意这个价格是LiteLLM仓库里预先配置的如果你的服务商改价了或者你走的是某个渠道的转售价格就要在配置里手动指定input_cost_per_token和output_cost_per_token否则统计出来就是错的。在代理模式下LiteLLM会把每次请求的日志写到数据库并提供查询接口。你可以按天、按Key、按团队拉取用量明细。我们团队原来每个月底对账要从各家服务商后台导出账单再用Excel手工核对半天。现在直接跑一遍日志统计脚本半小时出报表。这个收益在团队规模变大之后会非常明显。3.4 流式输出与工具调用和交互场景强相关的两个能力做聊天机器人或者AI应用流式输出基本是标配。LiteLLM支持streamTrueresponse completion( modelgpt-4o-mini, messages[{role: user, content: 写一段500字的故事}], streamTrue, ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)流式模式下因为数据是分块返回的很多服务商不会在每一块都带上token统计。LiteLLM会在流结束后尽力汇总usage信息但如果服务商本身没给全量统计你可能需要自己用分词库估算。这不是LiteLLM的缺陷而是流式接口本身的限制。工具调用方面LiteLLM把各家不同的工具定义格式统一成了通用的tools参数。这个功能在做Agent类应用时特别有用——你的代码只需要写一套工具定义换模型时不用重写。但我提醒一句工具调用返回的数据不一定规范尤其是一些偏小的开源模型你声明的工具它不一定真的会用甚至可能返回格式错误的伪工具调用。应用层一定要对返回结果做二次校验别指望翻译层能清洗所有脏数据。4. 进阶实战把LiteLLM部署成LLM网关服务SDK模式适合在代码内部使用但如果你面对的是多个前端、多个后端服务、多个团队更推荐把LiteLLM跑成一个独立的网关服务。这一节讲生产部署。4.1 代理模式的价值边界该用和不该用要想清楚网关模式的本质是把所有大模型请求收敛到一个统一的入口。前端页面不再直接持有服务商密钥而是把请求发给你的网关后端服务也不用各自接一遍不同服务商的SDK统一走同一个端点。这就好比公司只有一个前台所有访客都走这里登记安全性、审计、流量控制全部集中在一处。但这里要泼一盆冷水如果你的项目只是一个小Demo部署在本地访问量很低用不起独立网关的维护成本那直接SDK模式就够了。网关模式并没有降低延迟反而多了一层转发。对于每秒只有个位数请求的应用为它维护一个网关服务是一种浪费。取舍标准就一条多个调用方需要共享同一套模型能力、密钥与配额管理时网关才划算。4.2 快速部署一条命令跑起来但生产环境要补数据库最简易的启动方式是命令行直接起服务litellm --config ./config.yaml --port 4000或者用Docker镜像适合放到容器环境docker run -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ ghcr.io/berriai/litellm:main-latest网关启动后对外暴露的是符合行业通用格式的API端点/v1/chat/completions。你把请求发到这个地址网关根据配置路由到真实服务商再把结果转回来。对调用方来说它们只看到一个标准接口不需要关心背后是哪家模型。生产环境部署时我强烈建议配置数据库。默认的SQLite适合单机调试但要长期跑、多实例部署、集中式审计PostgreSQL是更稳的选择。LiteLLM会把虚拟Key、调用日志、用量统计、预算额度全部存下来。配置项主要是环境变量DATABASE_URLpostgresql://user:passlocalhost:5432/litellm LITELLM_MASTER_KEYsk-your-master-key有了数据库之后你关掉网关再重启数据不会丢这对线上排查问题太重要了。4.3 虚拟Key、配额与多租户给团队里每个人都发一把“子钥匙”LiteLLM网关一个很实用的设计是“主Key 虚拟Key”。管理员持有主Key用来调用管理接口创建虚拟Key每个虚拟Key可以绑定特定的模型范围、预算上限、过期时间还能归属到某个团队。创建虚拟Key的典型流程是curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o-mini], max_budget: 10, team_id: team-a }前端或某个业务方拿到虚拟Key后调用网关统一地址即可。这样一来即使某个Key泄露影响面也局限在它绑定的模型和预算范围内你可以随时吊销重建。多租户场景同理不同部门用不同的team_id月底按部门出成本报表。我们团队后来把虚拟Key分配到了测试组、算法组、前端组各组独立配额互不干扰。这种用法比让所有人共用一把服务商Key安全得多。4.4 安全加固的三个必做项第一启动网关前必须设置主Key。没有主Key的网关管理接口裸露等于大门敞开。我见过有人为了省事把主Key留空结果内网扫描直接打穿了管理端。第二对管理接口做网络层限制。比如/key/generate这样的接口最好只允许内网IP段访问。如果部署在云上用安全组规则限制来源别把这些接口暴露到公网。第三日志脱敏。LiteLLM默认会把请求内容记录到数据库如果你的业务涉及用户隐私信息要评估是否关闭请求日志存储或者配置脱敏规则。合规压力大的业务最好自己接日志管道做过滤不依赖默认方案。5. 常见报错与排查经验最后这部分我整理了几类高频问题和对应的排查思路。这些都是实际踩过、查过源码才弄明白的希望能帮你省点时间。5.1 报错速查表错误类型典型现象排查方向AuthenticationError提示鉴权失败检查环境变量里的密钥是否配置正确是否和目标服务商匹配RateLimitError请求被限流检查并发和每分钟调用限制调大重试间隔或降低并发ContextWindowExceededError提示词超出上下文窗口截断历史消息或换用上下文更长的模型ModelNotFoundError找不到指定的模型检查model参数里的前缀是否拼错网关模式检查是否已加入model_listAPIConnectionError网络连接失败检查网络环境、api_base配置是否正确、服务商端点是否可达流式输出为空流式请求后拿不到内容遍历分块时先判断delta.content是否为空再取值5.2 成本统计不准的几个原因成本统计不准最常见的原因有三个一是模型价格没在配置里注册成最新价用默认旧价计算二是流式请求提前中断服务商返回的usage不完整三是图片输入、缓存命中等特殊计费维度没有单独配置。应对思路线上成本统计不要全依赖自动计算定期从服务商后台拉账单做交叉核对。如果用量大建议把每次请求的原始usage字段持久化到自己的数据库用离线任务统一计算成本。LiteLLM的实时统计可以当参考对账还是要以原始数据为准。5.3 我的排雷记录三个容易翻车的小细节升级版本时要留意破坏性变更。LiteLLM版本迭代很快一些老版本里能用的模型名在新版本里要求显式加服务商前缀。我就遇到过一次旧配置里写model: claude-2新版本直接报错改成anthropic/claude-2才恢复。所以每次升级前先看发布说明里的Breaking Changes列表。网关端点路径要和标准格式保持一致。有些人喜欢把路由简写成/chat/completions但LiteLLM对外端点默认是/v1/chat/completions。如果你用自定义路由转发注意别把/v1这一级丢掉否则会404。这问题很像“网址打不开你先看有没有少个斜杠”这种低级错误排查时往往一眼看不出来。配置密钥时别用明文写进代码仓库。被推送到仓库里的密钥一旦泄露后果是账单爆炸或数据泄漏。就算觉得自己仓库是私有的也建议养成用环境变量的习惯这是成本最低的安全投资。我个人在实际操作中的体会是LiteLLM最值得投入的地方不是省下了那几百行适配代码而是它逼着你把密钥管理、成本统计、路由策略这些“非业务的事”提前想清楚。很多人写AI应用时最容易被“跑通就行”的心态带着走结果模型一多、团队一大各种混乱就全冒出来了。如果你正在从单模型Demo走向多模型产品化可以沿着LiteLLM这条路径把自己的工程规范也一起建立起来。 
长河君 · 2026/10/13 11:46:32 · 阅读 1.2k LiteLLM实战：统一大模型API调用，构建可运维的AI网关
做AI应用开发这一年多我花在“接API”上的时间比花在调参上的时间还多。今天想聊的LiteLLM就是专门解决这个问题的开源工具——它能把国内外主流大模型服务商千奇百怪的接口格式统一成同一种调用方式。不管你是想快速对比各家模型效果还是想把大模型能力封装成一个稳定、可审计、可计费的内部服务这个项目都能帮你省掉一大片适配代码。下面是我从零接入LiteLLM的完整过程包含环境搭建、核心功能拆解、网关部署和一堆实战中踩过的坑希望对正在折腾多模型接入的朋友有参考价值。1. 先搞清楚LiteLLM到底解决了什么问题在写第一行代码之前我建议先理解这个项目存在的理由。因为如果你只是随便调一个模型LiteLLM带来的额外抽象层反而可能成为负担。只有当你同时面对多家服务商、多种协议、多套密钥的时候它才会体现出真正的价值。1.1 大模型API的“方言”困境每家服务商的API都有自己的“方言”。有的用conversation参数有的用prompt参数有的把系统提示词放在独立字段里有的要求你统一塞进messages数组工具调用有的叫functions有的叫tools里面的参数结构又不一样。就连最基础的鉴权方式有的用请求头带密钥有的用额外参数传递还有的必须走特定的签名流程。我这边的实际经历是当时做一个模拟项目X需要同时接三家服务商的API做模型效果A/B评测。每家都要写一套独立的请求封装包含鉴权、参数拼装、响应解析、错误码映射、重试策略。光这一层适配代码我写了六七百行。最崩溃的是三家对限流的反馈方式完全不同——一个返回429一个返回503还有一个在响应体里塞了一段JSON错误信息错误处理逻辑根本没法复用。这种“方言”问题在团队里还会放大每来一个新同事都要重新学一遍不同API的调用习惯代码仓库里到处是风格各异的HTTP客户端封装。1.2 LiteLLM给出的核心思路做一层统一的API翻译层LiteLLM的思路一点都不玄乎它充当一个“翻译层”把所有服务商接口统一成同一套格式。你在代码里只需要写一种调用方式指定模型名和常规参数剩下的格式转换、鉴权、响应解析全部由LiteLLM在内部完成。你可以把它理解为大模型世界的“万能电源转换头”。不管插座是两脚、三脚还是圆脚你手头只需要一个标准插头。LiteLLM内部维护了大量适配规则知道某服务商的消息格式长什么样、参数名对应什么、返回的数据结构怎么映射回统一格式。对你来说调用的大模型服务商只是model字符串里的一个前缀而已。更重要的一点是LiteLLM不只是做格式转换。它还集成了生产环境需要的配套设施密钥管理、成本统计、重试机制、熔断策略、负载均衡、虚拟Key和多租户支持。换句话说你装好它之后等于顺手拥有了一套轻量级的AI网关而不是一个只能“翻译格式”的小工具。1.3 什么时候你才需要LiteLLM我见过不少团队把LiteLLM当成万能钥匙所有项目都强行套一层其实没必要。我梳理一下真正适合接入它的场景你需要在多个模型之间做效果对比和选型评测希望切换模型时不改业务代码。你的产品要根据用户等级、请求类型动态路由到不同模型。比如简单问题走便宜的小模型复杂推理才用贵的大模型。公司里多个团队、多个项目都在调用大模型API需要一个统一入口来管理密钥、配额和审计日志。你要把大模型能力封装成内部服务给前端页面或其他后端系统调用但不想把服务商密钥暴露到各个角落。反过来如果你的业务只依赖某一家的模型短期内完全不会切换而且对网络延迟极其敏感那直接调官方SDK可能更干净。LiteLLM的抽象层是有代价的——多一层封装就意味着多一次转发和一层可能的故障点。方案选型不能只看“有没有用”还要看“值不值得”。2. 从零跑通第一个请求环境准备与基础接入这一节我按最简路径走先让你在10分钟内发出第一个请求。工程上我们追求“最小可运行闭环”先把链路跑通再逐层加功能。2.1 安装环境避免踩Python版本和依赖的坑LiteLLM是基于Python的官方要求Python 3.8及以上建议直接用3.10或3.11省得遇到一些老版本的类型语法兼容问题。安装命令很简单pip install litellm[proxy]如果只是想在自己项目里当SDK用不打算起代理服务可以只装pip install litellm。但既然要长期用我推荐直接带上proxy扩展后面部署网关模式会用到。我的习惯是用虚拟环境安装无论你用venv还是poetry不要让LiteLLM直接污染系统Python环境。曾经有位同事把LiteLLM直接装进系统环境后面又装了一个依赖pydantic旧版本的项目两者冲突排查了半天。虚拟环境隔离成本极低别在这个环节偷懒。2.2 第一个调用统一格式的请求长什么样装完之后核心用法是这样import os from litellm import completion os.environ[OPENAI_API_KEY] 你的密钥 response completion( modelgpt-4o-mini, messages[ {role: system, content: 你是一个简洁的助手}, {role: user, content: 帮我用一句话介绍量子计算}, ], temperature0.7, ) print(response.choices[0].message.content)注意看不管背后的服务商是哪一家你写的参数结构始终是这套model、messages、temperature。LiteLLM会根据model字符串里的前缀自动判断该把请求发给谁。比如gpt-4o-mini默认走某家官方接口openai/前缀可以显式指定走这家anthropic/claude-3-5-sonnet则是另一家如果你本地自建了兼容通用格式的模型服务还可以用openai/custom-model并配一个api_base指向本地地址。这里有个小细节messages里的角色到底是system还是assistant还是user各家理解基本一致但有些服务商对system消息的处理方式不同。LiteLLM会做一定程度的兼容但如果模型本身对系统提示词的遵循程度很低那不是LiteLLM能解决的事应用层还是要自己控制提示词的写法。2.3 密钥管理别再把服务商密钥硬编码到代码里很多初学者喜欢把密钥直接写在Python文件里甚至不小心把代码推向公开仓库。我的习惯是配合环境变量文件.env来管理OPENAI_API_KEYsk-xxx ANTHROPIC_API_KEYsk-yyy COHERE_API_KEYsk-zzzLiteLLM会自动读取.env文件里的变量。你在代码里只需要确保环境变量存在其他不用管。团队协作时密钥应当收敛到服务器或网关端而不是每个开发者的本地配置。测试环境、预发环境、生产环境的密钥最好分开这样就算某个环境的密钥泄露也能快速定位和轮换。3. 核心功能逐个拆解路由、重试、成本与流式跑通基础调用之后重点来了。LiteLLM之所以在圈内受欢迎是因为它把大模型接入的“脏活累活”都标准化了。这里挑几个我用得最频繁、也最能提升效率的功能展开讲。3.1 多模型路由与故障切换让业务代码不再绑定单一服务商如果你只想固定用一个模型那LiteLLM的优势还不明显。但一旦你想实现“OpenAI挂了自动切别的”或者“不同请求走不同模型”它的路由能力就派上用场了。在代理模式下你可以通过配置文件声明一个model_list把多个后端模型映射到同一个对外名称model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet - model_name: gpt-4o-mini litellm_params: model: azure/chatgpt-v4o-mini api_base: https://your-resource.openai.azure.com/ api_key: os.environ/AZURE_API_KEY这个例子里有个很实用的玩法你对外统一暴露gpt-4o-mini这个名字内部却配了两个后端实例。当第一个后端返回限流错误或者超时LiteLLM会自动把请求转到第二个后端业务层完全无感知。相当于给服务商做了热备。路由策略上LiteLLM支持按优先级顺序调用也支持按权重分发还可以根据延迟做动态选择。我实际使用时的偏好是默认主备模式主服务商承担绝大多数流量备服务商平时可以切到小流量灰度一旦主链路抖动自动切备份。这种方案对可用性要求高的线上服务非常友好。3.2 重试、超时与限流生产环境最容易被忽视的一环大模型API没有不超时的。网络抖动、服务商过载、并发限流每一条都可能让你的请求直接失败。LiteLLM内置了重试机制你只需要设置几个全局变量import litellm litellm.max_retries 3 litellm.request_timeout 30重试策略默认带指数退避也就是第一次失败后等一会儿再试第二次等待时间更长避免在服务商已经过载的情况下继续猛撞。这个设计符合常规的限流退避原则。为什么必须用指数退避而不是固定间隔因为限流往往是服务商整体过载的信号如果所有客户端都用固定间隔重试很容易造成“重试风暴”把服务商彻底压垮。我建议把max_retries设置为2到3次就好不要贪多。超过3次的重试在大模型场景里意义不大——很多错误是请求本身的问题比如提示词超长重试多少次都不会成功。而且每次重试都意味着额外的时间成本和费用成本。对延迟敏感的业务你可以把request_timeout调到10秒以内对离线批处理任务可以放宽到60秒甚至更久。3.3 成本追踪与用量统计别等到月底账单才发现超支接入多家模型之后成本是一个绕不开的问题。LiteLLM提供了成本计算能力和明细日志这一点在代理模式下尤其突出。在SDK模式下你可以这样估算单次请求成本from litellm import completion_cost response completion(...) cost completion_cost(completion_responseresponse)它会根据模型、输入token数和输出token数按服务商的公开价格标准算出一个估算值。需要注意这个价格是LiteLLM仓库里预先配置的如果你的服务商改价了或者你走的是某个渠道的转售价格就要在配置里手动指定input_cost_per_token和output_cost_per_token否则统计出来就是错的。在代理模式下LiteLLM会把每次请求的日志写到数据库并提供查询接口。你可以按天、按Key、按团队拉取用量明细。我们团队原来每个月底对账要从各家服务商后台导出账单再用Excel手工核对半天。现在直接跑一遍日志统计脚本半小时出报表。这个收益在团队规模变大之后会非常明显。3.4 流式输出与工具调用和交互场景强相关的两个能力做聊天机器人或者AI应用流式输出基本是标配。LiteLLM支持streamTrueresponse completion( modelgpt-4o-mini, messages[{role: user, content: 写一段500字的故事}], streamTrue, ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)流式模式下因为数据是分块返回的很多服务商不会在每一块都带上token统计。LiteLLM会在流结束后尽力汇总usage信息但如果服务商本身没给全量统计你可能需要自己用分词库估算。这不是LiteLLM的缺陷而是流式接口本身的限制。工具调用方面LiteLLM把各家不同的工具定义格式统一成了通用的tools参数。这个功能在做Agent类应用时特别有用——你的代码只需要写一套工具定义换模型时不用重写。但我提醒一句工具调用返回的数据不一定规范尤其是一些偏小的开源模型你声明的工具它不一定真的会用甚至可能返回格式错误的伪工具调用。应用层一定要对返回结果做二次校验别指望翻译层能清洗所有脏数据。4. 进阶实战把LiteLLM部署成LLM网关服务SDK模式适合在代码内部使用但如果你面对的是多个前端、多个后端服务、多个团队更推荐把LiteLLM跑成一个独立的网关服务。这一节讲生产部署。4.1 代理模式的价值边界该用和不该用要想清楚网关模式的本质是把所有大模型请求收敛到一个统一的入口。前端页面不再直接持有服务商密钥而是把请求发给你的网关后端服务也不用各自接一遍不同服务商的SDK统一走同一个端点。这就好比公司只有一个前台所有访客都走这里登记安全性、审计、流量控制全部集中在一处。但这里要泼一盆冷水如果你的项目只是一个小Demo部署在本地访问量很低用不起独立网关的维护成本那直接SDK模式就够了。网关模式并没有降低延迟反而多了一层转发。对于每秒只有个位数请求的应用为它维护一个网关服务是一种浪费。取舍标准就一条多个调用方需要共享同一套模型能力、密钥与配额管理时网关才划算。4.2 快速部署一条命令跑起来但生产环境要补数据库最简易的启动方式是命令行直接起服务litellm --config ./config.yaml --port 4000或者用Docker镜像适合放到容器环境docker run -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ ghcr.io/berriai/litellm:main-latest网关启动后对外暴露的是符合行业通用格式的API端点/v1/chat/completions。你把请求发到这个地址网关根据配置路由到真实服务商再把结果转回来。对调用方来说它们只看到一个标准接口不需要关心背后是哪家模型。生产环境部署时我强烈建议配置数据库。默认的SQLite适合单机调试但要长期跑、多实例部署、集中式审计PostgreSQL是更稳的选择。LiteLLM会把虚拟Key、调用日志、用量统计、预算额度全部存下来。配置项主要是环境变量DATABASE_URLpostgresql://user:passlocalhost:5432/litellm LITELLM_MASTER_KEYsk-your-master-key有了数据库之后你关掉网关再重启数据不会丢这对线上排查问题太重要了。4.3 虚拟Key、配额与多租户给团队里每个人都发一把“子钥匙”LiteLLM网关一个很实用的设计是“主Key 虚拟Key”。管理员持有主Key用来调用管理接口创建虚拟Key每个虚拟Key可以绑定特定的模型范围、预算上限、过期时间还能归属到某个团队。创建虚拟Key的典型流程是curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o-mini], max_budget: 10, team_id: team-a }前端或某个业务方拿到虚拟Key后调用网关统一地址即可。这样一来即使某个Key泄露影响面也局限在它绑定的模型和预算范围内你可以随时吊销重建。多租户场景同理不同部门用不同的team_id月底按部门出成本报表。我们团队后来把虚拟Key分配到了测试组、算法组、前端组各组独立配额互不干扰。这种用法比让所有人共用一把服务商Key安全得多。4.4 安全加固的三个必做项第一启动网关前必须设置主Key。没有主Key的网关管理接口裸露等于大门敞开。我见过有人为了省事把主Key留空结果内网扫描直接打穿了管理端。第二对管理接口做网络层限制。比如/key/generate这样的接口最好只允许内网IP段访问。如果部署在云上用安全组规则限制来源别把这些接口暴露到公网。第三日志脱敏。LiteLLM默认会把请求内容记录到数据库如果你的业务涉及用户隐私信息要评估是否关闭请求日志存储或者配置脱敏规则。合规压力大的业务最好自己接日志管道做过滤不依赖默认方案。5. 常见报错与排查经验最后这部分我整理了几类高频问题和对应的排查思路。这些都是实际踩过、查过源码才弄明白的希望能帮你省点时间。5.1 报错速查表错误类型典型现象排查方向AuthenticationError提示鉴权失败检查环境变量里的密钥是否配置正确是否和目标服务商匹配RateLimitError请求被限流检查并发和每分钟调用限制调大重试间隔或降低并发ContextWindowExceededError提示词超出上下文窗口截断历史消息或换用上下文更长的模型ModelNotFoundError找不到指定的模型检查model参数里的前缀是否拼错网关模式检查是否已加入model_listAPIConnectionError网络连接失败检查网络环境、api_base配置是否正确、服务商端点是否可达流式输出为空流式请求后拿不到内容遍历分块时先判断delta.content是否为空再取值5.2 成本统计不准的几个原因成本统计不准最常见的原因有三个一是模型价格没在配置里注册成最新价用默认旧价计算二是流式请求提前中断服务商返回的usage不完整三是图片输入、缓存命中等特殊计费维度没有单独配置。应对思路线上成本统计不要全依赖自动计算定期从服务商后台拉账单做交叉核对。如果用量大建议把每次请求的原始usage字段持久化到自己的数据库用离线任务统一计算成本。LiteLLM的实时统计可以当参考对账还是要以原始数据为准。5.3 我的排雷记录三个容易翻车的小细节升级版本时要留意破坏性变更。LiteLLM版本迭代很快一些老版本里能用的模型名在新版本里要求显式加服务商前缀。我就遇到过一次旧配置里写model: claude-2新版本直接报错改成anthropic/claude-2才恢复。所以每次升级前先看发布说明里的Breaking Changes列表。网关端点路径要和标准格式保持一致。有些人喜欢把路由简写成/chat/completions但LiteLLM对外端点默认是/v1/chat/completions。如果你用自定义路由转发注意别把/v1这一级丢掉否则会404。这问题很像“网址打不开你先看有没有少个斜杠”这种低级错误排查时往往一眼看不出来。配置密钥时别用明文写进代码仓库。被推送到仓库里的密钥一旦泄露后果是账单爆炸或数据泄漏。就算觉得自己仓库是私有的也建议养成用环境变量的习惯这是成本最低的安全投资。我个人在实际操作中的体会是LiteLLM最值得投入的地方不是省下了那几百行适配代码而是它逼着你把密钥管理、成本统计、路由策略这些“非业务的事”提前想清楚。很多人写AI应用时最容易被“跑通就行”的心态带着走结果模型一多、团队一大各种混乱就全冒出来了。如果你正在从单模型Demo走向多模型产品化可以沿着LiteLLM这条路径把自己的工程规范也一起建立起来。