KV缓存池（Ascend存储）部署指南

目录

• 环境依赖
• 使用Mooncake作为KV池后端的示例
• 使用Memcache作为KV池后端的示例
• 使用元戎作为KV池后端的示例
• 常见问题

环境依赖

• 软件：
  • CANN >= 8.5.0
  • vLLM：main分支
  • vLLM-Ascend：main分支
  • mooncake：>= 0.3.9

KV池参数说明

kv_load_failure_policy：KV加载失败处理策略

kv_load_failure_policy 是 kv-transfer-config 中的顶级字段。

• recompute：当KV加载失败时，vLLM将请求回滚到最后一个有效前缀，并重新调度以重新计算失败的KV块。尚不支持混合注意力模型（例如DeepSeekV4、Qwen 3.5）。
• fail：当KV加载失败时，受影响的请求将直接终止并返回错误。

vLLM中的默认值为 fail。如果希望在KV加载失败后请求回退到重新计算，请将其设置为 recompute。

使用 MultiConnector 时，请在 kv_load_failure_policy 顶级 MultiConnector 上配置 kv-transfer-config，而不是在子连接器上配置。

kv_connector_extra_config：池化的其他可配置参数

参数	描述
lookup_rpc_port	池化调度进程与工作进程之间RPC通信的端口：每个实例需要配置唯一的端口。
load_async	是否启用异步加载。默认值为false。
backend	设置kvpool的存储后端（mooncake、memcache、yuanrong），默认为mooncake。
consumer_is_to_put	Decode节点是否将KV Cache放入KV Pool。默认值为false。
consumer_is_to_load	Decode节点是否从KV Pool加载KV cache。默认值为false。
prefill_pp_size	Prefill PP大小，当Prefill节点启用PP时需要设置。
prefill_pp_layer_partition	Prefill PP层分区，当Prefill节点启用PP时需要设置。

环境变量配置

为保证统一的哈希生成，在启用KV池时，需要在所有节点上同步PYTHONHASHSEED环境变量。

export PYTHONHASHSEED=0

使用Mooncake作为KV池后端的示例

• 软件：

  • 检查NPU HCCN配置：

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

    cat /etc/hccn.conf
    

  • 安装Mooncake

    Mooncake是Kimi（Moonshot AI提供的领先LLM服务）的服务平台。 安装和编译指南：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
    

    （可选）如果网络状况不佳，请替换go安装URL

    cd Mooncake
    sed -i 's|https://go.dev/dl/|https://golang.google.cn/dl/|g' dependencies.sh
    

    安装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
    

    设置环境变量

    注意：

    • 根据您的具体Python安装调整Python路径
    • 确保 /usr/local/lib 和 /usr/local/lib64 位于您的 LD_LIBRARY_PATH 中

    export LD_LIBRARY_PATH=/usr/local/lib64/python3.12/site-packages/mooncake:$LD_LIBRARY_PATH
    

环境变量说明

硬件	依赖项	导出命令	描述
800 I/T A3系列	HDK >= 26.0 或 HDK >= 25.5 且 mooncake >= v0.3.11 CANN >= 9.0.0 灵衢计算网络 >= 1.5	export ASCEND_ENABLE_USE_FABRIC_MEM=1	推荐。启用统一内存地址直传方案。使用SSD卸载时，请参见Fabric内存大小对齐 — 内存大小必须按1GB对齐。
800 I/T A3系列	如果上述任一依赖不满足	export ASCEND_BUFFER_POOL=4:8	配置NPU设备上用于聚合和KV传输的缓冲区数量和大小（例如，4:8表示4个8MB的缓冲区）。
800 I/T A2系列	建议HDK >= 25.5	export HCCL_INTRA_ROCE_ENABLE=1	800 I/T A2系列直传方案所需

运行Mooncake Master

注意： 在继续之前，请查看以下Mooncake指南：

• Mooncake存储部署指南
• SSD卸载

1. 配置mooncake.json

环境变量 MOONCAKE_CONFIG_PATH 配置为mooncake.json所在的完整路径。

{
    "metadata_server": "P2PHANDSHAKE",
    "protocol": "ascend",
    "device_name": "",
    "master_server_address": "xx.xx.xx.xx:50088",
    "global_segment_size": "1GB" (1024MB/1048576KB/1073741824B/1073741824),
    "preferred_segment": false,
    "prefer_alloc_in_same_node": true
}

metadata_server: 配置为 P2PHANDSHAKE。
protocol: 在NPU上必须设置为 'Ascend'。 device_name: "" master_server_address: 配置主服务的IP和端口。也可以通过 MOONCAKE_MASTER 环境变量设置，该环境变量优先级高于此配置项（用于通过Kubernetes注入主地址）。
global_segment_size: 每张卡注册到KV Pool的内存大小。需要按1GB对齐。 也可以通过 MOONCAKE_GLOBAL_SEGMENT_SIZE 环境变量设置，该环境变量优先级高于此配置项。
preferred_segment: 向KV Pool放入对象时，是否优先将KV存储到本地段。默认为 false。
prefer_alloc_in_same_node: 是否优先在同一节点上分配KV。默认为 true。

2. 启动 mooncake_master

在 mooncake 文件夹下：

mooncake_master --port 50088 --eviction_high_watermark_ratio 0.9 --eviction_ratio 0.1 --default_kv_lease_ttl 11000

eviction_high_watermark_ratio 决定 Mooncake Store 执行驱逐的水位线，eviction_ratio 决定被驱逐的存储对象比例。 default_kv_lease_ttl 控制 KV 对象的默认租约 TTL（毫秒）；通过 --default_kv_lease_ttl 配置，并确保其大于 ASCEND_CONNECT_TIMEOUT 和 ASCEND_TRANSFER_TIMEOUT。

PD 分离场景

1. 运行 prefill 节点和 decode 节点

使用 MultiConnector 同时利用 MooncakeConnectorV1 和 AscendStoreConnector。MooncakeConnectorV1 执行 kv_transfer，而 AscendStoreConnector 作为前缀缓存节点。

prefill 节点：

bash multi_producer.sh

multi_producer.sh 脚本的内容：

export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages:$LD_LIBRARY_PATH
export PYTHONHASHSEED=0
export PYTHONPATH=$PYTHONPATH:/xxxxx/vllm
export MOONCAKE_CONFIG_PATH="/xxxxxx/mooncake.json"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
export ACL_OP_INIT_MODE=1
#A3
export ASCEND_ENABLE_USE_FABRIC_MEM=1
#A2
#export HCCL_INTRA_ROCE_ENABLE=1

#Minimum retransmission timeout of the RDMA, equals 4.096 μs * 2 ^ timeout.
#Needs to satisfy the equation: ASCEND_TRANSFER_TIMEOUT > RDMA_TIMEOUT * 7, where 7 is the default number of retry for RDMA transfer.
#HCCL_RDMA_TIMEOUT also affects collective communication behavior and should be configured carefully.
export HCCL_RDMA_TIMEOUT=17

# Unit: ms. The timeout for one-sided communication connection establishment is set to 10 seconds by default (see PR: https://github.com/kvcache-ai/Mooncake/pull/1039). Users can adjust this value based on their specific setup.
# The recommended formula is: ASCEND_CONNECT_TIMEOUT = connection_time_per_card (typically within 500ms) × total_number_of_Decode_cards.
# This ensures that even in the worst-case scenario—where all Decode cards simultaneously attempt to connect to the same Prefill card the connection will not time out.
export ASCEND_CONNECT_TIMEOUT=10000

# Unit: ms. The timeout for one-sided communication transfer is set to 10 seconds by default (see PR: https://github.com/kvcache-ai/Mooncake/pull/1039).
export ASCEND_TRANSFER_TIMEOUT=10000

python3 -m vllm.entrypoints.openai.api_server \
    --model /xxxxx/Qwen2.5-7B-Instruct \
    --port 8100 \
    --trust-remote-code \
    --enforce-eager \
    --no-enable-prefix-caching \
    --tensor-parallel-size 1 \
    --data-parallel-size 1 \
    --max-model-len 32768 \
    --block-size 128 \
    --max-num-batched-tokens 16384 \
    --kv-transfer-config \
    '{
    "kv_connector": "MultiConnector",
    "kv_role": "kv_producer",
    "kv_load_failure_policy": "recompute",
    "kv_connector_extra_config": {
        "connectors": [
            {
                "kv_connector": "MooncakeConnectorV1",
                "kv_role": "kv_producer",
                "kv_port": "20001",
                "kv_connector_extra_config": {
                    "prefill": {
                        "dp_size": 1,
                        "tp_size": 1
                    },
                    "decode": {
                        "dp_size": 1,
                        "tp_size": 1
                    }
                }
            },
            {
                "kv_connector": "AscendStoreConnector",
                "kv_role": "kv_producer",
                "kv_connector_extra_config": {
                    "lookup_rpc_port":"0",
                    "backend": "mooncake"
                }
            }  
        ]
    }
    }'

decode 节点：

bash multi_consumer.sh

multi_consumer.sh 的内容：

export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages:$LD_LIBRARY_PATH
export PYTHONPATH=$PYTHONPATH:/xxxxx/vllm
export PYTHONHASHSEED=0
export MOONCAKE_CONFIG_PATH="/xxxxx/mooncake.json"
export ASCEND_RT_VISIBLE_DEVICES=4,5,6,7
export ACL_OP_INIT_MODE=1
#A3
export ASCEND_ENABLE_USE_FABRIC_MEM=1
#A2
#export HCCL_INTRA_ROCE_ENABLE=1
export HCCL_RDMA_TIMEOUT=17
export ASCEND_CONNECT_TIMEOUT=10000
export ASCEND_TRANSFER_TIMEOUT=10000

python3 -m vllm.entrypoints.openai.api_server \
    --model /xxxxx/Qwen2.5-7B-Instruct \
    --port 8200 \
    --trust-remote-code \
    --enforce-eager \
    --no-enable-prefix-caching \
    --tensor-parallel-size 1 \
    --data-parallel-size 1 \
    --max-model-len 32768 \
    --block-size 128 \
    --max-num-batched-tokens 16384 \
    --kv-transfer-config \
    '{
    "kv_connector": "MultiConnector",
    "kv_role": "kv_consumer",
    "kv_load_failure_policy": "recompute",
    "kv_connector_extra_config": {
        "connectors": [
        {
                "kv_connector": "MooncakeConnectorV1",
                "kv_role": "kv_consumer",
                "kv_port": "20002",
                "kv_connector_extra_config": {
                    "prefill": {
                        "dp_size": 1,
                        "tp_size": 1
                    },
                    "decode": {
                        "dp_size": 1,
                        "tp_size": 1
                    }
                }
            },
            {
                "kv_connector": "AscendStoreConnector",
                "kv_role": "kv_consumer",
                "kv_connector_extra_config": {
                    "lookup_rpc_port":"0",
                    "backend": "mooncake"
                }
            }
        ]
    }
    }'

目前，PD分离中的键值池默认只存储Prefill节点生成的kv缓存。在使用MLA的模型中，现在支持Decode节点存储kv缓存供Prefill节点使用，通过在AscendStoreConnector中添加consumer_is_to_put: true启用。如果Prefill节点启用了PP，还需要设置prefill_pp_size或prefill_pp_layer_partition。示例如下：

{
    "kv_connector": "AscendStoreConnector",
    "kv_role": "kv_consumer",
    "kv_load_failure_policy": "recompute",
    "kv_connector_extra_config": {
        "lookup_rpc_port": "0",
        "backend": "mooncake",
        "consumer_is_to_put": true,
        "prefill_pp_size": 2,
        "prefill_pp_layer_partition": "30,31"
    }
}

2. 启动 proxy_server

python vllm-ascend/examples/disaggregated_prefill_v1/load_balance_proxy_server_example.py \
    --host localhost \
    --prefiller-hosts localhost \
    --prefiller-ports 8100 \
    --decoder-hosts localhost \
    --decoder-ports 8200 \

