Files
ipass__ipass/docs/llm/MULTI_ACCOUNT_ROUTING.md
admin 0a9047840d feat(llm): 上游账号冷却改指数退避 + 真实请求探测闭环 (1.0.44)
天锚定重置边界计算(resets)删掉:锚点算错过两次(1.0.14 / 1.0.24),
线上表现为「厂商 15:00 已重置、网关锁到 18:00」。resets 只存不路由。

新口径:uac: = <backoff>:<next_probe>:<hard_cap>
- 到期放一个「无绑定/绑定失效」的真实请求过去探测,2xx → clear_cool 回队;
- 仍耗尽 → 退避翻倍(首轮 ipass_probe_min,默认 60s,30min 硬顶无条件回队自愈);
- 绑定流量永不被劫持当探测(保 prompt 缓存亲和)。
- pick_account 必须纯决策:四个 $llm_* 变量各求值一次,副作用只在 log 阶段记一次。

fix: 探测窗口判定改严格小于 —— 秒级时钟下 >= 会让「标记于 45.95s、next_probe=46」
的账号在 46.05s 即被当探测目标,1s 退避实际只等 0.05s,冷却形同虚设(回归暴露)。

回归 370 条全绿(网关 108 + LLM 262,新增「探测恢复闭环」剧本)。
2026-09-17 07:19:35 +08:00

