【No.9】feat(metrics): add rollout stop reason and turn quantiles

[Fredzjl]

Summary

• Add rollout stop reason count and ratio metrics from sample metadata.
• Add num_turn/p50, p90, p95, and p99 while preserving the existing min/mean/max metrics.
• Keep rollout_stop_reason as the canonical value, fall back to the normalized stop_reason category, and use unknown when neither is available.
• Keep the aggregation read-only and avoid changes to rollout control flow.

Implementation

The new aggregation helper:

• prioritizes rollout_stop_reason;
• falls back to the category prefix of stop_reason;
• computes stop-reason counts and ratios over all input samples;
• preserves the existing rollout_turns default of 1;
• returns no metrics for an empty input.

compute_metrics_from_samples now delegates the stop-reason and turn statistics to this helper.

Tests

Added focused coverage for:

• primary/fallback stop-reason precedence;
• missing and empty reasons;
• fallback reason normalization;
• count and ratio aggregation;
• p50/p90/p95/p99;
• existing min/mean/max behavior;
• missing rollout_turns;
• input immutability;
• metrics entry-point integration.

Local validation:

• focused tests: 68 passed, 3 skipped;
• Task 9 test file with the local import harness: 25 passed;
• broader regression: 626 passed, with the same optional-dependency failures/errors as the upstream baseline;
• pre-commit run --all-files: passed;
• git diff --check: passed.

The focused tests were also sanity-checked against deliberate mutations of the key aggregation semantics; each mutation was detected.

Scope

No rollout loop, stopping-condition, scheduling, routing, or session-state behavior is changed.

