# PR #6322 完整报告

- 仓库：`verl-project/verl`
- 标题：[megatron] fix: fix bug with mcore0.12.1 + torch2.9.0
- 合并时间：2026-05-12 21:31
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6322

---

# 执行摘要

- 一句话：为 mcore 0.12.1 patch 增加 torch 2.9.0 兼容
- 推荐动作：推荐合并。变更简洁且正确，为维持 NPU 升级链路兼容性所必须。值得注意的设计决策是将 patch 拆分为独立函数匹配特定版本组合，而非在单一函数内用复杂条件分支，便于未来按需增删版本支持。

# 功能与动机

NPU 环境下 vLLM 版本升级到 0.18 导致 PyTorch 版本随之升级到 2.9.0，之前仅在 torch 2.8.0 上应用的 Megatron-core 0.12.1 checkpoint 序列化 patch 在 torch 2.9.0 下同样需要启用，否则会出现 missing serialization_format 错误。PR body 明确指出 "torch2.9.0 也同步有这个 bug"。

# 实现拆解

变更涉及两个文件的极小改动：
1. **patch.py**（数据契约变更）：将函数 `apply_patch_megatron_v012_with_torch_v28` 重命名为 `apply_patch_megatron_v012_with_torch_v28_v29`，并将版本检查条件从 `version.parse(torch.__version__).base_version != "2.8.0"` 改为 `version.parse(torch.__version__).base_version not in ("2.8.0", "2.9.0")`。修改后该 patch 在 torch 2.8.0 或 2.9.0 时均会应用。
2. **__init__.py**（导入关系调整）：更新导入语句，从 `apply_patch_megatron_v012_with_torch_v28` 改为 `apply_patch_megatron_v012_with_torch_v28_v29`，并调用新函数。

两个文件均只替换了函数名及其调用点，未改动 patch 内部逻辑。

关键文件：
- `verl/models/mcore/patch.py`（模块 模型补丁；类别 source；类型 data-contract；符号 apply_patch_megatron_v012_with_torch_v28, apply_patch_megatron_v012_with_torch_v28_v29）: 核心补丁函数重命名并扩展版本检查条件，使 Megatron-core 0.12.1 的 checkpoint 序列化补丁同时支持 torch 2.8.0 和 2.9.0。
- `verl/models/mcore/__init__.py`（模块 模型入口；类别 source；类型 data-contract）: 导入和调用入口更新，将新的 patch 函数注册到模块初始化中，确保在导入 mcore 时自动应用补丁。

关键符号：apply_patch_megatron_v012_with_torch_v28_v29

## 关键源码片段

### `verl/models/mcore/patch.py`

核心补丁函数重命名并扩展版本检查条件，使 Megatron-core 0.12.1 的 checkpoint 序列化补丁同时支持 torch 2.8.0 和 2.9.0。

```python
def apply_patch_megatron_v012_with_torch_v28_v29() -> None:
    # 该补丁修复 Megatron-core v0.12.1 在分布式 checkpoint 异步写入时
    # 因缺少 serialization_format 属性而报错的 bug。实现直接复用 v0.13 的
    # write_preloaded_data 逻辑。
    import inspect
    import logging
    import os
    from pathlib import Path
    import megatron.core
    import torch
    from megatron.core.dist_checkpointing.strategies.async_utils import _disable_gc
    from megatron.core.dist_checkpointing.strategies.filesystem_async import _process_memory
    from packaging import version
    from torch import multiprocessing as mp
    from torch.distributed.checkpoint.filesystem import _write_item

    # 只有 megatron 0.12.1 且 torch 为 2.8.0 或 2.9.0 时才需要该补丁
    # （torch 2.9.0 复现了相同的 bug）
    if (
        version.parse(torch.__version__).base_version not in ("2.8.0", "2.9.0")
        or version.parse(megatron.core.__version__).base_version != "0.12.1"
    ):
        return

    WriteBucket = tuple[Path, str, tuple[list, list]]

    @staticmethod
    @_disable_gc()
    def write_preloaded_data_patch(
        transform_list,
        local_proc_idx: int,
        write_bucket: WriteBucket,
        results_queue: mp.SimpleQueue,
        count_queue: mp.JoinableQueue,
        use_fsync: bool,
        **kwargs,
    ) -> None:
        # 补丁内部实现（省略，与原函数相同）...
        pass

```

# 评论区精华

无人工 review 讨论。机器人 gemini-code-assist[bot] 确认变更仅涉及函数重命名和版本检查逻辑扩展，无其他问题。PR 被 wuxibin89 直接批准。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险极低。
- 仅修改了版本检查条件，patch 内部逻辑不变。
- 回溯兼容：除 torch 2.8.0 外，torch 2.9.0 触发相同 bug，扩展条件无副作用。
- 未覆盖 torch 2.10.0+ 或其他版本，但这些版本可能已由 Megatron-core 上游修复，无需 patch。
- 无测试配套，但 CI 中 NPU 相关流水线会验证该路径。
- 影响：影响范围有限。
- 仅影响使用 Megatron-core 0.12.1 且 PyTorch 版本为 2.9.0 的 NPU 训练场景（vLLM 0.18 配套）。
- 修复后这些场景的 checkpoint 异步写入不再因 serialization_format 缺失而失败。
- 对其他框架（FSDP、TRT-LLM）或非 NPU 环境无影响。
- 风险标记：缺少测试覆盖

# 关联脉络

- 暂无明显关联 PR