metrics.py — 这个文件实现了调试度量指标的计算

模块路径: verl.utils.debug.metrics

文件概述

这个文件实现了调试度量指标的计算，用于对比 rollout 阶段和 actor 阶段的 log probabilities 差异。这种对比在 RL 训练的调试中非常重要：如果两者差异过大，可能说明存在数值问题或模型同步问题。

关键代码讲解

1. Token 差异计算

def calculate_token_list_diff(tensor1, tensor2, mask):
    """计算两个 token 序列在 mask 区域内的差异数量"""
    diff_mask = tensor1 != tensor2
    valid_diff_mask = diff_mask & (mask == 1)
    diff_counts = valid_diff_mask.sum(dim=1)  # 每个样本的差异 token 数
    return diff_counts

2. Pearson 相关系数

def pearson_correlation_coefficient(tensor1, tensor2, mask):
    """计算两个 tensor 在 mask 区域内的 Pearson 相关系数"""
    mt1 = torch.masked_select(tensor1, mask)
    mt2 = torch.masked_select(tensor2, mask)
    result = torch.corrcoef(torch.stack([mt1, mt2], dim=0))
    return result[0][1].detach().item()

参考论文 https://arxiv.org/pdf/2506.13585 的实现。

3. 综合调试度量

def calculate_debug_metrics(data: DataProto) -> dict:
    """计算 rollout vs actor logprobs 的各种差异指标"""
    rollout_old_log_probs = data.batch["rollout_log_probs"]
    actor_old_log_probs = data.batch["old_log_probs"]

    # 计算概率差异
    actor_probs = torch.exp(actor_old_log_probs)
    rollout_probs = torch.exp(rollout_old_log_probs)
    pearson_corrcoef = pearson_correlation_coefficient(actor_probs, rollout_probs, response_mask_bool)
    rollout_probs_diff = calculate_log_prob_diff(actor_probs, rollout_probs, response_mask_bool)

    return {
        "training/rollout_probs_diff_valid": 1,
        "training/rollout_probs_diff_max": torch.max(rollout_probs_diff).item(),
        "training/rollout_probs_diff_mean": torch.mean(rollout_probs_diff).item(),
        "training/rollout_probs_diff_std": torch.std(rollout_probs_diff).item(),
        "training/rollout_actor_probs_pearson_corr": pearson_corrcoef,
    }

核心类/函数列表

函数名	作用
calculate_debug_metrics	计算 rollout vs actor 的调试度量
calculate_token_list_diff	token 序列差异计算
pearson_correlation_coefficient	Pearson 相关系数
calculate_log_prob_diff	log probability 差异

与其他模块的关系

• 使用 verl.protocol.DataProto 的数据结构
• 在训练循环中可选调用，输出到训练日志中
• 帮助监控 rollout 和 actor 模型的一致性

小结

在 PPO 训练中，rollout 模型（生成样本时的模型）和 actor 模型（当前训练中的模型）的 log probability 差异是一个关键的监控指标。如果差异过大，可能需要调整 KL 惩罚或检查模型同步。Pearson 相关系数提供了整体一致性的度量。