将 localhost 替换为您的实际IP地址。

3. 运行推理

将命令中的 localhost、端口和模型权重路径配置为您自己的设置。

简短问题：

curl -s http://localhost:8000/v1/completions -H "Content-Type: application/json" -d '{ "model": "/xxxxx/Qwen2.5-7B-Instruct", "prompt": "Hello. I have a question. The president of the United States is", "max_completion_tokens": 200, "temperature":0.0 }'

详细问题：

curl -s http://localhost:8000/v1/completions -H "Content-Type: application/json" -d '{ "model": "/xxxxx/Qwen2.5-7B-Instruct", "prompt": "Given the accelerating impacts of climate change—including rising sea levels, increasing frequency of extreme weather events, loss of biodiversity, and adverse effects on agriculture and human health—there is an urgent need for a robust, globally coordinated response. However, international efforts are complicated by a range of factors: economic disparities between high-income and low-income countries, differing levels of industrialization, varying access to clean energy technologies, and divergent political systems that influence climate policy implementation. In this context, how can global agreements like the Paris Accord be redesigned or strengthened to not only encourage but effectively enforce emission reduction targets? Furthermore, what mechanisms can be introduced to promote fair and transparent technology transfer, provide adequate financial support for climate adaptation in vulnerable regions, and hold nations accountable without exacerbating existing geopolitical tensions or disproportionately burdening those with historically lower emissions?", "max_completion_tokens": 256, "temperature":0.0 }'

PD混合推理

1. 运行混合部署脚本

bash pd_mix.sh

pd_mix.sh 的内容：

export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages:$LD_LIBRARY_PATH
export PYTHONPATH=$PYTHONPATH:/xxxxx/vllm
export MOONCAKE_CONFIG_PATH="/xxxxxx/mooncake.json"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
export PYTHONHASHSEED=0
export ACL_OP_INIT_MODE=1
#A3
export ASCEND_ENABLE_USE_FABRIC_MEM=1
#A2
#export HCCL_INTRA_ROCE_ENABLE=1
export HCCL_RDMA_TIMEOUT=17
export ASCEND_CONNECT_TIMEOUT=10000
export ASCEND_TRANSFER_TIMEOUT=10000

python3 -m vllm.entrypoints.openai.api_server \
    --model /xxxxx/Qwen2.5-7B-Instruct \
    --port 8100 \
    --trust-remote-code \
    --enforce-eager \
    --no-enable-prefix-caching \
    --tensor-parallel-size 1 \
    --data-parallel-size 1 \
    --max-model-len 32768 \
    --block-size 128 \
    --max-num-batched-tokens 16384 \
    --kv-transfer-config \
    '{
    "kv_connector": "AscendStoreConnector",
    "kv_role": "kv_both",
    "kv_load_failure_policy": "recompute",
    "kv_connector_extra_config": {
        "lookup_rpc_port":"1",
        "backend": "mooncake"
    }
}' > mix.log 2>&1

2. 运行推理

将命令中的 localhost、端口和模型权重路径配置为您自己的设置。发送的请求只会到达混合部署脚本所在的端口，无需启动单独的代理。

简短问题：

curl -s http://localhost:8100/v1/completions -H "Content-Type: application/json" -d '{ "model": "/xxxxx/Qwen2.5-7B-Instruct", "prompt": "Hello. I have a question. The president of the United States is", "max_completion_tokens": 200, "temperature":0.0 }'

详细问题：

curl -s http://localhost:8100/v1/completions -H "Content-Type: application/json" -d '{ "model": "/xxxxx/Qwen2.5-7B-Instruct", "prompt": "Given the accelerating impacts of climate change—including rising sea levels, increasing frequency of extreme weather events, loss of biodiversity, and adverse effects on agriculture and human health—there is an urgent need for a robust, globally coordinated response. However, international efforts are complicated by a range of factors: economic disparities between high-income and low-income countries, differing levels of industrialization, varying access to clean energy technologies, and divergent political systems that influence climate policy implementation. In this context, how can global agreements like the Paris Accord be redesigned or strengthened to not only encourage but effectively enforce emission reduction targets? Furthermore, what mechanisms can be introduced to promote fair and transparent technology transfer, provide adequate financial support for climate adaptation in vulnerable regions, and hold nations accountable without exacerbating existing geopolitical tensions or disproportionately burdening those with historically lower emissions?", "max_completion_tokens": 256, "temperature":0.0 }'

注意：对于启用了 ASCEND_BUFFER_POOL 的 MooncakeStore，建议在运行实际性能基准测试前执行预热阶段。

这是因为涉及设备间通信时，HCCL单边通信连接会在实例启动后延迟创建。目前，需要所有设备之间的全网格连接。建立这些连接会带来一次性时间开销和持续的设备内存消耗（每个连接4 MB设备内存）。

对于预热，建议发送输入序列长度为8K、输出序列长度为1的请求，请求总数应为设备数（卡/芯）的2–3倍。

使用嵌入式真实客户端模式启用 MooncakeStore SSD卸载

• 需要 mooncake >= v0.3.11。

启动主服务

按照运行 Mooncake 主服务中的描述启动 Mooncake 主服务。要启用SSD卸载，请在相同的主服务启动命令中添加 --enable_offload=true。例如：

mooncake_master --port 50088 --eviction_high_watermark_ratio 0.9 --eviction_ratio 0.1 --default_kv_lease_ttl 11000 --enable_offload=true --client_ttl=120

字段	描述
enable_offload	设置为true以在Mooncake master中启用SSD卸载。保持master端口与master_server_address中的mooncake.json一致。
client_ttl	客户端在最后一次Ping后保持存活的秒数。CLI默认值为10；请参见SSD卸载时的SEGMENT_NOT_FOUND。

配置

从运行 Mooncake 主服务mooncake.json中配置的 开始，添加以下SSD卸载字段：

{
    "enable_ssd_offload": true,
    "ssd_offload_path": "/nvme/mooncake_offload"
}

