# PR #5724 完整报告

- 仓库：`verl-project/verl`
- 标题：[docker, ci] fix: all CIs, transformers upgrade to 5.3.0 and vllm==0.18.0
- 合并时间：2026-04-03 13:44
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/5724

---

# 执行摘要
本 PR 系统性修复了因 transformers 升级至 5.3.0 和 vLLM 升级至 0.18.0 引发的 CI 流水线错误，通过更新 Docker 镜像、调整模型兼容性代码和优化权重同步逻辑，确保了测试环境的稳定性和跨后端兼容性。

# 功能与动机
此次变更主要为了应对 transformers 5.0 版本后的 API 变更，特别是 RoPE 参数结构改动和 MoE 权重格式调整，这些变更导致多个 CI 作业（如 `e2e_fully_async_policy_megatron`）失败。PR body 中明确指出目标是“修复所有 CIs”，并解决由历史 PR 引入的依赖循环问题。

# 实现拆解
1. **CI 配置模块**：更新了 10 个 `.github/workflows/*.yml` 文件，统一将 Docker 镜像标签从 `vllm017.dev2` 升级为 `vllm018.dev1`，移除对 transformers 版本的硬性限制（如 `transformers<5.0.0`），并添加缺失依赖（如 mbridge）。
2. **Docker 构建模块**：修改 `docker/Dockerfile.stable.vllm`，基础镜像升级至 Ubuntu 24.04，优化 pip 安装参数以提升构建效率。
3. **模型处理模块**：
 - 将 `get_hf_rope_theta` 函数从 `verl/models/mcore/config_converter.py` 移至 `verl/utils/megatron_utils.py`，解决循环依赖。
 - 在 `verl/models/transformers/` 下的 GLM4V、Qwen2_VL 等文件中，添加对 `rope_parameters` 字段的兼容性处理。
 - 新增 `unpack_visual_output` 函数（`verl/utils/transformers_compat.py`），处理 transformers>=5.0.0 中视觉编码器输出格式变化。
4. **权重同步模块**：重构 `verl/workers/engine_workers.py` 中的 `update_weights` 方法，确保 LoRA 场景下先发送基础权重再发送适配器权重，并更新对应测试文件。

# 评论区精华
Review 讨论聚焦于权重同步逻辑的正确性：
- **HollowMan6**提出：“If the base_sync_done is always set to True... we will always export lora weights instead of base weights”。
- **cavities12**确认：“This should stay as `self.base_sync_done` and not hardcoded True”。
最终通过重构解决，**HollowMan6**总结：“I did the refactor... now we still hardcode `base_sync_done=True` for the initial call”，确保逻辑正确性。

# 风险与影响
- **技术风险**：transformers 和 vLLM 版本升级可能引入未测试的回归 bug，尤其在 MoE 模型（如 Qwen3.5-MoE）中，权重格式变更可能导致加载失败；Docker 镜像更新可能影响构建稳定性。
- **影响评估**：短期可能增加 CI 运行时间，但长期提升测试可靠性；模型兼容性增强支持新 transformers 特性，但对现有代码有轻微侵入性改动。

# 关联脉络
本 PR 是近期 CI 和依赖维护趋势的一部分：历史 PR 如 5874（新增 Megatron 脚本）和 5861（量化文档）显示团队在扩展功能同时注重基础设施稳定。关联 PR 5717 引入了 megatron 依赖循环，本 PR 直接响应修复；PR 5769 涉及类似权重同步问题，表明该领域是持续优化重点。整体上，此次变更反映了系统化应对重大依赖升级的工程实践。