From fddaa91de38d84866b0a4555dbed72e89c775862 Mon Sep 17 00:00:00 2001 From: api-gateway Date: Thu, 24 Sep 2026 14:39:09 +0800 Subject: [PATCH] =?UTF-8?q?fix(usage):=20=E6=B5=81=E5=BC=8F=20usage=20?= =?UTF-8?q?=E9=80=8F=E4=BC=A0=20prompt=5Ftokens=5Fdetails=20=E2=80=94?= =?UTF-8?q?=E2=80=94=20=E4=BF=AE=20QwenPaw=20=E7=BC=93=E5=AD=98=E5=91=BD?= =?UTF-8?q?=E4=B8=AD=E7=8E=87=E6=81=92=200?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 老板报: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`。 --- app/main.py | 42 +++++++++++++++++++++++++---- tests/test_gateway.py | 61 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 5 deletions(-) diff --git a/app/main.py b/app/main.py index eaa1b23..f154986 100644 --- a/app/main.py +++ b/app/main.py @@ -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: diff --git a/tests/test_gateway.py b/tests/test_gateway.py index 3003814..4b154fe 100644 --- a/tests/test_gateway.py +++ b/tests/test_gateway.py @@ -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__":