基于Mooncake多实例的PD共置部署

快速开始

vLLM-Ascend 现已支持基于 Mooncake 特性的 PD 共置部署。 本指南提供在资源受限条件下测试这些功能的分步说明。

以 Qwen2.5-72B-Instruct 模型为例，本指南演示如何在两台 Atlas 800T A2 节点上使用 vllm-ascend v0.22.1rc1（基于 vLLM v0.22.1）部署两个 vLLM 实例。 每个实例占用 4 张 NPU 卡，并采用 PD 共置部署方式。

验证多节点通信环境

物理层要求

• 两台 Atlas 800T A2 节点必须通过 RoCE 网络进行物理互联。 若无 RoCE 互联，跨节点 KV Cache 访问性能将显著下降。
• 所有 NPU 卡必须正常通信。节点内通信使用 HCCS， 节点间通信使用 RoCE 网络。

验证流程

以下流程作为参考示例。请根据实际环境修改 IP 地址等参数。

1. 单节点验证：

依次执行以下命令。结果必须全部为 success，且状态必须为 UP：

# Check the remote switch ports
for i in {0..7}; do hccn_tool -i $i -lldp -g | grep Ifname; done
# Get the link status of the Ethernet ports (UP or DOWN)
for i in {0..7}; do hccn_tool -i $i -link -g ; done
# Check the network health status
for i in {0..7}; do hccn_tool -i $i -net_health -g ; done
# View the network detected IP configuration
for i in {0..7}; do hccn_tool -i $i -netdetect -g ; done
# View gateway configuration
for i in {0..7}; do hccn_tool -i $i -gateway -g ; done

1. 检查 NPU HCCN 配置：

确保环境中存在 hccn.conf 文件。如果使用 Docker， 请将其挂载到容器中。

cat /etc/hccn.conf

1. 获取 NPU IP 地址：

for i in {0..7}; do hccn_tool -i $i -ip -g; done

1. 跨节点 PING 测试：

# Execute the following command on each node, replacing x.x.x.x
# with the target node's NPU card address.
for i in {0..7}; do hccn_tool -i $i -ping -g address x.x.x.x; done

1. 检查 NPU TLS 配置

# The tls settings should be consistent across all nodes.
for i in {0..7}; do hccn_tool -i $i -tls -g ; done | grep switch

使用 Docker 运行

在每个节点上启动一个 Docker 容器。

# Update the vllm-ascend image
export IMAGE=quay.io/ascend/vllm-ascend:v0.22.1rc1
export NAME=vllm-ascend

# Run the container using the defined variables
# This test uses four NPU cards to create the container.
# Mount the hccn.conf file from the host node into the container.
docker run --rm \
--name $NAME \
--net=host \
--shm-size=1g \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
--device /dev/davinci3 \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/Ascend/driver/tools/hccn_tool:\
/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /etc/hccn.conf:/etc/hccn.conf \
-v /root/.cache:/root/.cache \
-it $IMAGE bash

（可选）安装 Mooncake

Mooncake 已在 v0.22.1rc1 镜像中预装并可正常使用。 以下安装步骤为可选操作。

Mooncake 是 Moonshot AI 旗下领先的大语言模型服务 Kimi 的推理平台。 安装与编译指南： https://github.com/kvcache-ai/Mooncake?tab=readme-ov-file#build-and-use-binaries.

首先，使用以下命令获取 Mooncake 项目：

git clone -b v0.3.9 --depth 1 https://github.com/kvcache-ai/Mooncake.git
cd Mooncake
git submodule update --init --recursive

安装 MPI：

apt-get install mpich libmpich-dev -y

安装相关依赖（无需安装 Go）：

bash dependencies.sh -y

编译并安装：

mkdir build
cd build
cmake .. -DUSE_ASCEND_DIRECT=ON
make -j
make install

安装完成后，验证 Mooncake 是否正确安装：

python -c "import mooncake; print(mooncake.__file__)"
# Expected output path:
# /usr/local/Ascend/ascend-toolkit/latest/python/
# site-packages/mooncake/__init__.py

启动 Mooncake Master 服务

要在某个节点容器中启动 Mooncake master 服务，请使用 以下命令：

docker exec -it vllm-ascend bash
cd /vllm-workspace/Mooncake
mooncake_master --port 50088 \
  --eviction_high_watermark_ratio 0.95 \
  --eviction_ratio 0.05

参数	值	说明
port	50088	Port for the master service
eviction_high_watermark_ratio	0.95	High watermark ratio (95% threshold)
eviction_ratio	0.05	Percentage to evict when full (5%)

创建名为 mooncake.json 的 Mooncake 配置文件

mooncake.json 文件的模板如下：

