Prhub

#15562 [Feature] Add Reasoning Tokens Usage

原始 PR 作者 Muqi1029 合并时间 2026-04-04 17:18 文件变更 12 提交数 58 评论 26 代码增减 +283 / -15

feature run-ci consistency

执行摘要

添加推理令牌使用统计，修复当前字段始终为 0 的问题。

PR body 中指出：'SGLang currently returns token usage information, but the reasoning_tokens field is always 0, which makes it unusable as a statistical metric.' 这影响了分析和监控，用户无法获取正确的推理令牌计数。

该 PR 值得精读，特别是设计决策：将逻辑放在输出处理器而非服务器进程以避免重新标记化复杂性，以及如何处理推测解码场景的统一令牌ID格式。

讨论亮点

Review 中核心讨论点：1) JustinTong0323 询问推测解码场景的处理，作者随后添加支持，统一令牌ID格式。2) CatherineSue 建议重命名 _reasoning_over 为 _is_reasoning_over，作者采纳以提升可读性。3) 关于 gRPC 中 getattr 的使用，cklxx 快速修复为直接访问属性。未解决疑虑：用户是否可以在不启用推理解析器的情况下获取推理令牌？讨论中提及但未达成结论。

实现拆解

实现分为四个主要部分：1) 在 schedule_batch.py 的 Req 类中添加 reasoning_tokens 字段和 update_reasoning_tokens 方法，用于基于 think_end_id 检测推理阶段结束并累加令牌。2) 在 scheduler_output_processor_mixin.py 中添加 _maybe_update_reasoning_tokens 方法，在预填充和解码阶段调用更新逻辑，并统一处理推测解码的令牌ID格式。3) 更新 OpenAI API 端点文件（如 serving_chat.py）和 usage_processor.py，将推理令牌纳入响应统计计算。4) 新增测试文件验证功能正确性。

文件 模块 状态 重要度
python/sglang/srt/managers/schedule_batch.py scheduling modified 8.0
python/sglang/srt/managers/scheduler_output_processor_mixin.py scheduling modified 7.0
python/sglang/srt/entrypoints/openai/usage_processor.py api modified 6.0
test/registered/openai_server/features/test_reasoning_usage_tokens.py test added 5.0

分析完成后，这里会展示 LLM 生成的相对完整源码片段和详细注释。

关键符号

update_reasoning_tokens _maybe_update_reasoning_tokens calculate_token_usage

评论区精华

推测解码处理 正确性

JustinTong0323 提问如果推测解码开启如何处理推理令牌计数

结论：作者更新代码，在 process_batch_result_decode 中统一 next_token_ids 格式并调用更新方法 · 已解决

变量命名优化 style

CatherineSue 建议将 _reasoning_over 重命名为 _is_reasoning_over 以提升可读性

结论：作者采纳建议，重命名变量 · 已解决

gRPC 属性访问设计 设计

CatherineSue 询问为什么在 gRPC 中使用 getattr，cklxx 指出并修复为直接访问属性

结论：cklxx 修改代码，移除不必要的 getattr 用法 · 已解决

风险与影响

技术风险包括：1) 回归风险：核心调度文件（schedule_batch.py 和 scheduler_output_processor_mixin.py）变更可能影响其他请求处理逻辑。2) 性能风险：添加额外计数逻辑，但作者称开销小，需监控对高并发场景的影响。3) 兼容性风险：API 响应添加新字段，保持向后兼容，但客户端可能需要适配。4) 测试覆盖：新增测试覆盖正常和推测解码场景，但边缘案例（如空推理令牌列表）需进一步验证。

影响范围：1) 用户：现在可以正确获取推理令牌统计，用于成本监控、分析和计费，提升用户体验。2) 系统：无破坏性变更，API 响应添加字段，不影响现有功能。3) 团队：需要更新相关文档以反映新字段，并确保在后续开发中一致使用。

核心调度变更 推测解码兼容性 缺少文档更新

关联 Issue

未识别关联 Issue

当前没有检测到明确关联的 Issue 链接，后续同步到相关引用后会出现在这里。

完整报告

Markdown PDF

