fix(usage): 流式 usage 透传 prompt_tokens_details —— 修 QwenPaw 缓存命中率恒 0

老板报:QwenPaw 上用 ai 网关(wangjinding 供应商)调用 v4.1,
网页显示的缓存命中率一直是 0。

排查(实测,非推断):
- QwenPaw 侧 messages/tools 完全正常:6 份连续抓包逐条比对,前面所有消息
  逐字节一致、仅末尾追加 2 条(msgs 362→372 单调递增),tools 26 个逐字节相同。
- 网关出站 payload 正常:model/stream/stream_options 全同,session 稳定。
- 用网关真实出站 payload 原样直打上游:cached_tokens=126464 / 126848(99% 命中)
  ⇒ 上游缓存一直好好的。
- 真因:**网关流式响应重建 usage 时只挑 prompt_tokens/completion_tokens/
  total_tokens 三个字段累加,把 `prompt_tokens_details.cached_tokens` 丢了**,
  末尾又用这份残缺 usage 覆盖上游原始值发给客户端 —— QwenPaw 从未收到缓存字段,
  只能记 0。(同一 bug 让网关自己的控制台也看不到缓存命中。)

修复:
- 新增 `_merge_usage()`:整数累加、非整数(如 prompt_tokens_details 这类整份
  快照)覆盖,实现**全字段透传**;流式累加改用它。
- `_UsageScanner`(直传线记账)顺带收集 cached_tokens,counts() 多返回该键
  (消费方按名取值,不影响既有逻辑),网关控制台口径同步修正。
- 非流式路径本就原样透传 `result["usage"]`,无需改动。

回归:test_merge_usage_keeps_prompt_tokens_details、
test_usage_scanner_collects_cached_tokens。测试 198 passed / 0 failed。

上线验证:流式请求第 2 次 usage 已带 `prompt_tokens_details.cached_tokens=7168`。
This commit is contained in:
api-gateway committed 2026-09-24 14:39:09 +08:00
1 parent 4678fc6858
commit fddaa91de3
2 files changed
+98 -5

No files matched your search

+37 -5
View File
@@ -1345,6 +1345,7 @@ class _UsageScanner:
self.protocol = protocol
self.prompt = 0
self.completion = 0
self.cached = 0
self.seen = False
self._buf = ""
@@ -1384,9 +1385,40 @@ class _UsageScanner:
if out is not None:
self.completion = int(out)
self.seen = True
# 第三十三轮:顺带把缓存命中量也收进来(此前只记 prompt/completion,
# 网关自己的控制台因此也看不到缓存命中;不改变对客户端的任何字节)。
det = u.get("prompt_tokens_details")
if isinstance(det, dict) and det.get("cached_tokens") is not None:
try:
self.cached = int(det["cached_tokens"])
except (TypeError, ValueError):
pass
def counts(self) -> dict[str, int]:
return {"prompt_tokens": self.prompt, "completion_tokens": self.completion}
return {"prompt_tokens": self.prompt, "completion_tokens": self.completion,
"cached_tokens": self.cached}
def _merge_usage(dst: dict, src: dict) -> dict:
"""把上游 chunk 的 usage 合并进 dst —— **全字段透传**,不再只挑三个计数。
第三十三轮修复(2026-09-24,老板报「QwenPaw 缓存命中率恒 0」):
此前流式只累加 prompt/completion/total_tokens,**丢掉 `prompt_tokens_details`
(`cached_tokens` 就在里面)**,末尾又用这份残废 usage 覆盖上游原始值发给客户端
—— 于是 QwenPaw 永远收不到缓存字段,命中率只能记 0(实测:同一 payload 直接打
上游 `cached_tokens=126464`,经网关回给客户端却没了这字段)。
规则:
· 整数字段 → 累加(上游可能分多个 chunk 报,语义是增量)
· 非整数(dict/list/str/bool/None,如 `prompt_tokens_details`)→ 后到的覆盖先到的
(这类是"整份快照",累加会立刻算错)
"""
for k, v in (src or {}).items():
if isinstance(v, int) and not isinstance(v, bool):
dst[k] = int(dst.get(k, 0)) + v
else:
dst[k] = v
return dst
def _resolve_passthrough(cfg: GatewayConfig, body: dict, protocol: str):
@@ -1930,11 +1962,11 @@ def _stream_response(request, req, model_id, messages, tools):
if chunk.get("done"):
break
# 功能 8: 累计上游 chunk 的 usage(若有)
# 第三十三轮:改为**全字段**合并 —— 此前只挑 3 个计数,把
# `prompt_tokens_details.cached_tokens` 丢了,导致客户端(QwenPaw)
# 拿不到缓存字段、命中率恒 0。见 _merge_usage() 的说明。
if chunk.get("usage"):
u = chunk["usage"]
stream_usage["prompt_tokens"] = stream_usage.get("prompt_tokens", 0) + int(u.get("prompt_tokens", 0))
stream_usage["completion_tokens"] = stream_usage.get("completion_tokens", 0) + int(u.get("completion_tokens", 0))
stream_usage["total_tokens"] = stream_usage.get("total_tokens", 0) + int(u.get("total_tokens", 0))
_merge_usage(stream_usage, chunk["usage"])
# Bug 5 修复: meta 帧在首个 content 到达时才发送 —— 第六轮补齐为合法 chunk
# (缺 id/created/choices 的"元信息帧"会被严格校验的 SDK 直接拒掉)。
if chunk.get("choices") and not emitted_meta: