# PR #5763 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] refactor: add constraints on the use of vpp and mbridge parameters
- 合并时间：2026-03-26 20:18
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/5763

---

## 执行摘要
本 PR 更新了 Ascend 后端文档，明确了 VPP (virtual_pipeline_model_parallel_size) 与 mbridge 参数不能同时使用的约束，提醒用户在使用 VPP 时需显式禁用 mbridge，以避免运行时错误。这是一个低风险的文档改进，旨在提升用户配置体验。

## 功能与动机
此变更旨在澄清一个当前兼容性约束：在 verl 中，mbridge 不支持 VPP。根据 PR body，这是为了避免用户在配置 Megatron actor 时遇到混淆的运行时失败，尤其是在 use_mbridge 默认启用的情况下（引用 issue #4528）。文档更新帮助用户正确配置参数，减少因不兼容参数导致的调试问题。

## 实现拆解
实现非常简单，仅涉及一个文件的修改：
- **文件**：`docs/ascend_tutorial/features/ascend_backend_features.md`
- **变更**：在第 276 行添加注释，说明 `actor_rollout_ref.actor.megatron.use_mbridge` 与 `actor_rollout_ref.actor.megatron.virtual_pipeline_model_parallel_size` (VPP) 暂不支持同时开启，并给出配置建议（手动将 `use_mbridge` 设为 False）。
- **代码示例 **（变更内容）：
  ```markdown
  注：`actor_rollout_ref.actor.megatron.use_mbridge` 与 `actor_rollout_ref.actor.megatron.virtual_pipeline_model_parallel_size` (VPP) 暂不支持同时开启。由于 verl 默认开启 mbridge，使用 VPP 参数时请手动将 `actor_rollout_ref.actor.megatron.use_mbridge` 置为 False。
  ```

## 评论区精华
在 review 过程中，gemini-code-assist[bot] 提出了重要建议，聚焦于文档清晰度：
> 为了提高文档的清晰度和准确性，建议在注释中明确指出完整的参数路径，而不是使用缩写（如 `mbridge` 和 `VPP`）。这可以帮助用户更轻松地找到并修改相关配置，避免因参数名不明确而导致的配置错误。

此建议被采纳，PR 作者更新了注释以包含更清晰的参数路径，减少了用户配置错误的风险。讨论无其他争议，快速解决。

## 风险与影响
**风险**：风险极低，因为是纯文档变更，不涉及代码逻辑、性能或安全。文档的清晰度通过 review 已得到改进，但潜在风险是用户可能忽略此注释，导致配置错误。无回归或兼容性问题。
**影响**：影响范围限于用户配置行为，正确阅读文档的用户能避免配置错误，减少运行时失败。对系统架构、性能或安全性无直接影响，但能提升用户体验和减少支持负担。

## 关联脉络
从历史 PR 看，此文档变更与 Megatron 模块相关（如 PR #5575 添加了 Megatron 检查点功能），但无直接代码关联。主要服务于 issue #4528 解决的默认启用 mbridge 后带来的配置复杂性，反映了项目在优化用户配置体验方面的持续努力。