NixlConnector 用法指南¶

NixlConnector 是 vLLM 分离式预填充功能的高性能 KV 缓存传输连接器。它使用 NIXL 库提供全异步的发送/接收操作，以实现高效的跨进程 KV 缓存传输。

先决条件¶

安装¶

安装 NIXL 库：uv pip install nixl，作为快速入门。

有关更多安装说明，请参阅 NIXL 官方仓库
指定的必需 NIXL 版本可以在 requirements/kv_connectors.txt 和其他相关配置文件中找到

对于非 cuda 平台，请通过从源代码构建 UCX 来安装 nixl，如下所示。

python tools/install_nixl_from_source_ubuntu.py

传输配置¶

NixlConnector 使用 NIXL 库进行底层通信，该库支持多种传输后端。UCX (Unified Communication X) 是 NIXL 使用的主要默认传输库。配置传输环境变量

# Example UCX configuration, adjust according to your environment
export UCX_TLS=all  # or specify specific transports like "rc,ud,sm,^cuda_ipc" ..etc
export UCX_NET_DEVICES=all  # or specify network devices like "mlx5_0:1,mlx5_1:1"

提示

当使用 UCX 作为传输后端时，NCCL 环境变量（如 NCCL_IB_HCA, NCCL_SOCKET_IFNAME）不适用于 NixlConnector，因此请配置 UCX 特定的环境变量而不是 NCCL 变量。

基本用法（在同一主机上）¶

生产者（Prefiller）配置¶

启动一个生成 KV 缓存的 prefiller 实例

# 1st GPU as prefiller
CUDA_VISIBLE_DEVICES=0 \
UCX_NET_DEVICES=all \
VLLM_NIXL_SIDE_CHANNEL_PORT=5600 \
vllm serve Qwen/Qwen3-0.6B \
  --port 8100 \
  --enforce-eager \
  --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both"}'

消费者（Decoder）配置¶

启动一个消耗 KV 缓存的 decoder 实例

# 2nd GPU as decoder
CUDA_VISIBLE_DEVICES=1 \
UCX_NET_DEVICES=all \
VLLM_NIXL_SIDE_CHANNEL_PORT=5601 \
vllm serve Qwen/Qwen3-0.6B \
  --port 8200 \
  --enforce-eager \
  --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both"}'

代理服务器¶

使用代理服务器在 prefiller 和 decoder 之间路由请求

python tests/v1/kv_connector/nixl_integration/toy_proxy_server.py \
  --port 8192 \
  --prefiller-hosts localhost \
  --prefiller-ports 8100 \
  --decoder-hosts localhost \
  --decoder-ports 8200

环境变量¶

VLLM_NIXL_SIDE_CHANNEL_PORT：NIXL 握手通信的端口
- 默认值：5600
- Prefiller 和 Decoder 实例均需要
- 每个 vLLM 工作节点在其主机上需要一个唯一的端口；在不同主机上使用相同的端口号是可以的
- 对于 TP/DP 部署，节点上每个工作节点的端口计算方式为：base_port + dp_rank（例如，使用 --data-parallel-size=2 和 base_port=5600，dp_rank 0..1 在该节点上使用端口 5600, 5601）。
- 用于 prefiller 和 decoder 之间的初始 NIXL 握手
VLLM_NIXL_SIDE_CHANNEL_HOST：侧信道通信的主机
- 默认值："localhost"
- 当 prefiller 和 decoder 在不同机器上时设置
- 连接信息通过 KVTransferParams 从 prefiller 传递给 decoder 进行握手
VLLM_NIXL_ABORT_REQUEST_TIMEOUT：自动释放特定请求的 prefiller KV 缓存的超时时间（秒）。（可选）
- 默认值：480
- 如果请求被中止，并且 decoder 尚未通过 nixl 通道读取 KV 缓存块，则 prefill 实例将在该超时后释放其 KV 缓存块，以避免无限期地占用它们。

多实例设置¶

不同机器上的多个 Prefiller 实例¶

# Prefiller 1 on Machine A (example IP: ${IP1})
VLLM_NIXL_SIDE_CHANNEL_HOST=${IP1} \
VLLM_NIXL_SIDE_CHANNEL_PORT=5600 \
UCX_NET_DEVICES=all \
vllm serve Qwen/Qwen3-0.6B --port 8000 \
  --tensor-parallel-size 8 \
  --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_producer"}'

# Prefiller 2 on Machine B (example IP: ${IP2})
VLLM_NIXL_SIDE_CHANNEL_HOST=${IP2} \
VLLM_NIXL_SIDE_CHANNEL_PORT=5600 \
UCX_NET_DEVICES=all \
vllm serve Qwen/Qwen3-0.6B --port 8000 \
  --tensor-parallel-size 8 \
  --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_producer"}'

不同机器上的多个 Decoder 实例¶

# Decoder 1 on Machine C (example IP: ${IP3})
VLLM_NIXL_SIDE_CHANNEL_HOST=${IP3} \
VLLM_NIXL_SIDE_CHANNEL_PORT=5600 \
UCX_NET_DEVICES=all \
vllm serve Qwen/Qwen3-0.6B --port 8000 \
  --tensor-parallel-size 8 \
  --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_consumer"}'

# Decoder 2 on Machine D (example IP: ${IP4})
VLLM_NIXL_SIDE_CHANNEL_HOST=${IP4} \
VLLM_NIXL_SIDE_CHANNEL_PORT=5600 \
UCX_NET_DEVICES=all \
vllm serve Qwen/Qwen3-0.6B --port 8000 \
  --tensor-parallel-size 8 \
  --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_consumer"}'

多实例的代理¶

python tests/v1/kv_connector/nixl_integration/toy_proxy_server.py \
  --port 8192 \
  --prefiller-hosts ${IP1} ${IP2} \
  --prefiller-ports 8000 8000 \
  --decoder-hosts ${IP3} ${IP4} \
  --decoder-ports 8000 8000

对于多主机 DP 部署，只需提供头实例的主机/端口。

KV 角色选项¶

kv_producer：用于生成 KV 缓存的 prefiller 实例
kv_consumer：用于从 prefiller 消耗 KV 缓存的 decoder 实例
kv_both：启用对称功能，连接器可以同时作为生产者和消费者。这为实验性设置和角色尚未预先确定的场景提供了灵活性。

提示

NixlConnector 目前不区分 kv_role；实际的 prefiller/decoder 角色由上层代理（例如，使用 --prefiller-hosts 和 --decoder-hosts 的 toy_proxy_server.py）决定。因此，--kv-transfer-config 中的 kv_role 实际上是一个占位符，不会影响 NixlConnector 的行为。

实验性功能¶

异构 KV 布局支持¶

支持用例：使用 'HND' 进行预填充，并使用实验性配置用 'NHD' 进行解码

--kv-transfer-config '{..., "enable_permute_local_kv":"True"}'

示例脚本/代码¶

请参阅 vLLM 仓库中的这些示例脚本