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 向规划器请求可用种子，它适用于实例动态创建和回收的集群。
• Topology-sensitive deployments: RFork encodes kv_role, node_rank, optional pp_rank, tp_rank, optional ep_rank, and optional draft role into the seed key, so only topology-compatible instances are matched together.

---

使用方法

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

RFork 前提条件

• 在每个 RFork 实例上安装运行时依赖 YuanRong TransferEngine。
• Run a planner service that implements the RFork seed protocol. A simple mock planner script is provided at 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
• pp_rank when pipeline parallel size is greater than 1
• tp_rank
• ep_rank when expert parallelism is enabled for an MoE model
• 当工作进程作为草稿模型运行时，可选的 draft 后缀

这意味着两个实例必须在模型标识和部署拓扑上都达成一致，规划器才会将它们视为可互换的种子。 For deployments without pipeline or expert parallelism, the existing seed-key format is unchanged.

量化模型

对于量化模型，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.启动规划器

A simple planner implementation is provided at 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 weight transfer does not support dynamic EPLB because expert weights and placement can change after the seed service starts. If eplb_config.dynamic_eplb or eplb_config.expert_map_record_path enables dynamic EPLB, RFork transfer is bypassed and the model is loaded through the default model loader.
• The example rfork_planner.py is only a simple mock implementation. If you need stronger scheduling, capacity management, or production-grade availability behavior, implement your own planner based on the RFork seed protocol.