# PR #1838 完整报告

- 仓库：`radixark/miles`
- 标题：remove duplicated field in actor group, unify dashboard hook guard, and change init order
- 合并时间：2026-09-04 12:04
- 原文链接：http://prhub.com.cn/radixark/miles/pull/1838

---

# 执行摘要

- 一句话：清理 RDT 权重同步代码并统一 Dashboard 钩子守卫，为 Rollout 模块拆分做准备。
- 推荐动作：本 PR 作为重构链的关键清理步骤，**值得相关开发者精读**。重点关注以下设计决策：
 1) 如何安全地废弃并移除一个已部署的复杂功能（RDT）；
 2) 在重构前，如何通过“拆除脚手架”来简化代码结构（移除 actor_factory、server_group 中的 RDT 专用逻辑）；
 3) 如何统一并优化旁路逻辑（Dashboard 钩子守卫）。其变更模式（大范围删除、参数清理、测试配套）是大型重构初期阶段的典型示例。

# 功能与动机

此 PR 是 Issue #1837 “Tracking issue for refactoring and enhancements” 跟踪问题的一部分。根据提交信息，其核心动机是“临时重置 PR #1313，以允许重构链在不携带服务器组 /actor_factory 管道的情况下进行变基”，并“为 Rollout 拆分准备三个独立的修复”。具体而言，RDT 权重同步功能（在 #1313 中引入）因其架构（如需要 `use_ray=True`、独占 GPU 捆绑包）与新的 Rollout 模块拆分方向不兼容，需要被移除并计划在重构后重新引入。

# 实现拆解

1. **删除 RDT 协议实现**：完全移除了 `miles/backends/training_utils/weight_update/protocols/rdt.py` 文件。该文件实现了基于 NIXL/RDMA 的 P2P 权重传输协议 `UpdateWeightFromRDT`，包括 GPU 桶管理、引擎调度器 Actor 获取和连接逻辑。此删除是本次重构的核心，标志着 RDT 功能的暂时移除。
2. **删除 SGLang 服务器 Actor**：移除了 `miles/ray/rollout/sglang_server_actor.py`。该 Actor 用于在 RDT 模式下托管 SGLang HTTP 服务器和调度器。其功能被 `sglang_engine.py` 中的直接进程启动所取代。
3. **简化引擎启动与放置组逻辑**：在 `miles/backends/sglang_utils/sglang_engine.py` 中，移除了 `_launch_sglang_server` 函数及 `SGLangEngine` 类中与 RDT 相关的 `pg_bundles`、`_scheduler_actors` 等字段和逻辑，将 `_init_normal` 方法恢复为仅使用 `launch_server_process` 的标准路径。在 `miles/ray/placement_group.py` 中，移除了为 RDT 设计的特殊放置组排序逻辑（`is_rdt` 参数），并将 `allocate_train_group` 中的 `num_gpus_per_actor` 固定回 0.4。
4. **清理参数与验证**：在 `miles/utils/arguments.py` 中，从 `--update-weight-transfer-mode` 的可选值中移除了 `"rdt"`，并删除了与之相关的验证断言（如必须为 Megatron 后端、不兼容 PPO）。相应地，更新了 `tests/fast/utils/test_arguments.py`，移除了 `TestRdtValidation` 测试类。
5. **统一 Dashboard 钩子守卫与调整初始化**：修改了 `miles/dashboard/hooks.py` 中的 `register_router` 函数，使其在仪表盘未启用时（`use_miles_dashboard=False`）提前返回，避免不必要的收集器解析。同时，更新了相关测试 `tests/fast/dashboard/test_hooks.py` 以覆盖此新行为。

关键文件：
- `miles/backends/training_utils/weight_update/protocols/rdt.py`（模块 权重同步协议；类别 source；类型 deletion；符号 _staging_span, _EngineRankBucket, __init__, stage）: 被完全删除的 RDT 权重传输协议核心实现文件，包含 `UpdateWeightFromRDT` 类和 GPU 桶管理逻辑。
- `miles/ray/rollout/sglang_server_actor.py`（模块 服务器进程管理；类别 source；类型 deletion；符号 SGLangServerActor, __init__, start, is_alive）: 被完全删除的文件，包含了用于 RDT 模式托管 SGLang HTTP 服务器的 `SGLangServerActor` 类。
- `miles/backends/sglang_utils/sglang_engine.py`（模块 引擎启动逻辑；类别 source；类型 core-logic；符号 _launch_sglang_server, get_scheduler_actors）: 包含 `SGLangEngine` 类，移除了大量 RDT 相关的初始化、启动和关闭逻辑，是引擎启动路径重构的关键文件。

关键符号：UpdateWeightFromRDT.__init__, UpdateWeightFromRDT.connect, UpdateWeightFromRDT.create_gpu_replica, _launch_sglang_server, SGLangServerActor.start, SGLangEngine.get_scheduler_actors, _create_placement_group, miles_validate_args

