1. 项目概述litellm 到底解决什么问题先抛一个场景你大概率遇到过。公司同时接了 OpenAI 的 GPT 系列、某云厂商的国产大模型、还有个开源模型部署在自己的 GPU 服务器上。每个厂商的 API 格式还不一致OpenAI 是/v1/chat/completions某云厂商的接口路径、鉴权方式、参数命名全是自己的一套。业务方每次接一个新模型都要重新写一遍调用代码、重新处理鉴权、重新排查报错。光联调就耗掉大半周。更头疼的是老板说要做模型降本要能看到每个业务线实际花了多少钱调了哪些模型。你数了数手里的对账单发现不同模型在各自厂商控制台里压根没法按你自己的业务维度去统计费用。数据是散的、格式是乱的、成本是看不清的。litellm 就是冲着这些痛点来的。它本质上是一个大语言模型的统一网关和代理服务核心思路特别简单把所有主流 LLM 厂商的 API 统一成一套 OpenAI 风格的接口格式。你只需要用一套 SDK 或者一个 HTTP 请求就能调通 OpenAI、Anthropic、Azure、各家国产大模型甚至本地部署的 Ollama、vLLM 服务。我最早接触 litellm 的时候它还只是个轻量的 Python 库主要解决“代码里切换模型厂商”的问题。后来项目迭代得很快加入了代理服务器模式可以做密钥管理、负载均衡、成本追踪、限流熔断慢慢从“一个库”变成了“一个网关”。这个项目适合谁用我个人的判断是后端研发和 AI 应用开发者想减少多厂商 API 对接成本团队负责人或架构师想把多模型接入、成本、权限收口到一个统一入口独立开发者想在自己项目里快速切换模型不被单一厂商绑定做模型评估、A/B 测试的工程师想在不同模型之间自由切换一句话概括如果你项目里只需要调用一个模型litellm 对你是锦上添花如果你要管理多个模型、多个密钥、多条业务线litellm 就是刚需。2. 核心机制拆解两种模式各有什么门道2.1 嵌入模式SDK是怎么做到统一调用的litellm 最早的核心能力就是把各家模型的调用参数“翻译”成统一格式。这个翻译过程你可以理解成万能插座转换头——不管充电器是美标、欧标还是国标插头转换头都能给你转成能插的接口。代码层面它实现的远不止“换一个 URL 地址”这么简单。不同模型的 API 差异非常隐蔽参数命名不同。有的模型用max_tokens有的用max_completion_tokens有的叫generation_config温度、top_p 的取值范围不同有的模型 0-1有的 0-2系统提示词的传递方式不同有的平台要求用列表里首个rolesystem消息有的平台要求独立字段返回结构不同有的返回choices[0].message.content有的返回outputs[0].textlitellm 在底层逐个适配了这些差异对上层只暴露 OpenAI 兼容格式。你从 GPT-4 换到 Claude 3代码只需要改一行模型名。听起来简单但能把上百家供应商的细微差异都抹平这是这个项目最值钱的部分。2.2 代理模式Proxy解决了什么问题嵌入模式适合单机单进程的场景但团队协作、生产环境多业务接入就需要代理模式了。代理模式就是启动一个本地 HTTP 服务相当于一个独立部署的 LLM 中转站。所有团队内部的请求都打到这个代理上由代理统一转发到真实的模型厂商。用了代理之后你会获得几个立竿见影的好处业务方不需要知道真实厂商的 API 密钥密钥只存在网关侧可以在代理层做统一的鉴权、限流、负载均衡不需要每个业务都自己实现所有调用日志、token 消耗、费用估算都集中在一处想看随时看模型切换、厂商故障转移改配置文件重启即可业务方完全无感代理模式是 litellm 真正区别于一般 SDK 的关键。它加了一层抽象让 LLM 调用变成了公司内部的标准化基础设施。这件事的价值我会在后面展开讲。2.3 为什么非要兼容 OpenAI 格式这里有一个关键的设计决策litellm 为什么选 OpenAI 的接口格式作为统一标准而不是自创一套格式原因很现实。OpenAI 的 API 格式是事实上的行业标准几乎所有主流的 LLM 工具链、框架比如各种 Agent 框架、LangChain、LlamaIndex、向量数据库的工具都原生支持 OpenAI 格式。如果你用 litellm 代理意味着你现有的、基于 OpenAI SDK 写的代码不需要做任何修改把 base_url 指到 litellm 就行。这个兼容策略极其聪明。它把 litellm 的接入成本降到了最低——不是让你改代码来适配 litellm而是 litellm 来适配你的代码。同时你还能拿到统一网关带来的全部附加能力。3. 快速上手指南从安装到调通第一个模型3.1 安装与依赖准备litellm 是纯 Python 项目安装方式很简单pip install litellm[proxy]这里我建议直接装[proxy]扩展因为自带代理模式需要的依赖。如果你只是想当 SDK 用可以只装litellm本体。装完之后验证一下python -c import litellm; print(litellm.__version__)有版本号输出就说明装好了。3.2 写好配置文件 models.yaml代理模式的核心配置是一个 YAML 文件。我们先从最基础的写起model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: sk-你的密钥 - model_name: claude-3-5-haiku litellm_params: model: anthropic/claude-3-5-haiku-20241022 api_key: sk-ant-你的密钥 - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的密钥这里要解释几个容易懵的点model_name是你自己起的别名暴露给业务方用的。你可以叫gpt-4o-mini也可以叫main-chat甚至可以故意叫advice-bot这样后续切换底层模型不需要告诉业务方litellm_params.model是真实模型的完整标识格式是厂商名/模型名如果厂商不支持通过环境变量注入密钥你就在这里显式写api_key单个模型有一个隐藏的使用场景一个model_name配置多个真实模型实现同一别名背后做负载均衡。这个高级用法后面讲。3.3 启动代理与连通性验证配置文件准备好了启动命令非常简单litellm --config config.yaml --port 4000看到类似Uvicorn running on http://0.0.0.0:4000的日志就说明服务起来了。验证是否连通可以直接用 curlcurl http://localhost:4000/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-自定义主密钥 \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好介绍一下自己}] }注意这里的Authorization头里带的密钥不是真实厂商的密钥而是 litellm 自己生成的主密钥。用config.yaml启动时需要在配置里加一行general_settings.master_key来设定。如果返回了正常的 ChatCompletion 格式响应恭喜你你的统一 LLM 网关已经跑通了。3.4 SDK 接入方式对你团队里用 Python 写业务的同事来说接入成本几乎为零。他们的代码原来是这样的from openai import OpenAI client OpenAI() resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)接到 litellm 代理之后只需要改两行from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-自定义主密钥 ) resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)就这两行改动。原先代码里的重试逻辑、超时设置、异步调用逻辑全部不用动。从业务方视角看litellm 只是一个换了地址的 OpenAI API。4. 进阶能力负载均衡、故障转移与成本追踪4.1 同一模型多厂商配置实现真正的降本弹性先聊负载均衡。这是 litellm 的一个杀手级功能。假设你希望“小模型”这个逻辑概念背后有两个供应商一个 GPT-4o-mini一个国产模型。平时流量平摊某个厂商故障时自动全部切到另一个。配置如下model_list: - model_name: small-chat litellm_params: model: openai/gpt-4o-mini api_key: sk-密钥1 rpm: 1000 - model_name: small-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-密钥2 rpm: 1000两个条目用了同一个model_name: small-chatlitellm 会自动把它们归为一个模型组请求默认轮询分发。rpm参数是每分钟请求数上限用来做流量权重控制。这里润色一下虽然写法上两个条目的model_name相同但 litellm 会把它们当作同一逻辑模型下的多个上游实例自动做负载均衡。我实测下来的经验是这种配置特别适合“主备切换”场景。一个主力服务商 一个备用服务商主力挂了备用顶上。业务方全程无感他们只知道自己在调用small-chat。4.2 故障转移与重试逻辑的配置细节litellm 支持非常细致的重试策略。举个我在生产环境用的配置router_settings: routing_strategy: usage-based-routing enable_pre_call_check: true num_retries: 2 request_timeout: 30 fallbacks: [ {small-chat: [gpt-4o-mini, deepseek-chat]} ] allowed_fails: 3 cooldown_time: 30逐个解释routing_strategy路由策略usage-based-routing会根据消耗情况动态调整流量分配enable_pre_call_check请求前先检查目标服务是否健康避免把请求打到已经挂掉的服务上num_retries重试次数我建议设置 1-2 次不宜过多避免雪崩fallbacks降级配置small-chat挂了之后依次尝试后两个模型allowed_fails允许连续失败几次才把某个上游标记为不健康cooldown_time上游被标记不健康之后的冷却时长30 秒后重新试探这套组合下来我的一个服务在某个上游厂商的 API 连续报 5xx 时自动故障转移耗时基本在几百毫秒以内用户的感受只是“偶尔慢了一点”而不是“服务不可用”。4.3 成本追踪让每个业务线为真实消耗买单litellm 内置了成本统计功能。它会根据 token 用量和各模型的定价表在请求日志里实时计算费用估算值。开启这个功能需要两步在数据库层做初始化。litellm 用 SQLite 做默认存储生产环境建议切 PostgreSQL在配置里开启费用统计相关开关# 初始化数据库 litellm --config config.yaml --port 4000首次启动时 litellm 自动建库建表。请求进来后每次调用的模型、token 数、估算金额、业务标识都会写入表里。费用估算的准确性取决于你配置的定价。litellm 自带了主流模型的官方定价表基本开箱即用。但如果你用的是私有化部署模型或者特殊计费协议建议在配置里手动覆盖model_info: input_cost_per_token: 0.0000015 output_cost_per_token: 0.000002所有以中文为源语言的内容如果涉及 model name、API 路径这些英文专有名词保持作为代码或参数原样呈现不会被翻译。4.4 虚拟密钥与权限管理密钥管理是代理模式的核心卖点之一。在 litellm 里可以生成虚拟密钥业务方拿到的虚拟密钥只能调用特定模型、有明确的预算上限。用命令创建密钥curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer 主密钥 \ -H Content-Type: application/json \ -d { models: [small-chat], max_budget: 50, budget_duration: 30d, info: {team: 数据分析组} }这个密钥的含义是只允许调用small-chat这一个模型30 天内预算上限 50 美元额外备注属于哪个团队。这样一来月度成本核算就变成了“按虚拟密钥拉账单”。各个业务线用掉了多少钱不再依赖厂商控制台的对账报表直接从 litellm 的数据库里查就行。这个能力在团队规模越大时价值越明显。5. 生产环境部署的实战经验5.1 Docker 部署与内存参数调优本地开发跑litellm命令没问题但生产环境我强烈建议用 Docker。官方镜像ghcr.io/berriai/litellm是现成的直接拉取。一个关键参数是环境变量LITELLM_LOG默认是 INFO 级别日志量不小生产环境可以调成 WARNING 减少磁盘压力docker run -d \ --name litellm-proxy \ -p 4000:4000 \ -e LITELLM_LOGWARNING \ -v /opt/litellm/config.yaml:/app/config.yaml \ -v /opt/litellm/data:/app/data \ ghcr.io/berriai/litellm:main \ --config /app/config.yaml这里注意两个细节第一数据目录/app/data必须挂载持久化卷。litellm 的密钥信息、成本记录都存在这里容器重建不丢数据是刚需。第二镜像 tag 尽量固定版本而不是追main。我吃过追最新版的亏——某次主分支代码引入了兼容性问题导致生产环境的虚拟密钥全部失效重发。固定版本号升级前在测试环境验证过再动生产。内存方面litellm 代理本身占用不高默认 512MB 足够应对中等流量。但如果开了 Prometheus 指标采集或者日志量大建议给到 1GB。5.2 跨区域多实例部署的注意事项有时候你的团队分布在多个区域或者需要高可用一个 litellm 实例不够。它的架构没法天然做到多实例共享内存状态所以多实例部署有个前提数据库要统一。把所有实例的DATABASE_URL指向同一个 PostgreSQL这样才能保证虚拟密钥在各实例间通用。注意 SQLite 不支持跨实例共享多实例场景必须上 PostgreSQL。我建议的部署拓扑是前面挂一层 Nginx 做负载均衡后面跑 2-3 个 litellm 实例共享同一个 PostgreSQL。这样单个实例挂了请求自动落到其他实例对业务无感。5.3 安全加固的几个细节网关是整个团队的 LLM 调用入口安全配置务必重视。主密钥必须足够复杂建议至少 32 位随机字符串并且只保存在运维人员手里生产环境强制开启 HTTPS不允许明文 HTTP 传输密钥在网关前再加一层 IP 白名单限制只有公司内网能访问如果业务方有调用量突增的嫌疑利用虚拟密钥的max_budget做兜底防止异常逻辑导致费用失控我踩过的一个真实坑是某个内部工具误用了死循环调用 LLM跑了一晚上花费了不菲的费用。第二天查虚拟密钥的费用明细一眼就定位到是哪个业务线的哪个密钥。从那之后我规定所有虚拟密钥必须设预算上限哪怕设得高一点但不能不设。6. 常见问题排查与避坑实录6.1 请求超时的调优方向现象业务方反馈 LLM 响应特别慢甚至偶发超时报错。排查思路先用 curl 直接请求目标模型厂商的原始 API确认是不是厂商本身慢。排除之后再看 litellm 的日志重点看耗时分布。litellm 的request_timeout默认是 600 秒对于单次 LLM 调用来说太长了。如果业务方需要快速失败建议调小到 30-60 秒。但注意长文本生成场景本身耗时可能就不短调太小会误杀正常请求。6.2 鉴权报错的排查清单现象业务方调用时报 401 或 403。这个问题的排查点比较固定按顺序查排查项检查内容密钥类型业务方用的是虚拟密钥不是主密钥密钥有效期虚拟密钥是否已过期模型权限该虚拟密钥的 models 列表是否包含所调模型预算状态该密钥的预算是否已用完用完会被自动禁用时间同步服务器时间偏差可能导致 JWT 类认证失败6.3 Token 统计与实际费用对不上现象litellm 估算的费用和厂商账单不一致。原因基本有两种一是 litellm 内置定价表和你的实际采购价不同二是有些厂商对缓存命中、输入缓存 token 有特殊计费规则litellm 未必覆盖到每一条特殊规则。解决方案就是在model_info里手动覆盖单价把 litellm 的估价与自身商务合同对齐。估算始终是估算用于日常监控和成本分配够用但最终以厂商账单为准。6.4 报错信息里的 Provider 字段有什么用litellm 的报错信息挺讲究一般会带上 Provider 字段标明错误来自哪个上游。比如litellm.provider: OpenAI或litellm.provider: Anthropic。这个字段特别有用。当你的model_name背后配置了多个上游时报错能让你准确知道这次请求实际打到了哪个厂商而不是一头雾水地猜测。排查问题时的标准动作先看litellm.provider字段定位厂商再看具体的 HTTP 状态码和错误消息最后回到厂商那边的状态页看是否有大面积故障。6.5 一个小技巧用自定义回调做告警litellm 支持配置 webhook 回调在请求失败或费用超阈值时推送告警。配置非常简单general_settings: alerting: - webhook_url: https://通知服务的地址 alert_types: - budget_alerts - llm_webhooks配置好之后当虚拟密钥费用超过预算的 85% 时就会收到告警推送。这个能力帮我提前拦截过好几次费用失控的事故强烈建议启用。7. 我在实际使用中的一些体会最后聊几点偏“软”的东西。litellm 这类工具表面上解决的是 API 格式统一的技术问题但实际解决的是组织协作的问题。当你的 AI 应用从单体项目长成多团队协作系统时LLM 调用入口混乱带来的沟通成本、费用不可见带来的失控风险、密钥散落各处带来的安全隐患这些才是真正棘手的东西。一个统一的网关层是把这些问题收口的最短路径。我觉得接入 litellm 最好的时机不是等系统已经无比复杂之后而是在你准备接第二个模型厂商的时候。第一个模型用 SDK 直连没问题第二个模型加入时就应该考虑网关层了。这个判断标准非常简单你的代码里有过“复制一段调用逻辑改改参数”的经历就说明网关该上场了。另外想提醒的是litellm 迭代速度非常快新版本偶尔会调整配置格式。我自己的习惯是固定版本跑生产环境新功能先在测试环境试用一个版本周期稳定后再升级。不要为了追新功能去打乱稳定的生产节奏。如果你只是一个人在开发个人项目不接多个厂商litellm 可能显得有点重。但只要你开始想“我是不是该换一个模型试试”的时候用 litellm 做统一出口就会让这个动作变成一个配置项的事。这个便利性用过的都回不去了。
1. 项目概述litellm 到底解决什么问题先抛一个场景你大概率遇到过。公司同时接了 OpenAI 的 GPT 系列、某云厂商的国产大模型、还有个开源模型部署在自己的 GPU 服务器上。每个厂商的 API 格式还不一致OpenAI 是/v1/chat/completions某云厂商的接口路径、鉴权方式、参数命名全是自己的一套。业务方每次接一个新模型都要重新写一遍调用代码、重新处理鉴权、重新排查报错。光联调就耗掉大半周。更头疼的是老板说要做模型降本要能看到每个业务线实际花了多少钱调了哪些模型。你数了数手里的对账单发现不同模型在各自厂商控制台里压根没法按你自己的业务维度去统计费用。数据是散的、格式是乱的、成本是看不清的。litellm 就是冲着这些痛点来的。它本质上是一个大语言模型的统一网关和代理服务核心思路特别简单把所有主流 LLM 厂商的 API 统一成一套 OpenAI 风格的接口格式。你只需要用一套 SDK 或者一个 HTTP 请求就能调通 OpenAI、Anthropic、Azure、各家国产大模型甚至本地部署的 Ollama、vLLM 服务。我最早接触 litellm 的时候它还只是个轻量的 Python 库主要解决“代码里切换模型厂商”的问题。后来项目迭代得很快加入了代理服务器模式可以做密钥管理、负载均衡、成本追踪、限流熔断慢慢从“一个库”变成了“一个网关”。这个项目适合谁用我个人的判断是后端研发和 AI 应用开发者想减少多厂商 API 对接成本团队负责人或架构师想把多模型接入、成本、权限收口到一个统一入口独立开发者想在自己项目里快速切换模型不被单一厂商绑定做模型评估、A/B 测试的工程师想在不同模型之间自由切换一句话概括如果你项目里只需要调用一个模型litellm 对你是锦上添花如果你要管理多个模型、多个密钥、多条业务线litellm 就是刚需。2. 核心机制拆解两种模式各有什么门道2.1 嵌入模式SDK是怎么做到统一调用的litellm 最早的核心能力就是把各家模型的调用参数“翻译”成统一格式。这个翻译过程你可以理解成万能插座转换头——不管充电器是美标、欧标还是国标插头转换头都能给你转成能插的接口。代码层面它实现的远不止“换一个 URL 地址”这么简单。不同模型的 API 差异非常隐蔽参数命名不同。有的模型用max_tokens有的用max_completion_tokens有的叫generation_config温度、top_p 的取值范围不同有的模型 0-1有的 0-2系统提示词的传递方式不同有的平台要求用列表里首个rolesystem消息有的平台要求独立字段返回结构不同有的返回choices[0].message.content有的返回outputs[0].textlitellm 在底层逐个适配了这些差异对上层只暴露 OpenAI 兼容格式。你从 GPT-4 换到 Claude 3代码只需要改一行模型名。听起来简单但能把上百家供应商的细微差异都抹平这是这个项目最值钱的部分。2.2 代理模式Proxy解决了什么问题嵌入模式适合单机单进程的场景但团队协作、生产环境多业务接入就需要代理模式了。代理模式就是启动一个本地 HTTP 服务相当于一个独立部署的 LLM 中转站。所有团队内部的请求都打到这个代理上由代理统一转发到真实的模型厂商。用了代理之后你会获得几个立竿见影的好处业务方不需要知道真实厂商的 API 密钥密钥只存在网关侧可以在代理层做统一的鉴权、限流、负载均衡不需要每个业务都自己实现所有调用日志、token 消耗、费用估算都集中在一处想看随时看模型切换、厂商故障转移改配置文件重启即可业务方完全无感代理模式是 litellm 真正区别于一般 SDK 的关键。它加了一层抽象让 LLM 调用变成了公司内部的标准化基础设施。这件事的价值我会在后面展开讲。2.3 为什么非要兼容 OpenAI 格式这里有一个关键的设计决策litellm 为什么选 OpenAI 的接口格式作为统一标准而不是自创一套格式原因很现实。OpenAI 的 API 格式是事实上的行业标准几乎所有主流的 LLM 工具链、框架比如各种 Agent 框架、LangChain、LlamaIndex、向量数据库的工具都原生支持 OpenAI 格式。如果你用 litellm 代理意味着你现有的、基于 OpenAI SDK 写的代码不需要做任何修改把 base_url 指到 litellm 就行。这个兼容策略极其聪明。它把 litellm 的接入成本降到了最低——不是让你改代码来适配 litellm而是 litellm 来适配你的代码。同时你还能拿到统一网关带来的全部附加能力。3. 快速上手指南从安装到调通第一个模型3.1 安装与依赖准备litellm 是纯 Python 项目安装方式很简单pip install litellm[proxy]这里我建议直接装[proxy]扩展因为自带代理模式需要的依赖。如果你只是想当 SDK 用可以只装litellm本体。装完之后验证一下python -c import litellm; print(litellm.__version__)有版本号输出就说明装好了。3.2 写好配置文件 models.yaml代理模式的核心配置是一个 YAML 文件。我们先从最基础的写起model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: sk-你的密钥 - model_name: claude-3-5-haiku litellm_params: model: anthropic/claude-3-5-haiku-20241022 api_key: sk-ant-你的密钥 - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的密钥这里要解释几个容易懵的点model_name是你自己起的别名暴露给业务方用的。你可以叫gpt-4o-mini也可以叫main-chat甚至可以故意叫advice-bot这样后续切换底层模型不需要告诉业务方litellm_params.model是真实模型的完整标识格式是厂商名/模型名如果厂商不支持通过环境变量注入密钥你就在这里显式写api_key单个模型有一个隐藏的使用场景一个model_name配置多个真实模型实现同一别名背后做负载均衡。这个高级用法后面讲。3.3 启动代理与连通性验证配置文件准备好了启动命令非常简单litellm --config config.yaml --port 4000看到类似Uvicorn running on http://0.0.0.0:4000的日志就说明服务起来了。验证是否连通可以直接用 curlcurl http://localhost:4000/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-自定义主密钥 \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好介绍一下自己}] }注意这里的Authorization头里带的密钥不是真实厂商的密钥而是 litellm 自己生成的主密钥。用config.yaml启动时需要在配置里加一行general_settings.master_key来设定。如果返回了正常的 ChatCompletion 格式响应恭喜你你的统一 LLM 网关已经跑通了。3.4 SDK 接入方式对你团队里用 Python 写业务的同事来说接入成本几乎为零。他们的代码原来是这样的from openai import OpenAI client OpenAI() resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)接到 litellm 代理之后只需要改两行from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-自定义主密钥 ) resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)就这两行改动。原先代码里的重试逻辑、超时设置、异步调用逻辑全部不用动。从业务方视角看litellm 只是一个换了地址的 OpenAI API。4. 进阶能力负载均衡、故障转移与成本追踪4.1 同一模型多厂商配置实现真正的降本弹性先聊负载均衡。这是 litellm 的一个杀手级功能。假设你希望“小模型”这个逻辑概念背后有两个供应商一个 GPT-4o-mini一个国产模型。平时流量平摊某个厂商故障时自动全部切到另一个。配置如下model_list: - model_name: small-chat litellm_params: model: openai/gpt-4o-mini api_key: sk-密钥1 rpm: 1000 - model_name: small-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-密钥2 rpm: 1000两个条目用了同一个model_name: small-chatlitellm 会自动把它们归为一个模型组请求默认轮询分发。rpm参数是每分钟请求数上限用来做流量权重控制。这里润色一下虽然写法上两个条目的model_name相同但 litellm 会把它们当作同一逻辑模型下的多个上游实例自动做负载均衡。我实测下来的经验是这种配置特别适合“主备切换”场景。一个主力服务商 一个备用服务商主力挂了备用顶上。业务方全程无感他们只知道自己在调用small-chat。4.2 故障转移与重试逻辑的配置细节litellm 支持非常细致的重试策略。举个我在生产环境用的配置router_settings: routing_strategy: usage-based-routing enable_pre_call_check: true num_retries: 2 request_timeout: 30 fallbacks: [ {small-chat: [gpt-4o-mini, deepseek-chat]} ] allowed_fails: 3 cooldown_time: 30逐个解释routing_strategy路由策略usage-based-routing会根据消耗情况动态调整流量分配enable_pre_call_check请求前先检查目标服务是否健康避免把请求打到已经挂掉的服务上num_retries重试次数我建议设置 1-2 次不宜过多避免雪崩fallbacks降级配置small-chat挂了之后依次尝试后两个模型allowed_fails允许连续失败几次才把某个上游标记为不健康cooldown_time上游被标记不健康之后的冷却时长30 秒后重新试探这套组合下来我的一个服务在某个上游厂商的 API 连续报 5xx 时自动故障转移耗时基本在几百毫秒以内用户的感受只是“偶尔慢了一点”而不是“服务不可用”。4.3 成本追踪让每个业务线为真实消耗买单litellm 内置了成本统计功能。它会根据 token 用量和各模型的定价表在请求日志里实时计算费用估算值。开启这个功能需要两步在数据库层做初始化。litellm 用 SQLite 做默认存储生产环境建议切 PostgreSQL在配置里开启费用统计相关开关# 初始化数据库 litellm --config config.yaml --port 4000首次启动时 litellm 自动建库建表。请求进来后每次调用的模型、token 数、估算金额、业务标识都会写入表里。费用估算的准确性取决于你配置的定价。litellm 自带了主流模型的官方定价表基本开箱即用。但如果你用的是私有化部署模型或者特殊计费协议建议在配置里手动覆盖model_info: input_cost_per_token: 0.0000015 output_cost_per_token: 0.000002所有以中文为源语言的内容如果涉及 model name、API 路径这些英文专有名词保持作为代码或参数原样呈现不会被翻译。4.4 虚拟密钥与权限管理密钥管理是代理模式的核心卖点之一。在 litellm 里可以生成虚拟密钥业务方拿到的虚拟密钥只能调用特定模型、有明确的预算上限。用命令创建密钥curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer 主密钥 \ -H Content-Type: application/json \ -d { models: [small-chat], max_budget: 50, budget_duration: 30d, info: {team: 数据分析组} }这个密钥的含义是只允许调用small-chat这一个模型30 天内预算上限 50 美元额外备注属于哪个团队。这样一来月度成本核算就变成了“按虚拟密钥拉账单”。各个业务线用掉了多少钱不再依赖厂商控制台的对账报表直接从 litellm 的数据库里查就行。这个能力在团队规模越大时价值越明显。5. 生产环境部署的实战经验5.1 Docker 部署与内存参数调优本地开发跑litellm命令没问题但生产环境我强烈建议用 Docker。官方镜像ghcr.io/berriai/litellm是现成的直接拉取。一个关键参数是环境变量LITELLM_LOG默认是 INFO 级别日志量不小生产环境可以调成 WARNING 减少磁盘压力docker run -d \ --name litellm-proxy \ -p 4000:4000 \ -e LITELLM_LOGWARNING \ -v /opt/litellm/config.yaml:/app/config.yaml \ -v /opt/litellm/data:/app/data \ ghcr.io/berriai/litellm:main \ --config /app/config.yaml这里注意两个细节第一数据目录/app/data必须挂载持久化卷。litellm 的密钥信息、成本记录都存在这里容器重建不丢数据是刚需。第二镜像 tag 尽量固定版本而不是追main。我吃过追最新版的亏——某次主分支代码引入了兼容性问题导致生产环境的虚拟密钥全部失效重发。固定版本号升级前在测试环境验证过再动生产。内存方面litellm 代理本身占用不高默认 512MB 足够应对中等流量。但如果开了 Prometheus 指标采集或者日志量大建议给到 1GB。5.2 跨区域多实例部署的注意事项有时候你的团队分布在多个区域或者需要高可用一个 litellm 实例不够。它的架构没法天然做到多实例共享内存状态所以多实例部署有个前提数据库要统一。把所有实例的DATABASE_URL指向同一个 PostgreSQL这样才能保证虚拟密钥在各实例间通用。注意 SQLite 不支持跨实例共享多实例场景必须上 PostgreSQL。我建议的部署拓扑是前面挂一层 Nginx 做负载均衡后面跑 2-3 个 litellm 实例共享同一个 PostgreSQL。这样单个实例挂了请求自动落到其他实例对业务无感。5.3 安全加固的几个细节网关是整个团队的 LLM 调用入口安全配置务必重视。主密钥必须足够复杂建议至少 32 位随机字符串并且只保存在运维人员手里生产环境强制开启 HTTPS不允许明文 HTTP 传输密钥在网关前再加一层 IP 白名单限制只有公司内网能访问如果业务方有调用量突增的嫌疑利用虚拟密钥的max_budget做兜底防止异常逻辑导致费用失控我踩过的一个真实坑是某个内部工具误用了死循环调用 LLM跑了一晚上花费了不菲的费用。第二天查虚拟密钥的费用明细一眼就定位到是哪个业务线的哪个密钥。从那之后我规定所有虚拟密钥必须设预算上限哪怕设得高一点但不能不设。6. 常见问题排查与避坑实录6.1 请求超时的调优方向现象业务方反馈 LLM 响应特别慢甚至偶发超时报错。排查思路先用 curl 直接请求目标模型厂商的原始 API确认是不是厂商本身慢。排除之后再看 litellm 的日志重点看耗时分布。litellm 的request_timeout默认是 600 秒对于单次 LLM 调用来说太长了。如果业务方需要快速失败建议调小到 30-60 秒。但注意长文本生成场景本身耗时可能就不短调太小会误杀正常请求。6.2 鉴权报错的排查清单现象业务方调用时报 401 或 403。这个问题的排查点比较固定按顺序查排查项检查内容密钥类型业务方用的是虚拟密钥不是主密钥密钥有效期虚拟密钥是否已过期模型权限该虚拟密钥的 models 列表是否包含所调模型预算状态该密钥的预算是否已用完用完会被自动禁用时间同步服务器时间偏差可能导致 JWT 类认证失败6.3 Token 统计与实际费用对不上现象litellm 估算的费用和厂商账单不一致。原因基本有两种一是 litellm 内置定价表和你的实际采购价不同二是有些厂商对缓存命中、输入缓存 token 有特殊计费规则litellm 未必覆盖到每一条特殊规则。解决方案就是在model_info里手动覆盖单价把 litellm 的估价与自身商务合同对齐。估算始终是估算用于日常监控和成本分配够用但最终以厂商账单为准。6.4 报错信息里的 Provider 字段有什么用litellm 的报错信息挺讲究一般会带上 Provider 字段标明错误来自哪个上游。比如litellm.provider: OpenAI或litellm.provider: Anthropic。这个字段特别有用。当你的model_name背后配置了多个上游时报错能让你准确知道这次请求实际打到了哪个厂商而不是一头雾水地猜测。排查问题时的标准动作先看litellm.provider字段定位厂商再看具体的 HTTP 状态码和错误消息最后回到厂商那边的状态页看是否有大面积故障。6.5 一个小技巧用自定义回调做告警litellm 支持配置 webhook 回调在请求失败或费用超阈值时推送告警。配置非常简单general_settings: alerting: - webhook_url: https://通知服务的地址 alert_types: - budget_alerts - llm_webhooks配置好之后当虚拟密钥费用超过预算的 85% 时就会收到告警推送。这个能力帮我提前拦截过好几次费用失控的事故强烈建议启用。7. 我在实际使用中的一些体会最后聊几点偏“软”的东西。litellm 这类工具表面上解决的是 API 格式统一的技术问题但实际解决的是组织协作的问题。当你的 AI 应用从单体项目长成多团队协作系统时LLM 调用入口混乱带来的沟通成本、费用不可见带来的失控风险、密钥散落各处带来的安全隐患这些才是真正棘手的东西。一个统一的网关层是把这些问题收口的最短路径。我觉得接入 litellm 最好的时机不是等系统已经无比复杂之后而是在你准备接第二个模型厂商的时候。第一个模型用 SDK 直连没问题第二个模型加入时就应该考虑网关层了。这个判断标准非常简单你的代码里有过“复制一段调用逻辑改改参数”的经历就说明网关该上场了。另外想提醒的是litellm 迭代速度非常快新版本偶尔会调整配置格式。我自己的习惯是固定版本跑生产环境新功能先在测试环境试用一个版本周期稳定后再升级。不要为了追新功能去打乱稳定的生产节奏。如果你只是一个人在开发个人项目不接多个厂商litellm 可能显得有点重。但只要你开始想“我是不是该换一个模型试试”的时候用 litellm 做统一出口就会让这个动作变成一个配置项的事。这个便利性用过的都回不去了。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
