litellm 实战：为大模型调用搭建统一网关与路由策略

做 AI 应用开发的朋友大概都遇到过这种场面今天用 A 家的模型API 是这种格式明天想换成 B 家的又要重写一遍请求逻辑好不容易接好了对方接口突然升级又得跟着改更别说不同模型价格不同、限流策略不同统计成本的时候鸡飞狗跳。我最早看到 litellm 这个开源项目时以为只是一个普通的 SDK直到用它在内部项目里跑通了一次“一行代码切换大模型供应商”才意识到它的真正价值是给大模型调用搭建了一个统一网关。这篇东西就围绕 litellm 聊一聊它到底是什么、核心设计怎么拆、怎么快速上手、生产环境有什么坑我把实际用下来的经验一次说清楚。适合正在做 AI 应用、想接入多家大模型或者想给团队建一个模型管理入口的开发者。1. 为什么要用 litellm先理解它解决的是哪种痛1.1 大模型生态“百花齐放”带来的接入成本现在的大模型服务商很多各家为了差异化请求参数、返回结构、鉴权方式、错误码都不一样。有的用temperature有的用top_p有的返回choices[0].message.content有的返回outputs[0].text有的要求在 Header 里带Authorization有的要放在 query 参数里。如果只是写 demo这些差异忍忍也就过去了但一旦进入真实产品你要同时支持多个供应商做容灾、做价格对比、做 A/B 测试最朴素的办法就是为每一家封装一套 client然后写一堆if provider xxx的分支。我见过某团队在代码里维护了四五套模型调用封装每次新增模型都要改业务代码。这不是技术问题是工程管理问题。litellm 做的事情简单说就是把“到底调哪家”这件事从业务代码里抽出来变成一份配置和一个统一入口。业务侧只跟 litellm 打交道至于背后是 A 家还是 B 家由 litellm 在运行时决定。这等于给所有大模型调用加上了一个适配层。1.2 它不是一个简单的 SDK更像一个“网关”litellm 的官方定位是一个 Python 库同时也提供了一个 OpenAI 兼容的代理服务器Proxy Server。这意味着你可以把它当作库嵌入进程也可以把它作为一个独立服务部署在集群里让团队内所有应用都通过这个代理访问不同模型的 API。这个设计非常聪明。嵌入库的方式适合单机脚本、本地调试代理服务的方式适合微服务架构所有应用只需要配置一个 base_url服务端统一处理模型路由、重试、计费、日志。我自己的感受是litellm 最核心的价值不是“省几行代码”而是“把模型选择和调用策略从业务代码中剥离”。业务开发只需面向一个稳定的 OpenAI 兼容接口模型供应商怎么变、价格怎么调、哪家暂时不可用都是平台侧的事。1.3 什么样的人适合现在就用它如果你只是写一个一次性脚本直接调某家的 SDK 也没什么问题litellm 反而多了一层抽象。但如果你属于下面几类场景litellm 的收益就很直接你的应用要同时接入多个大模型供应商用来做故障转移或成本优化。你的团队有多条业务线都要用大模型希望统一管理 API Key、模型白名单和调用限额。你希望精确统计每个业务、每个用户的 token 消耗和费用而不是靠 Excel 手工记账。你想从某个供应商迁移到另一个但不想重写业务代码。这些场景本质上是“大模型服务化、平台化”的需求litellm 正好踩在这个点上。后面我展开讲它的核心功能时你会发现它不只是把接口格式统一了还顺手解决了一堆工程化问题。2. 核心功能拆解不只是转发请求那么简单2.1 Unified API把不同供应商的“方言”翻译成一种“普通话”litellm 最底层的功能是对外提供一套统一的调用接口。官方的做法是兼容 OpenAI 的请求/响应格式因为 OpenAI 的格式已经成了事实标准很多开源工具比如各类评估框架、Agent 框架都默认支持 OpenAI 协议。你调用 litellm 时只需要传modelanthropic/claude-3-5-sonnet-20241002或者modelgpt-4o这样的模型名litellm 会识别出对应的供应商然后把你的 OpenAI 风格请求翻译成对方真正需要的格式再把对方的响应翻译回 OpenAI 风格。这个翻译过程包括URL 映射不同供应商有不同的 endpoint。鉴权头处理有的需要api-key头有的需要Authorization: Bearer。参数名转换比如某些供应商用max_new_tokenslitellm 会把它转成 OpenAI 的max_tokens。响应结构归一化无论原供应商返回什么结构litellm 都统一包装成choices、usage等字段。错误码归一化把供应商特有的错误码映射成 OpenAI 风格的错误类型方便上层做统一处理。这样做的好处是明显的你为 litellm 写的业务逻辑可以原封不动地用在所有被支持的模型上。比如你用同样的代码调用 GPT-4o 和 Claude只需改model参数连解析响应的方式都不用变。2.2 Router 与自动重试让“换一个模型”变成配置项如果你的需求只是“调用不同供应商”一个 SDK 就够了。但真实场景更复杂某家服务超时了怎么办某家限流了怎么办某些请求对延迟敏感能不能先走便宜的模型不行再走贵的litellm 内置了一个Router组件你可以把它理解成带策略的调度器。Router 可以配置多个 provider 或多个模型然后根据策略分发请求。常见的策略包括优先级策略优先使用配置列表里排在前面的模型失败后自动切换到下一个。权重策略按比例把请求分配到不同模型适合灰度或成本优化。限流感知如果某个模型已触发 429 限流自动绕开它一段时间。区域/延迟感知根据 provider 的响应时间动态调整路由。我自己最常用的是 fallback主模型挂了自动降级到备选模型。以前你要在业务代码里写try: A except: B现在只需要在 litellm 配置里写一行fallbacks[{gpt-4o: [claude-...]}]。这不只是少写代码更重要的是把高可用策略集中管理业务侧永远只是调一个接口。2.3 成本跟踪与预算控制把每一分 token 花在哪说得清大模型应用跟传统 API 不同成本高度依赖 token 数量而 token 数量又随用户输入动态变化。litellm 内置了 Token 计数和成本计算它内部维护了一张模型价格表能根据模型名、输入/输出 token 数计算费用。如果你通过代理服务器模式运行litellm 会自动为每个请求记录usage并把成本数据落到数据库里。这样就带来了三个价值第一实时知道当前项目的日/月花费第二可以按团队、按 App 做预算限制超出就直接拒绝请求第三可以为内部系统做成本分摊比如按用户维度记录 token 消耗。我认为成本追踪是 litellm 很容易被低估的功能。很多时候业务方只关心“能不能调通”忽略了“钱是怎么花的”。没有统一网关时多个服务各自记一批日志成本很难对账有了 litellm至少有一个全局视角。2.4 代理服务器模式把模型能力变成团队的基础设施litellm 的proxy模式是一个基于 FastAPI 的高性能服务启动后对外暴露/chat/completions、/embeddings、/models等接口完全兼容 OpenAI API。团队内的应用不需要装 litellm只需把 OpenAI SDK 的base_url指向 litellm 代理把 API Key 换成 litellm 管理下的 Key就能调用各种模型。这个模式特别适合多团队协作。你可以为不同团队生成不同的 Key设置不同的模型白名单、速率限制和预算上限。比如 A 团队只能用 GPT-4oB 团队只能用 Claude或者所有团队的日预算都是 100 元超出自动拒绝。这些运维能力让大模型调用从“开发者的自由发挥”变成了“平台可控的服务”。2.5 额外能力缓存、日志、提示词管理与流式处理除了上面几个核心点litellm 还内置了几种实用的辅助能力缓存支持 Redis 和内存缓存对相同请求可以命中缓存减少调用次数和成本。日志与监控代理模式会记录完整的请求/响应元数据可以对接外部日志系统。提示词管理提供一个类似管理界面可以存模板、版本化提示词。流式输出支持 SSE 流式返回且会正确处理各家的流式格式差异。这些功能不是必需的但在生产环境里往往能省不少事。比如缓存很多人可能觉得“AI 请求怎么缓存”但实际很多请求是重复的比如固定 prompt 的文本分类、相似度计算缓存命中率相当可观。3. 快速开始从零搭一个 litellm 网关3.1 安装与最小配置litellm 的安装很简单直接用 pippip install litellm[proxy]这里我推荐装[proxy]版本因为即使你现在只用 SDK以后大概率也会用到代理模式。装完后可以先用一个最简单的 Python 脚本验证import litellm response litellm.completion( modelgpt-4o, messages[{role: user, content: 你好用一句话介绍自己}], api_key你的key ) print(response.choices[0].message.content)第一次运行前需要设置环境变量OPENAI_API_KEY或者在调用时传api_key参数。如果只需要测通这一步就够了。litellm 会根据model的前缀自动识别供应商比如gpt-前缀默认走 OpenAIclaude-前缀默认走 Anthropic。3.2 以 OpenAI 兼容方式调用代理等你验证完 SDK接下来值得做的是启动代理服务。在终端执行litellm --model gpt-4o --port 4000这样会在http://localhost:4000起一个 OpenAI 兼容服务。然后在任意 Python 项目里用 OpenAI SDK 指向它from openai import OpenAI client OpenAI( api_keysk-litellm-test-key, # 代理模式下可以用任意占位key开头 base_urlhttp://localhost:4000 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)注意这时候业务代码完全不依赖 litellm用的是标准的 openai 库。这样做的意义我在前面已经说过让业务侧只认一个接口而 litellm 负责搞定背后所有差异。3.3 用配置文件管理多个模型命令行参数适合快速测试真正生产建议用配置文件。litellm 代理支持 YAML 配置下面是一个最小但完整的示例model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241002 api_key: os.environ/ANTHROPIC_API_KEY litellm_settings: drop_params: true set_verbose: false general_settings: master_key: sk-my-master-key然后用litellm --config config.yaml启动。这里有几个细节值得注意对非 OpenAI 模型需要在model字段加供应商前缀比如anthropic/、openai/。api_key可以写os.environ/XXXlitellm 会从环境变量读取方便密钥管理。master_key是代理的全局管理密钥客户端请求时作为 API key 传入也可以在管理后台调用。配置好后代理端的/models接口会动态列出可用的模型名客户端只要用配置文件里的model_name比如claude-sonnet请求即可即使背后的实际模型换了客户端也不需要改。3.4 SDK 模式下的高级调用方式除了 completionlitellm 还支持# 嵌入向量 litellm.embedding(modeltext-embedding-ada-002, input[hello]) # 图片输入 response litellm.completion( modelgpt-4o, messages[ { role: user, content: [ {type: text, text: 图片里有什么}, {type: image_url, image_url: {url: ...}} ] } ] )对于流式SDK 调用里加streamTrue即可litellm 会把底层 provider 的流式响应转换成 OpenAI SSE 格式。如果你用代理模式客户端收到的是标准 SSE 流对前端非常友好。4. 生产环境实操要点从能跑到跑稳4.1 环境变量和密钥管理千万别把 Key 写进代码你接 litellm 的代理时第一件事是把所有供应商的 Key 都放到环境变量或专门的密钥管理服务里。YAML 配置文件里写os.environ/是 litellm 推荐的做法但要注意它读取的是启动 litellm 进程的环境所以部署时要把密钥注入到进程环境里比如借助容器或编排系统的 secret 功能。另外litellm 代理的master_key一定要单独设置不要跟真正供应商的 Key 混用。代理模式下客户端用的 Key 是由 litellm 生成的虚拟 Key背后对应的是哪个供应商的 Key、允许用哪些模型都存储在自己的数据库里。这样可以实现“客户端拿到了 Key 也不能调用未授权的模型”。4.2 配置 fallback 和重试高可用不是靠运气生产环境最怕上游接口不稳定。litellm 支持两种层面的故障处理一种是 provider 本身返回错误比如 5xx、429一种是请求超时。在配置里可以这么写model_list: - model_name: gpt-4o litellm_params: model: gpt-4o - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241002 router_settings: fallbacks: - gpt-4o: [claude-sonnet] retry_policy: gpt-4o: timeout: 30 max_retries: 3 retryable_status_codes: [429, 500, 503]fallback 的意思是当gpt-4o请求失败时自动改发claude-sonnet。这个策略在业务层完全透明用户只会感觉到“偶尔慢了一点”不会直接看到报错。我建议所有生产环境都配上 fallback哪怕你只有 90% 的请求走主模型也能把可用性拉到很高。4.3 预算控制和模型白名单把权限边界定清楚多团队共用一个 litellm 网关时最好提前规划虚拟 Key。litellm 的代理提供/key/generate接口可以生成带models、max_budget、budget_duration等约束的虚拟 Key。比如你可以为一个新项目生成这样的 Keycurl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-my-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 100, budget_duration: 1d }这样这个 Key 每天最多花 100 元而且只能调gpt-4o。这种能力对成本治理真的有用内部系统经常出现有人拿错 Key 调用高价模型最后月底账单爆炸的情况。有了 litellm至少能让预算在入口处就被控制住。4.4 自定义请求参数和模型扩展有时候你需要在请求中传入 provider 特有的参数比如某家的top_k。litellm 有两种处理方式在调用时直接传extra_body或litellm_params中带 provider 参数。如果只是想在所有请求里统一加参数可以在 YAML 的litellm_params里设置additional_args。重点说下drop_params。不同 provider 对参数的容忍度不同有些参数在 OpenAI 上合法在另一家却会被直接报错。如果配置文件里开了drop_params: truelitellm 会自动丢弃不支持的参数而不是报错。这个选项在处理多个模型时很实用但也要注意它可能会悄悄去掉你本来想传的参数导致模型行为不符合预期。所以建议只在有把握的场景打开并配合日志观察。5. 常见问题与排查实录5.1 鉴权失败401 Unauthorized这是最典型的问题。如果你用的是 SDK 模式先确认环境变量名是否正确。litellm 对每个供应商有固定的环境变量命名规则比如 OpenAI 是OPENAI_API_KEYAnthropic 是ANTHROPIC_API_KEY。如果你设置了变量但报错可以在代码里加litellm.set_verboseTrue打印详细请求头确认 Key 有没有传对。如果你用的是代理模式客户端报 401通常是虚拟 Key 没设置对。先在启动代理的终端里确认master_key已设置然后用Authorization: Bearer key访问。还有一种容易被忽略的情况你之前用旧版本的 litellm 生成的虚拟 Key升级后数据库结构变了换个新 Key 即可。5.2 模型名不对Model Not Foundlitellm 对模型名的解析依赖前缀。如果你传modelclaude-3-5-sonnet-20241002它可能会识别成 OpenAI 的模型而不是 Anthropic。正确做法是带供应商前缀例如anthropic/claude-3-5-sonnet-20241002。如果使用代理模式则必须使用model_name配置的别名。你可以调/models接口看看当前到底有哪些模型名可用。5.3 429 限流和超时429 说明触发了上游限流。litellm 默认对 429 会做重试但要注意重试策略不要过猛否则可能加剧上游压力。建议在配置里设置retry_policy时给 429 一个稍长的重试间隔比如cooldown_time设为 5 秒以上。如果同时有大量请求打到同一个模型可以考虑在 litellm 前面加一层负载均衡或者用router_settings.allowed_fails控制失败熔断。超时类的报错先确认是连接超时还是读取超时。litellm 里可以设置timeout但不同 provider 的响应时间差异很大。我遇到过某个模型在生成长回复时经常超时后来把timeout从默认值调大到 120 秒才好。这里要权衡超时太长用户体验差太短响应慢的场景频繁失败。建议结合具体模型的常见响应时长来设置。5.4 流式输出断流或不完整如果你用代理模式并开启了streamTrue最常遇到的坑是前端拿到的流中间断掉。先排查是不是反向代理的缓冲问题。很多 Nginx 默认会缓冲 SSE 流导致消息不是实时到达甚至超时断连。你需要关闭该路径的代理缓冲比如设置proxy_buffering off以及对/chat/completions路径设置较长的proxy_read_timeout。还有一类问题是 litellm 的流式转换本身。因为不同 provider 的流式 chunk 格式不一样litellm 把它们统一成 OpenAI 格式时可能因为某个字段缺失而中断。升级到最新版本通常能解决大部分这类问题因为项目维护很活跃兼容性问题修复很快。5.5 成本统计不准有时你会发现 litellm 统计的费用和预期差很多。最常见的原因是没有传入input_cost_per_token和output_cost_per_token导致费用计算使用了默认价格而默认价格可能已过时或不符合你所用的模型版本。另一个原因是你用了自定义模型名litellm 不认识无法匹配到内置价格表。解决方法是在配置的litellm_params里显式指定模型实际名称或者为自定义模型在配置里补充成本参数。如果只差一点点也可以忽略但如果差距持续存在建议先用/cost相关接口检查一下 litellm 对你的模型费用估算。5.6 日志和调试技巧litellm 提供了几个很实用的调试入口litellm.set_verboseTrue打印详细请求/响应适合开发阶段。代理模式下/spend/logs接口查看每个 Key 的花费明细。/model/info接口查看配置文件中所有模型的状态。我调试时经常先看/model/info确认模型配置是否加载正确然后再用set_verbose追踪单个请求。这个顺序能帮你快速区分是配置问题还是网络/上游问题。6. 一些个人使用体会我在实际项目中已经跑了近半年的 litellm最深的体会是这类工具的定位不是“消灭复杂度”而是“把复杂度收敛到一个可控的层”。如果你只在单机脚本里用可能感受不到它的好处但一旦到了多模型、多团队、需要算钱、需要审计的场景它会变成基础设施的一部分。有几个细微的操作习惯值得分享。一是版本管理litellm 迭代非常快新特性多但也可能带来配置兼容性变化建议在正式环境锁版本升级前先在测试环境跑一遍回归。二是尽量用代理模式而不是把 litellm 库直接嵌入太多服务否则升级库版本时所有服务都要联动代理模式能把这层变化隔离住。三是配置变更尽量走配置文件加上版本管理避免直接在数据库里改模型路由不然事后很难复盘。最后再提醒一句litellm 的功能很多但没必要一开始全用上。从统一接口做起先解决接入问题等有需要了再逐步开路由、预算、缓存。逐步演进比自己一次性堆配置要稳得多。希望这篇内容能帮你少走点弯路。