Related to Contributor Program Cohort 2 — Task 9 (#321).

[rai-studio-bot]

Nyanpasu 审查看板

审查状态： ✅ 已通过

审查版本： ec99918

新版本（维护者合并 main 后，ec99918b）增量复审完成：PR 自身改动与上一轮已批准版本语义一致（测试文件逐字节相同，生产 diff 仅上下文行偏移），合并未引入新问题。本地隔离加载真实聚合函数复跑单测 23 项通过；本轮全部 8 项 CI（Pre-commit、Python 3.10/3.11/3.12、H20 单测、Qwen3-4B-4xgpu-async、Qwen3-VL-4B-2xgpu、NPU）均在 ec99918 通过。无未解决问题，同意合入。

审查阶段	进度	范围与结果
常规审查	✅ 已完成	已在 ec99918 完成增量复审：核对 PR 自身 diff 与已批准轮次语义一致；上游合并范围内无 stop_reason/rollout_turns/num_turn 相关改动；num_turn/、stop_reason/ 指标键无其他写入方；入口空输入守卫为任务验收所需。未发现问题。
深度审查	✅ 已完成	生产与测试必要性审计由主审直接完成（改动小，未派发子任务）：全部保留，无删除/合并/替换建议。独立设计参照按增量轮次跳过：新提交仅为合并 main，无状态/生命周期/边界变更，设计已在上一轮完整审查。

没有未解决的审查问题。

提交范围 · 接收 3 · 建议移出 0 · 待确认 0

接收 3 个文件 · 建议移出 0 个文件 · 待确认 0 个文件。移出与待确认部分暂停深审，不代表审查通过。

文件	结论	仓库维护必要性	依据	替代去向或方案
relax/utils/metrics/metric_utils.py	接收	Task 9（#321，official-task.md）要求新增纯聚合函数输出 stop reason 计数/占比与轮数 P50/P90/P95/P99；该 helper 是唯一实现，被 compute_metrics_from_samples 调用，属生产行为。	https://github.com/redai-studio/community/blob/main/contributor-program/2026-cohort-2/official-task.md（Task 9：『新增纯聚合函数，参考 _compute_min_mean_max_stats』）	在 rollout.py 内联计算会绕开任务要求的纯聚合函数形态并重复聚合逻辑；外部实验产物无法提供生产指标。
relax/distributed/ray/rollout.py	接收	任务指定的接入点：compute_metrics_from_samples 委托新 helper 并保留原 num_turn min/mean/max；diff 仅 +4/-3，是唯一生产调用方。	https://github.com/redai-studio/community/blob/main/contributor-program/2026-cohort-2/official-task.md（Task 9 参考文件列出 relax/distributed/ray/rollout.py）	不接入则指标不会经现有汇总入口上报，任务验收条件无法满足。
tests/utils/test_metric_utils_stop_reason.py	接收	任务验收要求覆盖空输入、缺失 metadata、分位数经现有入口上报等边界；该文件是对已交付生产行为的持久回归测试。	https://github.com/redai-studio/community/blob/main/contributor-program/2026-cohort-2/official-task.md（Task 9 验收标准）	仅保留一个冒烟测试无法发现 unknown 归类、优先级回退、占比求和为 1 等指定语义的回归。

精简审查与验证依据

审查范围	进度	结论
生产代码	✅ 已完成	检查了内联、拆分、守卫位置三类替代方案；两处新增均为任务要求的最小实现，无冗余权威或多余包装。
测试	✅ 已完成	逐用例核对失败模型：25 个用例各自覆盖独立语义，未发现可合并或可删除的重复覆盖。

生产代码的必要性与替代方案

范围	必须保留的契约	更简单的方案	结论	依据与限制
relax/utils/metrics/metric_utils.py 新增 _get_stop_reason 与 compute_stop_reason_and_num_turn_metrics（+43 行）	纯聚合：优先原样上报 rollout_stop_reason，回退 stop_reason 冒号前类别，缺失归 unknown；占比以全部样本为分母、和为 1；保留 num_turn/min|mean|max 并新增 p50/p90/p95/p99。调用方为 relax/distributed/ray/rollout.py 的 compute_metrics_from_samples。	在调用点内联两段统计，或拆成 stop-reason 与 turns 两个独立函数。	保留	Task 9（official-task.md）明确要求单一纯聚合函数；调用点仅一处且已按既有模式委托多个子聚合，拆分只增加接线不减少逻辑。隔离加载真实函数复跑单测 23 项通过；ec99918b 全部 CI 通过。无冗余权威：num_turn/、stop_reason/ 键无其他写入方，agentic 原始 metadata 指标路径显式跳过 rollout_turns（relax/agentic/rollout.py:56）。
relax/distributed/ray/rollout.py 的 compute_metrics_from_samples：空输入早退并委托新 helper（+4/-3）	空输入返回空指标且不触发统计异常（任务验收标准）；非空输入指标集合与迁移前一致并新增 stop_reason/ 与 num_turn/p*。	仅在 helper 内部判空，入口不加早退。	保留	合并基线（git show 99a0b6a）上入口对空输入会产生 numpy RuntimeWarning 与 nan；仅 helper 判空无法覆盖入口其余聚合（response_len、reward 等）。入口早退是满足验收条件的最小完整修复，调用点净增 1 行。

测试的必要性与替代方案

范围	必须保留的契约	更简单的方案	结论	依据与限制
tests/utils/test_metric_utils_stop_reason.py（25 用例：解析矩阵、完整键集、分布求和、分位数插值、默认值、legacy 类型钉住、不可变性、2 个真实入口用例）	任务验收矩阵：空输入、缺失 metadata、分位数经现有汇总入口上报、不修改 sample。	将 single_sample 并入参数化用例；用纯单元测试替代入口集成用例。	保留	各用例对应独立失败模型（优先级/归一化/分布/插值/默认/向后兼容含类型一致/不变性/真实接线）；single_sample 是唯一对 helper 全部 9 个键的精确断言，入口用例是唯一覆盖 compute_metrics_from_samples 真实路径的用例，合并会丧失这两个性质。隔离环境 23 项通过，2 个入口用例经 CI（Python 3.10-3.12、H20）通过。

^{Powered by Nyanpasu with glm-5.3[1m] xhigh, please check the suggestions carefully.}

[rai-studio-bot]

已审查目标提交 1f8c719 的全部变更及指标调用路径，未发现需要修改的问题，同意合入。

隔离加载真实聚合函数与 Sample 后，23 项单测通过，差异格式检查通过。完整模块测试因本地依赖缺失未能运行，两个入口集成用例未执行；本地无多节点 GPU 环境，未运行训练集成测试。当前未发现 CI 检查结果。

^{Powered by Nyanpasu with gpt-6-astra medium, please check the suggestions carefully.}

[rai-studio-bot]

审查结论：同意合入

已在目标提交 ec99918b（维护者合并 main 后）完成增量复审。PR 自身改动与上一轮已批准版本语义一致：测试文件逐字节相同，生产 diff 仅因上游 has_repetition 重构与版权头产生上下文行偏移；合并范围内无 stop_reason / rollout_turns / num_turn 相关上游改动，指标键无冲突写入方。本地隔离加载真实聚合函数复跑单测 23 项通过；本轮全部 8 项 CI（Pre-commit、Python 3.10/3.11/3.12、H20 单测、Qwen3-4B-4xgpu-async、Qwen3-VL-4B-2xgpu、NPU）均在该提交通过，上一轮遗留的 CI 待确认项已全部转绿。生产与测试必要性审计已完成，无删除或合并建议。

审查看板：#339 (comment)

^{Powered by Nyanpasu with glm-5.3[1m] xhigh, please check the suggestions carefully.}

[SigureMo]

如果完成了，记得按照流程「提交」哦

[SigureMo]

本赛题已经由 #330 合入并锁定，感谢参与～