RFork 指南

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

---

概述

RFork 是 vLLM Ascend 的一种热启动权重加载路径。新实例无需始终从存储中读取模型权重，而是可以向外部调度器请求一个兼容的 种子 实例，然后通过 YuanRong TransferEngine 直接从该种子实例拉取权重。

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

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

流程图

应用场景

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

---

使用方法

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

RFork 前提条件

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

配置字段

字段名	类型	描述	允许值 / 备注
model_url	字符串	用于构建 RFork 种子键的逻辑模型标识符。	RFork 传输必需。需要共享种子的实例必须使用相同的值。
model_deploy_strategy_name	字符串	与 model_url 一起用于构建种子键的部署策略标识符。	RFork 传输必需。需要共享种子的实例必须使用相同的值。
rfork_scheduler_url	字符串	用于种子分配、释放和心跳的规划器服务的基础 URL。	基于规划器的匹配必需。示例：http://127.0.0.1:1223。
rfork_seed_timeout_sec	数字	等待本地种子 HTTP 服务在启动后变为健康状态的超时时间。	可选。默认值：5.0。必须大于 0。无效值将回退为默认值。
rfork_seed_key_separator	字符串	构建 RFork 种子键字符串时使用的分隔符。	可选。默认值：$。在兼容的实例之间保持相同的值。

RFork 如何匹配 Seeds

RFork 不单独通过 model_url 匹配实例。本地 seed 键由以下部分组成：

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

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

量化模型

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

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

验证量化模型的 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 传输成功且加载的实例通过基本推理验证后，才应将模型添加到此表中。

模型	精度 / 量化	硬件	验证状态	备注
Qwen2.5-7B	BF16	A2	已测试	RFork 传输已验证通过。
Qwen3-32B	BF16	A2	已测试	RFork 传输已验证通过。
Qwen3-235B-A22B	BF16	A2	已测试	RFork 传输已验证通过。
DeepSeek-V4-Flash-W8A8-MTP	W8A8	A2	已测试	带 MTP 草稿模型的 RFork 传输已验证通过。
GLM5-W4A8	W4A8	A2	已测试	RFork 传输已验证通过。
Kimi2.5-W4A8	W4A8	A2	已测试	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 启动命令。

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

对于后续实例，如果规划器可以分配一个兼容的 seed，RFork 将尝试从现有 seed 实例传输权重，然后再回退到默认加载器。

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 权重传输不支持 additional_config.layer_sharding。如果 --load-format rfork 与 layer_sharding 一起使用，RFork 传输将被绕过，模型将通过默认模型加载器加载。
• RFork 权重传输不支持动态 EPLB，因为专家权重和放置位置可能在种子服务启动后发生变化。如果 eplb_config.dynamic_eplb 或 eplb_config.expert_map_record_path 启用了动态 EPLB，RFork 传输将被绕过，模型将通过默认模型加载器加载。
• 示例 rfork_planner.py 仅是一个简单的模拟实现。如果您需要更强的调度、容量管理或生产级可用性行为，请基于 RFork 种子协议实现您自己的规划器。