一个 slot 挂多把上游账号 Key,解决厂商「单账号额度/并发受限」与 「同一用户缓存命中」两个矛盾诉求。 多账号路由 (plugin-llm) - models: Upstream.accounts[] (auth/note/resets) + 上游级 exhaust_status/exhaust_markers;顶层 auth 保留兼容(accounts 为空时合成单账号) - upstreams::pick_account:粘性绑定 ukb:<key> 优先 → 无绑定时 FNV-1a(下游 Key) % 可用数 冷分散 → 绑定账号冷却则重新分散 → 全冷却取最早恢复 * 分散避开厂商单账号 agent 并发上限;落点固定保住 prompt/token 缓存 - cool_until_until 天锚定冷却:boundary = day0 + ceil(已过/窗口)*窗口, 封顶次日 0 点(MiniMax 5h 窗口、24=5*4+4 → 末段 20:00-24:00 只有 4h 随天重置) - 耗尽双检测 (log 阶段):$upstream_status 命中 exhaust_status,或 usage_filter 流式扫到 marker → $llm_acct 定位本次账号 → 写冷却 uac: - shm: up:/upa:/uac:/ukb:/upe: 五类前缀;$llm_acct 变量 (NOCACHEABLE) 账号级负载统计(问题发现与跟踪) - 新增 uda:<slot>:<idx>:<day>(请求/token)与 uex:(耗尽次数) 日桶, 复用内核 usage::bump_day —— 无数据库、无新进程(项目红线) - 计数点只在 log 阶段一次;pick_account 会被 $llm_target/$llm_auth/$llm_acct 三个变量各触发一次,放进那里会三倍计数 - view() 投影带每账号 load 与 account_trend + trend_labels(日期由后端算) - 管理台「上游」页密钥列:各 Key 今日请求/token/耗尽 + 负载比例条 + 14 天迷你趋势(自绘 SVG,零第三方依赖)+ 冷却/耗尽徽标 + 上游合计 测试与验证 - 回归 279 条全绿(网关 102 + LLM 177),新增 6 条多账号/负载断言 - 假上游新增 UPSTREAM_FAIL_AUTH 模拟账号额度耗尽;靶机验证 Key 真被替换 - 前端以真实 admin.css + upstreams.js 渲染路径做无头浏览器断言: 比例条与负载成比例(412 vs 96 → 100%/23%)、每账号 14 条块、 悬停峰值日期与数据逐位吻合、单账号/无账号兜底正常、无横向溢出、零 JS 错误 文档 - 新增 docs/llm/MULTI_ACCOUNT_ROUTING.md(数据模型/路由/冷却数学/shm 布局/负载统计) - readme §11 数据模型 + §15 上游配置 + §15 用量统计 + §12.6 tag 表 + §16 变更记录 - 修正 docs/llm/*.md 中插件化前的过时路径(rust/src/* → crates/plugin-llm/src/*)
10 KiB
LLM 上游多账号路由与额度耗尽自动切换
适用版本:
ipass-1.0.14(插件化后的plugin-llm)。 涉及文件:rust/crates/plugin-llm/src/{models,upstreams,llm,usage_filter,handlers,api}.rs、conf/nginx.conf(LLM server)、tests/llm/{e2e.sh,upstream.py,fixtures/llm-upstreams.json}。
一、解决什么问题
同一上游厂商(如 MiniMax)往往给多个账号 Key,且额度按周期清零(MiniMax 是
「每周清零 + 每 5 小时清零」)。本特性让一个 slot(上游)挂多个账号,做到:
- 下游用户 Key → 上游账号 Key 粘性绑定:同一下游 Key 尽量一直走同一个上游账号 (便于对账、便于厂商侧按账号看用量),但这是尽力语义——重启后重新绑定。
- 额度耗尽自动切换:某上游账号被厂商判额度耗尽,下次请求自动切到同厂商下一个可用账号。
- 重置窗口感知:额度按周期清零,冷却时长取「最近一个重置边界」,不盲目冷却整段固定时间。
二、数据模型(llm-upstreams.json 的 slot)
{
"minimax": {
"base": "https://api.minimax.chat/v1",
"models": ["abab6.5s-chat"],
"enabled": true,
"accounts": [
{"auth": "Bearer <key1>", "note": "acct-1", "resets": [604800, 18000]},
{"auth": "Bearer <key2>", "note": "acct-2", "resets": [604800, 18000]}
],
"exhaust_status": [401, 402, 429, 403],
"exhaust_markers": ["\"status_code\":1004", "余额不足"],
"created_at": 1757500000
}
}
| 字段 | 含义 |
|---|---|
accounts |
多账号数组。取代旧版单 auth 字段;accounts 为空时由顶层 auth 兼容合成单账号 |
accounts[].auth |
完整的 Authorization 头值(如 Bearer sk-xxx)。留空表示免鉴权后端 |
accounts[].note |
备注(如「华东主账号」),仅展示 |
accounts[].resets |
该账号的额度重置周期(秒)数组,如 [604800, 18000] = 周 + 5 小时。全空=不自动切换 |
exhaust_status |
命中即判「额度耗尽」的 HTTP 状态码(上游级,所有账号共用)。如 [401,402,429,403] |
exhaust_markers |
响应体含任一子串即判耗尽(逐字节匹配,大小写敏感)。用于厂商「HTTP 200 + body 报错」的场景 |
敏感级别等同
users.json:accounts[].auth含上游真 Key,配置文件不入库 / 不进 Gitea raw。
三、路由逻辑(access 阶段 pick_account)
1. 查下游 Key 的粘性绑定 ukb:<downstream_key> → 已有账号下标
2. 无绑定 → FNV-1a(key) % 可用数 → 冷分散(不是固定 avail[0],也不是随机)
3. 绑定账号在冷却中 → 跳过,按下流 key 在剩余可用里重新分散
4. 全部冷却中 → 选「最早恢复」的账号(min cool_until)
5. 选定后写/刷新 ukb 粘性绑定(TTL = max(resets),兜底 7 天)
3.1 冷分配为什么用「键哈希」而不是「随机」或「固定第 0 个」
三者要同时满足两个看似矛盾的目标:
| 目标 | 为什么需要 |
|---|---|
| 均匀铺开 | MiniMax 这类厂商对单账号有 agent 并发上限。若所有下游 Key 都落 account#0,一把 Key 被打满、同 slot 的其它 Key 却闲着 |
| 分配后保持 | 同一用户的请求若被轮到不同上游账号,prompt / token 缓存前缀对不上 → 缓存命中率暴跌,等于白缓存 |
- 固定
avail[0]:满足「保持」但不满足「铺开」——全部压在第一个账号。 - 随机分配:满足「铺开」但不满足「保持」——同一用户每次请求都可能换账号,缓存必然失效。
- FNV-1a(key) % n:
key固定 ⇒ 落点固定(满足保持);不同key哈希值不同 ⇒ 落到不同账号(满足铺开)。 且确定性可复现——本机回归能用同一段哈希精确预测首次落点,不必依赖全局随机源。 (随机源仅在没有下游 Key 时兜底:管理台「测试」按钮这类内部探测流量走ngx_random(),不要求粘性。)
⚠️ 分散是冷分配时选一次,之后由 ukb: 绑定固定住;绑定账号冷却被跳过时会在剩余可用账号里按同一哈希重新分散。
- 粘性仅共享内存:重启后绑定丢失,下次请求重新冷分配,符合「尽可能同一 Key 用同一上游 Key」的尽力语义。
四、耗尽检测(log 阶段,双重保险)
| 来源 | 机制 | 适用场景 |
|---|---|---|
| HTTP 状态码 | 读 $upstream_status 末段,命中 exhaust_status → 标记 |
厂商直接回 401/402/429/403 |
| 响应体标记 | usage_filter 在 body 流式扫描 exhaust_markers,take_exhausted 透给 log |
厂商「HTTP 200 + body 报错」(如 MiniMax status_code:1004) |
任一命中 → 读 $llm_acct(本次 access 阶段选中的账号下标,确定一致)→
mark_exhausted(slot, idx, resets) 写冷却。
五、冷却窗口(天锚定,关键)
cool_until_until(resets, now) 的边界计算锚定到「当天的 0 点」,而非简单 now + 窗口 滚动:
day0 = RESET_DAY_OFFSET_SEC + floor((now - RESET_DAY_OFFSET_SEC) / 86400) * 86400
elapsed = now - day0
boundary = day0 + ceil(elapsed / 窗口) * 窗口,且封顶到 day0 + 86400(次日 0 点)
为什么必须天锚定(MiniMax 实测口径):
MiniMax 的 5 小时额度从当天 0 点起每 5h 清一次,但 24 = 5×4 + 4——
最后一段窗口 20:00–24:00 只有 4 小时,到点随「天」一起重置。
如果简单 now + 5h 滚动,21:00 耗尽会冷却到次日 01:00,与厂商口径对不上;
天锚定后封顶到当日 24:00(差 3h),与厂商行为一致。
RESET_DAY_OFFSET_SEC(默认28800= 北京时间)让 MiniMax 描述的开箱即用;其他时区厂商改成0即可。- 多窗口取最早恢复:
resets=[604800, 18000]时,周额度与 5h 额度哪个先恢复用哪个。 resets全空 → 兜底滚动冷却ACCT_COOLDOWN_DEFAULT = 4h。
六、共享内存布局
| 键 | 值 | 说明 |
|---|---|---|
up:<slot> |
base \n <naccounts> |
上游基址 + 账号数 |
upa:<slot>:<idx> |
auth \n <resets csv> |
单账号 auth + 重置周期 |
uac:<slot>:<idx> |
exhausted_until |
冷却截止(TTL = until,自然到期即视为恢复) |
ukb:<downstream_key> |
acct_idx |
粘性绑定(TTL = max resets) |
upe:<slot> |
status_csv \n markers_json |
上游级耗尽检测配置 |
uda:<slot>:<idx>:<day> |
requests:tin:tout(DayBucket) |
账号级负载日桶(TTL 90 天) |
uex:<slot>:<idx>:<day> |
requests(=耗尽次数) |
账号级额度耗尽次数日桶(TTL 90 天) |
写操作均写穿共享内存;停用(enabled=false)即摘 up: 条目,热路径「查不到=停用」。
七、账号级负载统计(问题发现与跟踪)
为什么用共享内存日桶而不是数据库:项目红线是「不引入数据库 / Redis / MQ / 额外常驻进程」。
而负载统计本质是每请求计数器——nginx 共享内存 zone 正是为此而生(worker 间天然共享、
原子、TTL 自动淘汰、无文件锁);换成 SQLite 反而要在多 worker 下处理 WAL 与 busy_timeout 的写锁竞争,
在网关热路径上是退步。账号级只是给已有的上游级日桶(uds:)多一维下标,
完全复用内核 ipass_core::usage 的 bump_day 原语,零新依赖、零新文件。
7.1 计数点:log 阶段,且只记一次
access : pick_account 只做决策,不记账
($llm_target / $llm_auth / $llm_acct 三个变量各触发一次 pick_account,
在这里记账会把同一请求记三遍)
proxy : nginx 原生转发
log : read_llm_acct(r) 取本次选中账号(NOCACHEABLE,与 access 同一结果)
→ bump_acct_load(slot, idx) 每次真实转发 +1
→ 命中耗尽 → bump_acct_exhaust(...) +1
→ body filter 抓到 usage → add_acct_tokens(...)
口径与请求级用量一致:只算真的转发出去的请求(被拒的 401/403/404/429 不入账)。
7.2 展示(管理台「上游」页 · 密钥 / 负载 列)
每个上游账号一块:
- 今日负载行:
今日 N 请求 · 入 X / 出 Y tok - 比例条:该 Key 占「本上游负载最大的 Key」的百分比——本上游内部相对量最有信息量, 谁在扛、有没有偏斜一眼可见(不占全局总量,否则多上游场景下每根条都很短)
- 14 天迷你趋势:后端
account_trend()按日窗 id 精确取键渲染(零第三方依赖的 SVG), 悬停给出「近 14 天合计 / 峰值 / 峰值日期」 - 徽标:
冷却(uac:键存在)、耗尽N(今日被判耗尽并冷却的次数,来自uex:) - 上游级一行合计:
N 把 Key · 今日合计 M 请求
账号级序列不参与任何转发决策,纯展示;view() 投影见 upstreams::view。
八、管理台
www/assets/upstreams.js编辑卡支持多账号行:每行 auth(掩码回显)、note、resets(逗号分隔周期)。- 列表「密钥 / 负载」列展示账号数、冷却/耗尽状态与各 Key 今日负载 + 比例条 + 14 天迷你趋势(见 §七)。
- 保存接口
POST /api/admin/upstreams/save接受accounts(JSON 数组); auth 留空=保留原值(编辑时不用每次重填真 Key)。
九、验证
- 本机回归:
tests/llm/e2e.sh多账号组(粘性 + 耗尽自动切换 + 靶机真收 Key + 账号级负载分布), 全量bash tests/run.sh all期望 279 条断言全绿(gateway 102 + llm 177)。 假上游upstream.py支持UPSTREAM_FAIL_AUTH环境变量模拟「账号额度耗尽」。 - 真 MiniMax 双 Key 实测:key1 稳定 200 + 粘性
acct=0;key1 失效 → 自动切 key2(acct=1,200)。 真 Key 仅存临时目录、测完即删,不入库。 - 前端渲染:以真实
admin.css+ 真实upstreams.js渲染路径做无头浏览器断言—— 比例条宽度与负载成比例(412 vs 96 → 100% / 23%)、每账号 14 个条块、悬停峰值日期与数据逐位吻合、 单账号老记录与无账号上游兜底正常、无横向溢出、零 JS 错误。