{
    "metadata_server": "P2PHANDSHAKE",
    "protocol": "ascend",
    "device_name": "",
    "master_server_address": "<your_server_ip>:50088",
    "global_segment_size": 107374182400
}

参数	值	说明
metadata_server	P2PHANDSHAKE	点对点握手模式
protocol	ascend	Ascend 专有协议
master_server_address	90.90.100.188:50088（示例）	主服务器地址
global_segment_size	107374182400	Size per segment (100 GB)

vLLM 实例部署

在节点 1 和节点 2 上分别创建容器，并在每个容器中启动 Qwen2.5-72B-Instruct 模型服务，以测试跨节点、跨实例 KV Cache 的 可复用性和性能。实例 1 使用第一台 Atlas 800T A2 服务器上的 NPU 卡 [0-3]，实例 2 使用第二台服务器上的卡 [0-3]。

部署实例 1

根据实际环境配置替换文件路径、host 和 port 参数。

export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/\
latest/python/site-packages:$LD_LIBRARY_PATH
export MOONCAKE_CONFIG_PATH="/vllm-workspace/mooncake.json"
# NPU buffer pool: quantity:size(MB)
# Allocates 4 buffers of 8MB each for KV transfer
export ASCEND_BUFFER_POOL=4:8

vllm serve <path_to_your_model>/Qwen2.5-72B-Instruct/ \
--served-model-name qwen \
--dtype bfloat16 \
--max-model-len 25600 \
--tensor-parallel-size 4 \
--host <your_server_ip> \
--port 8002 \
--max-num-batched-tokens 4096 \
--gpu-memory-utilization 0.9 \
--kv-transfer-config '{
      "kv_connector": "MooncakeConnectorStoreV1",
      "kv_role": "kv_both",
      "kv_connector_extra_config": {
          "use_layerwise": false,
          "mooncake_rpc_port": "0",
          "load_async": true,
          "register_buffer": true
      }
  }'

部署实例 2

实例 2 的部署方法与实例 1 相同。只需根据实例 2 的配置 修改 --host 和 --port 参数即可。

配置参数

参数	值	说明
kv_connector	MooncakeConnectorStoreV1	使用 StoreV1 版本
kv_role	kv_both	同时启用生产和消费
use_layerwise	false	传输整个缓存（参见注释）
mooncake_rpc_port	0	Automatic port assignment
load_async	true	启用异步加载
register_buffer	true	PD 同地部署模式必需

关于 use_layerwise 的说明：

• false：传输整个 KV Cache（适用于带宽充足的跨节点场景）
• true：逐层传输（适用于单节点内存受限的场景）

基准测试

建议使用 AISBench 工具评估性能。测试使用完全随机的 数据集 A，配置如下：

• 输入/输出 tokens：1024/10
• 总请求数：100
• 并发数：25

测试流程包含三个步骤：

步骤1：基准测试（无缓存）

将数据集A发送至节点1上的实例1，记录首Token时间 （TTFT）为 TTFT1。

步骤2准备

在步骤2之前，将完全随机的数据集B发送至实例1。由于采用LRU（最近最少使用）淘汰策略的统一 片上内存/DRAM KV缓存，数据集B的缓存会将数据集A的缓存从片上内存中淘汰，使得数据集A的 缓存仅保留在节点1的DRAM中。

步骤2：本地DRAM命中

再次将数据集A发送至实例1，以测量命中本地DRAM中KV缓存时的性能。 记录TTFT为 TTFT2。

步骤3：跨节点DRAM命中

将数据集A发送至实例2。借助Mooncake KV缓存池，这将实现从节点1的DRAM 跨节点命中KV缓存。记录TTFT为 TTFT3。

模型配置：

from ais_bench.benchmark.models import VLLMCustomAPIChatStream
from ais_bench.benchmark.utils.model_postprocessors import extract_non_reasoning_content

models = [
    dict(
        attr="service",
        type=VLLMCustomAPIChatStream,
        abbr='vllm-api-stream-chat',
        path="<path_to_your_model>/Qwen2.5-72B-Instruct",
        model="qwen",
        request_rate = 0,
        retry = 2,
        host_ip = "<your_server_ip>",
        host_port = 8002,
        max_out_len = 10,
        batch_size= 25,
        trust_remote_code=False,
        generation_kwargs = dict(
            temperature = 0,
            ignore_eos = True,
        ),
    )
]

性能基准测试命令：

ais_bench --models vllm_api_stream_chat \
  --datasets gsm8k_gen_0_shot_cot_str_perf \
  --debug --summarizer default_perf --mode perf

测试结果

请求数	并发数	TTFT1 (毫秒)	TTFT2 (毫秒)	TTFT3 (毫秒)
100	25	2322	739	948