RFork 指南¶

本指南说明如何在 vLLM Ascend 中将 RFork 用作模型加载器插件。

概述¶

RFork 是 vLLM Ascend 的预热启动权重加载路径。它不会总是从存储中读取模型权重，而是允许新实例向外部规划器请求一个兼容的 seed 实例，然后通过 YuanRong TransferEngine 直接从该 seed 拉取权重。

当前实现中，RFork 的加载流程如下：

1. vLLM 使用 --load-format rfork 启动。
2. RFork 根据模型标识和部署拓扑构建 seed key。
3. RFork 向规划器请求与该 key 匹配的可用 seed。
4. 如果返回了 seed，新实例会在本地 NPU 上初始化模型结构，注册本地权重内存，从 seed 获取远程传输引擎元数据，并将权重批量传输到本地参数缓冲区。
5. 如果没有可用 seed，或任何步骤失败，RFork 会清理并回退到默认加载器。
6. 实例完成加载后，会启动本地 seed 服务，并定期向规划器上报心跳，以便后续实例可以复用它。

流程图¶

应用场景¶

• 首次成功加载后扩容：第一个实例可能仍然从存储加载，但具有相同部署标识的后续实例可以将其作为 seed 复用，从而缩短启动时间。
• 弹性服务集群：由于 RFork 会向规划器请求可用 seed，因此适用于实例动态创建和回收的集群。
• 拓扑敏感型部署：RFork 会将 kv_role、node_rank、可选的 pp_rank、tp_rank、可选的 ep_rank 以及可选的 draft 角色编码到 seed key 中，因此只会匹配拓扑兼容的实例。

使用方法¶

要启用 RFork，请传入 --load-format rfork，并通过 --model-loader-extra-config 以 JSON 字符串形式提供 RFork 配置。

RFork 前置条件¶

• 在每个 RFork 实例上安装运行时依赖 YuanRong TransferEngine。
• 运行一个实现 RFork seed 协议的规划器服务。rfork_planner.py 提供了一个简单的 mock 规划器脚本。

配置字段¶

RFork 如何匹配 Seed¶

RFork 不会仅根据 model_url 匹配实例。本地 seed key 由以下部分组成：

• model_url
• model_deploy_strategy_name
• 从 kv_transfer_config.kv_role 或 kv_both 推导出的分离模式
• node_rank
• 当流水线并行大小大于 1 时的 pp_rank
• tp_rank
• 当 MoE 模型启用专家并行时的 ep_rank
• 当 worker 作为 draft 模型运行时的可选 draft 后缀

这意味着两个实例必须在模型标识和部署拓扑上都一致，规划器才会将它们视为可互换的 seed。 对于没有流水线并行或专家并行的部署，现有 seed-key 格式保持不变。

量化模型¶

对于量化模型，RFork 传输的是 Ascend 权重后处理之后的张量，而不是原始 checkpoint 参数。接收端首先构建与 seed 相同的加载后张量布局，然后 RFork 复制推理使用的实时 NPU 张量。

该路径处理 Ascend 量化变更，例如权重转置、NZ 格式转换、打包权重、派生 scale 张量，以及 W_UV 和 W_UK_T 等 MLA/SFA 运行时张量。在后处理期间释放的空张量不会包含在传输清单中。

在验证量化模型的 RFork 时：

• 对 seed 实例和接收端实例应用相同的 vLLM Ascend 代码。
• 更改 RFork 代码后，重启规划器和所有 vLLM 实例，因为现有 seed 会保留旧的传输元数据。
• 更改模型参数或 RFork 代码后，使用新的 model_deploy_strategy_name，以免规划器将接收端与不兼容的旧 seed 匹配。
• 成功的 RFork 传输会记录 transfer weights starts 和 transfer weights time。回退路径会记录 RFork transfer failed。

已测试模型¶

下表记录了已明确使用 RFork 权重传输测试过的模型。只有当 RFork 传输成功且加载后的实例通过基本推理验证后，才应将模型添加到此处。

示例命令与占位符¶

运行前，请替换 <...> 中的部分。

1. 安装 YuanRong TransferEngine¶

pip install openyuanrong-transfer-engine

2. 启动规划器¶

在 rfork_planner.py 中提供了一个简单的规划器实现。

python rfork_planner.py \
  --host 0.0.0.0 \
  --port <planner_port>

3. 启动 vLLM 实例¶

在同一部署中，第一个实例和后续实例都应使用相同的 RFork 启动命令。

对于第一个实例，规划器通常还没有兼容的种子，因此 RFork 会回退到默认加载器。加载完成后，该实例会启动本地种子服务，并向规划器报告自身。

对于后续实例，如果规划器能够分配一个兼容的种子，RFork 会先尝试从现有种子实例传输权重，然后再回退到默认加载器。

export RFORK_CONFIG='{
  "model_url": "<model_url>",
  "model_deploy_strategy_name": "<deploy_strategy>",
  "rfork_scheduler_url": "http://<planner_ip>:<planner_port>"
}'

vllm serve <model_path> \
  --tensor-parallel-size 1 \
  --served-model-name <served_model_name> \
  --port <port> \
  --load-format rfork \
  --model-loader-extra-config "${RFORK_CONFIG}"

占位符说明¶

• <model_path>：传递给 vllm serve 的模型路径或模型标识符。
• <served_model_name>：vLLM 暴露的服务名称。
• <planner_ip>：RFork 规划器的 IP 地址或主机名。
• <planner_port>：RFork 规划器的监听端口。
• <model_url>：用于构建 RFork 种子键的稳定模型标识字符串。
• <deploy_strategy>：用于构建 RFork 种子键的稳定部署策略名称。
• <port>：正在启动的 vLLM 实例的服务端口。

注意事项与说明¶

• RFork 在运行时依赖 YuanRong TransferEngine。如果缺少该包，RFork 将无法初始化传输后端。
• 如果使用 RFORK，每个工作进程都必须绑定一个监听端口。该端口会随机分配。
• RFork 权重传输不支持动态 EPLB，因为在种子服务启动后，专家权重和放置可能会发生变化。如果 eplb_config.dynamic_eplb 或 eplb_config.expert_map_record_path 启用了动态 EPLB，则 RFork 传输会被绕过，模型将通过默认模型加载器加载。
• 示例 rfork_planner.py 只是一个简单的模拟实现。如果你需要更强的调度、容量管理或生产级可用性行为，请基于 RFork 种子协议实现自己的规划器。