# PR #2021 完整报告

- 仓库：`THUDM/slime`
- 标题：Support update_from_disk
- 合并时间：2026-06-05 11:55
- 原文链接：http://prhub.com.cn/THUDM/slime/pull/2021

---

# 执行摘要

- 一句话：支持完整权重磁盘同步模式
- 推荐动作：值得精读，尤其关注 `UpdateWeightFromDisk` 的同步流程和参数兼容性设计。配套测试可作为集成测试参考。

# 功能与动机

提供一种无需 NCCL 广播的权重同步方式，适用于共享文件系统环境，降低网络开销并提高可靠性。PR 标题明确支持通过磁盘更新权重。

# 实现拆解

1. 新增 `UpdateWeightFromDisk` 类（`slime/backends/megatron_utils/update_weight/update_weight_from_disk.py`），实现 `connect_rollout_engines`、`disconnect_rollout_engines`、`pop_metrics` 和 `update_weights` 方法。`update_weights` 在 rank 0 暂停引擎、刷新缓存，然后调用 `save_hf_model_to_path` 将模型保存到版本化目录，最后通知引擎从磁盘加载。

2. 重构 `hf_checkpoint_saver.py`：将原 `save_hf_model_direct` 函数拆分为通用函数 `save_hf_model_to_path` 和 `save_hf_model_direct_to_path`，前者根据 `megatron_to_hf_mode` 选择桥接或直接转换，后者实现具体保存逻辑，支持任意输出路径和自定义进度描述。

3. 参数扩展：在 `arguments.py` 中新增 `--update-weight-disk-dir` 和 `--update-weight-disk-keep-files`，将 `--update-weight-delta-dir` 标记为废弃别名，并通过 `_resolve_update_weight_disk_dir` 函数统一处理冲突和回填。

4. 删除旧 `save_hf_model` 函数（`model.py`），将入口统一到新的 `save_hf_model_to_path`。

5. 测试配套：`test_megatron_argument_validation.py` 新增参数验证测试，`test_full_disk_weight_update.py` 新增端到端 CI 测试，验证完整磁盘同步流程。`test_hf_checkpoint_saver.py` 增加对输出路径冲突的测试。

关键文件：
- `slime/backends/megatron_utils/update_weight/update_weight_from_disk.py`（模块 权重同步；类别 source；类型 core-logic；符号 UpdateWeightFromDisk, __init__, connect_rollout_engines, disconnect_rollout_engines）: 新增磁盘权重同步核心类
- `slime/backends/megatron_utils/hf_checkpoint_saver.py`（模块 HF 检查点保存；类别 source；类型 dependency-wiring；符号 save_hf_model_direct, save_hf_model_to_path, save_hf_model_direct_to_path, save_hf_model_bridge_to_path）: 重构 HF 检查点保存函数以支持任意输出路径
- `slime/utils/arguments.py`（模块 参数解析；类别 source；类型 dependency-wiring；符号 _resolve_update_weight_disk_dir, _validate_update_weight_args）: 新增 --update-weight-disk-dir 参数并废弃 --update-weight-delta-dir
- `slime/backends/megatron_utils/model.py`（模块 模型管理层；类别 source；类型 data-contract；符号 save_hf_model）: 删除旧的 save_hf_model 函数，统一入口到 hf_checkpoint_saver
- `tests/test_megatron_argument_validation.py`（模块 参数验证测试；类别 test；类型 test-coverage；符号 load_slime_arguments_module, test_update_weight_disk_dir_required_for_disk_transport, test_update_weight_disk_dir_normalizes_delta_alias, test_update_weight_disk_dir_backfills_legacy_delta_field）: 新增参数验证测试覆盖磁盘同步参数组合
- `tests/test_full_disk_weight_update.py`（模块 磁盘同步测试；类别 test；类型 test-coverage；符号 prepare, execute）: 端到端 CI 测试验证完整磁盘权重更新流程

关键符号：UpdateWeightFromDisk, save_hf_model_to_path, save_hf_model_direct_to_path, _resolve_update_weight_disk_dir


# 评论区精华

该 PR 无 review 评论，可能由作者直接合并。关键设计决策（如磁盘同步与 NCCL 的对比、废弃参数兼容）已在代码注释中体现。

- 暂无高价值评论线程

# 风险与影响

- 风险：新增磁盘 I/O 路径可能成为性能瓶颈，尤其在高频同步时；共享文件系统的延迟和容错性影响可靠性；废弃参数 `--update-weight-delta-dir` 可能导致用户困惑，但通过警告和回填缓解；需要确保引擎有权读写磁盘目录。
- 影响：用户获得替代 NCCL 的同步选项，适合文件系统环境；系统增加磁盘写入和读取负载；团队需维护两套传输模式；测试覆盖了主要路径，但边缘情况（权限、磁盘满）未覆盖。
- 风险标记：共享文件系统依赖 , 废弃参数兼容 , 磁盘 I/O 性能

# 关联脉络

- PR #1993 Patch sglang 0.5.12.post1 for delta sync: 本 PR 扩展了 delta 同步基础设施，引入磁盘传输模式
- PR #2020 Accelerate raw HF save with node writers: 优化了 HF 保存性能，本 PR 的磁盘同步流程依赖保存操作
- PR #1991 [ci] Add e2e test for delta weight update: 类似的端到端测试结构，本 PR 参考其设计与断言方式