分层与稀疏 KV 缓存卸载指南¶

本指南介绍如何配置以下内容：

Prefill 阶段的分层 KV 缓存卸载
Decode 阶段的稀疏 KV 缓存卸载
在分离式 Prefill/Decode 部署中结合使用这两个特性

有关底层架构和实现细节，请参阅分层与稀疏 KV 缓存卸载设计。

支持的模型¶

组合部署目前支持以下稀疏注意力模型系列：

其他稀疏注意力模型尚未经过验证。

1. 安装依赖项¶

安装步骤按硬件分组。支持 A3 与 950PR&950DT 产品。在 950PR&950DT 产品节点上，请按照第 2 节和第 3 节的说明将 MemFabric 传输协议设置为 device_urma。

Prefill 构建依赖项¶

A3 series

Prefill 需要 MemFabric Hybrid 和 Memcache Hybrid。请按以下顺序安装。

MemFabric Hybrid¶

在每个 Prefill 节点上安装 MemFabric Hybrid 1.2 版本。该版本需要 NPU 驱动 25.5.1 或更高版本。

pip uninstall -y memfabric_hybrid
git clone -b release/1.2 https://gitcode.com/Ascend/memfabric_hybrid.git
cd memfabric_hybrid
bash script/build_and_pack_run.sh
bash output/memfabric_hybrid-1.2.0_linux_aarch64.run

Memcache Hybrid¶

在安装 MemFabric Hybrid 之后安装 Memcache Hybrid：

git clone https://gitcode.com/Ascend/memcache.git
cd memcache
git submodule update --recursive --init
git -c submodule.3rdparty/memfabric_hybrid.branch=release/1.2 \
    submodule update --remote --recursive 3rdparty/memfabric_hybrid
bash script/build_and_pack_run.sh --build_mode RELEASE
bash output/memcache_hybrid-*_linux_aarch64.run

配置 mmc-meta.conf：

ock.mmc.meta_service_url = tcp://<META_HOST>:5000
ock.mmc.meta_service.config_store_url = tcp://<CONFIG_STORE_HOST>:6000
ock.mmc.meta.lease_ttl_ms = 30000
ock.mmc.log_level = error

在每个 Prefill 节点上配置 mmc-local.conf：

ock.mmc.meta_service_url = tcp://<META_HOST>:5000
ock.mmc.local_service.config_store_url = tcp://<CONFIG_STORE_HOST>:6000
ock.mmc.log_level = error
ock.mmc.local_service.world_size = 256
ock.mmc.local_service.protocol = device_sdma
ock.mmc.local_service.dram.size = 10GB

这两个文件必须使用相同的 MetaService 端点。LocalService 的 Config Store 端点必须与 MetaService 的 Config Store 端点一致。

将 world_size 设置为支持的最大 LocalService rank 数量。
使用带 HCCS 的 device_sdma。
将 dram.size 设置为目标序列长度和并发度所需的总 KV 缓存大小除以 Prefill rank 数量后的值，并将结果向上取整到整数 GiB。

注意： 下面的配置路径假定使用 Python 3.11.10。如果您使用其他 Python 版本，请将 Python 安装目录和 site-packages 目录替换为当前环境对应的目录。可使用以下命令定位其 site-packages 目录：

python -c "import site; print(site.getsitepackages())"

在独立进程中启动 MetaService：

source /usr/local/memcache_hybrid/set_env.sh
source /usr/local/memfabric_hybrid/set_env.sh
export MMC_META_CONFIG_PATH=/usr/local/python3.11.10/lib/python3.11/site-packages/memcache_hybrid/latest/config/mmc-meta.conf
python -c "from memcache_hybrid import MetaService; MetaService.main()"

启动 vLLM 之前，在每个 Prefill 节点上执行以下准备步骤：

source /usr/local/memcache_hybrid/set_env.sh
source /usr/local/memfabric_hybrid/set_env.sh
export MMC_LOCAL_CONFIG_PATH=/usr/local/python3.11.10/lib/python3.11/site-packages/memcache_hybrid/latest/config/mmc-local.conf
export MEMFABRIC_HYBRID_EXTEND_LIB_PATH=/usr/local/memfabric_hybrid/1.2.0/aarch64-linux/lib64
export PYTHONHASHSEED=0

Decode 构建依赖项¶

A3 series

重要： MemFabric Hybrid 1.2 版本必须同时安装在 Prefill 和 Decode 节点上。Memcache Hybrid 仅 Prefill 节点需要。

使用上文所示的相同 MemFabric Hybrid 构建和安装命令。Decode 还需要 Clang 和 OpenMP。在每个 Decode 节点上执行以下准备步骤：

source /usr/local/memfabric_hybrid/set_env.sh
export MEMFABRIC_HYBRID_EXTEND_LIB_PATH=/usr/local/memfabric_hybrid/1.2.0/aarch64-linux/lib64
clang --version
ls "$(clang --print-resource-dir)/include/omp.h"

如果缺少 Clang 或 OpenMP：

apt-get update
apt-get install -y clang libomp-dev

如果镜像提供特定版本的 Clang，请安装匹配的 OpenMP 包，例如 Clang 17 对应 libomp-17-dev。

