一个 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/*)
18 KiB
流式响应下的 token 级用量统计 —— 调研与方案
写作动机:
stats.rs模块头注释里有句"为什么不 token 级"—— "上游响应体里才有 usage,SSE 必须关缓冲透传,网关不缓冲就解析不到"。 这句当时拍板是对的,但只列了死路没列活路。本文档把"活路"补齐, 对比开源做法、给出我们能落地的 5 档方案与推荐路线。关联文档:
docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md(出站头 / 多协议)、rust/src/stats.rs(当前请求级计数实现)、rust/src/config.rs§LLM 限流。 最后更新:2026-09-12(基于 ipass-1.0.6)。⚠️ 路径已过时:本文写于插件化重构(
ipass-1.0.12)之前,正文里的rust/src/*.rs与其中的行号均为当时的单 crate 布局。现对应关系:rust/src/stats.rs→rust/crates/plugin-llm/src/stats.rs、rust/src/config.rs→ 策略常量分家(内核rust/crates/ipass-core/src/config.rs+ 插件rust/crates/plugin-llm/src/config.rs)、rust/src/lib.rs→ 拆为rust/gateway/src/lib.rs(装配根 + 管理 API 的ApiHandler) 与各插件的handlers.rs;LLM 热路径的三个处理器(LlmHandler/LlmHealthHandler/AuditHandler)在rust/crates/plugin-llm/src/handlers.rs,stats::record的调用点也在此。 阅读时以模块名为准,不要按行号定位。
0. 结论先放出来
| 方案 | 改动代价 | 流式是否破坏 | 精度 | 推荐阶段 |
|---|---|---|---|---|
当前:请求级 ust:/ums: |
0 | 否 | 低(请求数) | P0 保留 ✅ |
| A 自建 C body filter 抓 usage | 中(一个独立 .so) | 否(链尾 + busy chain 副本) | 高 | P2 推荐 |
| B access 阶段预扣 prompt_tokens | 中(破 access 不读 body) | 否 | 中(只 prompt) | P1 推荐 |
| C A+B reconcile | 高 | 否 | 高 | P3 |
| D Rust 模块自建 upstream 重写转发 | 极高(重做 proxy_pass) | 是 | 高 | 否决 |
E 客户端协议约定(让客户端带 include_usage) |
0 | 否 | 看客户端配合度 | P1 辅助 |
推荐路线:P0(现状)→ P1(方案 B 起步,只对 OpenAI 系)→ P2(方案 A 抓真实 usage)→ P3(A+B reconcile 调账)。不要做方案 D。
1. 流式场景的核心矛盾
SSE 三个流式要件(conf/nginx.conf L181-184):
proxy_buffering off; # 1. 不缓冲响应
proxy_request_buffering off; # 2. 不缓冲请求
chunked_transfer_encoding on; # 3. 分块传输
关掉缓冲的根本理由:上游产一个字就推一个字,客户端打字机式渲染,关缓冲后首字节延迟从「分钟级」降到「亚秒级」(参考 sse-protocol-fundamentals-architecture/proxy-and-cdn-configuration-for-sse)。
副作用:网关拿不到完整响应体,usage 字段在最后一个 chunk 里(OpenAI chat.completion.chunk,Anthropic message_delta/message_stop),我们看不到。这是"流式 vs 统计"的根本矛盾——不是工程问题,是协议问题。
2. 开源对照表(行扫描 / 双消费 / 异步镜像)
2.1 one-api / new-api(Go):行扫描 + 主从 channel
源:relay/channel/openai/main.go::StreamHandler。关键代码(删节):
scanner := bufio.NewScanner(resp.Body)
scanner.Split(/* 按 '\n' 切 */)
dataChan := make(chan string)
var usage *model.Usage
go func() { // ① 后台 goroutine:解析
for scanner.Scan() {
data := scanner.Text()
if data[:6] != "data: " && data[:6] != "[DONE]" { continue }
dataChan <- data // 把每行喂给前端
if !strings.HasPrefix(data, "[DONE]") {
var streamResponse ChatCompletionsStreamResponse
json.Unmarshal([]byte(data[6:]), &streamResponse)
if streamResponse.Usage != nil {
usage = streamResponse.Usage // ② 抓到 usage
}
}
}
stopChan <- true
}()
c.Stream(func(w io.Writer) bool { // ③ 前台 c.Stream:边收边 Render 给客户端
select {
case data := <-dataChan:
c.Render(-1, common.CustomEvent{Data: data})
return true
case <-stopChan: return false
}
})
核心模式:主链路零阻塞,旁路 goroutine 解析 SSE 行;usage 一旦出现就更新引用;流结束([DONE] 或 scanner.Scan()==false)时把 usage 写库。
new-api 的扩展:service/token_counter.go 加了 tiktoken-go —— 请求发出前用 tokenizer 估算 prompt_tokens 预扣配额,响应到达后用真实 usage 调账(reconcile)。这是最完整的范式。
2.2 LiteLLM(Python):CustomStreamWrapper + async logging
源:CustomStreamWrapper + pass_through_cost_tracking。
- 主 SDK 返回
CustomStreamWrapper(包装 httpx 流),迭代产生ModelResponse - 异步 logging loop 在
logging_loop()里跑,不影响迭代 stream_options={"include_usage": true}是客户端约定 —— 让上游把 usage 放进最后一个 chunk
关键承认(来自 LiteLLM 文档原文):
"Streaming targets work, because response headers arrive before the body. A target that only knows its final cost after it has finished streaming cannot report it through this contract, since by then the headers are already on the wire."
—— LiteLLM 自己的 pass-through 也承认:纯流式场景无法靠响应头拿 cost。我们的处境一样。
2.3 Portkey(Node/TS):OpenTelemetry 异步镜像
源:LogsService + OTEL logs。
- 完全异步:用
HooksService+LogsService在请求生命周期各阶段打点 - 完成后把 LogObject 打包成 OTel span 推给 collector
- 主链路零依赖:OTel collector 挂了不影响转发
- 代价:每个请求都有 OTel 序列化开销(Portkey 把它做成可关闭的实验特性)
2.4 Higress(Go Wasm plugin):Wasm body filter
阿里 Higress 的 LLM 插件(plugins/wasm-go/extensions/ai-content-copilot 等)走的是 Wasm body filter:
- 在 response body filter 阶段把 buf 拷一份解析
- 把解析结果通过 host function 调回 Go 主进程
- 限制:host function 调 Go 是同步阻塞的,所以不能每 chunk 调一次 —— 必须在
last_buf一次性调 - 仍是 buf 副本,不破坏主链路
2.5 经典 nginx body filter(ngx_http_sub_filter_module):busy/free chain
源:src/http/modules/ngx_http_sub_filter_module.c。这是 nginx 内置 sub_filter 的实现,所有想做"旁路拿到响应"的 C 模块都参考它:
- 维护 busy chain(正在被下家消费的 buf)与 free chain(已消费完的 buf)
body_filter拿到inchain(来自上游)后:① 调ngx_http_next_body_filter(r, in)把同一份 buf 透传给下家;② 把 buf 入 busy chain 备用- 关键:buf 是 nginx-alloc 的,复用由下家消费后调
ngx_chain_update_chains回收 - 主链路延迟 = 0
3. 我们的硬约束 vs 各方案的兼容性
3.1 红线(节选自 CLAUDE.md)
| 红线 | 影响 |
|---|---|
| 单容器零依赖(vanilla nginx + Rust 动态模块) | 不引入 Redis/MQ/独立进程 |
rust/ 是唯一 Rust 真源(vendor 全部走 path 依赖) |
多文件 Rust 模块没问题(已在多个 .rs) |
shm 是运行期真源;data/*.json 只是持久化副本 |
用量统计必须写 shm(已有 ust:/ums:) |
access 阶段不读请求体(upstreams 模块头注释) |
方案 B 破坏,需要用户拍板 |
不用代理传 JSON model 字段(路由靠 URL slot) |
方案 B 估 tokenizer 时也读不到 model —— 这是额外问题 |
3.2 现状代码定位
- 请求级计数点:
rust/src/lib.rs:308——stats::record(&username, &slot, util::now()),在 access 阶段、所有放行检查都通过之后 - 响应路径:access 阶段返
Status::NGX_DECLINED让 nginx 原生proxy_pass走完转发 —— 我们没有 body filter 钩子(ngx-rust vendor 没暴露ngx_http_top_body_filter) - shm 编码:见
rust/src/stats.rs:84<day>:<today>:<total>:<last_ts>—— 新增字段只需扩字段位(要改encode/decode协议)
3.3 ngx-rust 现状对方案的影响
vendor/ngx-rust/src/http/request.rs:360 只有调用 filter 链的 output_filter(),没有让我们成为 filter 一环的钩子。也就是说:
- 方案 A(独立 C body filter) ✅ 完整可行 —— C 模块直接调
ngx_http_top_body_filter,与 ngx-rust 互不干涉 - 方案 D(Rust 自建 upstream) ⚠️ ngx-rust 没暴露
ngx_http_upstream_t::conf->output_filter,要做就得绕过整个 proxy 模块 → 否决
4. 五档方案详解
4.1 方案 A:C body filter 抓 usage(推荐 P2)
做法:新增一个独立 C 动态模块 libngx_ipass_usage.so,与 libipass_gateway.so 同容器同 nginx 实例:
load_module /usr/local/nginx/modules/libngx_gateway.so;
load_module /usr/local/nginx/modules/libngx_usage.so; # 新增
模块逻辑(伪代码):
static ngx_int_t
ipass_usage_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
ngx_chain_t *cl;
for (cl = in; cl; cl = cl->next) {
ngx_buf_t *b = cl->buf;
if (b->last_buf) {
// 主链路先送客户端
ngx_http_next_body_filter(r, in);
// 旁路:把 busy chain 上的字节拼起来
char *full = ngx_pnalloc(r->pool, total_size);
// ... 拼字节流到 full ...
// 调 Rust FFI:ipass_usage_record(username, slot, full)
// Rust 端走 serde_json 解析 "usage" 字段 → 写 ust:tk:<user> / ums:tk:<user>:<slot>
return NGX_OK;
}
// 主链路照常送
}
return ngx_http_next_body_filter(r, in);
}
关键点:
- 注册位置
HTTP_AUX_FILTER_MODULES(在 gzip 之后、write 之前)—— 不能注册太前,否则被 gzip 的边界切碎;不能太后,否则 write 阶段已经写完 socket busy chain模式参照ngx_http_sub_filter_module.c::ngx_http_sub_output—— buf 复用省分配- 解析失败(不是 SSE / 缺 usage 字段)→ 静默丢弃,绝不阻塞主链路
代价:
- C 代码 + nginx 编译流水线(conf/tls/ 那套已经成熟,但新增模块要走
auto/module) - shm 写入走 C→Rust FFI(状态键已经存在,FFI 函数声明在 lib.rs)
不破坏流式:buf 是同一份,nginx output_filter 透传给客户端,字节进 socket 的时机不变。只是多了一份"进 buf 时顺便看一眼"的 CPU 工作。
4.2 方案 B:access 阶段预扣 prompt_tokens(推荐 P1 起步)
做法:access 阶段读完全部请求体(或仅读前 N 字节)→ 解析 messages → 用 tokenizer 估算 prompt_tokens → 预扣配额。
// 伪代码
fn on_access_llm(r: &mut Request) -> Status {
// ... 已有鉴权/白名单 ...
// 新增:读请求体(小请求在内存里、大请求分块读完)
let body = http::read_full_body(r)?;
let v: serde_json::Value = serde_json::from_slice(&body)?;
let model = v["model"].as_str().unwrap_or("");
let messages = v["messages"].as_array().map(|a| a.len()).unwrap_or(0);
let est = tiktoken::estimate(model, &v)?; // tiktoken-rs 或字符近似
quota::pre_consume(&username, &slot, est.prompt);
// ... 已有 stats::record ...
Status::NGX_DECLINED
}
关键难点:
- access 阶段不读 body 是已有硬约束(
upstreams.rs头注释)—— 多模态请求体可达 100MB,全部读完决策会破坏 SSE 首字节 - model 字段在 body 里,但路由靠 URL slot —— 用 slot 对应的"厂商默认 tokenizer" 估精度差
- completion_tokens 估不出来(要等响应),所以只能"上限保护"
折中:只对 OpenAI 系(gpt-4/o1/o3/o4 系)做预扣(用 tiktoken-rs),其他厂商降级为"请求级"。
代价:access 阶段读 body = 打破硬约束。需要用户拍板。
4.3 方案 C:A+B reconcile(推荐 P3)
new-api 模式:方案 B 在请求前预扣(防超限),方案 A 在响应后用真实 usage 调账(精确扣费)。
请求进入 → B 预扣 max(prompt_tokens, daily_remaining) → 转发
↓
用量键:pre_deducted:pts:<user> = 估的数
↓
上游响应 → A 抓真实 usage
↓
调账:ust:tk:<user> += 真实 prompt + completion
↓
若 pre_deducted > 真实 → 释放差额回配额
若 pre_deducted < 真实 → 从配额里再扣(极少见,预扣有上浮 buffer)
代价:P1+P2 全做,复杂度叠加。留到 P3。
4.4 方案 D:Rust 自建 upstream(否决)
做法:模块里用 hyper/ureq 起 upstream 请求,完全不依赖 nginx proxy_pass。
否决理由:
- 重做整个转发栈:TLS / SNI / keepalive / 超时 / 错误页 / 大文件上传 / WebSocket —— 每个都是坑
- 与 nginx 原生
proxy_pass撞车:原生的连接池、错误页(error_page 502 503 504 = /llm_error)要全部弃用 - SSE 在 hyper 里也得自己实现 chunk 切割 + flush 调度
- 完全违反"vanilla nginx + Rust 模块补强"的根本设计
4.5 方案 E:客户端协议约定(无侵入辅助)
让客户端 SDK 主动带 stream_options={"include_usage":true}:
- OpenAI / Azure / DeepSeek / 大部分 OpenAI 兼容厂商都支持
- Anthropic 系不用这个字段(usage 在
message_delta/message_stop里默认就有)
做法:把这条规则写进管理台"客户端接入文档",并由客户端主动汇报(不是网关解析)。好处是零代码改动;代价是依赖客户端配合度,且无法强制。
位置:作为 P1/P3 的辅助手段写文档即可。
5. 推荐路线(按时间顺序)
P0(已就绪)—— 请求级计数
stats::record 已经按"已放行的请求"计数,存 ust:/ums:。保留现状。
P1(1-2 周)—— 方案 B 起步 + 方案 E 写文档
两件事并行做:
- access 阶段读 body → tokenizer 估算 prompt_tokens → 写
ust:pts:<user>/ums:pts:<user>:<slot>(新增两个 shm 键) - 管理台"客户端接入"页加一段:"建议在请求里加
stream_options: {include_usage: true},这样精确度更高"
P1 接受的取舍:
- 破坏 access 不读 body 的硬约束(需用户拍板)
- 只对 OpenAI 系做估算,其他厂商降级
- 估不到 completion_tokens —— 只能"上限保护"
P2(2-4 周)—— 方案 A 抓真实 usage
新增 C 模块 libngx_ipass_usage.so:
- 注册到
ngx_http_top_body_filter链尾(aux slot) - 只对
Content-Type: text/event-stream的响应启用(其他类型直接放行) - 解析 SSE 行 → 找
data: {"usage": {...}}最后一个 chunk → 调 Rust FFI → 写ust:tk:<user>/ums:tk:<user>:<slot>
新增 shm 键(与现有 ust:/ums: 同前缀,value 多 1 字段):
ust:tk:<user>→<day>:<today_pt>:<today_ct>:<today_total>:<total_pt>:<total_ct>:<total_total>:<last_ts>ums:tk:<user>:<slot>→ 同上
P3 —— A+B reconcile
按 new-api 模式:P1 的 pre_deducted 被 P2 的真实 usage 覆盖(差额回配额或再扣)。这是精度最高的方案,但要 P1+P2 都验证后再做。
6. 决策点(必须用户拍板)
| 编号 | 决策 | 选项 |
|---|---|---|
| D1 | 是否接受"多一个 .so" | A. 接受(推荐) / B. 否决(那 P2 无解) |
| D2 | 是否接受"access 阶段读 body" | A. 接受(方案 B 才走得通) / B. 否决(方案 B 推后) |
| D3 | P1 token 粒度 | A. 只统计总 token 数 / B. 拆 prompt + completion |
| D4 | 优先级 | A. 先做 P1(方案 B) / B. 先做 P2(方案 A) |
| D5 | 现有 ust:/ums: 计数(请求级) |
A. 保留并行 / B. 替换 |
我的推荐组合:D1=A, D2=A, D3=B, D4=B(先方案 A 后方案 B),D5=A。
7. 相关文件 / 引用
- 现状实现:
rust/src/stats.rs、rust/src/config.rs §KEY_UST_PREFIX/KEY_UMS_PREFIX - 调用点:
rust/src/lib.rs:308 stats::record - nginx 配置:
conf/nginx.confL181-184 SSE 三件套 - 出站头策略:
docs/llm/UPSTREAM_PROTOCOL_AND_AUTH.md - 开源源码:
- one-api: https://gitee.com/Cavalier/one-api/blob/main/relay/channel/openai/main.go
- new-api token_counter: https://ithub.global.ssl.fastly.net/x01n/new-api/blob/70ea899e373e487ffa550e068800db769e30ba1c/service/token_counter.go
- LiteLLM pass-through: https://litellm.vercel.app/docs/proxy/pass_through_cost_tracking
- Portkey OTel logs: https://portkey.ai/docs/product/enterprise-offering/otel/complete-logs
- nginx body filter 官方: https://www.nginx.org/en/docs/dev/development_guide.html
- sub_filter 模块(busy/free chain 范式):
src/http/modules/ngx_http_sub_filter_module.c