feat(advantage): add budget-aware group admission for GRPO

[tatazhangya]

PR type

• Bug Fix
• New Feature
• Document Updates
• More Models or Datasets Support

PR information

背景

当 GRPO 组内所有 completion 的 reward 完全相同时，中心化后的 advantage 全为零，该组无法提供有效训练信号。

对于稠密或组合 reward，还存在一类更隐蔽的弱信号组：reward 虽然不完全相同，但差异可能低于有效分辨率，标准化后仍可能被放大成较强的相对 advantage，使模型学习 reward 噪声。仅判断 reward 是否完全相同，或仅使用 std > 0，无法识别这类 near-tie 组。

本 PR 新增与 Trainer、Sampler 和 Rollout 基础设施解耦的完整组准入策略，并提供预算有界的补采规划，使同步流程、异步 Worker、离线 Rollout 和 Challenger 可以复用同一套判定逻辑。

本 PR 不修改 GRPO loss 和标准化 advantage 的计算。

主要改动

1. 分辨率感知的组准入

在 twinkle.advantage.group_admission 中新增以下接口：

GroupAdmissionConfig
GroupAdmissionDecision
GroupAdmissionPolicy

Reward Gate 支持：

• 最小 reward 总体标准差；
• 最小 reward 极差；
• 非平凡 advantage 门：至少指定数量的 completion 满足 |reward - 组均值| > 容差。

min_reward_std 表达统计离散度，min_reward_range 表达具体场景下 reward 的有效分辨率。相同 reward 极差在不同组大小和分布下可能对应不同的标准差，因此二者作为独立配置提供。

使用示例：

from twinkle.advantage.group_admission import (
    GroupAdmissionConfig,
    GroupAdmissionPolicy,
)

policy = GroupAdmissionPolicy(
    GroupAdmissionConfig(
        min_reward_std=1e-6,
        min_reward_range=0.02,
        min_nontrivial_advantages=2,
    )
)

decision = policy.evaluate(rewards)
if decision.admitted:
    train_complete_group()

准入始终以完整 prompt group 为单位，不从被拒绝组中选择部分 completion，从而保持 GRPO 的组内相对语义。

互斥的主要拒绝原因包括：

• exact_dead：组内 reward 完全相同；
• near_tie：reward 不完全相同，但未达到配置的分辨率或离散度要求；
• redundant：可选近重复门拒绝该组；
• external：外部前置条件拒绝该组。

exact_dead 对应传统零方差组；near_tie 则用于识别稠密 reward 下仍存在数值差异、但差异不足以构成可靠训练信号的组。

2. 预算感知的补采规划

新增以下接口：

SamplingBudgetConfig
SamplingBudgetState
SamplingBudgetController
ResamplePlan

控制器根据已观测的 effective group rate 维护指数移动平均，并估算达到目标有效组数量所需的补采量。

支持以下硬预算：

• 最大额外组数；
• 单轮最大额外组数；
• 最大补采轮数；
• 最大生成样本数；
• 最大生成 token 数。

ResamplePlan 返回建议补采组数、剩余目标、有效率估计、预算是否耗尽以及具体限制原因。

控制器只负责确定性规划，不直接调用 Sampler，因此不绑定具体同步或异步训练架构。

3. 可观测指标

新增 group_admission_metrics()，记录：

• candidate、admitted 和 rejected group 数量；
• effective group rate；
• reward、near-duplicate 和 external 拒绝数量；
• exact_dead、near_tie 和 redundant 的互斥计数。

拒绝原因主要以原始计数输出，使分布式调用方可以先进行全局聚合，再使用统一分母计算比例。

策略还提供可选近重复 Gate，用于检测组内 completion 的字面重复情况；该 Gate 默认关闭，内置零依赖的 n-gram Jaccard 作为基线，调用方可按需注入自定义 scorer。

4. Challenger 轻量接入

同一个策略可以传入 AgenticChallenger：

challenger = AgenticChallenger(
    backend,
    envs=envs,
    group_admission_policy=policy,
)

该接入复用 Challenger 已有的完整组边界和连续补充机制。

兼容性与边界

• 所有新增准入阈值默认关闭；
• 默认 GroupAdmissionPolicy 放行全部合法组；
• 未传入策略时 Challenger 行为保持不变；
• 不要求 Trainer、Sampler 或 Rollout 使用特定架构。

Experiment results

实验设置

使用可执行代码 Agent 任务进行了 6 轮机制验证。

Base 和 Exp 使用相同的模型、任务、Prompt、Reward 和优化器配置；实验变量为完整组准入和有界补采。

项目	配置
模型	Qwen3.5-4B
训练方式	LoRA GRPO
硬件	单张 Ascend NPU
训练轮次	Round 0–5
每轮任务数	50
Group size	3 completions
Base	固定采样，关闭动态组准入
Exp	分辨率感知准入和有界补采
min_reward_std	1e-6
min_reward_range	0.02
min_nontrivial_advantages	2
补采预算	最多 2 个额外组、1 轮补采
Sample/token 上限	每任务最多 9 个样本、30,000 tokens

机制验证结果

以下数值根据 6 轮实验 Dashboard 读取，为近似值：

指标	Round 0–5 观测结果
补采前 informative group rate	0.85–0.90
补采后 informative group rate	0.97–1.00
Informative yield 平均绝对提升	约 11 个百分点
Rejected-group recovery rate	0.61–1.00，均值约 0.83
Sampling cost multiplier	1.21×–1.35×，均值约 1.28×
Budget exhaustion rate	0.02–0.05，均值约 0.03
Exact-dead 拒绝数量	每轮 6–10 组
Near-tie 拒绝数量	每轮 0–2 组

在当前实验中观察到：

• 平均生成成本增加约 28%；
• informative group yield 平均提高约 11 个百分点；
• 首批采样失败的任务中，平均约 83% 可以通过有界补采恢复；
• 预算耗尽率维持在约 3%。

上述结果说明，该机制能够在成本可测量、预算有硬上限的前提下，提高实际进入训练的有效组比例。

指标定义：

• 补采前 informative rate：首批候选组中通过准入的比例；
• 补采后 informative rate：补采结束后获得有效组的任务比例；
• Recovery rate：首批失败任务中被补采成功恢复的比例；
• Sampling cost multiplier：生成组数除以最终评估任务数；
• Budget exhaustion rate：达到预算上限后仍未获得有效组的任务比例。

测试结果

定向测试命令：

PYTHONPATH="$PWD/src" python -m pytest \
  tests/advantage/test_group_admission.py \
  tests/twinkle_agentic/test_challenger_group_admission.py \
  -q

定向测试执行通过，无失败用例。覆盖范围包括：

• 默认兼容行为；
• exact-dead 和 near-tie 判定；
• std-only 配置；
• 非平凡 advantage 计数；
• 自定义 scorer；
• 拒绝原因与聚合指标；
• group、round、sample 和 token 预算；
• budget exhaustion；
• Challenger 默认行为和完整组准入。

其他检查：

9 个修改文件的 pre-commit hooks：通过
git diff --check：通过
Python 3.12 语法编译：通过

[kevssim]

可以补充一个端到端的运行脚本到cookbook里么

[tatazhangya]

可以补充一个端到端的运行脚本到cookbook里么

已补充端到端 Cookbook：cookbook/rl/grpo/group_admission.py 及启动脚本 group_admission.sh。示例基于官方 short_math_grpo.py，覆盖真实 GSM8K rollout、完整组准入、有界补采、GRPO advantage、反向传播和 optimizer step，并确保首轮与补采使用同一 rollout policy snapshot。exact-dead、near-tie 和预算边界由单元测试稳定覆盖。