做AI应用开发最烦的事情之一就是接模型。今天要聊的 litellm就是专门治这个问题的开源工具。它不是一个模型也不是某个厂商的SDK而是一层非常薄的统一接入层你用同一套调用风格就能对接不同厂商、不同协议的大模型API同时还把事情背后那些工程问题比如重试、超时、路由、成本统计、密钥管理一并接住了。适合谁所有正在做AI应用、写Agent、给团队搭内部模型网关的开发者尤其是被多套API格式、多个供应商来回切换折磨过的人。我最早用 litellm 的原因很简单项目里需要对比两个不同厂商的模型效果但两边请求格式、鉴权方式、流式解析全都不一样。要是硬写适配层代码会越来越脏。后来逐步试了代理模式、虚拟Key、成本追踪发现它已经不是“一个小库”而是一个能变成网关的完整工程组件。这篇就从实际使用角度出发把 litellm 是什么、怎么快速集成、怎么部署成代理网关、有哪些坑一次讲清楚。你不需要有很深的背景知识只要写过几段Python、知道大模型API大概长什么样就能跟上。1. 为什么需要 litellm先搞懂它解决的是哪类痛点1.1 多模型接入的格式碎片化现在大模型服务已经不止一家。头部厂商、开源社区、云平台都提供各自的API。表面看大家长得差不多都是POST一段消息列表过去再拿回一段生成结果。但实际用起来差异全藏在细节里有的服务要求把Key放在Header里有的支持额外的组织ID字段有的参数叫 max_tokens有的叫 max_completion_tokens有的流式事件结构很规整有的会把额外字段塞得五花八门。如果业务只接一家这些差异无所谓。一旦要同时接两三家甚至随时准备把流量在多条供应商之间切换代码就会迅速变成一坨if-else。今天适配这家明天调试那家大量时间花在“翻译协议”而不是“产品逻辑”上。这个问题其实很像支付场景每家银行都给你一套独立协议你最终必须有聚合支付层。litellm 做的就是聚合层的事对外统一格式对内把请求分发到真实的服务商。我和很多同行交流下来大家遇到的第一道坎基本都不是“模型效果不行”而是“接不进去、接不稳、改起来太慢”。这个问题足够普遍才让 litellm 这类工具变得有价值。1.2 litellm 的定位一个“翻译层”而不是新模型litellm 本身不包含大模型权重也不做模型推理。它就是一个轻量化库把发往各家的请求和响应做统一转换。真实生成能力完全来自上游模型服务litellm 不会改变模型质量也不会因为多了这层而增加额外生成延迟。这个定位很关键。很多人一听到“统一大模型接入”会误以为它是个黑盒路由能帮你自动判断哪个模型更好用、哪个更便宜。实际上litellm 更偏向于工程化接入而不是智能策略。你可以自己实现分流、降级、灰度但控制权始终在你手里。litellm 负责把你写好的规则落地。为什么叫“lite”因为它核心代码确实不重没有依赖一堆重型组件。大多数场景装完就能用。要注意的是不同模型的独有能力不一定能完全通过统一参数覆盖。比如某个模型有特殊的思考过程参数、特殊的工具调用格式litellm 会尽量兼容也提供“透传”机制把额外字段原样传过去但你不能指望所有私有能力都被抽象成一个统一方法。1.3 哪些场景值得引入我实际用下来值得引入 litellm 的场景主要有这么几类AI 应用和 Agent 开发项目要调用多个模型做对比、兜底或分工但不想维护一整套厂商SDK的适配代码。团队模型网关前端或多个业务后端要访问模型API但不想把真实密钥散落到各处需要统一入口、统一鉴权。成本治理多个团队复用同一个账号需要按项目拆分Key统计各自花费还要设置预算上限。模型迁移今天用的模型A效果不理想想低成本切到模型B业务代码尽量不改。不适合的场景也很清楚。比如你只是本地脚本里短期调用一个固定厂商直接用厂商SDK最轻没必要引一层中间件。如果团队对某个供应商的私有功能依赖极深也要先评估 litellm 能不能完整承接再决定是否引入。任何工具都有边界litellm 的边界就是“统一工程操作”而不是“包治百病”。2. 最快上手方式Python SDK 的基础调用2.1 安装与第一次请求安装特别简单。如果只是Python项目里调用装基础版就行pip install litellm如果你想把 litellm 作为独立代理服务部署建议直接装带 proxy 扩展的版本pip install litellm[proxy]装完以后最基础的调用长这样import litellm response litellm.completion( modelprovider-a/model-a, messages[ {role: system, content: 你是一个简洁的助手}, {role: user, content: 用一句话介绍你自己}, ], temperature0.7, ) print(response.choices[0].message.content)这里最关键的是 model 参数。litellm 的默认约定是“服务商标识/模型名”也就是 provider-a/model-a 这种形式。前半段决定请求被改写成哪家协议后半段是上游真实的模型标识。如果你用了官方配置方式也可以只传 model-a让 litellm 从配置里反查完整标识。密钥通常通过环境变量注入。我习惯在项目根目录放一个 .env 文件用类似 python-dotenv 的机制加载。启动前先确认环境变量存在不然第一个请求会因为缺Key直接报401。这个看起来基础但我见过太多人在这一步卡住。2.2 同步、异步、流式三种常见调用姿势同步调用最简单适合脚本和低频场景。但实际AI应用大多数是Web服务高并发下都用异步。litellm 对异步支持很成熟import asyncio import litellm async def main(): response await litellm.acompletion( modelprovider-a/model-a, messages[{role: user, content: 你好}], ) print(response.choices[0].message.content) asyncio.run(main())流式场景同样重要。现在的对话应用几乎都要打字机效果直接加 streamTrue 就能拿到增量内容response litellm.completion( modelprovider-a/model-a, messages[{role: user, content: 写一段100字的欢迎语}], streamTrue, ) for chunk in response: delta chunk.choices[0].delta.content if delta: print(delta, end, flushTrue)异步流式就用 litellm.acompletion 加 streamTrue返回的是一个异步迭代器遍历方式类似。这几招基本覆盖90%的日常开发场景不需要再为不同厂商单独写解析逻辑。在本地快速验证的时候我喜欢先跑同步加非流式把整段返回结构打印出来看一遍确认通后再改成异步或流式。这样能更快定位问题也方便看到上游返回的原始字段。新手往往一上来就写流式结果发现某个字段解析出来是空的排查半天反而不如先同步看一眼。2.3 用一套参数覆盖不同API的差异不同厂商对参数的处理差异大。litellm 会做很多桥接比如某家只认 max_tokens另一家认 max_completion_tokens你统一写 max_tokens它会按目标厂商的规则映射。类似还有 temperature、top_p、stop 等通用参数基本都能直接传。还有一些模型独有参数可以通过 extra_body 透传response litellm.completion( modelprovider-a/model-a, messages[{role: user, content: 解释一下量子纠缠}], extra_body{ thinking_budget: 1000 }, )extra_body 里的键值会原样拼到请求体里这是给高级场景留的“逃生通道”。但要注意代理模式下这个透传字段默认不一定开放需要在网管配置里把“允许额外参数”的开关打开否则会被拦截。后面讲配置时会提到。我也要泼一盆冷水统一调用风格不等于“所有模型能力完全一致”。有的模型支持结构化输出有的支持工具调用有的连系统提示都有单独限制。litellm 的目标是让通用能力保持一致特殊能力走透传。建立这个预期才不会在集成某个冷门模型时觉得“被坑了”。3. 把 litellm 变成网关部署本地代理服务3.1 为什么要把接入层独立成服务SDK 方式适合代码内部调用。但如果你有多个项目、多个团队甚至前端要直接调模型API每次都把密钥分发到各处就非常危险。更合理的做法是把 litellm 跑成一个独立网关统一入口、统一鉴权、统一计量。上游是什么厂商、密钥在哪里对下游客户端完全不可见。客户端只拿一个网关注册的虚拟Key。这个Key能绑定某个模型范围也能绑定预算上限。这样安全性和治理能力都上来了。部署成网关还能解决另一个问题上游API地址可能会变某些模型也可能要走特殊内网出口。如果客户端直连上游这些变动要改一遍所有客户端如果走 litellm 网关只要改网关配置就行。我用下来最大的体感是模型调用变成了“内部微服务”谁想接入先申请Key再来问文档。这对团队协作的规范化帮助非常大。3.2 一份最小可用的代理配置litellm 代理使用 YAML 配置文件。最小配置大概这样model_list: - model_name: chat-main litellm_params: model: provider-a/model-a api_key: os.environ/PROVIDER_A_KEY api_base: https://provider-a.example.com/v1 - model_name: chat-backup litellm_params: model: provider-b/model-b api_key: os.environ/PROVIDER_B_KEY启动命令litellm --config config.yaml --port 8000启动后网关会提供一个兼容主流 SDK 的 /chat/completions 端点。客户端的 base_url 指向 http://localhost:8000model 参数传 model_list 里定义的 model_name比如 chat-mainKey 传虚拟Key。这里最有价值的一点是下游业务不需要知道真实模型标识只认识你定义的业务别名。哪天你想把主模型换成某个新版本只需要改网关配置客户端一行代码都不用动。如果业务侧有多个环境比如开发环境和生产环境可以分别维护两份配置用相同的 model_name指向不同的上游逻辑完全隔离。3.3 路由策略、失败重试与限流网关模式下最有用的工程能力是路由。你可以在 model_list 里给同一个 model_name 配置多个候选上游并设置权重实现负载均衡model_list: - model_name: chat-main litellm_params: model: provider-a/model-a api_key: os.environ/PROVIDER_A_KEY model_info: weight: 5 - model_name: chat-main litellm_params: model: provider-b/model-b api_key: os.environ/PROVIDER_B_KEY model_info: weight: 3这样所有发给 chat-main 的请求会按 5:3 的比例分到两个上游。每次请求是独立路由的所以会话上下文里如果希望连续对话始终落在同一个模型可能需要额外传用户标识或会话标识否则不同轮次可能被分到不同模型。这是我在实际项目中踩过的一个细坑做状态管理时要留意。重试和超时配置放在 litellm_settings 里litellm_settings: drop_params: true num_retries: 3 request_timeout: 60 retry_after: 0.2num_retries 会在遇到网络错误、超时、上游5xx时自动重试。retry_after 是基础等待时间litellm 使用指数退避递增。这个机制实测下来很有用尤其上游偶尔抖动时对客户端基本无感。不过重试也可能放大压力如果上游已经过载频繁重试只会更糟所以别把重试次数设得太大3次左右比较合理。限流方面litellm 支持 RPM每分钟请求数和 TPM每分钟Token数控制。可以按模型配置也可以按虚拟Key配置。后面讲Key时再具体展开。3.4 Key下发与预算追踪代理模式下litellm 支持虚拟Key管理。开启方式是在 general_settings 里配置 master_key 和数据库连接general_settings: master_key: sk-master-123 database_url: os.environ/DATABASE_URLmaster_key 是管理Key不能暴露给普通客户端。第一次使用要先创建一个虚拟Key调用管理接口curl -X POST http://localhost:8000/key/generate \ -H Authorization: Bearer sk-master-123 \ -H Content-Type: application/json \ -d { models: [chat-main], max_budget: 20.0 }返回结果里会带一个 sk- 开头的虚拟Key。之后客户端用这个Key去调 /chat/completionslitellm 会自动记录每次调用的 token 数和花费并把成本写回数据库。虚拟Key的预算统计依赖数据库。如果本地临时跑一下没配置数据库很多功能不会生效甚至 Key 生成接口都会报错。生产使用至少接一个关系型数据库存 Key、用量和审计日志。数据是你做成本治理的核心别省这一步。给数据库单独建一个最小权限账号只允许读写业务库不要用超管账号跑 litellm。4. 进阶功能和避坑指南4.1 多模型统一入口与别名管理model_list 本质上是一张路由表。除了把同一个业务名映射到多个模型你也可以给同一个模型起多个别名方便不同团队使用。比如有的团队习惯叫 chat-main有的团队习惯叫 review-model你可以在 model_list 里配置两条记录指向同一个上游名称不同而已。这样有另一个好处每个团队拿到的虚拟Key可以绑定不同的模型别名天然做到权限隔离。运营团队只能调某个专用模型研发团队可以调全部模型都在Key层面控制不用每个请求都写很多判断逻辑。litellm 代理还自带一个模型列表查询接口/v1/models。客户端通过它拉取当前可用的模型列表很多管理后台会拿这个做下拉框。它返回的是你配置的 model_name 别名不会直接暴露真实上游模型标识对安全也比较友好。4.2 成本核算与模型价格配置litellm 有内置价格表很多主流模型的价格会自动识别。但如果用的是私有化部署模型或者服务商价格表有调整内置价格可能不准。这时需要自定义成本model_list: - model_name: private-llm litellm_params: model: provider-private/custom-model api_base: http://internal.example.com/v1 api_key: os.environ/PRIVATE_KEY model_info: custom_cost_per_token: 0.000002custom_cost_per_token 是每个 token 的成本。某些场景还需要区分输入和输出价格litellm 也支持分别设置。价格配置好后统计的花费才接近真实账单。如果不配置litellm 只能记录 token 数量花费字段可能为空或不准。这里我特别想提醒一句做成本统计时单位一定要确认清楚。有的服务商报价单位是“每千 token”有的直接给“每个 token”。写成配置前先统一换算否则月底账单出来会吓一跳。我的做法是写个小脚本用一条短请求和一条长请求分别测试统计结果和上游账单对一下调准了再上线。4.3 超时、重试与错误码的正确处理方式litellm 的错误可以分为几类上游服务返回错误、网络超时、本地参数校验错误。默认情况下它会把上游错误包装成统一格式返回给客户端。但客户端不应该只盯着错误信息文本判断而是根据响应里的状态码或错误类型字段去处理。我的建议如下429触发了速率限制客户端应退避后重试。401/403鉴权失败检查Key、模型权限。400请求体或参数有问题优先检查消息格式。5xx上游故障可等待后重试。litellm 支持对 429 做自动重试默认重试次数和退避可以在配置里调整。这里容易踩的坑是 timeout 设太短。大模型响应时间并不稳定如果 request_timeout 只有10秒稍微复杂一点的生成或流式请求很容易断。至少给到60秒。流式场景更要留意超时通常应该覆盖单个 chunk 之间的间隔而不是整体完成时间不然客户端很容易在用户读到一半时报错。5. 常见问题排查实录5.1 请求失败且日志不够直观我第一次用 litellm 时遇到一个常见情况调用 completion 报错但日志只有一串很长、不直观的异常。后来发现 litellm 有环境变量可以开启详细日志export LITELLM_LOGDEBUG开启后能看到请求被改写成什么样、发到了哪个地址、上游返回了什么。排查请求被拒、参数映射错误时这个是最优先的手段。日志级别可以从 DEBUG 调到 INFO生产环境不建议一直开着 DEBUG噪声太大。还有一类问题是在干净环境里跑不起来多半是缺依赖。litellm 依赖处理得已经比较干净但如果用了异步流式某些环境还要检查一个东西相关HTTP客户端库版本是否太旧。建议直接升级到最新版本再试。别小看版本问题很多时候报错信息指向“字段不存在”其实是某个中间依赖版本不匹配。5.2 代理部署后流量全部串到同一个模型配置了多个模型路由但压测发现所有请求都打到了同一个模型。这种情况通常不是 litellm 的 bug而是配置没生效。请检查每个 model_name 的 litellm_params 是否都写对了完整模型标识model_info.weight 是否漏配。还有一个细节如果客户端没有把 model 参数传成你定义的别名而是传了一个不存在的名字litellm 会直接报 model not found而不是默认路由到第一个模型。新版里可以配置“允许任意模型名”的开关但生产环境不建议开尽量保持白名单模式。如果你希望“一个业务名对应多个模型”并且每个模型失败时自动切换而不是按权重均衡那本质上是 fallback 策略不是负载均衡。litellm 两种都支持但规则不一样一定要先想清楚自己需要哪种。负载均衡是让流量分摊fallback 是等主路失败再用备路混着写容易出现不符合预期的效果。5.3 Key/预算数据不准或丢失虚拟Key生成后预算统计不准大多数情况是数据库没接或者表结构没有自动初始化。litellm 启动时会尝试自动建表但某些只读权限的数据库用户会导致初始化失败日志里能看到迁移错误。我的处理方式单独给 litellm 创建一个有读写权限的数据库启动时允许它自动迁移。如果公司数据库权限管理严格可以手动执行迁移脚本但需要注意版本对齐。另外成本统计依赖 token 数如果你自定义了模型价格还要确认价格单位写对是“每个 token”还是“每千 token”这个前面提过真的很容易出错。预算上限还有一个潜在问题多次并发请求可能同时通过预算检查导致实际花费略超预算。litellm 的预算控制不是强一致的事务扣减而是近似控制。如果预算必须是硬上限你需要在网关前再包一层更严格的请求计数逻辑。5.4 安全边界与合规自查litellm 网关本质上是替你转发请求所以它是一个统一出入口。我的几条经验master_key 一定要用强随机值不要用示例里的默认值。生产环境把网关部署在内网或前置一层认证不要直接暴露公网。虚拟Key按最小权限分配只能访问某个模型就不要给它全部模型权限。日志中不要明文记录完整API Key。litellm 一般会做脱敏但如果你自己接日志也要注意。如果模型返回内容涉敏网关日志和成本库同样要做访问控制别只盯着模型侧。这些事早期嫌麻烦不做后面出一次问题就要花好几倍成本去补。安全不是某个开关而是从Key生成、网络隔离、日志采集到数据库权限的一整套边界。最后再说说我对 litellm 的实际体会。它不是银弹也不该成为每套系统里的强制依赖。我个人经验是先把它当成接口适配层只解决格式统一问题等团队规模上来再逐步开启代理、虚拟Key、成本追踪这些能力。上线初期别贪多先跑通一条主链路确认日志和统计数据正常再慢慢放开给更多业务方。一个小技巧维护一份内部的“模型清单”文档把所有 model_name、真实上游模型标识、权限范围、价格条目都写全。不管是自己排查问题还是后面同事接手都会轻松很多。我踩过几次坑之后才明白工具只是帮你收敛复杂度真正让人省心的是你在使用工具之前有没有把结构和边界想清楚。