# PR #6955 完整报告

- 仓库：`verl-project/verl`
- 标题：[env] chore: Adapt qwen3.5 to Docker containers for Verl release 0.8.0
- 合并时间：2026-07-08 14:52
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6955

---

# 执行摘要

- 一句话：适配 Qwen3.5 到 Verl 0.8.0 Docker 容器
- 推荐动作：PR 符合发布准备目标，变更内容合理。但建议考虑优化 Git 克隆策略以加速 Docker 构建（如使用 `git init && git fetch --depth 1 <remote> <commit>` 替代 `git clone && git fetch`），并在未来避免类似低效操作。

# 功能与动机

根据 PR 描述，需要在 Verl 0.8.0 版本中适配 Qwen3.5 到 Docker 容器。Review 讨论指出，Qwen3.5 需要基于 transformers 5.3.0 的 bugfix commit 才能正确训练。

# 实现拆解

1. **Dockerfile 更新 **（docker/ascend/Dockerfile.ascend_9.0.0_a2_v0.8.0 和 a3）：添加 Megatron-Bridge 和 transformers 的源码克隆至特定 commit；安装 torchvision（x86_64）；安装额外依赖：nvidia-modelopt、flash-linear-attention、qwen_vl_utils、viztracer、mathruler；设置 PYTHONPATH 包含 Megatron-Bridge/src。
2. **文档更新 **（docs/ascend_tutorial/model_support/examples/qwen3_5_megatron_npu.md）：更新版本表，镜像标签改为专用 v0.8.0 版本；移除手动 git checkout 步骤，简化使用说明。
3. **代码格式化 **（verl/checkpoint_engine/mooncake_checkpoint_engine.py）：将 transfer_sync_read 和 transfer_sync_write 调用的参数按多行排列，以符合代码风格规范，无功能变化。

关键文件：
- `verl/checkpoint_engine/mooncake_checkpoint_engine.py`（模块 检查点引擎；类别 source；类型 refactor；符号 receive_weights）: 虽然仅包含代码格式化，但改动了核心 RDMA 权重接收函数的调用格式，影响代码可读性。
- `docker/ascend/Dockerfile.ascend_9.0.0_a2_v0.8.0`（模块 Docker 镜像；类别 infra；类型 infrastructure）: 核心变更文件，定义新镜像的构建步骤，包括新增 Megatron-Bridge 和 transformers 等依赖。
- `docker/ascend/Dockerfile.ascend_9.0.0_a3_v0.8.0`（模块 Docker 镜像；类别 infra；类型 infrastructure）: 与 a2 版本几乎相同的配置变更，用于不同 Ascend 基础镜像。
- `docs/ascend_tutorial/model_support/examples/qwen3_5_megatron_npu.md`（模块 文档；类别 docs；类型 documentation）: 更新版本号和镜像标签，简化用户操作步骤。

关键符号：receive_weights

## 关键源码片段

### `docker/ascend/Dockerfile.ascend_9.0.0_a2_v0.8.0`

核心变更文件，定义新镜像的构建步骤，包括新增 Megatron-Bridge 和 transformers 等依赖。

```dockerfile
# 在一个 RUN 命令中串联所有源码克隆与安装步骤
RUN ARCH=$(uname -m) && \
    # ... 原有 vllm-ascend, MindSpeed, Megatron-LM 克隆 ... && \
    # 新增：克隆 Megatron-Bridge 并切换到特定 commit
    git clone --depth 1 https://github.com/NVIDIA-NeMo/Megatron-Bridge.git && \
    cd Megatron-Bridge && \
    git fetch --depth 1 origin de93536e9028ecf1e4dc28608dc80f336dcdfe59 && \
    git checkout de93536e9028ecf1e4dc28608dc80f336dcdfe59 && cd .. && \
    # 新增：克隆 transformers 并切换到 bugfix commit（基于 5.3.0）
    git clone --depth 1 https://github.com/huggingface/transformers.git && \
    cd transformers && \
    git fetch --depth 1 origin cc7ab9be508ce6ed3637bba9e50367b29b742dc6 && \
    git checkout cc7ab9be508ce6ed3637bba9e50367b29b742dc6 && cd ..
# 安装 torchvision（仅 x86_64）
RUN if [ '$ARCH' = 'x86_64' ]; then \
        pip install torchvision==0.24.0+cpu --index-url https://download.pytorch.org/whl/cpu/; \
    fi
# 安装 Qwen3.5 必需的额外依赖
RUN pip install 'nvidia-modelopt[torch]>=0.37.0' flash-linear-attention==0.5.0 qwen_vl_utils viztracer mathruler
# 将 Megatron-Bridge 源码加入 PYTHONPATH
ENV PYTHONPATH=/Megatron-Bridge/src:$PYTHONPATH

```
（注：实际 Dockerfile 中部分命令合并在多行 RUN 中，此处为清晰展示新增加的内容。）

# 评论区精华

**自动化代码审查建议**：针对 git 克隆 transformers 的方式，建议使用更高效的策略（先创建空仓库再 fetch 指定 commit），以减少构建时间和网络开销。开发者未采纳该建议。
**人工审查**：zjchenn 询问为何 transformers 使用特定 commit，ruanhao566 回应称该 commit 是基于 transformers 5.3.0 的 bugfix，已验证 FSDP 和 Megatron 后端均可正常训练。

- Git 克隆 transformers 的效率问题 (performance): 开发者未采纳建议，PR 保持当前实现。
- transformers 使用特定 commit 的原因 (question): 问题得到明确解答。

# 风险与影响

- 风险：**Docker 构建风险**：外部仓库（Megatron-Bridge、transformers）可能因网络或仓库变更导致构建失败，但已锁定 commit，风险可控。**兼容性风险**：新镜像仅支持特定软件版本，若用户使用旧镜像可能无法运行 Qwen3.5。**无功能风险**：checkpoint 引擎代码仅格式化，不影响逻辑。
- 影响：**用户影响**：使用 Ascend 的用户需要拉取新镜像才能训练 Qwen3.5 模型。**系统影响**：Docker 镜像体积因新增依赖而有所增加。**团队影响**：为 Verl 0.8.0 发布做准备，属于标准发布流程的一部分。
- 风险标记：外部依赖变更 , 构建失败风险 , Docker 镜像体积增长

# 关联脉络

- PR #6813 [ckpt] fix: use separate magic_recv buffer to prevent weight corruption: 同一文件 mooncake_checkpoint_engine.py，但本 PR 仅格式化，无功能交互。