vLLM V0 到 V1 迁移：在强化学习修正之前，先确保正确性

背景

vLLM V1 是对 V0 引擎的一次重大重写。随着大型语言模型（LLM）在强化学习（RL）训练中的广泛应用，确保推理后端（Backend）与训练器（Trainer）之间的一致性变得至关重要。特别是在在线 RL 系统中，Rollout 侧生成的 logprobs（对数概率）直接作为优化目标的一部分，任何后端行为的细微偏差都可能导致训练不稳定或收敛失败。

本文档记录了 Hugging Face 团队在将 RL 训练工作负载从 vLLM 0.8.5 (V0) 迁移到 vLLM 0.18.1 (V1) 过程中的调试经历。迁移的目标非常明确且狭窄：首先验证 V1 返回的 rollout logprobs 格式是否符合 Trainer 的预期，并在恢复后端一致性后，再评估目标函数层面的变化。

在迁移初期，研究人员观察到 GSPO（Generalized Self-Policy Optimization）训练运行中出现了一系列指标异常，包括 clamp_log_ratio_new_old_indicator、kl_new_old、entropy 和 reward。这些指标在训练早期就迅速偏离了 V0 参考基线。同样的模式也出现在 Trainer 指标中，其中 Clip rate（裁剪率）是最容易读取的信号。

核心内容

故障模式分析

团队将潜在原因分为三个层级，并遵循“先排除后端行为问题，再调整目标函数”的诊断逻辑：

1. 语义不匹配（Semantic mismatch）：后端返回的 logprobs 含义与 Trainer 预期不符。
2. 推理路径不匹配（Inference-path mismatch）：后端使用了不同的运行时默认值（如缓存、调度或请求处理），导致相同提示词遵循了不同的执行路径。
3. 目标不匹配（Objective mismatch）：由于残留的过时数据（staleness）或后端不匹配，RL 目标函数需要修正。

团队最初过早地怀疑了第三类原因（目标函数问题），但正确的诊断方法是将前两类视为后端行为问题并优先排除。

V1 后端修复细节

1. Logprobs 语义修复

第一个问题是语义层面的。默认情况下，vLLM V1 从原始模型输出中返回 logprobs，即在 logits 后处理（如温度缩放、惩罚、top-k/top-p 过滤）之前。然而，PipelineRL 期望从采样器使用的处理后分布中获取 logprobs。

解决方案： 设置 logprobs-mode=processed_logprobs。

这一修复消除了 rollout logprobs 中明显的均值偏移。启用 processed_logprobs 后，策略比率（policy-ratio）图显示，在所有三次运行中，平均策略比率都极其接近 1.0 居中，确立了均值偏差修复的有效性。然而，训练曲线与已知良好的参考基线之间仍存在差距，表明问题出在推理路径上。

2. 运行时默认值修复

早期的 V1 运行混合了引擎版本与 V1 的运行时默认值，导致与 V0 参考路径不一致：

• 前缀缓存（Prefix caching）：早期运行未设置，应用了 vLLM 0.18.1 的默认值。
• 异步调度（Async scheduling）：早期运行未设置，应用了 vLLM 0.18.1 的默认值。
• 非标准的注意力覆盖：通过启动时 kwarg 透传设置了 ad-hoc 的 disable-cascade-attn，这不在提交的配置一致性配方中。

解决方案： 在一致性运行中，显式指定以下配置：

vllm_config:
  use_v1: true
vllm_kwargs:
  logprobs-mode: processed_logprobs
  enable-prefix-caching: false
  async-scheduling: false

关于前缀缓存的特别说明： 虽然前缀缓存通常是针对固定模型状态的正确性保留推理优化，但在该在线 RL 设置中，它成为了 V1 独有的差异点。由于缓存策略忽略了权重更新边界，前缀缓存命中可能会复用权重更新前计算的状态。此外，Actor 还需要处理重复前缀、并发请求、异步调度和在途权重更新。禁用前缀缓存消除了 V1 独有的自由度，从而简化了对比。

3. 在途权重更新（Inflight Weight Updates）

权重同步必须匹配在线 RL 的更新模型。V0 的有效行为更接近于：

1. 在引擎边界暂停执行。
2. 加载新权重。
3. 恢复执行，且没有显式的缓存状态失效。

为了在 V1 中匹配这一行为，团队使用了以下代码路径：

await engine.pause_generation(mode="keep", clear_cache=False)
await engine_client.collective_rpc_async(
    "receive_weight_update",
    args=(request.model_dump_json(),),
)
await engine.resume_generation()

关键细节在于：

• mode="keep"：比 wait 或 abort 更贴近旧的在途更新模型。
• clear_cache=False：匹配 V0 包装器的行为，即在更新时保留缓存状态。

运行时诊断显示，初始 V1 路径在训练后期携带了比修正后的 V1 运行更持久的延迟（lag）。

4. 最后的差距：fp32 lm_head

上述后端修复消除了明显的迁移问题，但最终的一致性仍需要匹配用于计算 logits 的数值路径。Trainer 使用 fp32 lm_head 进行最终投影，Rollout 后端必须匹配这一行为。

这一问题在 MiniMax-M1 技术报告中也有类似体现：他们的 RL 运行显示出训练/推理 token 概率不匹配，最终追溯至 LM 输出头，并通过以 fp32 计算头部来修复。

为什么这很重要？ RL 更新直接消耗 token logprobs。logits 的微小变化会在策略比率、KL 散度和裁剪中显现出来。因此，最终投影精度是在线 RL 正确性表面的一部分。ScaleRL 论文后来也将 fp32 logits/head 计算纳入其 RL 配方，并将其作为大规模 RL 的有用设计选择进行了消融实验。

引入 fp32 lm_head 路径后，Reward 指标提供了最终一致性的紧凑视图。最终 V1 运行成功追踪了 V0 参考曲线，而初始 V1 尝试产生了明显不同的奖励曲线。

关键要点

• 后端正确性优先：在尝试通过目标函数修正（如截断重要性采样、重要性比率重加权）来解决训练问题之前，必须先确保推理后端产生正确的 logprobs 和运行时行为。否则，目标函数修正可能会掩盖后端错误，使训练曲线难以解释。
• Logprobs 模式配置：vLLM V1 默认返回原始 logprobs，而在 RL 训练中通常需要使用 logprobs-mode=processed_logprobs 以匹配采样器使用的分布。
• 显式配置默认值：V1 引入了新的默认行为（如前缀缓存、异步调度）。在迁移到 V0 参考基线时，必须显式禁用或配置这些特性，以避免引入隐藏的 V1 独有差异。
• 权重更新同步：在在线 RL 中，在途权重更新需要精确控制缓存状态（clear_cache=False）和暂停模式（mode="keep"），以匹配 V0 的行为。
• 数值精度一致性：确保 Rollout 后端的 lm_head 计算精度（如 fp32）与 Trainer 一致，以防止因 logits 微小差异导致的策略比率偏差。

意义与影响

1. 为大规模 RL 训练提供工程基准

本文档揭示的不仅是 vLLM 的版本差异，更是大规模在线 RL 训练中的通用工程挑战。它强调了在分布式系统中，推理后端与训练逻辑之间的“隐式契约”必须被显式验证。对于任何使用 LLM 进行 RLHF（人类反馈强化学习）或 DPO（直接偏好优化）的团队，验证 logprobs 语义和数值精度是训练稳定性的前提。

2. 澄清