字段	描述
enable_ssd_offload	设置为true以启用SSD卸载。不支持环境变量。
ssd_offload_path	当enable_ssd_offload为true时必需。 Mooncake存储卸载的KV数据的本地目录的绝对路径（例如，/nvme/mooncake_offload）。该目录必须存在且可由vLLM进程写入；请在启动前创建它（mkdir -p <path>）。Mooncake拒绝相对路径、符号链接以及包含..的路径。作为SSD存储根目录传递给MooncakeDistributedStore.setup()（相当于独立客户端中的MOONCAKE_OFFLOAD_FILE_STORAGE_PATH）。仅在mooncake.json中配置此字段；不支持环境变量。

运行嵌入式真实客户端

在模式A（嵌入式真实客户端）下，Mooncake 嵌入在 vLLM 中。当 vLLM 服务启动时，AscendStoreConnector / MooncakeBackend 会根据 MooncakeDistributedStore.setup() 中的设置（包括启用 SSD 卸载时的 mooncake.json 和 enable_ssd_offload）自动调用 ssd_offload_path。无需单独的 mooncake_client 进程。

SSD 磁盘使用控制

以下环境变量控制 SSD 卸载（桶后端）的磁盘空间使用：

环境变量	默认值	描述
MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES	1342177280 (1280 MB)	每个rank的SSD读写缓冲区大小（字节）。不可**在mooncake.json中配置。如果遇到BUFFER_OVERFLOW，请增大此值——请参见调整MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES的大小。**在A3上使用ASCEND_ENABLE_USE_FABRIC_MEM=1时，必须按1GB对齐，并计入每个rank的fabric mem配额（请参见Fabric内存大小对齐）。
MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE	0	逐出阈值（字节）。当设置为0时，后端使用**物理磁盘容量的90%**作为配额。设置显式值以精确控制磁盘使用量。
MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY	none	逐出策略：none（满时写入失败）、fifo或lru。
MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES	2199023255552 (2 TB)	报告给Mooncake master的**每个rank**的最大磁盘使用量。Master跨客户端聚合此值（在SSD Storage总计中约为**2 TB × rank数量**）。**始终覆盖**以匹配实际磁盘容量——默认值通常超过可用空间。

MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES 风险： 如果保留 2 TB 的默认值，master 显示的 SSD 总配额将远大于物理磁盘（例如，16 个 rank → 在 1 TB NVMe 上显示约 32 TB）。磁盘填满时卸载仍会失败，但监控看起来正常。在生产使用前，请将其设置为实际的每个 rank 预算。

由于每个 TP rank 在 rank_0/ 下使用独立的 SSD 子目录（rank_1/、ssd_offload_path、...），所有 rank 共享同一物理磁盘。为防止单个 rank 消耗过多空间，请设置显式的每个 rank 配额。例如，对于 800 GB 磁盘和 8 个 TP rank：

