1. 先说清楚LiteLLM 到底是干嘛的如果你手里管着三五个大模型 API每天要切换 GPT、Claude、Gemini还要给不同团队发密钥、限额、看账单你很快就会明白一件事真正麻烦的不是模型本身的调用而是围绕谁能用、能用多少、花多少钱这一堆管理琐事。LiteLLM 就是在这个场景里精准踩中痛点的工具。简单说LiteLLM 是一个开源的 LLM 网关Gateway / Proxy它把 OpenAI、Anthropic、Azure OpenAI、本地部署的 Ollama/vLLM、甚至你自己微调的模型全部统一成 OpenAI 兼容的接口。客户端只要配置一个 base_url 指向 LiteLLM 服务剩下的路由、重试、限流、预算、密钥管理全都交给它处理。我最早接触它是因为团队里有人用 GPT-4o有人用 Claude还有人坚持用本地 Llama 3接口格式五花八门光是维护每个服务的 SDK 版本就够头疼。后来统一走 LiteLLM 之后前端代码彻底收敛成一套 OpenAI SDK 调用后端每次新增模型只是改一行配置的事。这个工具适合谁适合像我这样在中小团队里既当开发者又兼运维的人适合需要给多个子部门或外部客户提供模型接口的 SaaS 团队也适合想在自己应用里快速接入多模型但不想重复造轮子的个人开发者。如果你只是单机调用一个模型那 LiteLLM 确实有点重但只要你开始考虑多人多模型多预算的管理问题它就是最省心的那一层。2. 整体设计思路为什么是一套代理 管理面的架构2.1 代理层的价值统一接口与统一行为LiteLLM 的核心设计思路是把自己做成所有模型请求的唯一入口。客户端不直接碰任何一家模型厂商的 API而是把请求发给 LiteLLM 服务。LiteLLM 根据配置文件中的模型映射关系把请求转发给真实的模型服务商拿到结果后再返回给客户端。这个中间人的角色带来的第一个好处是接口格式统一。OpenAI 格式的 /chat/completions、/embeddings、/completions 接口LiteLLM 全都兼容这意味着你现有的 OpenAI SDK 几乎不用改代码只需要把 base_url 换成 LiteLLM 的地址再换上 LiteLLM 签发的密钥就行。第二个好处是行为统一。比如重试策略、超时设置、请求日志、错误处理这些原来每个模型商都不一样用了 LiteLLM 之后所有模型都走同一套规则。举个例子OpenAI 的 rate limit 错误返回 429Anthropic 返回 529Gemini 可能返回 503如果客户端自己接每种错误都要单独写处理逻辑。但在 LiteLLM 里你可以统一配置 retry 次数和退避策略它对上游不同错误码做了归一化处理客户端只需要感知最终结果。2.2 管理面的价值密钥、用户、配额三位一体LiteLLM 的另一半设计是内置了一套用户与用量管理模块。它借鉴了企业级 API 网关的思路每个用户绑定自己的虚拟密钥每个密钥关联特定的模型权限和速率限制每次调用都会记录 token 消耗和费用。这套设计把模型接入和业务管理解耦了。你的研发团队不再需要直接接触上游模型的真实 API key每个人拿到的是 LiteLLM 签发的虚拟密钥。就算有人泄露了密钥你可以在控制台一键删除不影响上游账号安全。而用量管理呢可以精确到某个用户今天用了几万 token、花了多少钱这在月底做成本分摊的时候简直救命。我见过不少团队一开始觉得直接让后端配置环境变量里的 API key 不就行了但等到人多了、场景杂了才发现连最基本的谁把 key 用到别的项目里了都查不出来。LiteLLM 的价值就是在一开始就把这些管理能力内置进去你不需要额外搭一套计费系统。2.3 为什么不用自己写代理层我知道有人会说这不就是个反向代理嘛我用 Nginx 加一点脚本也能做。这话对一半。Nginx 确实能做转发但你想想模型格式转换怎么做不同模型的 prompt 格式不同、参数名不同、返回结构不同你要写多少转换代码重试策略和超时管理怎么做按 token 计费怎么做用户虚拟密钥的生成、校验、权限隔离怎么做LiteLLM 把这些全都做成开箱即用的功能。它自己就是 OpenAI 兼容服务端接收标准请求后在内部把请求转换成各模型商需要的格式。比如 Anthropic 的 messages 格式和 OpenAI 的 messages 格式略有差别LiteLLM 会自动做字段映射。这种格式兼容层的工程量远比想象中大自己维护不划算。3. 模型管理实操配置文件就是你的模型目录3.1 基础配置文件结构LiteLLM 的一切配置都集中在一个 YAML 文件里默认叫 config.yaml。启动服务时用litellm --config config.yaml --port 4000就能拉起一个代理服务。基础结构长这样model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llama litellm_params: model: ollama/llama3 api_base: http://localhost:11434 general_settings: master_key: sk-litellm-master-key database_url: postgresql://user:passwordlocalhost:5432/litellm这里的model_name是你自己起的别名客户端调用的就是这个名字。litellm_params是真正决定转发到哪里的参数model字段的格式是服务商前缀/模型名比如openai/gpt-4o、anthropic/...、ollama/...。3.2 多模型接入统一模型名的两种玩法多模型接入时有个很实用的技巧可以让多个上游模型共享同一个model_name。比如你想做模型高可用主用 GPT-4o备用 Claude Sonnet那么可以这么配model_list: - model_name: primary-assistant litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: completion - model_name: primary-assistant litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY客户端始终请求primary-assistant这个模型名LiteLLM 内部把请求轮询发给两个上游服务。遇到某个上游故障时它会自动尝试下一个。这种方式对业务代码完全透明属于零改动切换模型的典型场景。另一种玩法是显式映射每个model_name对应一个真实的模型客户端直接按名字挑选。这种方式直观适合模型能力区分明显的场景比如你同时提供便宜的快速模型和昂贵的高质量模型两种选择给用户。3.3 模型路由与 Fallback别让单点故障拖垮业务生产环境用 LiteLLM必须配置 fallback 策略。我在实际使用中最深的感受是上游模型服务商不是每时每刻都稳定哪天你正在线上演示结果模型商那边限流了如果没有 fallback整个应用就瘫了。LiteLLM 支持两种 fallback 写法一种是在配置里声明model_list后通过路由规则指定优先级另一种是客户端请求时通过fallbacks参数动态指定。推荐在配置层面搞定因为客户端不需要感知容灾策略。基本配置方式router_settings: routing_strategy: usage-based fallbacks: [ {primary-assistant: [secondary-assistant]} ]usage-based策略会优先选择等待时间短、吞吐余量大的模型配合 fallback能在高峰期自动把部分流量导到备用模型用户体验几乎无感。3.4 模型参数与上下文长度管理每个模型的 context window 不同多模型混用时最容易踩的坑是截断或越界。在 LiteLLM 里每个模型可以声明自己的max_input_tokens、max_output_tokens服务端会据此做请求校验避免一个 128K 上下文的请求发给了只支持 8K 的模型。model_list: - model_name: small-model litellm_params: model: openai/gpt-3.5-turbo model_info: max_input_tokens: 8192 max_output_tokens: 4092这里有个经验如果用了多个供应商的模型一定要核对官方最新上下文数据别照抄旧文档。我踩过一次Azure 某个模型已经升级了上下文长度但配置里还写着旧值导致用户正常的长文档请求被 LiteLLM 预先拒绝排查了半天才发现是配置过期。4. 用户管理与密钥体系每一位使用者都应有独立身份4.1 虚拟密钥机制的核心逻辑LiteLLM 的密钥体系模仿了 Stripe 的 API key 设计。每个用户User可以拥有多个密钥Key每个密钥绑定特定权限和配额。客户端用虚拟密钥请求LiteLLM 侧通过数据库校验密钥有效性、加载用户配置、检查用量。使用虚拟密钥有三个好处不用泄露上游真实 key上游 key 只存在 LiteLLM 的环境变量里可以针对不同团队、不同项目颁发不同权限的密钥密钥泄露时可以直接吊销甚至通过key_alias追踪到是哪个团队的责任需要在config.yaml中启用数据库才能完整使用用户管理能力通常用 PostgreSQL。SQLite 也能跑但只适合本地测试生产环境千万别用并发一高就锁。4.2 创建用户与分配密钥命令行实战启动服务后可以用 LiteLLM 提供的 CLI 工具来管理用户和密钥。最常用的几个命令# 创建用户 litellm --create_user --user_id team-a-user-001 --user_email devexample.com # 为用户生成密钥 litellm --create_key --user_id team-a-user-001 --models gpt-4o,primary-assistant # 查看用户 litellm --list_users # 删除密钥 litellm --delete_key --key sk-litellm-xxxx也可以用管理 API 直接创建密钥。比如通过 curl 调用/key/generate接口带上models参数来限定该密钥可调用的模型列表带上max_budget来限制总消费。示例curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { user_id: team-a-user-001, models: [gpt-4o], max_budget: 50.0, budget_duration: 1mo }响应里会包含key字段把那个 key 发给使用者就行。这里如果你是第一次接触很容易忽略budget_duration参数。它配合max_budget才有效表示这个预算是按多久算的。比如max_budget: 50budget_duration: 1mo表示用户每个月最多消费 50 美元到了下个月自动重置。不写budget_duration的话预算会被当成永久额度用完就彻底被锁死。4.3 RBAC 权限控制哪些人能调哪些模型多部门共享一个代理时RBAC 几乎是刚需。LiteLLM 的权限模型分三层用户User拥有角色属性可以是管理员或普通用户密钥Key拥有模型访问列表未列入的模型一律拒绝模型本身可以声明访问组team_id / user_group限制谁有权限实际操作中我的习惯是这样配置权限model_list: - model_name: expensive-model litellm_params: model: openai/gpt-4o model_info: teams: [core-team, admin-team] - model_name: cheap-model litellm_params: model: openai/gpt-3.5-turbo model_info: teams: [all-teams]这样贵价的模型只有特定团队能用便宜的模型所有人可用。配合密钥生成时的models参数就能组成模型团队双重限制。经验之谈尽量少给所有模型权限。哪怕内部团队也应该先给最小权限集等有明确需求再扩。这样即使密钥泄露影响范围也有限。4.4 用户组织与多团队隔离的设计思考当用户数量超过几十个单纯用 User 表管理就不够用了你需要引入 Team团队的概念。LiteLLM 的消息模型里一个 Team 可以包含多个用户一个用户也可以属于多个 Team典型的多对多关系。团队隔离的关键在于预算和用量隔离。我推荐的做法每个团队创建独立的 Team 对象分配独立的预算团队成员生成密钥时把team_id传进去在控制面板里按 Team 维度查看用量和费用这样月底财务要数据时直接导出每个团队的消费即可不用再从一堆 User 数据里手工汇总。这个习惯越早建立越省事等用量涨到百万 token 级别再回头补就痛苦了。5. 用量管理与成本控制从能跑到花得明白5.1 用量数据是怎么被追踪的LiteLLM 每次请求完成后会记录完整的元信息用户 ID、密钥、模型名、prompt tokens、completion tokens、总费用、延迟等。这些数据写入配置的database_url对应的数据库里然后可以在/usage页面或者在管理 API 中查询。用管理 API 查用量的方式curl http://localhost:4000/global/spend/logs \ -H Authorization: Bearer sk-litellm-master-key返回内容里每条记录包含user、model、spend、total_tokens、request_time等字段。你可以基于这些数据写一些简单的统计脚本也可以直接用内置的仪表盘界面。5.2 限流与配额设置防止单个用户占满资源限流配置在 LiteLLM 里有三个维度每秒请求数RPM限制请求频率防止单用户刷爆资源每分钟 token 数TPM限制 token 吞吐量每日预算daily budget限制一天的消费总量配置示例curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 100, budget_duration: 1d, rpm_limit: 60, tpm_limit: 60000 }这里我给一个实际经验RPM 和 TPM 别设得太紧。我一开始给团队设了 rpm_limit60结果他们批量处理数据时频繁触发 429到处报错。后来我看了下真实峰值发现他们正常业务偶尔一秒钟会发到 80 个请求直接把额度提到 120 才消停。限流的意义是挡住异常流量而不是给正常业务添堵。5.3 基于团队与用户的预算报警LiteLLM 支持设置预算超出时的行为可以配置成只告警不停服务或者直接停止。配置方式是在 key 生成的请求体里加metadata和budget_duration同时在 LiteLLM 服务端开启告警渠道。我比较推荐三级告警策略预算用到 50%仅记录日志通知到内部群预算用到 80%发出告警提醒通知负责人把关预算用到 100%自动停用密钥或降级到备用模型这个策略不是 LiteLLM 内置一次性搞定的。前两级需要你自己写脚本查/spend接口或者直接查数据库最后一级可以在 key 的max_budget上设置。虽然稍显原始但实际跑下来够用。5.4 费用统计与成本分析别让月底账单惊喜费用统计做得细其实是给自己减负。我的固定流程是每天早上写个定时任务拉取前一天各用户/各模型的 spend 数据生成一个简表按团队维度发到管理群每周做一次趋势对比看哪些模型成本在上升实现上一张简单的 SQL 查询就能完成SELECT user, model, SUM(spend) AS total_spend, SUM(total_tokens) AS total_tokens FROM spend_log WHERE request_time NOW() - INTERVAL 7 days GROUP BY user, model ORDER BY total_spend DESC LIMIT 20;如果你对数据展示有要求可以直接用 Grafana 接 PostgreSQL 数据库把消费趋势做成仪表盘。LiteLLM 虽然自带 UI但自带的 UI 更适合查一下的场景长期趋势分析还是得靠外部工具。6. 常见问题排查实录那些我踩过的坑6.1 模型调用报错先分清是配置问题还是上游问题我在实际运维 LiteLLM 时遇到过最典型的一类问题是为什么同一个请求有时候通有时候不通。排查逻辑其实很简单先看 LiteLLM 返回的错误码。如果返回401 Unauthorized大概率是虚拟密钥问题检查密钥是否存在、是否过期。如果返回404 Unknown Model检查model_name是否在model_list里。如果返回429 Rate Limit Exceeded检查本团队 RPM/TPM 配额。如果返回502 Bad Gateway或者503 Service Unavailable基本可以断定是上游模型服务商的问题去上游状态页确认。我分享一个排查小技巧启动 LiteLLM 时加上--debug参数这样请求级别的日志会打印详细信息包括上游选中的模型、token 消耗、耗时等。遇到疑难杂症这个日志比看 UI 高效十倍。6.2 用户权限失效多半是缓存惹的祸LiteLLM 在内存中缓存了用户和密钥关系如果你通过命令行或 API 修改了用户权限但客户端仍然用旧权限访问很可能是缓存没有刷新。处理方式有两种触发/key/update接口LiteLLM 会自动更新该 key 的缓存等待缓存过期LiteLLM 的缓存 TTL 默认约 30 秒如果着急直接重启服务我建议权限变更频繁的场景把数据库连接池调大避免权限校验时连不上数据库导致误判。6.3 用量数据不一致注意时钟与批次写入用量数据偶尔会出现延迟显示或统计误差通常是因为 LiteLLM 的用量写入是批次/异步模式突发流量时数据库写入会有堆积。排查时先检查数据库连接池大小和写入队列有没有积压。另外如果你的数据库和应用服务器不在同一时钟域会出现请求时间和写入时间错位的现象统计当天用量时就会发生轻微漂移。解决方案是统一使用 UTC 时间记录展示层再做时区转换这样跨时区协作的团队也能保持一致。6.4 性能问题当代理成了瓶颈LiteLLM 本身就是 HTTP 转发层性能通常不是瓶颈。但如果你把它部署在一台小机器上又同时跑了很多日志和分析任务就有可能出现端口不够用、连接池耗尽的情况。我给三个建议给 LiteLLM 单独准备一台 2C4G 以上的实例不要和业务服务混跑数据库单独部署不要用同一台机器的 SQLite打开--log参数时注意日志量生产环境建议只保留错误日志我自己用 2C4G 的服务器跑 LiteLLM 代理服务单日处理几十万次请求没出现过问题。真正要注意的是数据库性能因为每一次请求都要读写用量数据数据库连接池如果默认 20 太小高峰期会排队。6.5 密钥泄露后的应急处理流程密钥泄露这事遇到了也别慌按顺序处理立即调用/key/delete接口删除泄露的密钥检查该密钥的spend_log确认是否有异常消费如果泄露的是 master_key立即重启服务并更换general_settings.master_key给相关使用者重新签发新密钥并建议他们把密钥放到环境变量里不要写进代码我见过最离谱的情况是有人把 key 直接提交到 GitHub 公开仓库导致被爬虫扫到几分钟内消费了一百多美元。所以强烈建议生产环境开启模型总额上限就算某个 key 泄露损失也有限。7. 一些实用建议与扩展方向文章到这里核心内容基本讲完了。最后分享几个我在长期使用 LiteLLM 过程中形成的习惯。一是配置文件一定要走版本管理。config.yaml 就是你的模型目录和权限基线每次变更都要走 MR/PR 评审。我见过有人直接在服务器上改配置改完也不记录结果出了问题想回滚都不知道原来长什么样。二是凡是上生产的 key 都要关联到具体的用户或团队。最忌讳的就是随手生成一个不绑定用户的 key等月底复盘时完全对不上账。养成先用户后密钥的习惯成本分摊时你会感谢自己。三是多模型策略要留后手。LiteLLM 支持动态调整模型列表我建议至少有一种备用模型是开源本地部署的比如 Ollama 或 vLLM 跑的模型这样上游商业 API 集体故障时业务还能保持基本可用。就算推理质量差一点也好过直接停服。如果你有兴趣把这个体系做得更完整可以考虑结合 vLLM 或 SGlang 部署开源模型作为低成本推理通道把贵模型 便宜模型 本地模型三层阶梯搭出来。LiteLLM 做的是统一入口真正灵活的路由策略和成本调优还是需要根据业务特性一点点打磨出来的。从我自己的实际体会来说LiteLLM 是我用过的开源 AI 网关里上手门槛和覆盖面平衡得最好的一个。它不追求把所有功能都一次性堆给你而是把模型、用户、用量这三件最核心的事做得扎实。只要你的团队多人、多模型、有多头预算管理需求它基本上都能接得住。关键是尽早建立一套管理先行的习惯别等到账目乱了、密钥多了、模型杂了以后再来补课。
1. 先说清楚LiteLLM 到底是干嘛的如果你手里管着三五个大模型 API每天要切换 GPT、Claude、Gemini还要给不同团队发密钥、限额、看账单你很快就会明白一件事真正麻烦的不是模型本身的调用而是围绕谁能用、能用多少、花多少钱这一堆管理琐事。LiteLLM 就是在这个场景里精准踩中痛点的工具。简单说LiteLLM 是一个开源的 LLM 网关Gateway / Proxy它把 OpenAI、Anthropic、Azure OpenAI、本地部署的 Ollama/vLLM、甚至你自己微调的模型全部统一成 OpenAI 兼容的接口。客户端只要配置一个 base_url 指向 LiteLLM 服务剩下的路由、重试、限流、预算、密钥管理全都交给它处理。我最早接触它是因为团队里有人用 GPT-4o有人用 Claude还有人坚持用本地 Llama 3接口格式五花八门光是维护每个服务的 SDK 版本就够头疼。后来统一走 LiteLLM 之后前端代码彻底收敛成一套 OpenAI SDK 调用后端每次新增模型只是改一行配置的事。这个工具适合谁适合像我这样在中小团队里既当开发者又兼运维的人适合需要给多个子部门或外部客户提供模型接口的 SaaS 团队也适合想在自己应用里快速接入多模型但不想重复造轮子的个人开发者。如果你只是单机调用一个模型那 LiteLLM 确实有点重但只要你开始考虑多人多模型多预算的管理问题它就是最省心的那一层。2. 整体设计思路为什么是一套代理 管理面的架构2.1 代理层的价值统一接口与统一行为LiteLLM 的核心设计思路是把自己做成所有模型请求的唯一入口。客户端不直接碰任何一家模型厂商的 API而是把请求发给 LiteLLM 服务。LiteLLM 根据配置文件中的模型映射关系把请求转发给真实的模型服务商拿到结果后再返回给客户端。这个中间人的角色带来的第一个好处是接口格式统一。OpenAI 格式的 /chat/completions、/embeddings、/completions 接口LiteLLM 全都兼容这意味着你现有的 OpenAI SDK 几乎不用改代码只需要把 base_url 换成 LiteLLM 的地址再换上 LiteLLM 签发的密钥就行。第二个好处是行为统一。比如重试策略、超时设置、请求日志、错误处理这些原来每个模型商都不一样用了 LiteLLM 之后所有模型都走同一套规则。举个例子OpenAI 的 rate limit 错误返回 429Anthropic 返回 529Gemini 可能返回 503如果客户端自己接每种错误都要单独写处理逻辑。但在 LiteLLM 里你可以统一配置 retry 次数和退避策略它对上游不同错误码做了归一化处理客户端只需要感知最终结果。2.2 管理面的价值密钥、用户、配额三位一体LiteLLM 的另一半设计是内置了一套用户与用量管理模块。它借鉴了企业级 API 网关的思路每个用户绑定自己的虚拟密钥每个密钥关联特定的模型权限和速率限制每次调用都会记录 token 消耗和费用。这套设计把模型接入和业务管理解耦了。你的研发团队不再需要直接接触上游模型的真实 API key每个人拿到的是 LiteLLM 签发的虚拟密钥。就算有人泄露了密钥你可以在控制台一键删除不影响上游账号安全。而用量管理呢可以精确到某个用户今天用了几万 token、花了多少钱这在月底做成本分摊的时候简直救命。我见过不少团队一开始觉得直接让后端配置环境变量里的 API key 不就行了但等到人多了、场景杂了才发现连最基本的谁把 key 用到别的项目里了都查不出来。LiteLLM 的价值就是在一开始就把这些管理能力内置进去你不需要额外搭一套计费系统。2.3 为什么不用自己写代理层我知道有人会说这不就是个反向代理嘛我用 Nginx 加一点脚本也能做。这话对一半。Nginx 确实能做转发但你想想模型格式转换怎么做不同模型的 prompt 格式不同、参数名不同、返回结构不同你要写多少转换代码重试策略和超时管理怎么做按 token 计费怎么做用户虚拟密钥的生成、校验、权限隔离怎么做LiteLLM 把这些全都做成开箱即用的功能。它自己就是 OpenAI 兼容服务端接收标准请求后在内部把请求转换成各模型商需要的格式。比如 Anthropic 的 messages 格式和 OpenAI 的 messages 格式略有差别LiteLLM 会自动做字段映射。这种格式兼容层的工程量远比想象中大自己维护不划算。3. 模型管理实操配置文件就是你的模型目录3.1 基础配置文件结构LiteLLM 的一切配置都集中在一个 YAML 文件里默认叫 config.yaml。启动服务时用litellm --config config.yaml --port 4000就能拉起一个代理服务。基础结构长这样model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llama litellm_params: model: ollama/llama3 api_base: http://localhost:11434 general_settings: master_key: sk-litellm-master-key database_url: postgresql://user:passwordlocalhost:5432/litellm这里的model_name是你自己起的别名客户端调用的就是这个名字。litellm_params是真正决定转发到哪里的参数model字段的格式是服务商前缀/模型名比如openai/gpt-4o、anthropic/...、ollama/...。3.2 多模型接入统一模型名的两种玩法多模型接入时有个很实用的技巧可以让多个上游模型共享同一个model_name。比如你想做模型高可用主用 GPT-4o备用 Claude Sonnet那么可以这么配model_list: - model_name: primary-assistant litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: completion - model_name: primary-assistant litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY客户端始终请求primary-assistant这个模型名LiteLLM 内部把请求轮询发给两个上游服务。遇到某个上游故障时它会自动尝试下一个。这种方式对业务代码完全透明属于零改动切换模型的典型场景。另一种玩法是显式映射每个model_name对应一个真实的模型客户端直接按名字挑选。这种方式直观适合模型能力区分明显的场景比如你同时提供便宜的快速模型和昂贵的高质量模型两种选择给用户。3.3 模型路由与 Fallback别让单点故障拖垮业务生产环境用 LiteLLM必须配置 fallback 策略。我在实际使用中最深的感受是上游模型服务商不是每时每刻都稳定哪天你正在线上演示结果模型商那边限流了如果没有 fallback整个应用就瘫了。LiteLLM 支持两种 fallback 写法一种是在配置里声明model_list后通过路由规则指定优先级另一种是客户端请求时通过fallbacks参数动态指定。推荐在配置层面搞定因为客户端不需要感知容灾策略。基本配置方式router_settings: routing_strategy: usage-based fallbacks: [ {primary-assistant: [secondary-assistant]} ]usage-based策略会优先选择等待时间短、吞吐余量大的模型配合 fallback能在高峰期自动把部分流量导到备用模型用户体验几乎无感。3.4 模型参数与上下文长度管理每个模型的 context window 不同多模型混用时最容易踩的坑是截断或越界。在 LiteLLM 里每个模型可以声明自己的max_input_tokens、max_output_tokens服务端会据此做请求校验避免一个 128K 上下文的请求发给了只支持 8K 的模型。model_list: - model_name: small-model litellm_params: model: openai/gpt-3.5-turbo model_info: max_input_tokens: 8192 max_output_tokens: 4092这里有个经验如果用了多个供应商的模型一定要核对官方最新上下文数据别照抄旧文档。我踩过一次Azure 某个模型已经升级了上下文长度但配置里还写着旧值导致用户正常的长文档请求被 LiteLLM 预先拒绝排查了半天才发现是配置过期。4. 用户管理与密钥体系每一位使用者都应有独立身份4.1 虚拟密钥机制的核心逻辑LiteLLM 的密钥体系模仿了 Stripe 的 API key 设计。每个用户User可以拥有多个密钥Key每个密钥绑定特定权限和配额。客户端用虚拟密钥请求LiteLLM 侧通过数据库校验密钥有效性、加载用户配置、检查用量。使用虚拟密钥有三个好处不用泄露上游真实 key上游 key 只存在 LiteLLM 的环境变量里可以针对不同团队、不同项目颁发不同权限的密钥密钥泄露时可以直接吊销甚至通过key_alias追踪到是哪个团队的责任需要在config.yaml中启用数据库才能完整使用用户管理能力通常用 PostgreSQL。SQLite 也能跑但只适合本地测试生产环境千万别用并发一高就锁。4.2 创建用户与分配密钥命令行实战启动服务后可以用 LiteLLM 提供的 CLI 工具来管理用户和密钥。最常用的几个命令# 创建用户 litellm --create_user --user_id team-a-user-001 --user_email devexample.com # 为用户生成密钥 litellm --create_key --user_id team-a-user-001 --models gpt-4o,primary-assistant # 查看用户 litellm --list_users # 删除密钥 litellm --delete_key --key sk-litellm-xxxx也可以用管理 API 直接创建密钥。比如通过 curl 调用/key/generate接口带上models参数来限定该密钥可调用的模型列表带上max_budget来限制总消费。示例curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { user_id: team-a-user-001, models: [gpt-4o], max_budget: 50.0, budget_duration: 1mo }响应里会包含key字段把那个 key 发给使用者就行。这里如果你是第一次接触很容易忽略budget_duration参数。它配合max_budget才有效表示这个预算是按多久算的。比如max_budget: 50budget_duration: 1mo表示用户每个月最多消费 50 美元到了下个月自动重置。不写budget_duration的话预算会被当成永久额度用完就彻底被锁死。4.3 RBAC 权限控制哪些人能调哪些模型多部门共享一个代理时RBAC 几乎是刚需。LiteLLM 的权限模型分三层用户User拥有角色属性可以是管理员或普通用户密钥Key拥有模型访问列表未列入的模型一律拒绝模型本身可以声明访问组team_id / user_group限制谁有权限实际操作中我的习惯是这样配置权限model_list: - model_name: expensive-model litellm_params: model: openai/gpt-4o model_info: teams: [core-team, admin-team] - model_name: cheap-model litellm_params: model: openai/gpt-3.5-turbo model_info: teams: [all-teams]这样贵价的模型只有特定团队能用便宜的模型所有人可用。配合密钥生成时的models参数就能组成模型团队双重限制。经验之谈尽量少给所有模型权限。哪怕内部团队也应该先给最小权限集等有明确需求再扩。这样即使密钥泄露影响范围也有限。4.4 用户组织与多团队隔离的设计思考当用户数量超过几十个单纯用 User 表管理就不够用了你需要引入 Team团队的概念。LiteLLM 的消息模型里一个 Team 可以包含多个用户一个用户也可以属于多个 Team典型的多对多关系。团队隔离的关键在于预算和用量隔离。我推荐的做法每个团队创建独立的 Team 对象分配独立的预算团队成员生成密钥时把team_id传进去在控制面板里按 Team 维度查看用量和费用这样月底财务要数据时直接导出每个团队的消费即可不用再从一堆 User 数据里手工汇总。这个习惯越早建立越省事等用量涨到百万 token 级别再回头补就痛苦了。5. 用量管理与成本控制从能跑到花得明白5.1 用量数据是怎么被追踪的LiteLLM 每次请求完成后会记录完整的元信息用户 ID、密钥、模型名、prompt tokens、completion tokens、总费用、延迟等。这些数据写入配置的database_url对应的数据库里然后可以在/usage页面或者在管理 API 中查询。用管理 API 查用量的方式curl http://localhost:4000/global/spend/logs \ -H Authorization: Bearer sk-litellm-master-key返回内容里每条记录包含user、model、spend、total_tokens、request_time等字段。你可以基于这些数据写一些简单的统计脚本也可以直接用内置的仪表盘界面。5.2 限流与配额设置防止单个用户占满资源限流配置在 LiteLLM 里有三个维度每秒请求数RPM限制请求频率防止单用户刷爆资源每分钟 token 数TPM限制 token 吞吐量每日预算daily budget限制一天的消费总量配置示例curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-litellm-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o], max_budget: 100, budget_duration: 1d, rpm_limit: 60, tpm_limit: 60000 }这里我给一个实际经验RPM 和 TPM 别设得太紧。我一开始给团队设了 rpm_limit60结果他们批量处理数据时频繁触发 429到处报错。后来我看了下真实峰值发现他们正常业务偶尔一秒钟会发到 80 个请求直接把额度提到 120 才消停。限流的意义是挡住异常流量而不是给正常业务添堵。5.3 基于团队与用户的预算报警LiteLLM 支持设置预算超出时的行为可以配置成只告警不停服务或者直接停止。配置方式是在 key 生成的请求体里加metadata和budget_duration同时在 LiteLLM 服务端开启告警渠道。我比较推荐三级告警策略预算用到 50%仅记录日志通知到内部群预算用到 80%发出告警提醒通知负责人把关预算用到 100%自动停用密钥或降级到备用模型这个策略不是 LiteLLM 内置一次性搞定的。前两级需要你自己写脚本查/spend接口或者直接查数据库最后一级可以在 key 的max_budget上设置。虽然稍显原始但实际跑下来够用。5.4 费用统计与成本分析别让月底账单惊喜费用统计做得细其实是给自己减负。我的固定流程是每天早上写个定时任务拉取前一天各用户/各模型的 spend 数据生成一个简表按团队维度发到管理群每周做一次趋势对比看哪些模型成本在上升实现上一张简单的 SQL 查询就能完成SELECT user, model, SUM(spend) AS total_spend, SUM(total_tokens) AS total_tokens FROM spend_log WHERE request_time NOW() - INTERVAL 7 days GROUP BY user, model ORDER BY total_spend DESC LIMIT 20;如果你对数据展示有要求可以直接用 Grafana 接 PostgreSQL 数据库把消费趋势做成仪表盘。LiteLLM 虽然自带 UI但自带的 UI 更适合查一下的场景长期趋势分析还是得靠外部工具。6. 常见问题排查实录那些我踩过的坑6.1 模型调用报错先分清是配置问题还是上游问题我在实际运维 LiteLLM 时遇到过最典型的一类问题是为什么同一个请求有时候通有时候不通。排查逻辑其实很简单先看 LiteLLM 返回的错误码。如果返回401 Unauthorized大概率是虚拟密钥问题检查密钥是否存在、是否过期。如果返回404 Unknown Model检查model_name是否在model_list里。如果返回429 Rate Limit Exceeded检查本团队 RPM/TPM 配额。如果返回502 Bad Gateway或者503 Service Unavailable基本可以断定是上游模型服务商的问题去上游状态页确认。我分享一个排查小技巧启动 LiteLLM 时加上--debug参数这样请求级别的日志会打印详细信息包括上游选中的模型、token 消耗、耗时等。遇到疑难杂症这个日志比看 UI 高效十倍。6.2 用户权限失效多半是缓存惹的祸LiteLLM 在内存中缓存了用户和密钥关系如果你通过命令行或 API 修改了用户权限但客户端仍然用旧权限访问很可能是缓存没有刷新。处理方式有两种触发/key/update接口LiteLLM 会自动更新该 key 的缓存等待缓存过期LiteLLM 的缓存 TTL 默认约 30 秒如果着急直接重启服务我建议权限变更频繁的场景把数据库连接池调大避免权限校验时连不上数据库导致误判。6.3 用量数据不一致注意时钟与批次写入用量数据偶尔会出现延迟显示或统计误差通常是因为 LiteLLM 的用量写入是批次/异步模式突发流量时数据库写入会有堆积。排查时先检查数据库连接池大小和写入队列有没有积压。另外如果你的数据库和应用服务器不在同一时钟域会出现请求时间和写入时间错位的现象统计当天用量时就会发生轻微漂移。解决方案是统一使用 UTC 时间记录展示层再做时区转换这样跨时区协作的团队也能保持一致。6.4 性能问题当代理成了瓶颈LiteLLM 本身就是 HTTP 转发层性能通常不是瓶颈。但如果你把它部署在一台小机器上又同时跑了很多日志和分析任务就有可能出现端口不够用、连接池耗尽的情况。我给三个建议给 LiteLLM 单独准备一台 2C4G 以上的实例不要和业务服务混跑数据库单独部署不要用同一台机器的 SQLite打开--log参数时注意日志量生产环境建议只保留错误日志我自己用 2C4G 的服务器跑 LiteLLM 代理服务单日处理几十万次请求没出现过问题。真正要注意的是数据库性能因为每一次请求都要读写用量数据数据库连接池如果默认 20 太小高峰期会排队。6.5 密钥泄露后的应急处理流程密钥泄露这事遇到了也别慌按顺序处理立即调用/key/delete接口删除泄露的密钥检查该密钥的spend_log确认是否有异常消费如果泄露的是 master_key立即重启服务并更换general_settings.master_key给相关使用者重新签发新密钥并建议他们把密钥放到环境变量里不要写进代码我见过最离谱的情况是有人把 key 直接提交到 GitHub 公开仓库导致被爬虫扫到几分钟内消费了一百多美元。所以强烈建议生产环境开启模型总额上限就算某个 key 泄露损失也有限。7. 一些实用建议与扩展方向文章到这里核心内容基本讲完了。最后分享几个我在长期使用 LiteLLM 过程中形成的习惯。一是配置文件一定要走版本管理。config.yaml 就是你的模型目录和权限基线每次变更都要走 MR/PR 评审。我见过有人直接在服务器上改配置改完也不记录结果出了问题想回滚都不知道原来长什么样。二是凡是上生产的 key 都要关联到具体的用户或团队。最忌讳的就是随手生成一个不绑定用户的 key等月底复盘时完全对不上账。养成先用户后密钥的习惯成本分摊时你会感谢自己。三是多模型策略要留后手。LiteLLM 支持动态调整模型列表我建议至少有一种备用模型是开源本地部署的比如 Ollama 或 vLLM 跑的模型这样上游商业 API 集体故障时业务还能保持基本可用。就算推理质量差一点也好过直接停服。如果你有兴趣把这个体系做得更完整可以考虑结合 vLLM 或 SGlang 部署开源模型作为低成本推理通道把贵模型 便宜模型 本地模型三层阶梯搭出来。LiteLLM 做的是统一入口真正灵活的路由策略和成本调优还是需要根据业务特性一点点打磨出来的。从我自己的实际体会来说LiteLLM 是我用过的开源 AI 网关里上手门槛和覆盖面平衡得最好的一个。它不追求把所有功能都一次性堆给你而是把模型、用户、用量这三件最核心的事做得扎实。只要你的团队多人、多模型、有多头预算管理需求它基本上都能接得住。关键是尽早建立一套管理先行的习惯别等到账目乱了、密钥多了、模型杂了以后再来补课。
