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 种子协议的调度器服务。一个简单的模拟调度器脚本位于 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 如何匹配种子

RFork 不仅仅通过 model_url 匹配实例。本地种子键由以下部分组成：

• model_url

• model_deploy_strategy_name

• 从 kv_transfer_config.kv_role 或 kv_both 派生的解聚模式

• node_rank

• 当流水线并行大小大于 1 时的 pp_rank

• tp_rank

• 当 MoE 模型启用专家并行时的 ep_rank

• 当工作器作为草稿模型运行时的可选 draft 后缀

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

量化模型

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

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

验证量化模型的 RFork 时：

• 对种子实例和接收方实例应用相同的 vLLM Ascend 代码。

• 更改 RFork 代码后，请重启调度器和所有 vLLM 实例，因为现有种子会保留其旧的传输元数据。

• 在更改模型参数或RFork代码后，请使用新的model_deploy_strategy_name，以避免规划器将接收者与不兼容的旧种子匹配。

• 成功的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启动命令。

对于第一个实例，规划器通常尚无兼容的种子，因此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权重传输不支持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种子协议实现您自己的规划器。