289 lines
17 KiB
Markdown
Raw Permalink 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`);
> `ipass-1.0.44` 起冷却与恢复改为**指数退避 + 真实请求探测闭环**(§五),
> 天锚定边界计算已删除,`resets` 配置退出路由。
> 涉及文件:`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. **探测恢复**:冷却账号按指数退避到期后,放行**一个**真实请求当探测——
2xx 即自动回队、仍耗尽则退避翻倍。不猜厂商的重置窗口口径(见 §五 的历史教训)。
---
## 二、数据模型(`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`)。**只填裸 key 也行**——读出时 `normalize_auth` 自动补 `Bearer `,避免上游回 1004(详情见 §10) |
| `accounts[].note` | 备注(如「华东主账号」),仅展示 |
| `accounts[].resets` | **历史字段(1.0.44 起不参与路由)**:原为「重置周期(秒)数组」供天锚定边界计算;探测闭环上线后仅保留存储与展示,UI 已移除该输入,填错也不再影响任何行为 |
| `exhaust_status` | 命中即判「额度耗尽」的 HTTP 状态码(**上游级,所有账号共用**)。如 `[401,402,429,403]` |
| `exhaust_markers` | 响应体含任一子串即判耗尽(逐字节匹配,大小写敏感)。用于厂商「HTTP 200 + body 报错」的场景 |
> **敏感级别等同 `users.json`**:`accounts[].auth` 含上游真 Key,配置文件不入库 / 不进 Gitea raw。
---
## 三、路由逻辑(access 阶段 `pick_account`)
```
1. 绑定账号可用 → 直接用它。粘性与 prompt 缓存亲和高于一切,
绑定流量【永不】被劫持当探测(1.0.44)
2. 有冷却账号到期 → 本请求路由过去当探测(min next_probe;
哪怕池里有健康账号——无绑定/绑定失效流量承担,
代价被指数退避封顶)
3. 无到期探测、有可用账号 → FNV-1a(key) % 可用数 → 冷分散(绑定账号冷却/被删也走这支)
4. 全部冷却且无到期 → best-effort 选「最快要到期」的账号继续转发(不消耗探测窗口)
5. 选定后写/刷新 ukb 粘性绑定(TTL = 7 天常量)
```
⚠️ **`pick_account` 必须是纯决策**:`$llm_target/$llm_host/$llm_auth/$llm_acct` 四个变量
会把它求值多次(nginx 在 proxy_pass / Host / Authorization 各自求值时调用)。
副作用(re-arm、记账、清冷却)一律放 **log 阶段**——放 pick 里会让同一请求三次翻倍退避,
甚至 target 与 auth 落到不同账号(1.0.44 开发中真实踩过,e2e 探测组抓到)。
### 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)` 写/推进冷却;
**2xx 且无耗尽信号 → `clear_cool(slot, idx)` 清冷却**(探测成功的判定就这半边,幂等)。
log 阶段同时是 re-arm 的唯一落点(见 §三 的纯决策约束):
`mark_exhausted` 对已在冷却的账号,若 `now >= next_probe`(= 探测到期后仍失败)
则退避翻倍关窗;未到期(best-effort 撞墙)则时间线不动。
---
## 五、冷却与恢复(探测闭环,1.0.44 起)
不再猜厂商的重置时刻,而是**用真实流量验证恢复**:
```
标记耗尽(log 阶段) → 写 uac:<slot>:<i> = "<backoff>:<next_probe>:<hard_cap>"
首轮退避 = ipass_probe_min(默认 60s);键 TTL = 硬顶 30min
冷却期(access 求值) → now < next_probe:完全跳过(除非全池冷却走 best-effort 转发)
到期(next_probe ≤ now)→ 下一个「无绑定/绑定失效」的真实请求被路由过去当探测
log 阶段合流 → 2xx 且无耗尽信号 → 删键,账号【立即回队】
命中耗尽(= 探测失败)→ re-arm:退避翻倍(60s→2m→4m→…→30m 封顶)
其它结果(400/5xx/断连)→ 窗口原样,下个无绑定请求再试
硬顶到期(30min 无验证)→ 键自然过期、无条件回队;若仍耗尽,真实流量会再标——自愈
```
**为什么放弃边界计算**(线上事故记录,别再走回头路):
旧实现 `cool_until_until(resets, now)` 把冷却锁到「下一个天锚定重置边界」,
边界由纯 epoch 算术算出、**不随容器 TZ 变化**,但两次改动都以为会:
| 版本 | `RESET_DAY_OFFSET_SEC` | 作者以为锚 | 实际锚 | 后果 |
|---|---|---|---|---|
| 1.0.14 | `28800`(=UTC+8) | 北京 0 点 | 北京 16:00 | 边界整体错开 8h(没暴露:当时没人核对) |
| 1.0.24 | `0`("对齐 day_id") | 北京 0 点(以为 TZ 生效) | 北京 08:00 | **线上事故**:MiniMax 15:00 重置的额度被锁到 18:00,反向 13:00 又提前放闸吃 429 反复重标(单账号一天 156 次耗尽标记) |
1.0.44 把整条边界计算与 `resets` 路由语义一起删除。退避封顶 30min 意味着:
**厂商任意时刻恢复,最迟 ~30min 内被发现**;代价被严格封顶——
每账号每个退避周期最多牺牲 1 个无绑定请求(拿到的是上游真实错误,网关不发明状态码)。
- 首轮退避可调:`ipass_probe_min <秒>`(http 级指令,缺省 60;测试夹具压到 1s 保回归确定性)。
生产 `conf/nginx.conf` **刻意不写**,理由同 `ipass_stats_persist`:回滚旧镜像不受影响。
- 429(限速)与额度耗尽共用同一标记入口,但 60s 首轮退避让「限速误伤」一分钟内自愈,
不再有「一次 429 锁到下个边界」的放大。
---
## 六、共享内存布局
| 键 | 值 | 说明 |
|---|---|---|
| `up:<slot>` | `base \n <naccounts>` | 上游基址 + 账号数 |
| `upa:<slot>:<idx>` | `auth \n <resets csv>` | 单账号 auth + 重置周期 |
| `uac:<slot>:<idx>` | `<backoff>:<next_probe>:<hard_cap>` | 冷却时间线(TTL=硬顶;探测 2xx 删键即回队;见 §五。旧单段 `<until>` 值视作「立即可探测」,升级自然换代) |
| `ukb:<downstream_key>` | `acct_idx` | 粘性绑定(TTL = 7 天常量 `AFFINITY_TTL_DEFAULT`) |
| `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 展示(管理台「上游」页 · 密钥 / 负载 列)
![上游页密钥/负载列](img/upstreams-account-load.png)
(示意图,数据为构造值;含双 Key 轮换上游、单 Key 老记录、无账号上游三种形态)
每个上游账号一块:
- **今日负载行**:`今日 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
(1.0.44 起 resets 输入已移除——它不再参与路由,别再让用户猜厂商窗口口径)。
- `冷却中` 徽章带 tooltip:下次探测时刻与硬顶时刻(`view()` 新字段 `probe_next` / `cool_hard_cap`)。
- 列表「密钥 / 负载」列展示账号数、冷却/耗尽状态与**各 Key 今日负载 + 比例条 + 14 天迷你趋势**(见 §七)。
- 保存接口 `POST /api/admin/upstreams/save` 接受 `accounts`(JSON 数组);
auth 留空=保留原值(编辑时不用每次重填真 Key)。
---
## 九、验证
- **本机回归**:`tests/llm/e2e.sh` 多账号组(粘性 + 耗尽自动切换 + 靶机真收 Key + 账号级负载分布)
与**探测恢复闭环组**(`ipass_probe_min 1` 压秒;剧本:首标冷却 → 到期探测 → 2xx 回队 →
绑定流量不被劫持 → 无绑定被劫持吃真实 401 → 退避翻倍后仍持续探测 → view 投影核对),
全量 `bash tests/run.sh all` 期望**全绿**(1.0.44 时点 370 条 = 网关 108 + LLM 262;
条数随迭代增长,当前见 `CLAUDE.md`「本机验证夹具」一节)。
- 假上游 `upstream.py` 三档故障注入:`UPSTREAM_FAIL_AUTH`(按 auth 子串永远耗尽)、
`UPSTREAM_FAIL_FIRST_AUTH`(**每个 auth 只失败第一次**——验证探测成功回队)、
`UPSTREAM_FAIL_ALWAYS_AUTH`(子串命中即永远失败——验证退避持续与代价封顶)。
- **真 MiniMax 双 Key 实测**:key1 稳定 200 + 粘性 `acct=0`;key1 失效 → 自动切 key2(`acct=1`,200)。
真 Key 仅存临时目录、测完即删,不入库。
- **前端渲染**:以真实 `admin.css` + 真实 `upstreams.js` 渲染路径做无头浏览器断言——
比例条宽度与负载成比例(412 vs 96 → 100% / 23%)、每账号 14 个条块、悬停峰值日期与数据逐位吻合、
单账号老记录与无账号上游兜底正常、无横向溢出、零 JS 错误。
---
## 十、auth 规范化(兜住「只填裸 key」的历史坏数据)
> **适用版本**:`ipass-1.0.15+`
### 现象
线上某 slot(如 `minimax`)管理台「密钥」列能看到 `accounts[]`,但点「测试」按钮上游回:
```
minimax 不通:login fail: Please carry the API secret key in the
'Authorization' field of the request header (1004) (195 ms)
```
**1004 是 MiniMax 的「缺鉴权头」错误码**,与额度耗尽无关。原因:表单 placeholder 写的是
`sk-...`,用户照着填了**裸 key**,而 `accounts[].auth` 字段语义是「**完整的 Authorization
头值**」——转发时网关原样发出 `Authorization: sk-cp-...`,上游只认 `Bearer sk-cp-...`,
于是 1004。**唯一让用户感知到的现象就是「测试按钮红字」**——靶机层面的真实状态码与
厂商错误体都看不到(管理台没回显原始 body;点「测试」之前的旧版本会回 401 而非厂商原话,
更易让人误判成「Key 失效」)。
### 解决:`normalize_auth`
`plugin-llm/src/upstreams.rs` 新增 `normalize_auth(auth: &str) -> String`,
**两处应用**:
1. **写入(`upsert`)**:用户保存时若填了裸 key(无空格),自动补 `Bearer ` 前缀存盘——
历史坏数据在下次保存时归正,无需用户手动重填。
2. **读出(`read_upa`)**:转发时不管盘上存的是「裸 key」、「已带 Bearer」还是「Basic 自定义」,
读出即归一化后发往上游——**这一道是给存量坏数据用的兜底**,免去强制让用户重存的运维。
### 规则
| 输入 | 输出 | 说明 |
|---|---|---|
| `""`(空) | `""` | 未配 Key 是合法状态 |
| `sk-cp-xxx`(裸 key) | `Bearer sk-cp-xxx` | 兜住"只填裸 key" |
| `Bearer sk-cp-xxx` | `Bearer sk-cp-xxx` | 已完整,不动 |
| `Basic dGVzdA==` | `Basic dGVzdA==` | 非 Bearer scheme 也放过 |
| ` sk-cp-xxx ` | `Bearer sk-cp-xxx` | trim 后判定 |
| `Bearer sk cp` | `Bearer sk cp` | 含空格 = 已完整,不动 |
判定逻辑一句话:**「trim 后还含空白字符 → 视为已完整;否则补 `Bearer `」**。
### 自检工具
发版后用控制面脚本自助验证(不靠用户点管理台按钮):
```bash
bash deploy/agent.sh upstreams # 逐账号 Authorization 掩码 + 冷却 + 今日负载
bash deploy/agent.sh upstream-test minimax # 真实打上游 → 打印 status_code + 厂商响应体
```
`upstreams` 输出的「掩码为空 → 显式标 `**空**`」是发现这类问题的关键指示器:旧镜像没有这个
输出(直接回脱敏后的掩码,肉眼对比看不出问题),新镜像会显式标红。