LiteLLM 代理自建:四个文件搞定按 key 限额与失败切换(v1.110.0)
周末的花费说不清花在哪个功能上;一家厂商抽风整站跟着挂而不是切走;失败切换看着配了,从来没触发过。
📜 目录
这套配置要防的不是宕机,是周一早上那个问题:周末烧掉的一百八十美元,花在哪个功能上,用的是谁的 key。LiteLLM 是夹在应用和各家模型之间的代理,只有把三样东西配齐——数据库、主密钥、每个功能一把带预算的虚拟 key——它才答得上这个问题。第四样是失败切换列表,也是最容易写错的一处。
先说核对到了什么程度
下面每一条都对着 v1.110.0 的源码看过(2026 年 11 月 18 日发布,GitHub releases 接口取的),不是从博客抄的。配置字段标了所在文件和行号,换个版本可以自己复核。镜像名和端口取自该 tag 仓库里的 docker-compose.yml。这是一篇配置走查,不是压测:吞吐和延迟数字一个都没有,因为没测。
第一个文件:compose 栈
要让 key、预算、花费日志活过重启,就得接 Postgres。上游 v1.110.0 的 docker-compose.yml 起两个服务:litellm 用镜像 docker.litellm.ai/berriai/litellm:main-stable 占 4000 端口,另一个是 db;环境里给 DATABASE_URL 和 STORE_MODEL_IN_DB=True,再把 config.yaml 挂到 /app/config.yaml,用 command 传进去。两处细节值得单说:STORE_MODEL_IN_DB 决定模型列表能不能在启动之后改;general_settings.master_key 是可选项,但这一项「可选」差别很大:文档写明一旦设了它,所有请求必须带这把主密钥或带一把生成的 key——不设,代理就会接受匿名请求。
第二个文件:config.yaml 用一个别名挡住两家
别名的意义是应用代码里永远不出现厂商名,只请求 chat-default,由代理决定谁来接。同一个 model_name 可以挂两条 litellm_params,一条 deepseek/deepseek-flash,一条 openai/gpt-5-mini。router_settings 里 num_retries、timeout、allowed_fails、cooldown_time 四个字段在 litellm/types/router.py 的 224 到 227 行,fallbacks 在 230 行,形状是「字典列表」,键是主模型名。
失败切换最常见的错:写成字符串列表
网上流传的片段多写成 fallbacks: ["chat-backup"]。v1.110.0 里这个字段是以主模型名为键的字典列表,写成字符串列表表达不出「chat-default 挂了走 chat-backup」这条边。还有一处更隐蔽:chat-backup 必须在 model_list 里定义过,否则这条边指向一个不存在的模型,表现是请求失败而不是启动报错——部署前 grep 一遍备份名。
三类失败要用三张表。500 和超时归 fallbacks;输入超过主模型上下文窗口归 context_window_fallbacks;被厂商内容策略拦下归 content_policy_fallbacks。只配第一张,二十万 token 的提示词会一直撞在小模型上重试。
第三个文件:一个功能一把 key,带额度
预算挂在 key 上,不挂在配置文件里。key 相关端点在 management_endpoints/key_management_endpoints.py:/key/generate 在 2347 行,/key/info 在 5030 行,另有 /key/update(4019)、/key/delete(4753)、/v2/key/info。key 上的预算字段有 max_budget、budget_duration、model_max_budget,最后一个的形状在 proxy/_types.py 里写明是 {'gpt-4o': {'max_budget': ..., 'budget_duration': '1d', 'tpm_limit': 1000, 'rpm_limit': 1000}}。
给夜间任务单独发一把 key,models 只放它用得上的两个,max_budget 五十,budget_duration 30d,rpm_limit 按批处理节奏给。三十天满额后代理直接回 400 预算超限,不会悄悄继续扣。查额度和已用去 /key/info,返回里带 spend、budget、剩余额度和重置时间,这三个数才该上仪表盘。
key 的结构里还有一个 budget_fallbacks 字段(_types.py:1274),说明「按预算改道」是配在 key 上而不是配在 router_settings 里。这里只到「字段存在」为止:它的运行时行为没有实测,别拿这篇当保证,先在一把测试 key 上试。
第四个文件:两种看钱的方式
实时数:/key/info 看单把,/spend/keys 和 /spend/users 看汇总。原始明细:/spend/logs,但源码里明确写着这个接口会把结果截断到最近若干行,分页要用 /spend/logs/v2(spend_management_endpoints.py 第 380 行)。月底对账直接拉 v2 求和,或者查库;拿截断接口做汇总,会把忙的那一周算得偏便宜。
厂商可达性是另一件事。/health(health_endpoints.py:1557)和 /v1/models(proxy_server.py:12774)都要带 key,接监控时用主密钥。切换一直在触发的时候,从应用侧看服务是健康的,只有健康检查能看出主模型还在冷却期。
单次成本对上,额度才有意义
五十美元的月额度在不知道单次价格之前只是个数字。按本站测过的检索形态——输入 2198 token、输出 350 token——deepseek-flash 按官方现价(输入每百万 0.15 美元、输出每百万 0.60 美元,错峰档)单次 0.00054 美元;gpt-5-mini 按 LiteLLM 价格表(0.25 / 2.00)是 0.00125 美元,差 2.3 倍。同样五十美元,前者约九万两千次,后者约四万次。写在 key 旁边的应该是这个次数。
代理还顺手暴露一个杠杆:固定的提示词前缀能被厂商侧缓存命中,DeepSeek 的缓存命中输入是每百万 0.003 美元,未命中 0.15 美元,差五十倍。别名本身不制造缓存,但换到对缓存友好的厂商只要改一行。
放真实流量之前的检查
一,docker compose config 能解析,config.yaml 的挂载指向文件不是目录。二,用主密钥请求 /v1/models,每个预期的 model_name 都在,备份也在。三,把一家的凭据改成错的,确认请求仍是 200——这是切换那条边真的生效的唯一证据。四,发一把 max_budget 0.01 的 key,花掉两分钱,看 400 是不是准时来。五,拉 /spend/logs/v2,确认每行带的是 key 别名,不只是模型名。
站内相关:网关对比那篇讲为什么代理比每个 SDK 各存一份 key 好管,KV 缓存那篇讲自建模型挂在同一别名后面的显存账。
相关文章
本站文章由编辑人工撰写,收录的工具均经过实测或公开资料核验。文中链接指向工具官网或 GitHub 仓库,仅作信息参考,不构成付费推广。