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 29020e1374
commit 19e2b16107
2 files changed
+98 -5

No files matched your search

+61
View File
@@ -5229,6 +5229,67 @@ def test_remove_block_keeps_next_group_header_comment():
assert "kept-beta" in new
def test_merge_usage_keeps_prompt_tokens_details():
"""流式 usage 必须**全字段**透传,尤其 `prompt_tokens_details.cached_tokens`。
2026-09-24 老板报「QwenPaw 上缓存命中率恒 0」:真因是网关流式响应把上游 usage
重建成只含 prompt/completion/total_tokens 三个字段,把 `prompt_tokens_details`
(缓存命中量就在里面)丢了 —— 上游明明命中(同一 payload 直打上游
cached_tokens=126464),经网关回给客户端却没了这个字段。
修复:_merge_usage() 整数累加、非整数覆盖(details 是整份快照,累加会算错)。
"""
sys.path.insert(0, str(_ROOT / "app"))
import importlib
main = importlib.import_module("main")
# 典型上游 chunk:usage 带 prompt_tokens_details
dst: dict = {}
main._merge_usage(dst, {"prompt_tokens": 100, "completion_tokens": 5,
"total_tokens": 105,
"prompt_tokens_details": {"cached_tokens": 64}})
assert dst["prompt_tokens"] == 100
assert dst["prompt_tokens_details"] == {"cached_tokens": 64}, "缓存字段不能丢"
# 分多个 chunk 上报:计数累加、details 覆盖到最新
main._merge_usage(dst, {"prompt_tokens": 50, "completion_tokens": 3,
"total_tokens": 53,
"prompt_tokens_details": {"cached_tokens": 80}})
assert dst["prompt_tokens"] == 150, "整数字段应累加"
assert dst["completion_tokens"] == 8
assert dst["total_tokens"] == 158
assert dst["prompt_tokens_details"]["cached_tokens"] == 80, "details 取最新快照而非累加"
# 布尔不能被当成整数累加
main._merge_usage(dst, {"is_cached": True})
main._merge_usage(dst, {"is_cached": True})
assert dst["is_cached"] is True
# 空 dict 不炸
assert main._merge_usage({}, {}) == {}
def test_usage_scanner_collects_cached_tokens():
"""直传线的记账扫描器也要收 `prompt_tokens_details.cached_tokens`(网关控制台口径)。"""
sys.path.insert(0, str(_ROOT / "app"))
import importlib
main = importlib.import_module("main")
sc = main._UsageScanner("chat/completions")
assert sc.counts()["cached_tokens"] == 0
sc.feed(b'data: {"usage": {"prompt_tokens": 900, "completion_tokens": 12, '
b'"prompt_tokens_details": {"cached_tokens": 768}}}\n\n')
assert sc.seen
c = sc.counts()
assert c["prompt_tokens"] == 900
assert c["completion_tokens"] == 12
assert c["cached_tokens"] == 768, "控制台也应当能看到缓存命中"
# 没有 details 时不能炸、保持原值
sc2 = main._UsageScanner("chat/completions")
sc2.feed(b'data: {"usage": {"prompt_tokens": 10, "completion_tokens": 1}}\n\n')
assert sc2.counts()["cached_tokens"] == 0
# 直接运行(非 pytest)—— 必须留在文件末尾,见上方 `test_image_request_goes_to_requested_model`
# 之前的旁注:运行器只会收集执行到这一行时已经存在的 globals。
if __name__ == "__main__":