执行摘要
- 一句话：bench_serving 新增 --cache-report 展示缓存命中细分
- 推荐动作：该 PR 代码清晰、测试充分（通过现有 CI），适合合并。建议后续为该功能添加单元测试，确保
_extract_cache_from_sglext 在不同响应格式下的稳定性。审核时已注意兼容性，值得参考其安全处理 null 的方式。
功能与动机
在测试 HiCache 时，通常需要查看缓存命中情况、哪些缓存层被使用以及哪些层贡献了命中。SGLang 已支持每个请求返回 cache details（PR #17648 & #21764），但 bench_serving 缺乏聚合展示。本 PR 通过 --cache-report 标志启用该功能。
实现拆解
- 扩展输出数据结构：在
RequestFuncOutput dataclass 中新增 cached_tokens（int）和 cached_tokens_details（Optional[Dict]）字段，用于存储每个请求的缓存命中计数和详细来源。
- 新增解析函数：定义
_extract_cache_from_sglext(data, output) 函数，从 OpenAI 兼容的响应体中的 sglext 字段提取 cached_tokens_details，并安全地累加 device、host、storage 三级缓存到 cached_tokens。
- 注入到请求处理流程：在
async_request_openai_completions（流式响应时）、async_request_openai_chat_completions（流式和非流式）以及 async_request_sglang_generate（从 meta_info 直接读取）中，当 --cache-report 开启时调用 _extract_cache_from_sglext 或直接赋值。
- 聚合与报表输出：在结果汇总部分，通过单次遍历
outputs 累加 total_prompt_tokens、total_cached、以及各层级计数，最后计算缓存命中率并打印层级占比表格。
关键文件：
python/sglang/bench_serving.py（模块 工具脚本；类别 source；类型 core-logic；符号 _extract_cache_from_sglext）: 该文件是 bench_serving 工具的唯一实现，本次新增了 --cache-report 标志的解析、缓存命中数据的提取逻辑以及聚合输出功能。所有变更集中于此文件。
关键符号：_extract_cache_from_sglext
评论区精华
Review 中 bot 提出两点改进：
- 在
_extract_cache_from_sglext 中，使用 (details.get("field") or 0) 替代 details.get("field", 0) 以正确处理服务器返回的显式 null 值，避免 TypeError。
-
在聚合打印部分，建议合并多次循环为单次遍历，提升性能。开发者采纳了这些建议（最终代码中已体现）。
此外，审核人 xiezhq-hermann 批准了 PR，并提醒注意不影响其他基准测试。
-
null 值安全性：在 _extract_cache_from_sglext 中使用 (details.get("field") or 0) 替代 details.get("field", 0) (correctness): 作者采纳了建议，在最终代码中使用了 or 0 模式。
- 聚合指标循环优化 (performance): 作者采纳建议，最终代码使用单次循环计算所有聚合指标。
风险与影响
- 风险：主要风险是新增的
--cache-report 标志和解析逻辑可能对现有基准测试流程造成轻微影响：
- 如果服务器返回的
sglext 格式不兼容，_extract_cache_from_sglext 可能跳过或抛出异常。当前实现通过 or 0 安全处理了 null，且只在标志开启时才触发，默认不影响原有行为。
- 聚合循环增加了一次对
outputs 的遍历，但规模通常不大，性能影响可忽略。
- 没有新增测试文件，但该功能是对已有工具的扩展，风险较低。
- 影响：对用户：为用户（尤其是 HiCache 开发者）提供了可视化的缓存命中明细，帮助定位缓存效率问题。对系统：修改仅限基准测试工具，不影响推理服务核心逻辑。对团队：增强了 SGLang benchmark 的可观测性，有助于缓存层优化。影响度较小，仅限工具层面。
- 风险标记：新增命令行参数可能影响现有测试, 依赖服务端 sglext 格式
关联脉络
- PR #17648 Add per-request cache details to SGLang responses: 此 PR 在服务端添加了每个请求的缓存细节，本 PR 依赖该功能在 bench_serving 中聚合展示。
- PR #21764 Enhance cache details reporting: 进一步增强了缓存细节报告，本 PR 使用的
cached_tokens_details 格式来源于此。
参与讨论