# PR #5604 完整报告

- 仓库：`verl-project/verl`
- 标题：[BREAKING][trainer] feat: deprecate legacy engine fsdp and megatron workers
- 合并时间：2026-03-26 11:40
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/5604

---

# 执行摘要
此 PR 废弃了 legacy FSDP 和 Megatron workers 实现，通过将配置文件中的 `use_legacy_worker_impl` 默认设为 `disable`，并添加弃用装饰器，强制用户迁移到新 engine workers 架构。这是为 v0.8.0 移除旧代码做准备的关键步骤，影响 trainer 模块的核心工作流和用户配置。

# 功能与动机
动机源于代码库的统一化需求，旨在淘汰旧的分布式训练 worker 实现（如 `DataParallelPPOActor` 和 `MegatronPPOActor`），转而使用更现代的 `TrainingWorker` 引擎。根据 PR body，目标是在 v0.8.0 版本中完全移除这些 legacy workers，因此在此版本中先进行弃用，以减少未来升级的破坏性。关键表述来自 PR body："Deprecate legacy engine fsdp and megatron workers, which will be removed in v0.8.0."

# 实现拆解
主要改动点按模块拆解如下：
- **配置文件层**：在多个 yaml 文件（如 `verl/trainer/config/ppo_trainer.yaml` 和生成文件）中，将 `use_legacy_worker_impl` 从 `auto` 改为 `disable`，确保新实例默认使用新实现。
- **核心逻辑层**：在 `verl/trainer/main_ppo.py` 的 `add_critic_worker` 函数中添加条件导入：
  ```python
  if use_legacy_worker_impl in ["auto", "enable"]:
      from verl.workers.megatron_workers import CriticWorker
  elif use_legacy_worker_impl == "disable":
      from verl.workers.engine_workers import TrainingWorker
      CriticWorker = TrainingWorker
  ```
- **弃用标记层**：在 6 个旧 worker 类（如 `verl/workers/actor/dp_actor.py` 中的 `DataParallelPPOActor`）上添加 `@deprecated` 装饰器，消息为 "legacy worker implementation is deprecated and will be removed in v0.8.0"。
- **Engine 增强层**：在 fsdp 和 megatron 的 transformer 实现中，引入 `model_type` 字段支持（如 `verl/workers/engine/fsdp/transformer_impl.py` 中新增 value 模型加载逻辑），确保新 engine 能处理多种模型类型。

# 评论区精华
review 讨论由 gemini-code-assist[bot] 主导，聚焦于 `@deprecated` 装饰器的使用问题。关键交锋在于装饰器消息的格式：
> gemini-code-assist[bot] 指出：" 当前消息将产生混淆警告：`... Please use 'legacy worker implementation is deprecated and will be removed in v0.8.0' instead.` 为提升清晰度，请提供替换类名或重新措辞消息。"
此讨论未获回复，PR 已合并，意味着警告消息可能继续产生用户体验问题，但设计权衡倾向于快速推进弃用流程。

# 风险与影响
**技术风险**：
1. **弃用警告混淆**：当前 deprecated 消息格式不当，可能导致用户误解警告内容，影响调试效率。
2. **兼容性风险**：默认配置变更可能破坏现有工作流，用户需手动覆盖 `use_legacy_worker_impl` 或调整脚本（如示例脚本中的 `USE_FUSED_KERNELS` 和 `use_remove_padding` 调整）。
3. **回归风险**：engine 逻辑变更（如 value 模型支持）在 `verl/workers/engine/fsdp/transformer_impl.py` 中涉及复杂条件分支，需加强测试覆盖以避免运行时错误。

**影响评估**：
- 用户影响：中高程度。所有用户将默认使用新 engine workers，需验证配置兼容性；弃用警告虽提醒迁移，但消息缺陷可能降低有效性。
- 系统影响：高程度。推动架构统一，减少技术债务，但需监控新实现的稳定性和性能。
- 团队影响：中程度。标志着 trainer 模块的演进方向，为后续 v0.8.0 移除奠定基础，需团队协作确保平滑过渡。

# 关联脉络
从历史 PR 看，此 PR 是 engine workers 演进链条的一部分：
- PR #5627 为 `TrainingWorker` 添加 NUMA 亲和性，显示对新 worker 的性能优化。
- PR #5669 修复 fsdp workers 的 Liger 集成，反映 legacy 代码的维护负担。
- PR #5705 调整 megatron 配置，与本 PR 的 megatron engine 增强协同。
这些 PR 共同揭示仓库正从分散的 legacy 实现向统一、可维护的 engine 架构迁移，本 PR 是此过程的关键里程碑，为未来版本移除旧代码铺平道路。