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 倉庫中的這些示例指令碼