Netloader 使用指南#

本指南介绍如何使用 Netloader 作为权重加载插件来加速 vLLM Ascend。


概述#

Netloader 利用 NPU 卡之间的高带宽点对点(P2P)传输来加载模型权重。它作为插件实现(通过 vLLM 0.10 中新增的 register_model_loader API)。工作流程如下:

  1. 服务器预加载模型。

  2. 新的客户端实例请求权重传输。

  3. 在验证模型和分区匹配后,客户端使用 HCCL 集合通信(send/recv)按照模型存储的顺序接收权重。

服务器通过子线程和 vLLM 中的 stateless_init_torch_distributed_process_group 与正常推理任务并行运行。这样客户端无需从存储加载即可接管权重初始化。

流程图#

netloader 流程图

时序图#

netloader 时序图

应用场景#

  • 降低启动延迟:通过复用已加载的权重并在 NPU 卡之间直接传输,Netloader 相比传统的远程/本地拉取策略减少了模型加载时间。

  • 减轻网络与存储负载:避免重复从远程仓库下载权重文件,从而减轻中心存储和网络流量的压力。

  • 提高资源利用率并降低成本:更快的加载减少了对备用计算节点的依赖;资源可以更灵活地扩缩容。

  • 增强业务连续性与高可用性:在故障恢复时,新实例可以快速接管而无需长时间停机,提高了系统可靠性和用户体验。


使用方法#

要启用 Netloader,请传递 --load-format=netloader 并通过 --model-loader-extra-config(JSON 字符串形式)提供配置。以下是支持的配置字段:

字段名

类型

描述

允许值/说明

SOURCE

列表

权重数据源。每个条目是一个包含 device_id 和 sources 的映射,指定 rank 及其端点(IP:port)。
示例:{"SOURCE": [{"device_id": 0, "sources": ["10.170.22.152:19374"]}, {"device_id": 1, "sources": ["10.170.22.152:11228"]}]}
如果省略或为空,则回退到默认加载器。此处的 SOURCE 为第二优先级。

包含键 device_id: int 和 sources: List[str] 的对象列表

MODEL

字符串

模型名称,用于验证客户端和服务器之间的一致性。

如果未指定,默认为 --model 参数。

LISTEN_PORT

整数

服务器监听器的基端口。

实际端口 = LISTEN_PORT + RANK。如果省略,则选择一个随机有效端口。有效范围:1024–65535。如果超出范围,该服务器实例将不会打开监听器。

INT8_CACHE

字符串

处理量化模型中 int8 参数的行为。

可选值:["hbm", "dram", "no"]。
- hbm:将原始 int8 参数复制到高带宽内存(HBM)(可能消耗大量 HBM)。
- dram:复制到 DRAM。
- no:不做特殊处理(可能导致发散或不可预测的行为)。默认值:"no"。

INT8_CACHE_NAME

列表

应用 INT8_CACHE 的参数名称(即过滤条件)。

默认值:None(表示不过滤——所有参数)。

OUTPUT_PREFIX

字符串

在服务器模式下写入每个 rank 的监听器地址/端口文件的前缀。

如果设置,每个 rank 写入 {OUTPUT_PREFIX}{RANK}.txt(文本),内容为 IP:Port。

CONFIG_FILE

字符串

指定上述配置的 JSON 文件路径。

如果提供,此文件中的 SOURCE 具有最高优先级(覆盖其他配置中的 SOURCE)。


示例命令与占位符#

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

服务器#

VLLM_SLEEP_WHEN_IDLE=1 vllm serve <model_file> \
  --tensor-parallel-size 1 \
  --served-model-name <model_name> \
  --enforce-eager \
  --port `<port>` \
  --load-format netloader

客户端#

export NETLOADER_CONFIG='{"SOURCE":[{"device_id":0, "sources": ["<server_IP>:<server_Port>"]}]}'

VLLM_SLEEP_WHEN_IDLE=1 ASCEND_RT_VISIBLE_DEVICES=<device_id_diff_from_server> \
  vllm serve <model_file> \
  --tensor-parallel-size 1 \
  --served-model-name <model_name> \
  --enforce-eager \
  --port <client_port> \
  --load-format netloader \
  --model-loader-extra-config="${NETLOADER_CONFIG}"

占位符说明#

  • <model_file>:模型文件路径

  • <model_name>:模型名称(服务器与客户端必须一致)

  • <port>:服务器上的基础监听端口

  • <server_IP> + <server_Port>:Netloader 服务器的 IP 和端口(来自服务器日志)

  • <device_id_diff_from_server>:客户端设备 ID(必须与服务器不同)

  • <client_port>:客户端监听的端口

启动后,您可以通过发送 temperature = 0 的推理请求并比较输出来测试一致性。


注意事项与警告#

  • 如果使用 Netloader,每个工作进程必须绑定一个监听端口。该端口可由用户指定或随机分配。如果由用户指定,请确保该端口可用。

  • Netloader 需要额外的片上内存来建立 HCCL 连接(即 HCCL_BUFFERSIZE,默认约 200 MB)。用户应预留足够的容量(例如通过 --gpu-memory-utilization)。

  • 建议设置 VLLM_SLEEP_WHEN_IDLE=1 以缓解不稳定或缓慢的连接/传输。相关信息:vLLM Issue #16660、vLLM PR #16226。