# 800 GB total disk, 8 ranks, ~100 GB per rank
export MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES=$((100 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE=$((100 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY=lru
export MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES=1073741824   # 1 GB

使用 Memcache 作为 KV Pool 后端的示例

安装 Memcache

MemCache 依赖于 MemFabric。因此，必须先安装 MemFabric。在安装 MemFabric 之后安装 Memcache。

pip install memfabric-hybrid
pip install memcache-hybrid

配置 Memcache 配置文件

mmc-meta.conf：

ock.mmc.meta_service_url = tcp://xx.xx.xx.xx:5000
ock.mmc.meta_service.config_store_url = tcp://xx.xx.xx.xx:6000
ock.mmc.log_level = error

mmc-local.conf：

ock.mmc.meta_service_url = tcp://xx.xx.xx.xx:5000
ock.mmc.local_service.config_store_url = tcp://xx.xx.xx.xx: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 = 1GB

关键要点：

参数	描述
ock.mmc.meta_service_url	配置master节点的IP地址和端口号。P节点和D节点的IP地址和端口号可以相同。
ock.mmc.local_service.config_store_url	配置master节点的IP地址和端口号。P节点和D节点的IP地址和端口号可以相同。
ock.mmc.local_service.world_size	本地服务的总数，包括将来会添加的服务。
ock.mmc.local_service.protocol	device_rdma（当设备ROCE可用时，A2和A3支持，推荐用于A2），device_sdma（当HCCS可用时，A3支持，推荐用于A3）。当前不支持异构协议设置。
ock.mmc.local_service.dram.size	设置master占用的内存大小。配置的值是每张卡占用的内存大小。

运行 Memcache Master

启动 MetaService 服务。

export MMC_META_CONFIG_PATH=/usr/local/memcache_hybrid/latest/config/mmc-meta.conf

python -c "from memcache_hybrid import MetaService; MetaService.main()"

PD 分离场景

1. 运行 prefill 节点和 decode 节点

使用 MultiConnector 同时利用 MooncakeConnectorV1 和 AscendStoreConnector。MooncakeConnectorV1 执行 kv_transfer，而 AscendStoreConnector 启用 KV Cache Pool

800I A2/800T A2/800I A3/800T A3 系列

run_prefill.sh/run_decode.sh：

#!/bin/bash

ROLE="prefill"              # prefill / decode
HARDWARE_SERIES="A2"        # A2 (800I/800T A2) or A3 (800I/800T A3)
LOCAL_IP="xx.xx.xx.xx"
NIC_NAME="xxxxxx"

MODEL_PATH="xxxxxxx/Qwen3-32B"
SERVED_MODEL_NAME="qwen3"
DATA_PARALLEL_SIZE=1
TENSOR_PARALLEL_SIZE=8
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7

export MMC_LOCAL_CONFIG_PATH=/home/memcache/mmc-local.conf

if [ "$ROLE" == "prefill" ]; then
    KV_ROLE="kv_producer"
    KV_PORT="20001"
    LOOKUP_RPC_PORT="0"
else
    KV_ROLE="kv_consumer"
    KV_PORT="20002"
    LOOKUP_RPC_PORT="1"
fi

echo "Starting vLLM on Series: $HARDWARE_SERIES, Role: $ROLE"

rm -rf /root/ascend/log/*
rm -rf ./connector.log

if [ "$HARDWARE_SERIES" == "A2" ]; then
    echo 200000 > /proc/sys/vm/nr_hugepages
    export HCCL_IF_IP=$LOCAL_IP
    export GLOO_SOCKET_IFNAME=$NIC_NAME
    export TP_SOCKET_IFNAME=$NIC_NAME
    export HCCL_SOCKET_IFNAME=$NIC_NAME

elif [ "$HARDWARE_SERIES" == "A3" ]; then
    export ACL_OP_INIT_MODE=1
else
    echo "Error: Invalid HARDWARE_SERIES. Set to 'A2' or 'A3'."
    exit 1
fi

source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

export PYTHONHASHSEED=0
export HCCL_BUFFSIZE=1024
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=10
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export VLLM_USE_V1=1

KV_CONFIG='{
  "kv_connector": "MultiConnector",
  "kv_role": "'$KV_ROLE'",
  "kv_connector_extra_config": {
    "connectors": [
      {
        "kv_connector": "MooncakeConnectorV1",
        "kv_role": "'$KV_ROLE'",
        "kv_port": "'$KV_PORT'",
        "kv_connector_extra_config": {
          "prefill": {
            "dp_size": '$DATA_PARALLEL_SIZE',
            "tp_size": '$TENSOR_PARALLEL_SIZE'
          },
          "decode": {
            "dp_size": '$DATA_PARALLEL_SIZE',
            "tp_size": '$TENSOR_PARALLEL_SIZE'
          }
        }
      },
      {
        "kv_connector": "AscendStoreConnector",
        "kv_role": "'$KV_ROLE'",
        "kv_connector_extra_config": {
          "backend": "memcache",
          "lookup_rpc_port": "'$LOOKUP_RPC_PORT'"
        }
      }
    ]
  }
}'

CMD_ARGS=(
  --model "$MODEL_PATH"
  --served-model-name "$SERVED_MODEL_NAME"
  --trust-remote-code
  --enforce-eager
  --data-parallel-size "$DATA_PARALLEL_SIZE"
  --tensor-parallel-size "$TENSOR_PARALLEL_SIZE"
  --port 30050
  --max-num_seqs 20
  --max-model-len 32768
  --max-num-batched-tokens 16384
  --gpu-memory-utilization 0.9
  --kv-transfer-config "$KV_CONFIG"
)

python -m vllm.entrypoints.openai.api_server "${CMD_ARGS[@]}" > log_${ROLE}.log 2>&1

echo "vLLM started. Log file: log_${ROLE}.log"

2. 启动 proxy_server

请参考 MooncakeStore 部署章节中的 启动 proxy_server。

3. 运行推理

请参考 MooncakeStore 部署章节中的 运行推理。

PD 混合场景

1. 运行混合部署脚本

800I A2/800T A2/800I A3/800T A3 系列

Run_pd_mix.sh：

#!/bin/bash

HARDWARE_SERIES="A2"        # A2 (800I/800T A2) or A3 (800I/800T A3)
LOCAL_IP="xx.xx.xx.xx"
NIC_NAME="xxxxxx"

MODEL_PATH="xxxxxxx/Qwen3-32B"
SERVED_MODEL_NAME="qwen3"
DATA_PARALLEL_SIZE=1
TENSOR_PARALLEL_SIZE=8
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7

export MMC_LOCAL_CONFIG_PATH=/home/memcache/mmc-local.conf

echo "Starting vLLM on Series: $HARDWARE_SERIES"

rm -rf /root/ascend/log/*
rm -rf ./connector.log

if [ "$HARDWARE_SERIES" == "A2" ]; then
    echo 200000 > /proc/sys/vm/nr_hugepages
    export HCCL_IF_IP=$LOCAL_IP
    export GLOO_SOCKET_IFNAME=$NIC_NAME
    export TP_SOCKET_IFNAME=$NIC_NAME
    export HCCL_SOCKET_IFNAME=$NIC_NAME

elif [ "$HARDWARE_SERIES" == "A3" ]; then
    export ACL_OP_INIT_MODE=1
else
    echo "Error: Invalid HARDWARE_SERIES. Set to 'A2' or 'A3'."
    exit 1
fi

source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

export PYTHONHASHSEED=0
export HCCL_BUFFSIZE=1024
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=10
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export VLLM_USE_V1=1

KV_CONFIG='{
  "kv_connector": "AscendStoreConnector",
  "kv_role": "kv_both",
  "kv_connector_extra_config": {
     "backend": "memcache",
     "lookup_rpc_port": "0"
  }
}'

CMD_ARGS=(
  --model "$MODEL_PATH"
  --served-model-name "$SERVED_MODEL_NAME"
  --trust-remote-code
  --enforce-eager
  --data-parallel-size "$DATA_PARALLEL_SIZE"
  --tensor-parallel-size "$TENSOR_PARALLEL_SIZE"
  --port 30050
  --max-num_seqs 20
  --max-model-len 32768
  --max-num-batched-tokens 16384
  --gpu-memory-utilization 0.9
  --kv-transfer-config "$KV_CONFIG"
)

python -m vllm.entrypoints.openai.api_server "${CMD_ARGS[@]}" > log_mix.log 2>&1

echo "vLLM started. Log file: log_mix.log"

2. 运行推理

使用 Yuanrong 作为 KV Pool 后端的示例

• 软件：
  • 在所有节点上安装 openyuanrong-datasystem（必须可导入 yr.datasystem）。

安装 Yuanrong Datasystem

pip install openyuanrong-datasystem

如果预构建的软件包与您环境中的 CANN 或 Ascend 驱动版本不匹配，请在 vLLM Ascend 镜像中从源码构建 Yuanrong Datasystem。请遵循 Yuanrong Datasystem 的官方构建说明： https://atomgit.com/openeuler/yuanrong-datasystem

启动 etcd

Yuanrong Datasystem 使用 etcd 进行服务发现。以下示例 启动一个单节点 etcd 集群：

ETCD_VERSION="v3.5.12"
ETCD_IP="127.0.0.1"
if [ "$(uname -m)" = "aarch64" ]; then
  ETCD_ARCH="linux-arm64"
else
  ETCD_ARCH="linux-amd64"
fi
wget https://github.com/etcd-io/etcd/releases/download/${ETCD_VERSION}/etcd-${ETCD_VERSION}-${ETCD_ARCH}.tar.gz
tar -xvf etcd-${ETCD_VERSION}-${ETCD_ARCH}.tar.gz
cd etcd-${ETCD_VERSION}-${ETCD_ARCH}
sudo cp etcd etcdctl /usr/local/bin/

etcd \
  --name etcd-single \
  --data-dir /tmp/etcd-data \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://${ETCD_IP}:2379 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-advertise-peer-urls http://${ETCD_IP}:2380 \
  --initial-cluster etcd-single=http://${ETCD_IP}:2380 &

etcdctl --endpoints "${ETCD_IP}:2379" put key "value"
etcdctl --endpoints "${ETCD_IP}:2379" get key

对于生产环境，请参考官方 etcd 集群 文档：https://etcd.io/docs/v3.7/op-guide/clustering/

启动 Datasystem Worker

使用 dscli 在每个节点上启动一个 Datasystem 工作进程。以下 配置是针对高吞吐量 KV Pool 工作负载的推荐起点：

WORKER_LOG_DIR="/var/log/yuanrong/worker"
sudo mkdir -p "${WORKER_LOG_DIR}"
sudo chown "$(id -u):$(id -g)" "${WORKER_LOG_DIR}"

dscli start -w \
  --worker_address "${WORKER_IP}:31501" \
  --etcd_address "${ETCD_IP}:2379" \
  --log_dir "${WORKER_LOG_DIR}" \
  --shared_memory_size_mb 40960 \
  --arena_per_tenant 1 \
  --enable_huge_tlb true \
  --enable_fallocate false \
  --rpc_thread_num 64 \
  --oc_thread_num 64 \
  --enable_worker_worker_batch_get true \
  --sc_regular_socket_num 0 \
  --sc_stream_socket_num 0

--worker_address 的值稍后会被 DS_WORKER_ADDR 使用，因此请确保 同一节点上的主机和端口保持一致。

上述调优参数具有以下效果：

参数	描述
log_dir	设置Datasystem工作进程日志目录。启动前创建该目录并授予工作进程写入权限。
arena_per_tenant=1	每个租户使用一个共享内存区域，作为内存和文件描述符使用的保守起点。
enable_huge_tlb=true	使用HugeTLB页面支持工作进程共享内存。在启动工作进程前预留足够的2 MiB大页。
enable_fallocate=false	禁用共享内存文件的fallocate；将此设置与上述HugeTLB配置一起使用。
rpc_thread_num=64	设置RPC/ZMQ服务的并发数。
oc_thread_num=64	设置对象缓存业务线程池大小。
enable_worker_worker_batch_get=true	启用 Datasystem 工作节点之间的批量对象缓存读取。
sc_regular_socket_num=0, sc_stream_socket_num=0	禁用流缓存服务。两个值都必须大于零才能启用；当 KV Pool 不使用流缓存时，请将其保持为零。

对于 shared_memory_size_mb=40960，请预留至少 20480 个 2 MiB 大页，并 在启动工作进程前验证其可用性：

grep -E "HugePages_Total|HugePages_Free|Hugepagesize" /proc/meminfo

工作进程日志（包括通常以 datasystem_worker 为基本名称的文件）会写入 --log_dir 目录。请使用绝对路径，以确保日志位置不依赖于工作进程的 当前目录。

这些线程数是调优起点，而非通用默认值。请根据可用的 CPU 核心数和测量的请求 吞吐量进行调整。由于 -w 会消耗剩余的命令行参数，请将任何 dscli start 选项（如 --timeout）放在 -w 之前。

更多参数，请参阅元戎 Datasystem 官方网站上的 dscli 使用文档： https://atomgit.com/openeuler/yuanrong-datasystem

停止工作进程：

dscli stop --worker_address "${WORKER_IP}:31501"

环境变量配置

在启动 vLLM 之前，在每个节点上设置以下环境变量：

变量	是否必需	默认值	描述
PYTHONHASHSEED	是	0	所有节点必须保持一致，以确保生成统一的哈希值。
DS_WORKER_ADDR	是	不适用	Datasystem 工作节点地址，格式为 <host>:<port>。此值必须与本地 dscli start --worker_address 的值一致。
DATASYSTEM_CLIENT_LOG_DIR	否	~/.datasystem/logs	vLLM 进程创建的元融客户端 SDK 日志目录。请使用与工作节点日志不同的目录。
DS_ENABLE_EXCLUSIVE_CONNECTION	否	0	传递给元融 HeteroClient.enable_exclusive_connection。当部署需要时，使用 1 启用独占连接模式。
DS_ENABLE_REMOTE_H2D	否	0	传递给元融 HeteroClient.enable_remote_h2d。仅在满足以下远程 H2D 要求后使用 1。

export PYTHONHASHSEED=0
export DS_WORKER_ADDR="${WORKER_IP}:31501"
export DATASYSTEM_CLIENT_LOG_DIR="/var/log/yuanrong/client"
export DS_ENABLE_EXCLUSIVE_CONNECTION=0
export DS_ENABLE_REMOTE_H2D=0

mkdir -p "${DATASYSTEM_CLIENT_LOG_DIR}"

请在启动 vLLM 之前设置 DATASYSTEM_CLIENT_LOG_DIR，因为元戎 客户端在日志初始化期间会读取该变量。客户端 SDK 日志（通常以 ds_client 为基本名称）会写入此目录。

远程 H2D 要求

仅在元戎 Datasystem 部署中启用并验证了远程主机到设备传输时，才设置 DS_ENABLE_REMOTE_H2D=1：

• 在启动工作进程前预留足够的 2 MiB HugeTLB 页。对于 40 GiB 共享内存，请预留至少 20480 个 2 MiB 大页。
• 以启用远程 H2D 的方式启动每个 Datasystem 工作进程。工作进程启动 命令必须包含 --remote_h2d_device_ids、--enable_huge_tlb true、 --arena_per_tenant 1 和 --enable_fallocate false。建议使用多个 可用的 NPU 设备 ID，例如在 8-NPU 节点上使用 "0,1,2,3,4,5,6,7"。

dscli start -w \
  --worker_address "${WORKER_IP}:31501" \
  --etcd_address "${ETCD_IP}:2379" \
  --log_dir "/var/log/yuanrong/worker" \
  --shared_memory_size_mb 40960 \
  --arena_per_tenant 1 \
  --enable_huge_tlb true \
  --enable_fallocate false \
  --rpc_thread_num 64 \
  --oc_thread_num 64 \
  --enable_worker_worker_batch_get true \
  --sc_regular_socket_num 0 \
  --sc_stream_socket_num 0 \
  --remote_h2d_device_ids "0,1,2,3,4,5,6,7"

• 确保元戎远程 H2D 所需的 NPU 驱动、固件和 CANN 工具包已安装且对工作进程可见。在容器中， 挂载 Ascend 驱动路径、npu-smi、hccn_tool、/etc/hccn.conf、 /etc/ascend_install.info 以及所需的 /dev/davinci* 设备。
• 在启用客户端标志前验证 NPU 和 RoCE 环境：

# Check the current 2 MiB HugeTLB page size, total count, and free count.
grep -E "HugePages_Total|HugePages_Free|Hugepagesize" /proc/meminfo

# Optional: check 2 MiB HugeTLB pages on each NUMA node.
for node in /sys/devices/system/node/node*/hugepages/hugepages-2048kB; do
  echo "$node total=$(cat "$node/nr_hugepages") free=$(cat "$node/free_hugepages")"
done

# Check that NPU devices and the driver are visible to the worker environment.
npu-smi info

# Check that the NPU topology is visible.
npu-smi info -t topo

# Check optical module detection on the selected local NPU.
hccn_tool -i <local_npu_id> -optical -g

# Check RoCE physical link status. The expected link status is UP.
for i in {0..7}; do hccn_tool -i $i -link -g; done

# Check the selected NPU IP address and reachability to the remote NPU.
hccn_tool -i <local_npu_id> -ip -g
hccn_tool -i <local_npu_id> -ping -g address <remote_npu_ip>

如果这些检查失败，请保持 DS_ENABLE_REMOTE_H2D=0 并使用默认的 Datasystem 传输路径。

使用元戎后端运行 AscendStoreConnector

使用 AscendStoreConnector 并设置 backend: "yuanrong"：

python3 -m vllm.entrypoints.openai.api_server \
    --model /xxxxx/Qwen2.5-7B-Instruct \
    --port 8100 \
    --trust-remote-code \
    --enforce-eager \
    --no-enable-prefix-caching \
    --tensor-parallel-size 1 \
    --data-parallel-size 1 \
    --max-model-len 10000 \
    --block-size 128 \
    --max-num-batched-tokens 4096 \
    --kv-transfer-config \
    '{
    "kv_connector": "AscendStoreConnector",
    "kv_role": "kv_both",
    "kv_load_failure_policy": "recompute",
    "kv_connector_extra_config": {
        "lookup_rpc_port": "1",
        "backend": "yuanrong"
    }
}'

lookup_rpc_port 是池化调度进程与工作进程之间使用的 RPC 端口。 每个实例必须使用唯一的端口值。

注意事项

• 元戎后端在调用 Datasystem 之前会对 KV 键进行规范化。支持的最长 1024 字节的 ASCII 键会被保留。更长的键或包含不支持字符的键会被重写为最多 1024 个字符并附加 哈希后缀，因此在调试后端存储时不要依赖原始键字符串。
• 元戎不需要额外的缓冲区预注册步骤。后端在构建 blob 列表时直接使用设备指针。

2. 运行推理

常见问题

1. Mooncake 常见问题

1.1 放置/获取键失败

当 vLLM 报告 put 或 get 操作失败时，首先检查该错误是否由 Mooncake 自身报告。

• 如果错误由 Mooncake 报告：
  • 对于 put 失败，检查 Mooncake 日志是否包含 NO_AVAILABLE_HANDLE 或 BatchPut failed ... due to insufficient space。这通常意味着驱逐后剩余空间不足以容纳一个 BatchPut 请求。请确保驱逐策略留下的空间（例如，1 - eviction_ratio 隐含的容量）能够容纳一次批量 put，或者考虑增加可用容量、增加驱逐余量或减小批量大小。
  • 对于 get 失败，检查 Mooncake 日志是否包含 lease_expired_before_data_transfer_completed key=... 或返回 LEASE_EXPIRED。这意味着 KV 对象租约在数据传输完成前已过期。根据需要增加 --default_kv_lease_ttl 的 mooncake_master，并确保其大于 ASCEND_CONNECT_TIMEOUT 和 ASCEND_TRANSFER_TIMEOUT。
• 如果错误不是由 Mooncake 报告，则很可能是 HIXL (ascend_direct) 传输层问题。收集 /root/ascend/log/debug/plog 下的 plog 文件，并检查该问题是否与已知的 HIXL 问题匹配。

有关 HIXL (ascend_direct) 的常见故障排除和问题定位指南，请参阅： https://gitcode.com/cann/hixl/wiki/HIXL%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98%E5%AE%9A%E4%BD%8D%E6%89%8B%E5%86%8C.md

1.2 SSD 常见问题

1.2.1 SSD 卸载时的 SEGMENT_NOT_FOUND

如果客户端日志显示 OffloadObjectHeartbeat failed, error code is SEGMENT_NOT_FOUND，则 Master 已卸载该 rank 的 LOCAL_DISK 段（通常在 Ping 停止刷新 TTL 导致 client_expired 之后）。该 rank 上的 SSD 卸载将停止，直到该段被重新注册。

典型触发条件（当 enable_cpu_binding=true 时）： Mooncake 在初始化期间启动 Ping，然后 vLLM-Ascend 的 bind_cpus() 运行 migratepages/IRQ 绑定；Ping 线程未被绑定，因此在默认 client_ttl=10 下可能会错过心跳。

缓解措施	备注
临时方案： 提高 Master TTL	例如 mooncake_master ... --client_ttl=120。根据您的初始化/预热窗口进行调整（通常 60–120 就足够了）。不能解决根本原因。
恢复方案： 升级 Mooncake	> v0.3.11 版本（主分支）可以在 LOCAL_DISK 后重新挂载 SEGMENT_NOT_FOUND 并重新扫描元数据。这可以在清理后**恢复**；但不能防止元数据丢失期间的过期或正在处理的请求失败。
根本修复： Mooncake Ping CPU 亲和性	将存储 Ping 线程绑定到一个释放/隔离的 CPU（Mooncake 侧更改）。可选地，vLLM-Ascend 协作以传递每个 rank 的释放 CPU。

同时重启 Master 和 vLLM，以避免在调试重启时出现陈旧的 segment_already_exists 状态。

1.2.2 Fabric 内存大小对齐 (A3 + ASCEND_ENABLE_USE_FABRIC_MEM=1)

在启用了 fabric 内存的 A3 上，每次 fabric 内存分配必须是 1 GB（1073741824 字节）的整数倍。Mooncake 不会自动向上取整大小。

参数	配置来源	对齐方式
global_segment_size	mooncake.json 或导出 MOONCAKE_GLOBAL_SEGMENT_SIZE	每个 rank 的段大小必须与 1GB 对齐（例如 "1GB"、"20GB"）。
MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES	导出 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES（仅在 enable_ssd_offload=true 时）	必须与 1GB 对齐。默认值为 1280 MB（1.25 GB），该值**未**对齐，且对于长上下文 SSD 负载来说太小——请根据调整 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 大小进行设置。

local_buffer_size 中的 mooncake.json 在 fabric 内存模式下**不**使用（vLLM-Ascend 向 0 传递 setup()）。

未对齐的风险： adxl MallocMem / aclrtMapMem 失败并返回 Invalid_Argument。启用 SSD 卸载后，MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 分配失败可能导致 FileStorage 初始化期间出现段错误并中止 vLLM 启动。避免使用诸如 "1280MB"、"512MB" 或 "1.5GB" 之类的值。

Fabric 内存配额： global_segment_size 和 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 都是**每个 rank** 独立的 fabric 内存分配。它们的大小累加后受限于通过 ASCEND_GLOBAL_RESOURCE_CONFIG 配置的 HIXL fabric 内存限制（例如 "fabric_memory.max_capacity":32，单位 GB/进程 — 请参阅 HIXL 文档）。每个 rank 的大致预算：

fabric_memory.max_capacity  ≥  global_segment_size + MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES  (+ headroom)

配额过低的風險： 某些 rank 在 Memory_Allocation_Failure(EL0004) 成功但 global_segment_size 分配失败时，会报错 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES。请增加 fabric_memory.max_capacity，减小 global_segment_size 或 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES，或确保节点有足够的主机内存。

示例（在 SSD 卸载开启时，添加到您的 vLLM 启动脚本中）：

export ASCEND_ENABLE_USE_FABRIC_MEM=1
export MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES=1073741824   # 1 GB, fabric-mem aligned

仅在 fabric 内存过低时设置 ASCEND_GLOBAL_RESOURCE_CONFIG。

# Per-rank fabric mem budget: 20 GB segment + 1 GB MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES → set max_capacity ≥ 22 (GB)
export ASCEND_GLOBAL_RESOURCE_CONFIG='{"fabric_memory.max_capacity":32}'

1.2.3 调整 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 大小

当 enable_ssd_offload=true 时，Mooncake 会分配一个**独立的、每个 rank 的 SSD 读/写缓冲区**，其大小由 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 决定。此缓冲区**独立于** global_segment_size 中的 mooncake.json — 增加段大小并**不能**解决由 BUFFER_OVERFLOW 过小导致的 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 问题。

如果缓冲区太小，SSD 读取会在 BUFFER_OVERFLOW 期间失败并返回 error_code=-10 (FileStorage::AllocateBatch)，并且当 kv_load_failure_policy=fail 时，vLLM 可能会失败。

如果在使用过程中遇到 BUFFER_OVERFLOW，请尝试增大 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES。不要将其设置为高于 vLLM 工作进程日志中显示的 可用 KV 缓存内存 值：

(Worker_TP0_EP0 pid=21240) INFO 06-23 17:41:09 [worker.py:552] Available KV cache memory: XX

示例：

export MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES=10737418240   # 10 GB

请**仅使用字节字面量**（10737418240）。10G / 10GB 将被忽略并回退到 1280 MB 的默认值。

说明

* `--max-num-batched-tokens` 仅对预填充计算进行分块；它**不会**减少 `MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES` 所需的内存。

主机内存预算（单节点）

MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 是**按 rank** 分配的，除此之外还有 global_segment_size：

host_memory_for_mooncake ≈ TP × (global_segment_size + MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES + local_buffer_size)

确保主机上 free -h 的**可用**内存超过此总和加上 vLLM 的开销。MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 不需要 适应 global_segment_size。

调优后验证

1. 启动时：每个 rank 会记录 AlignedClientBufferAllocator: allocated <N> bytes，其中包含您配置的大小。
2. 负载下：没有 BUFFER_OVERFLOW / Failed to get ... keys out of ... error_codes=[-10]。
3. 如果使用大缓冲区时故障仍然存在，请检查重叠加载（load_async）。

2. Memcache 常见问题

有关 Memcache 的故障排除，请参阅： https://gitcode.com/Ascend/memcache/wiki/FAQ.md

3. DSv4 已知问题（临时）

有关临时的 DSv4 已知问题，请参阅： https://github.com/vllm-project/vllm-ascend/issues/9975