# PR #7185 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc, model] fix: refresh FSDP and SkyPilot guides
- 合并时间：2026-07-29 14:12
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/7185

---

# 执行摘要

- 一句话：刷新 FSDP 和 SkyPilot 文档，删除过时多轮示例
- 推荐动作：推荐阅读以了解当前 FSDP 模型集成路径和 SkyPilot 使用入口。特别是模型集成权限的明确划分值得注意。

# 功能与动机

根据 PR body，本 PR 旨在刷新两处过时的文档区域，使其与当前 main 分支保持一致。旧的 FSDP 文档提到了已废弃的 `dtensor_weight_loader` 方案，新的文档需要反映当前 Hugging Face 模型加载方式；SkyPilot 示例的命令和链接已过时，且多轮工具 YAML 引用了已删除的文件。

# 实现拆解

1. **重写 `docs/advance/fsdp_extension.rst`**：移除旧的 dtensor weight loader 教程，替换为面向当前 FSDP/FSDP2 引擎的模型加载、权重同步、扩展和验证路径。
2. **更新 `verl/models/README.md`**：用简洁的模型集成所有权说明替换了冗长的添加 Hugging Face 模型步骤，明确 `transformers/` 和 `mcore/` 职责。
3. **修复 SkyPilot 文档**：修改 `examples/tutorial/skypilot/README.md`、`docs/examples/skypilot_examples.rst` 和 `docs/start/multinode.rst` 中的命令路径和导航链接，移除多轮 YAML 引用。
4. **删除无效示例**：删除 `examples/tutorial/skypilot/verl-multiturn-tools.yaml`，因其引用了已删除的配置目录。
5. **导航同步**：更新 `examples/tutorial/README.md` 中的链接。

关键文件：
- `docs/advance/fsdp_extension.rst`（模块 进阶文档；类别 docs；类型 documentation）: 核心文档重写，替换旧的 dtensor 指南，反映当前 FSDP/FSDP2 模型加载和权重同步流程。
- `verl/models/README.md`（模块 模型说明；类别 docs；类型 documentation）: 更新模型集成所有权说明，明确 transformers/ 和 mcore/ 职责，引导用户使用 FSDP 指南。
- `examples/tutorial/skypilot/verl-multiturn-tools.yaml`（模块 示例配置；类别 config；类型 deletion）: 删除不再维护的多轮工具 SkyPilot 示例配置，避免用户使用不可运行文件。
- `examples/tutorial/skypilot/README.md`（模块 示例教程；类别 docs；类型 documentation）: 修复命令路径和链接，删除多轮 YAML 引用，引导用户使用 Agent Loop 教程。
- `docs/examples/skypilot_examples.rst`（模块 示例文档；类别 docs；类型 documentation）: 同步更新 SkyPilot 示例文档，反映命令路径和多轮示例移除。
- `docs/start/multinode.rst`（模块 入门文档；类别 docs；类型 documentation）: 更新 SkyPilot 配置列表，移除对多轮 YAML 的引用。
- `examples/tutorial/README.md`（模块 示例教程；类别 docs；类型 documentation）: 自动导航链接修复（更新指向 skypilot 目录的相对链接）。

关键符号：未识别


# 评论区精华

无实质性讨论。仅 Gemini Code Assist bot 发送自动停用通知。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险极低。变更仅限于文档和示例配置文件，不涉及任何运行时 API 或配置逻辑。唯一的风险是用户可能未注意到文档更新而继续使用旧命令，但新旧示例命令路径不同会自然报错，且 PR 通过删除和重定向来最小化混淆。
- 影响：对用户：FSDP 扩展指南的读者将获得准确的当前实践；SkyPilot 用户可成功运行示例；原多轮工具用户被引导至 Agent Loop 教程。对系统：无影响。
- 风险标记：文档与示例清理 , 无运行时变更

# 关联脉络

- PR #7161 [fsdp] refactor: move unfuse_moe_params to FSDP backend: 该 PR 重构了 FSDP 后端的参数解融合逻辑，当前文档 PR 的 FSDP 扩展指南更新即反映此类后端变更。
- PR #7144 [ckpt, fsdp] feat: sharded delta block placements + backend-owned HF export (engine core + FSDP): 该 PR 扩展了 FSDP 的分片 delta 同步功能，本 PR 中 FSDP 文档更新同步了相关同步边界说明。