## 关键源码片段

### `miles/backends/sglang_utils/sglang_engine.py`

包含 `SGLangEngine` 类，移除了大量 RDT 相关的初始化、启动和关闭逻辑，是引擎启动路径重构的关键文件。

```python
# miles/backends/sglang_utils/sglang_engine.py
# 关键变更：_init_normal 方法移除 RDT 分支，简化为标准路径

def _init_normal(self, server_args_dict):
    """
    初始化标准 SGLang 引擎进程。
    
    移除了 RDT (ray direct transport) 模式下的
    'use_ray=True'、'enable_rdt_weight_sync=True' 设置、
    SGLangServerActor 创建和调度器 Actor 管理逻辑。
    现在所有模式都统一通过 launch_server_process 启动进程。
    """
    # 移除了 use_rdt 判断分支和对应的 server_args_dict 修改
    logger.info(f"Launch HttpServerEngineAdapter at: {self.server_host}:{self.server_port}")
    # ServerArgs refuses writes once its declarations materialise, so the ipv6
    # host loses its brackets here rather than at the launch sites. The dict
    # keeps the bracketed form, which self.server_host uses to build urls.
    server_args = ServerArgs(**{**server_args_dict, "host": server_args_dict["host"].strip("[]")})
    # 统一使用 launch_server_process，无论何种权重更新模式
    self.process = launch_server_process(server_args)
    
    if self.node_rank == 0 and self.router_ip and self.router_port:
        # ... 路由器注册逻辑保持不变 ...
        response.raise_for_status()

```

# 评论区精华

Review 讨论较少，主要来自自动化安全扫描。

- **安全警告**：`github-advanced-security[bot]` 在 `miles/utils/external_utils/exec_command.py` 文件中指出了潜在的敏感信息（密码）明文记录风险。但该文件不在本 PR 的核心变更范围内，且该工具在重构系列中已多次提出类似警告，因此此评论与本 PR 的重构目标关联度较低。
- **审批**：`guapisolo` 提供了批准，表明代码变更符合团队共识。
- **结论**：本 PR 作为清理性重构，主要目的是移除特定功能（RDT），其决策已在 Issue #1837 的跟踪链中得到确认，因此 review 阶段未产生技术争议。

 - 暂无高价值评论线程

# 风险与影响

- 风险：
 1. **功能移除风险**：本 PR 显式移除了 RDT 权重同步功能。任何依赖 `--update-weight-transfer-mode rdt` 的现有工作流、脚本或 CI 测试（如 `test_qwen3_30B_A3B_rdt.py`，该测试已被删除）将不再工作。这是有意为之的破坏性变更，风险在于团队成员可能未完全知晓此变化。
 2. **重构链依赖风险**：此 PR 是更大重构链（#1839-#1845 等）的先行清理步骤。其正确性高度依赖于后续 PR（如 #1842 拆分 RolloutManager）能按计划进行。如果后续重构延迟或方向调整，可能使代码库处于不完整的中间状态。
 3. **回归风险**：变更涉及核心权重同步路径的初始化和验证逻辑。虽然 RDT 路径被移除，但需确保对 `broadcast`、`p2p`、`disk-delta` 等剩余模式的逻辑未产生意外影响。测试文件（如 `test_arguments.py`）的更新缓解了部分风险。
- 影响：
 1. **用户影响**：对于使用 `--update-weight-transfer-mode rdt` 配置的用户或团队，此变更是破坏性的。需要他们停止使用此模式或等待 RDT 在新架构下重新引入。对于使用其他模式的用户无直接影响。
 2. **系统影响**：简化了代码库，减少了配置复杂度和维护负担。移除了 `SGLangServerActor` 这一额外进程，可能略微提升非 RDT 模式下的启动效率和稳定性。
 3. **团队影响**：为团队实现了 Rollout 模块拆分的宏大目标（#1837）扫清了关键障碍，使后续的 `InferenceController` 与 `RolloutExecutor` 拆分（#1842, #1843）得以顺利进行。
 - 风险标记：核心路径变更 , 功能移除 , 依赖后续重构

# 关联脉络

- PR #1837 Tracking issue for refactoring and enhancements: 本 PR 是此跟踪 Issue 中明确列出的子任务之一（标记为 `op:op2-6`），属于整体重构链的一环。
- PR #1839 Clear the new-engine flag from the driver: 紧随本 PR 的后续清理步骤，同样在移除 RDT 相关代码，但侧重于清理标志和驱动程序代码。
- PR #1842 Split RolloutManager into InferenceController and RolloutExecutor: 本 PR 的清理工作为这个更核心的 Rollout 模块拆分 PR 铺平了道路，移除了可能干扰拆分的 RDT 专用逻辑。