天锚定重置边界计算(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,新增「探测恢复闭环」剧本)。
289 lines
17 KiB
Markdown
289 lines
17 KiB
Markdown
# 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 展示(管理台「上游」页 · 密钥 / 负载 列)
|
||
|
||

|
||
|
||
(示意图,数据为构造值;含双 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` 输出的「掩码为空 → 显式标 `**空**`」是发现这类问题的关键指示器:旧镜像没有这个
|
||
输出(直接回脱敏后的掩码,肉眼对比看不出问题),新镜像会显式标红。
|