做 AI 应用落地这一年多我最大的感受是模型本身反而不是最纠结的选项真正磨人的是把各家服务商串起来这件事。今天聊的 LiteLLM就是为这个痛点而生的开源项目——它既可以作为一个 Python 库嵌入你的代码也可以部署成独立的代理网关核心承诺只有一句话用 OpenAI 的接口格式统一调用 100 多家大模型服务商。我第一次接触它在一次多模型评测项目里。当时需要对比 GPT、Claude、Gemini 和几个开源模型的回答质量最原始的写法是每个模型都装一套官方 SDK各自初始化客户端、各自拼 messages、各自处理错误代码里全是 if-else日志格式还不统一。换模型等于重写小半套调用逻辑。LiteLLM 把这一层完全抹平了改一行 model 字符串就能切换供应商流式、异步、工具调用、成本统计都走同一套接口。如果你也在做多模型产品或想给团队搭一个统一的模型网关这篇文章应该能帮你省掉不少弯路。1. 统一接入层存在的意义各家 API 的差异远比你想的多1.1 每次都重写一遍 SDK 适配问题出在哪很多人以为各家大模型 API 大同小异不就是发个 prompt 拿个回复吗真上手写过才发现差距。初始化客户端的方式就不一样OpenAI 是 api_key 一把梭Anthropic 需要 x-api-key 放在请求头里AWS Bedrock 走的是 IAM 签名Azure OpenAI 还得额外带 endpoint 和 api-versionGoogle Gemini 有时候要处理 project、location 这一串参数。这只是身份认证后面还有更麻烦的消息结构不同。OpenAI 把 system prompt 放在 messages 里的 system 角色Anthropic 是独立的 system 参数Gemini 的消息结构又是另一套 content/parts 嵌套。流式输出的格式不同。各家 SSE 事件里的字段命名不一样有的给你 delta有的给 content解析代码没法复用。错误码语义不同。同样一个 429有的服务是限流有的是配额耗尽5xx 里还分过载和网关错误处理策略完全不同。用量字段不统一。有的返回 prompt_tokens/completion_tokens有的返回 input_tokens/output_tokens统计成本时还得各写一份换算逻辑。我见过不少项目因为这些差异把业务代码写得又厚又脆模型厂商一升级接口或者换了个参数命名就要跟着改业务。这就是我理解的适配地狱——模型越多维护成本越高而且这些代码基本没有业务价值纯粹是搬运工。1.2 LiteLLM 的思路用 OpenAI 格式当通用语言LiteLLM 的解法很直接把 OpenAI 的 Chat Completions 风格作为统一输入输出格式内部再做协议转换。你在代码里永远只写一套 messages、tools、stream 这些概念LiteLLM 负责把它们翻译成各家 API 真正需要的结构再把各家返回结果统一成 OpenAI 风格的对象。使用哪种模型通过 model 字符串来控制例如openai/gpt-4o、anthropic/claude-3-5-sonnet-latest、gemini/gemini-1.5-pro、bedrock/anthropic.claude-v3-sonnet前缀就是服务商标识。这个设计聪明在哪OpenAI 格式几乎是当前事实标准LangChain、LlamaIndex、各种开源工具链都兼容 OpenAI 风格 API。用 LiteLLM 等于让自己的代码天然呆在所有生态的连接器里。而且网关模式下它对外暴露的也是 OpenAI 兼容接口这意味着你项目中已存在的 OpenAI SDK 客户端只需要改一下 base_url 就能接入不需要引入任何新的客户端依赖。需要提醒的是LiteLLM 不是把所有模型的能力都缩减成最小公分母。对于各家特有的高级能力它也在不断补齐但如果你依赖某个品牌刚发布、只在官方 SDK 里出现的独家参数那就要先在 LiteLLM 的文档里确认支持情况别默认有手就行。2. SDK 模式实际用起来的样子2.1 最小调用代码与模型热切换最基础的使用方式就是直接当普通库调用。安装很简单SDK 模式一个 pip 命令就好pip install litellm然后设置环境变量比如OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEYLiteLLM 会按 model 前缀自动读取对应的密钥。写一个最小调用from litellm import completion response completion( modelgpt-4o, messages[ {role: system, content: 你是一个专业的中文写作助手。}, {role: user, content: 帮我写一段关于数据可视化的简介。} ], temperature0.7 ) print(response.choices[0].message.content)这段代码的返回值结构和 OpenAI SDK 几乎一样choices[0].message.content直接拿文本response.usage拿 token 用量。真正让我觉得舒服的是换模型成本极低把 model 改成response completion( modelclaude-3-5-sonnet-latest, messagesmessages, )别的代码一行不用动。做模型对比评测的时候这个特性省下的时间非常可观。如果不带提供商前缀比如直接写gpt-4o或claude-3-5-sonnet-latestLiteLLM 会根据内置的模型注册表自动推断供应商大多数知名模型都能正确猜到。但我的建议是生产环境务必写全前缀让路由意图显式化后面排查问题能少一层猜测。2.2 流式、异步与并发场景流式输出是大模型应用最常用的形态。LiteLLM 的流式接口依然向 OpenAI 靠拢response completion( modelgpt-4o, messagesmessages, streamTrue ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)流式场景里有个容易忽略的点不同服务商的流式协议差异很大LiteLLM 在 SDK 层统一成了 OpenAI 的 chunk 结构但流中途报错的表现不一定完全一致。比如某些供应商在流式传输中断时会先发一个正常 chunk 再掐断连接这会导致你的业务层看到的是一次成功结束而非错误。对这种行为我在后面高可用章节会说处理思路。异步调用也一样把方法名加个 a 就行from litellm import acompletion import asyncio async def main(): response await acompletion( modelgpt-4o, messagesmessages ) return response asyncio.run(main())生产环境处理批量任务时我通常用asyncio.Semaphore控制并发sem asyncio.Semaphore(10) async def safe_completion(**kwargs): async with sem: return await acompletion(**kwargs)如果不做并发控制脚本一跑起来很容易把供应商的 rate limit 打满还得回头处理一堆限流报错。LiteLLM 自带重试能力但重试并不意味着你可以无节制地开并发。2.3 工具调用和多模态传参工具调用是 Agent 应用的重点。LiteLLM 同样沿用了 OpenAI 的 tools 参数tools [ { type: function, function: { name: get_weather, description: 查询指定城市的天气, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } } ] response completion( modelgpt-4o, messagesmessages, toolstools )多模态输入则用 content 列表的方式传图response completion( modelgpt-4o, messages[ { role: user, content: [ {type: text, text: 这张图里有什么信息}, {type: image_url, image_url: {url: https://example.com/test.png}} ] } ] )这里有个实操经验别默认所有模型都支持所有模态。你把图片按 OpenAI 格式传给某个纯文本模型LiteLLM 可能不会报错但对端会直接忽略图片部分或者返回异常。动手前先确认目标模型的模态支持情况在代码里按模型维度做一次参数校验比事后排查诡异输出省心得多。3. 网关模式把密钥和路由收回到服务端3.1 一条 config.yaml 定义全部模型SDK 模式适合个人项目和单服务场景一旦涉及团队协作、多人共用密钥就要上网关模式了。LiteLLM 的代理网关是一个独立服务你用一份 config.yaml 声明要暴露哪些模型然后所有客户端只对着网关发请求真正的上游密钥都留在服务端。model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-latest api_key: os.environ/ANTHROPIC_API_KEY - model_name: gemini-1.5-pro litellm_params: model: gemini/gemini-1.5-pro api_key: os.environ/GEMINI_API_KEY litellm_settings: num_retries: 3 request_timeout: 600这里model_name是暴露给调用方的别名litellm_params.model才是实际上游模型。为什么要分两层因为你可以用别名对外屏蔽真实模型细节比如model_name: flagship映射到openai/gpt-4o将来换更强的模型改配置就好客户端完全感知不到。这是网关模式一个很实用的工程价值。启动前先用测试命令验证配置litellm --config config.yaml --test它会逐条尝试配置里的模型能通就输出成功信息不通会给出错误原因。我每次改完配置都会跑一遍比直接重启服务再发请求试错高效得多。3.2 虚拟密钥与预算绑定网关模式的核心管理对象是虚拟密钥。服务端通过主密钥管理一切然后为每个成员或每个应用生成一把 sk- 开头的虚拟密钥curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-my-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o, claude-3-5-sonnet], max_budget: 50, budget_duration: 30d, metadata: {team: simulation-project-a} }这把虚拟密钥只能调用你指定的模型额度是 50 美元、30 天有效。它背后对应某个真实上游密钥但对调用方完全透明。好处很明显同事拿到手的不是你的 OpenAI 主密钥泄露了也只是泄露一张受限的卡某个应用跑了异常消耗你可以精确到是哪个 key 在烧钱。预算维度还可以做到用户级、团队级。团队成员用同一个 key 也能区分到个人管理层能看到谁在用模型、花了多少钱这在大组织里几乎是刚需。配置了 Postgres 之后这些 key 和用量数据才有持久化保障本地测试用 SQLite 可以生产环境我强烈建议直接用 Postgres。3.3 Docker 部署和现有应用的无缝衔接网关部署最省事的方式是 Dockerdocker run -d --name litellm-proxy \ -p 4000:4000 \ -e LITELLM_MASTER_KEYsk-my-master-key \ -e DATABASE_URLpostgresql://user:passhost:5432/litellm \ -v $(pwd)/config.yaml:/app/config.yaml \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml启动后用两个健康检查端点确认状态curl http://localhost:4000/health/liveliness curl http://localhost:4000/health/readiness最让人心动的是接入成本。已有使用 OpenAI SDK 的应用改为走 LiteLLM 网关只需要换 base_urlfrom openai import OpenAI client OpenAI( api_keysk-虚拟密钥, base_urlhttp://localhost:4000 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] )代码里没有引入任何 LiteLLM 依赖却拿到了网关的密钥管理、多模型路由和成本统计能力。网关还提供一个/models端点客户端可以随时查看当前可用的模型列表配合 OpenAI 官方的模型列表动态发现机制体验很顺。4. 高可用配置重试、兜底和负载均衡4.1 重试与超时以及哪些错误值得重试大模型 API 的可用性再高也架不住网络抖动、供应商过载和限流。LiteLLM 内置了重试机制通过litellm_settings配置litellm_settings: num_retries: 3 request_timeout: 600 retry_after: 5num_retries是重试次数retry_after是重试间隔的基准值内部会做指数退避。单独调用时也可以在completion()里传timeout参数。这里有一个经验不是所有错误都值得重试。401 鉴权失败重试一万次也没用那是密钥配置问题429 和 5xx 才值得重试因为大概率是暂时性过载。LiteLLM 的默认重试逻辑主要面向这些可恢复错误但你在自己的业务代码里也应该加一道判断错误类型决定要不要重试而不是闭着眼睛 for 循环。网关模式下你可以通过/health/readiness这种探活端点接入容器编排系统的健康检查让无状态实例在异常时被自动替换。LiteLLM 网关本身无状态状态都存在数据库这让横向扩容变得很简单。4.2 兜底模型与多部署轮询比重试更高级的是兜底切换。比如主模型用 GPT-4o一旦请求失败或超时自动切到 Claude 或 Geminilitellm_settings: fallbacks: [ {gpt-4o: [claude-3-5-sonnet-latest, gemini/gemini-1.5-pro]} ]SDK 模式也能用response completion( modelgpt-4o, messagesmessages, fallbacks[claude-3-5-sonnet-latest, gemini/gemini-1.5-pro] )这个能力带来的不只是容灾还有成本策略空间。比如把某个高成本模型设为优先兜底的是低成本模型在非核心链路上能省不少钱。反过来也可以把低价模型设为主力兜底是高价强模型保证体验下限。负载均衡方面同一模型可以配置多个上游部署网关按策略分发请求model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: id: deployment-1 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_2 model_info: id: deployment-2多个同名校验互相留作备份配合 round-robin 或 least-busy 策略即使某个 key 被限流也能自动切换。流式场景要格外注意如果流已经开始传输中途报错往往是没法触发兜底的因为网关已经向下游吐了一部分内容。对流式任务我一般会在客户端做收到完整结果才算成功的校验必要时整段重试而不是把希望全押在服务端兜底上。5. 成本与可观测性每一分钱都要有据可查5.1 单次请求的成本核算大模型项目最容易被忽视的问题就是成本失控。LiteLLM 在成本计量上下过功夫每次请求后可以直接拿到金额from litellm import completion_cost response completion(modelgpt-4o, messagesmessages) cost completion_cost(completion_responseresponse) print(f本次请求成本: ${cost:.4f})它的背后是一份内置的价格清单涵盖了各家模型最新的 token 单价。每次调用按输入/输出 token 分别计价再汇总成总成本。这个能力对做模型性价比评测尤其有用——同样的任务不同模型跑一遍成本差异一目了然。自建或私有化模型没法用内置清单可以自定义计价model_list: - model_name: my-local-llama litellm_params: model: ollama/llama3 model_info: custom_pricing: true input_cost_per_token: 0.000001 output_cost_per_token: 0.000002设好之后网关依然会按同样的统计口径给你算钱。把内部成本核算统一到同一条体系里财务报表和优化决策就都有据可依了。5.2 预算、限额和告警前面提到的虚拟密钥最核心的价值就是预算控制。max_budget定义上限budget_duration定义周期还能设置单次请求最大预算之类的更细粒度限制。用户级和团队级预算则是更上层的管理维度适合给不同项目组划独立额度。某个组额度烧完了不会影响其他组。这些预算数据要真实起作用前提是把用量数据落库。网关会把每次调用的 token 数、费用、模型、耗时都记录到数据库里通过/spend相关端点可以按 key、按用户、按天维度拉取明细。没有这套记录所谓的成本管控就是纸上谈兵。告警方面LiteLLM 支持通过回调把异常和预算变化推送到内部 IM 工具例如配置alerting后超额、连续失败、限流频繁等事件都能自动通知到人。我们团队的实际做法是预算阈值的 50%、80%、100% 各设一道告警前两道是提醒第三道直接触发人工介入。5.3 日志、审计与指标采集可观测性是网关模式相对 SDK 模式的最大优势。LiteLLM 通过回调机制对接外部系统litellm_settings: success_callback: [prometheus, langfuse] failure_callback: [prometheus]配置 Prometheus 之后网关会暴露/metrics端点请求延迟、token 用量、错误率都可以直接配置到监控大盘上。Langfuse 等链路追踪工具则能帮你把一次业务请求从进入网关到模型返回的完整过程串起来非常适合排查为什么这个回答这么慢这类问题。还有一点容易被忽略的是审计日志。网关模式涉及密钥创建、预算修改、模型配置变更这类敏感操作打开audit_logs后谁在什么时间做了什么操作都有记录。团队规模一大没有审计日志出了事故都定位不到责任人。这些能力单靠各家 SDK 很难凑齐也是我推荐团队场景用网关模式的主要原因。6. 实战中踩过的坑以及什么场景别用它6.1 model 字符串的前缀与别名陷阱我踩过最隐蔽的坑是 model 字符串的前缀。SDK 模式下不带前缀的知名模型名通常能自动识别但在网关 config 里litellm_params.model必须带着正确前缀否则路由经常解析失败。比如某个部署里我写的是model: gpt-4o网关会尝试猜测供应商猜错就报模型不存在。后来统一改成openai/gpt-4o问题消失。另一个坑是虚拟密钥的模型限制。虚拟密钥生成时指定的models列表对应的是 config 里的model_name别名而不是上游模型名。如果你给调用方一把只能用gpt-4o的虚拟密钥但系统里同时存在gpt-4o和gpt-4o-mini的别名调用方以为自己在用同一个模型实际可能因为别名不一致而请求失败。建议把别名命名规范写进团队文档比如统一用provider-model的格式从源头避免歧义。6.2 版本迭代快配置漂移防不胜防LiteLLM 的迭代速度很快新模型、新参数、新配置项几乎周周有更新。好处是能力跟得紧坏处是旧配置可能无声无息失效。我就遇到过某个版本升级后原先的 fallback 配置格式不再被识别但服务不报错只是兜底不再触发直到线上故障才发现。从那以后我养成了一个习惯升级版本前先看 release notes升级后必须执行litellm --config config.yaml --test然后跑一轮包含流式、非流式、工具调用的冒烟用例。还有一点是生产环境别追最新版。LiteLLM 的 main-latest 镜像适合本地体验线上部署我会锁定一个经过验证的版本号等到有明确的升级收益再统一迁移。很多团队线上出问题往往不是功能不够而是版本漂移得太快文档和实际行为对不上。6.3 我的选型建议与上手路径说了这么多也得泼点冷水不是所有场景都需要 LiteLLM。如果你的项目只有一个模型、一个供应商直接用官方 SDK 是最简单可靠的选择引入任何中间层都是过度设计。如果你大量依赖某家供应商的独家能力比如最新发布的非标准参数那也应该先用官方 SDK 验证可行性再考虑怎么接入 LiteLLM。需要它的信号其实很明确你的代码里开始出现第二种模型供应商的 SDK或者团队里有超过三个人需要共享模型密钥或者你对成本核算有了横跨多模型的需求。满足任意一条LiteLLM 的价值就体现出来了。如果让我给一个最朴素的上手路径还是那句话先在本地pip install litellm把你现有 OpenAI SDK 的那段请求改成 LiteLLM 调用跑通后再把另一个模型加进来做个切换对比。当你发现配置多模型真的只是改字符串的时候你对这个项目的理解就到位了。等密钥要分给同事时才上代理一个 Docker 容器的事把之前的代码 base_url 指过去就行。这两步走完你就会知道 LiteLLM 在自己的技术栈里到底该站在哪个位置。
