Files
ipass__ipass/docs/llm/MULTI_ACCOUNT_ROUTING.md
T
admin bfa3cf8ff8 feat(llm): 上游多账号路由 + 账号级负载统计 (1.0.14)
一个 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/*)
2026-09-14 11:57:08 +08:00

192 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`(上游)挂多个账号,做到:
1. **下游用户 Key → 上游账号 Key 粘性绑定**:同一下游 Key 尽量一直走同一个上游账号
(便于对账、便于厂商侧按账号看用量),但这是**尽力语义**——重启后重新绑定。
2. **额度耗尽自动切换**:某上游账号被厂商判额度耗尽,下次请求自动切到同厂商下一个可用账号。
3. **重置窗口感知**:额度按周期清零,冷却时长取「最近一个重置边界」,不盲目冷却整段固定时间。
---
## 二、数据模型(`llm-upstreams.json` 的 slot)
```json
{
"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 错误。