# PR #5885 完整报告

- 仓库：`verl-project/verl`
- 标题：[cfg] fix: sync strategy from ActorConfig/CriticConfig to EngineConfig
- 合并时间：2026-04-07 10:46
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/5885

---

# PR 5885 分析报告

## 执行摘要
本次 PR 修复了 FSDP Actor 和 Critic 配置中 `strategy` 字段未同步到 EngineConfig 的问题，确保当用户设置 `actor.strategy=fsdp2` 时，引擎能正确选择 FSDP2 后端，避免因回退到 FSDP1 导致的模型训练崩溃（特别是 Qwen3.5 等多维 RoPE position_ids 模型）。该修复仅影响使用新 `engine_workers.py` 路径的 FSDP2 训练，风险较低但解决了关键兼容性问题。

## 功能与动机
**问题背景**：在 `FSDPActorConfig` 和 `FSDPCriticConfig` 的 `__post_init__` 方法中，虽然设置了 `self.engine = self.fsdp_config`，但未同步 `self.strategy` 到 `self.engine.strategy`。由于 `EngineConfig.strategy` 默认为 `None`，`engine_workers.py` 第 162 行始终传递 `None` 作为后端，导致回退到 FSDP1。这会导致需要 FSDP2 的模型（如 Qwen3.5）崩溃，因为 FSDP1 的参数包装会破坏 `apply_rotary_pos_emb` 的形状匹配。

**关键表述**：PR body 中明确指出：“For models with multi-dimensional position_ids (Qwen3.5, Qwen3-VL), FSDP1 wrapping breaks `apply_rotary_pos_emb`”。

## 实现拆解
修改涉及两个配置文件，均通过 `object.__setattr__` 强制同步 `strategy` 字段：

| 文件 | 修改内容 | 作用 |
|------|----------|------|
| `verl/workers/config/actor.py` | 在 `FSDPActorConfig.__post_init__` 中添加 `object.__setattr__(self.engine, "strategy", self.strategy)` | 将 actor 配置的 strategy 同步到 engine 配置 |
| `verl/workers/config/critic.py` | 在 `FSDPCriticConfig.__post_init__` 中添加相同逻辑 | 将 critic 配置的 strategy 同步到 engine 配置 |

**代码逻辑**：使用 `object.__setattr__` 是因为 `BaseConfig` 有冻结字段逻辑，阻止普通属性赋值。注释说明：“EngineConfig.strategy defaults to None, so without this, engine_workers.py always falls back to FSDP1”。

## 评论区精华
review 中仅有一条实质性讨论：
> **gemini-code-assist[bot]**："In addition to syncing the `strategy`, `ulysses_sequence_parallel_size` should also be synced to the engine configuration in `FSDPCriticConfig` for consistency and backward compatibility..."

该建议指出，为了保持一致性，critic 配置中的 `ulysses_sequence_parallel_size` 也应同步到 engine 配置。但 PR 最终未采纳此建议，仅同步了 `strategy` 字段。

## 风险与影响
**风险**：
1. 回归风险低，仅修改配置同步逻辑，不涉及核心训练流程。
2. 未同步 `ulysses_sequence_parallel_size` 可能导致 critic 的序列并行设置未正确传递，但根据评论该字段在 `FSDPEngineConfig` 中可变，风险可控。
3. 使用 `object.__setattr__` 绕过冻结逻辑需确保不破坏其他配置验证。

**影响**：
- 用户：修复后，设置 `actor.strategy=fsdp2` 能正确使用 FSDP2 后端，避免模型训练崩溃。
- 系统：确保 FSDP 版本选择与配置一致，提升训练稳定性。
- 团队：明确了配置层到引擎层的字段同步模式。

## 关联脉络
- **相关 PR 5870**：同样涉及 critic 配置修复，统一配置到 `HFModelConfig`，与本 PR 的 critic 配置同步问题相关。
- **相关 PR 5848**：涉及配置统一和重构，与本 PR 同属配置管理领域。

**演进趋势**：近期多个 PR（如 5870、5848）聚焦于配置系统的统一和修复，表明团队正在加强配置传递的可靠性和一致性，以支持更复杂的训练场景（如 FSDP2、Megatron 后端）。本 PR 是这一趋势中的一环，解决了 FSDP 版本选择的关键漏洞。