执行摘要

  • 一句话：添加推理令牌使用统计，修复当前字段始终为0的问题。
  • 推荐动作：该 PR 值得精读，特别是设计决策：将逻辑放在输出处理器而非服务器进程以避免重新标记化复杂性，以及如何处理推测解码场景的统一令牌ID格式。

功能与动机

PR body 中指出：'SGLang currently returns token usage information, but the reasoning_tokens field is always 0, which makes it unusable as a statistical metric.' 这影响了分析和监控，用户无法获取正确的推理令牌计数。

实现拆解

实现分为四个主要部分：1) 在 schedule_batch.py 的 Req 类中添加 reasoning_tokens 字段和 update_reasoning_tokens 方法，用于基于 think_end_id 检测推理阶段结束并累加令牌。2) 在 scheduler_output_processor_mixin.py 中添加 _maybe_update_reasoning_tokens 方法，在预填充和解码阶段调用更新逻辑，并统一处理推测解码的令牌ID格式。3) 更新 OpenAI API 端点文件（如 serving_chat.py）和 usage_processor.py，将推理令牌纳入响应统计计算。4) 新增测试文件验证功能正确性。

关键文件：

  • python/sglang/srt/managers/schedule_batch.py（模块 scheduling）: 添加推理令牌计数核心逻辑，包括 update_reasoning_tokens 方法和相关状态字段
  • python/sglang/srt/managers/scheduler_output_processor_mixin.py（模块 scheduling）: 集成推理令牌更新到调度输出处理，添加 _maybe_update_reasoning_tokens 方法并处理推测解码
  • python/sglang/srt/entrypoints/openai/usage_processor.py（模块 api）: 更新使用统计计算以包含推理令牌，影响所有 API 响应的令牌使用字段
  • test/registered/openai_server/features/test_reasoning_usage_tokens.py（模块 test）: 新增测试验证推理令牌计算正确性，覆盖正常、推测解码和流式场景

关键符号：update_reasoning_tokens, _maybe_update_reasoning_tokens, calculate_token_usage

评论区精华

Review 中核心讨论点：1) JustinTong0323 询问推测解码场景的处理，作者随后添加支持，统一令牌ID格式。2) CatherineSue 建议重命名 _reasoning_over 为 _is_reasoning_over，作者采纳以提升可读性。3) 关于 gRPC 中 getattr 的使用，cklxx 快速修复为直接访问属性。未解决疑虑：用户是否可以在不启用推理解析器的情况下获取推理令牌？讨论中提及但未达成结论。

  • 推测解码处理 (correctness): 作者更新代码，在 process_batch_result_decode 中统一 next_token_ids 格式并调用更新方法
  • 变量命名优化 (style): 作者采纳建议，重命名变量
  • gRPC 属性访问设计 (design): cklxx 修改代码，移除不必要的 getattr 用法

风险与影响

  • 风险：技术风险包括：1) 回归风险：核心调度文件（schedule_batch.py 和 scheduler_output_processor_mixin.py）变更可能影响其他请求处理逻辑。2) 性能风险：添加额外计数逻辑，但作者称开销小，需监控对高并发场景的影响。3) 兼容性风险：API 响应添加新字段，保持向后兼容，但客户端可能需要适配。4) 测试覆盖：新增测试覆盖正常和推测解码场景，但边缘案例（如空推理令牌列表）需进一步验证。
  • 影响：影响范围：1) 用户：现在可以正确获取推理令牌统计，用于成本监控、分析和计费，提升用户体验。2) 系统：无破坏性变更，API 响应添加字段，不影响现有功能。3) 团队：需要更新相关文档以反映新字段，并确保在后续开发中一致使用。
  • 风险标记：核心调度变更, 推测解码兼容性, 缺少文档更新

关联脉络

  • PR #15875 Fix: add reasoning tokens usage: 重复 PR，本 PR cherry-pick 了其中的测试代码
  • PR #14404 未知（讨论中提及）: 讨论中提到的另一个重复 PR，显示该功能有多人尝试实现
  • PR #21080 [Speculative Decoding] Add FA4-based Spec Support: 涉及推测解码功能，与本 PR 的推测解码处理逻辑相关

参与讨论