2. Prefill 阶段的分层 KV 缓存卸载¶

在专用 Prefill 节点上使用此模式，并具备以下条件：

kv_role: "kv_producer"；
Memcache 后端；
MLA、SFA 或 DSA 注意力后端；以及
eager 执行。

对于组合部署，Prefill TP 必须大于或等于 Decode TP，并且能够被 Decode TP 整除。

在 Prefill 启动命令中添加以下选项。MultiConnector 允许 AscendStoreConnector 将层缓冲区卸载到 Memcache，同时 SfaRemoteD2HConnector 将相同的缓冲区暴露给 Decode：

--enforce-eager \
--kv-transfer-config '{
    "kv_connector": "MultiConnector",
    "kv_role": "kv_producer",
    "kv_connector_extra_config": {
        "connectors": [
            {
                "kv_connector": "SfaRemoteD2HConnector",
                "kv_role": "kv_producer",
                "kv_connector_extra_config": {
                    "transfer_backend": "memfabric"
                }
            },
            {
                "kv_connector": "AscendStoreConnector",
                "kv_role": "kv_producer",
                "kv_connector_extra_config": {
                    "backend": "memcache",
                    "use_layerwise": true,
                    "layerwise_num_shared_buffers": 3,
                    "layerwise_independent_layers": [0]
                }
            }
        ]
    }
}'

请勿在 Prefill 上设置 sparse_kv_offload_config。 AscendStoreConnector 条目使用以下缓冲区选项：

参数	描述
`layerwise_num_shared_buffers`	可复用 NPU 缓冲区的数量。建议从两到四个开始，并根据内存和传输带宽进行调整。
`layerwise_independent_layers`	保留专用缓冲区的层。默认值为 `[0]`；`"all"` 会禁用跨层复用。

SfaRemoteD2HConnector 条目接受以下选项：

参数	描述
`transfer_backend`	传输后端。`memfabric` 是唯一支持的取值。
`memfabric_transfer_protocol`	MemFabric 数据路径协议：A3 系列使用 `sdma`（默认）和 `device_rdma`，950PR&950DT Products 使用 `device_urma`。必须在 Prefill 和 Decode 上设置为相同值。无效值会导致启动中止。

以下日志确认已启用缓冲区复用：

Layerwise KV cache reuse merged ... descriptors into ... descriptors using ... buffer assignments.

3. Decode 端稀疏 KV 缓存卸载¶

要求：

使用分离式 Prefill/Decode 部署；
仅在 Decode 上启用该功能；并且
使用 Model Runner V1。

将以下选项添加到 Decode 启动命令中：

--additional-config '{
    "sparse_kv_offload_config": {
        "enabled": true,
        "topk_buffer_size": 4096,
        "dram_size_per_dp_GB": 128
    }
}' \
--kv-transfer-config '{
    "kv_connector": "SfaRemoteD2HConnector",
    "kv_role": "kv_consumer",
    "kv_port": 20050,
    "kv_connector_extra_config": {
        "transfer_backend": "memfabric",
        "use_layerwise": true
    }
}'

在 Decode 上，从 kv_port 开始预留 decode_data_parallel_size * decode_tensor_parallel_size 个连续端口。

在 950PR&950DT Products 节点上，需在 Prefill 和 Decode 的 kv_connector_extra_config 中都添加 "memfabric_transfer_protocol": "device_urma"。

参数	描述
`topk_buffer_size`	设备热缓冲区大小。其值至少为 `index_topk`，且必须能被 `block_size` 整除。`index_topk` 的两倍是一个实用的起点。
`dram_size_per_dp_GB`	每个 DP 秩预留的主机内存。它必须能够容纳完整的 KV 缓存。TP 秩共享该内存池。
`keep_device_kv_cache`	仅用于调试的选项，用于保留完整的设备 KV 缓存。生产环境中请保持为 `false`。

4. 启动 P/D 代理¶

使用上述配置启动 Prefill 和 Decode。两个节点就绪后，启动代理：

python examples/disaggregated_prefill_v1/load_balance_proxy_layerwise_server_example.py \
    --host 127.0.0.1 \
    --port 9000 \
    --prefiller-hosts 127.0.0.1 \
    --prefiller-ports 8100 \
    --decoder-hosts 127.0.0.1 \
    --decoder-ports 8200

对于多节点部署，请通告可达地址，而不是 0.0.0.0。将推理请求发送到代理端口（本例中为 9000）。

5. 限制¶

共享缓冲区逐层 Prefill 卸载需要 Memcache 和急切模式。
上下文并行尚未与逐层 Prefill 卸载一起验证。
稀疏 Decode 卸载支持 DP 和 TP；不支持 CP 和 PP。
MemFabric 是 SfaRemoteD2HConnector 唯一支持的传输后端。
MemFabric 数据路径协议通过启动配置选择，而不是硬件检测：A3 系列使用 sdma（默认）或 device_rdma，950PR&950DT Products 使用 device_urma，且 Prefill 和 Decode 必须一致。
目前逐层缓冲区复用无法与 MooncakeLayerwiseConnector 组合使用，因为尚未实现按缓冲区的传输完成门控。计划在后续更新中提供支持。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 vl/vllm-ascend