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

本指南说明如何配置：

• 在Prefill阶段进行分层KV缓存卸载
• 在Decode阶段进行稀疏KV缓存卸载
• 在分离式Prefill/Decode部署中结合使用这两个功能

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

支持的模型

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

• GLM-5.1
• GLM-5.2
• DeepSeek-V3.2

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

1. 安装依赖

The installation steps are grouped by hardware. A3 and A5 series are supported. On A5 nodes, set the MemFabric transfer protocol to device_urma as described in sections 2 and 3.

Prefill构建依赖

A3系列

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数量。
• 将device_sdma与HCCS配合使用。
• 将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系列

重要： 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，并且能够被其整除。

在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"禁用跨层复用。

The SfaRemoteD2HConnector entry accepts the following options:

参数	描述
transfer_backend	Transfer backend. memfabric is the only supported value.
memfabric_transfer_protocol	MemFabric data-path protocol: sdma (default) and device_rdma for A3 series, device_urma for A5 series. Must be set to the same value on Prefill and Decode. Invalid values abort startup.

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

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个连续端口。

On A5 nodes, add "memfabric_transfer_protocol": "device_urma" to kv_connector_extra_config on both Prefill and Decode.

参数	描述
topk_buffer_size	设备热缓冲区大小。它必须至少为 index_topk，并且能被 block_size 整除。以 index_topk 的两倍作为起点是可行的。
dram_size_per_dp_GB	每个 DP rank 预留的主机内存。它必须能容纳完整的 KV 缓存。TP rank 共享此内存池。
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. 限制

• Shared-buffer Layerwise Prefill Offload requires Memcache and eager mode.
• Context parallelism has not been validated with Layerwise Prefill Offload.
• Sparse Decode Offload supports DP and TP; CP and PP are not supported.
• MemFabric is the only supported SfaRemoteD2HConnector transfer backend.
• The MemFabric data-path protocol is selected by launch configuration instead of hardware detection: use sdma (default) or device_rdma on A3 series and device_urma on A5 series, identically on Prefill and Decode.
• Layerwise buffer reuse cannot currently be combined with MooncakeLayerwiseConnector because per-buffer transfer completion gating is not yet implemented. Support is planned in a follow-up update.