跳转至

KV Cache 池(Ascend Store)

特性介绍

KV Cache Pool(Ascend Store)是 vLLM-Ascend 提供的跨节点 KV Cache 池化存储特性。它通过 AscendStoreConnector 将 KV Cache 写入外部存储后端(Mooncake / Memcache / Yuanrong),并与 PD(Prefill/Decode)分离架构配合,在多个 vLLM 实例之间共享和复用 KV Cache,避免相同前缀的重复计算。

主要优势包括:在 PD 分离部署中实现 Prefill 与 Decode 节点的内存解耦并支持独立扩缩容;跨请求/跨节点的 KV 复用减少冗余的 Prefill 计算;支持 SSD Offload 以扩展 KV 容量;以及传输 QoS 优先级控制。

自 vLLM-Ascend v0.23.0 起支持(推荐使用最新版本)。

使用场景

KV Cache 支持以下三种外部存储后端,请根据业务需求选择合适的存储后端:

场景 选择建议
Mooncake 后端 默认后端。Mooncake 是 Moonshot AI 开源的面向 LLM 推理的分布式 KVCache 系统;当需要 SSD Offload 扩展 KV 容量或多租户配额管理时选择它。
Memcache 后端 基于 MemFabric;当需要 A3 HCCS 高速互联以降低传输时延,或需要逐层 KV 传输(use_layerwise)时选择它。
Yuanrong 后端 基于 openyuanrong-datasystem(openEuler 开源的训推一体的分布式基础软件);当需要多节点部署、Remote H2D 传输或与 openEuler 生态集成时选择它。

约束与限制

通用

类别 约束
硬件 支持的硬件为 A2/A3/Ascend 950PR&950DT系列产品。
软件依赖 各系列的 HDK/CANN 要求请参见 HDK 与 CANN 版本配套关系参考。
模型 kv_load_failure_policy=recompute 尚不支持混合注意力模型(例如 DeepSeekV4、Qwen 3.5)。
特性互斥 use_layerwise 仅在 Mooncake/Memcache 后端的 Prefill 节点上支持。

后端特定

类别 约束
软件依赖 • Mooncake >= 0.3.11.post1(非默认租户要求 >= 0.3.12)。
• Mooncake wheel 要求 glibc >= 2.35。
• Layerwise 支持要求 Mooncake >= 0.3.14。
部署 同时支持 PD 分离和 PD 混合场景,Store/PD 流量分离适用于 A3 和 Ascend 950PR&950DT系列产品。
类别 约束
软件依赖 • 需要 memfabric-hybrid >= 1.3.0 和 memcache-hybrid >= 1.3.0。
• 在 A3 上,使用 device_sdma 协议需要 LingQu Computing Network >= 1.5。
部署 同时支持 PD 分离和 PD 混合场景。MemCache 与 vLLM 分离部署仅在 A3 上支持。
类别 约束
软件依赖 需要 openyuanrong-datasystem
特性互斥 • Worker 不能同时配置 Coordinator 和 etcd 两种发现后端。
• 在 P2P_TRANSFER 或 FabricMem 模式下,无论 enable_dev_mem_pregister 取值如何,客户端设备内存预注册都会被跳过。

升级使用跨步 MLA 缓存的池

当调度器块包含多个内核块且各内核块的有效载荷之间存在间隙时,批量池化和分层池化会在独立的物理块段中传输 MLA 组件。各组件在每个物理块内必须连续。部分分层传输仅复制每个段所覆盖的 token 区间。密集缓存布局保留其现有的打包表示。

由旧版连续区间实现写入的池对象,对于受影响的布局,与修正后的表示不兼容,即使其总字节大小未变。请同时升级所有写入方和读取方,并使受影响的池条目失效,或使用全新的缓存命名空间。对于请求级隔离,请对需要共享缓存前缀的请求一致地使用新的 cache_salt。仅重启 vLLM worker 并不会使已持久化的池对象失效。

对于非分层完整块传输,共享同一后备存储的相邻 MLA 组件会合并为每个物理页一个描述符;当各页之间没有间隙时,则合并为每个逻辑块一个描述符。填充内容永远不会被复制。分层传输、部分块配置、对齐状态组、解码缓存保存、TP 不匹配、DCP 和 KVPP 仍保留组件段回退方案。注册日志会报告每个合并后的层及其描述符数量。

此批量快速路径使用以物理页为主序的对象内容,而非之前的以组件为主序的分段内容。即使是从此修复的早期分段版本升级,也需要使用全新的命名空间。写入方和读取方必须在传输模式和缓存布局上保持一致;请勿将这些对象与分层读取方或使用不同组件布局的 worker 共享。

前缀缓存保留

使用上游 vLLM 参数 --prefix-cache-retention-interval 配置保留策略。 昇腾混合 HBM 协调器以及 AscendStore 调度器/工作器使用解析后的 配置。原有的 VLLM_PREFIX_CACHE_RETENTION_INTERVAL 环境变量 已从 vLLM 中移除,不再用于配置保留策略。

取值 滑动窗口 / Mamba 检查点保留
0(上游默认值) 保留提示重放所需的检查点,不保留周期性检查点。
正整数,例如 4096 同时保留周期性检查点;该间隔必须是调度器块大小的整数倍。
None 密集保留所有可达的检查点。

全注意力组仍保持其密集前缀缓存行为。该设置控制的是 检查点保留策略,而非所配置的 HBM 或外部池容量。从旧的环境变量读取方式 升级时,如需保持密集保留,请显式传入 --prefix-cache-retention-interval None;省略该参数则选择 0。 如需迁移原本设定的间隔 4096,请在之前导出该环境变量的 相同实例上传入 --prefix-cache-retention-interval 4096。

场景 1:Mooncake 后端

配置示例

环境准备

  1. 确认环境中存在 hccn.conf。使用 Docker 时,请将其挂载到容器中:

    cat /etc/hccn.conf
    

    Ascend 950PR&950DT系列产品需要额外挂载设备和配置:/dev/ummu、/dev/uburma、/usr/bin/urma_admin、/lib/route.conf、/etc/hccl_rootinfo.json。

  2. 在所有节点间同步 PYTHONHASHSEED:

    export PYTHONHASHSEED=0
    

步骤 1:软件安装

  1. 检查 Mooncake wheel 依赖(glibc 版本要求请参见约束与限制中的软件依赖):

    ldd --version
    
  2. vllm-ascend Docker 镜像已安装 Mooncake。请验证安装:

    python3 -m pip show mooncake-transfer-engine-npu
    

步骤 2:配置 mooncake.json 并启动 mooncake_master

以下 Mooncake 指南为可选的深入参考资料;不阅读它们也可以完成本文档中的部署:

  • Mooncake Store 部署指南:关于 Mooncake Store 部署架构与运维的深入参考,在自定义部署拓扑或排查 Store 层问题时很有用
  • SSD Offload:SSD Offload 容量规划与淘汰策略的高级配置参考
  1. 配置 mooncake.json,并将 MOONCAKE_CONFIG_PATH 指向其完整路径:

    {
        "metadata_server": "P2PHANDSHAKE",
        "protocol": "ascend",
        "device_name": "",
        "master_server_address": "<master_ip>:50088",
        "global_segment_size": "1GB",
        "preferred_segment": false,
        "prefer_alloc_in_same_node": true,
        "enable_ssd_offload": false,
        "ssd_offload_path": "/nvme/mooncake_offload",
        "tenant_id": "default"
    }
    

    mooncake.json 参数

    参数 类型 默认值 是否必填 取值范围 描述
    metadata_server str 无默认值 是 P2PHANDSHAKE 配置为 P2PHANDSHAKE。
    protocol str 无默认值 是 ascend 在 NPU 上必须设置为 ascend。
    device_name str ""(空字符串) 否 空字符串 Ascend 协议不使用设备名称;留空即可。
    master_server_address str 无默认值 是 : Master 服务 IP 和端口。可通过 MOONCAKE_MASTER 环境变量覆盖(优先级更高,适用于通过 Kubernetes 注入 master 地址)。
    global_segment_size str 无默认值 是 必须按 1 GB 对齐(1024 MB / 1048576 KB / 1073741824 B) 每张卡注册到 KV Pool 的内存大小。可通过 MOONCAKE_GLOBAL_SEGMENT_SIZE 环境变量覆盖(优先级更高)。
    preferred_segment bool false 否 true / false 是否优先将 KV 存储在本地 segment。
    prefer_alloc_in_same_node bool true 否 true / false 是否优先在同一节点上分配 KV。
    enable_ssd_offload bool false 否 true / false 是否启用 SSD offload。不支持通过环境变量配置。
    ssd_offload_path str 无默认值 启用 SSD offload 时必填 绝对路径 SSD offload 数据存储的绝对路径(例如 /nvme/mooncake_offload)。该目录必须存在且 vLLM 进程可写;请在启动前创建(mkdir -p <path>)。相对路径、符号链接以及包含 .. 的路径将被拒绝。
    enable_ssd_prefetch bool false 否 true / false 在 exist 查询时启用 SSD 到 DRAM 预取的总开关。由 Mooncake PR 4272 实现;该想法来自 RFC 2213。当为 true 时,batch_is_exist 会传入 ExistOptions(prefetch_to_memory=True),使 Mooncake 在缓存探测期间将仅存在于 SSD 的对象提升到 DRAM。需要 enable_ssd_offload=true 以及暴露 ExistOptions 的 Mooncake 构建。如果缺少 ExistOptions,预取将被禁用并记录一条警告。
    ssd_prefetch_cooldown_sec int 省略 否 整数秒;0 表示禁用 DRAM 压力退避。当提升操作因 NO_AVAILABLE_HANDLE 失败后,预取会暂停这么多秒,以便驱逐和卸载释放 DRAM。省略此字段时,Mooncake 的内置默认值为 5。vLLM-Ascend 仅在 mooncake.json 设置该字段时才转发它。
    ssd_prefetch_dedup_ttl_sec int 省略 否 整数秒;0 表示禁用 按 key 的触发去重 TTL。同一个 key 在此周期内最多预取一次,从而抑制跨 TP rank 的重复探测。省略此字段时,Mooncake 的内置默认值为 30。仅在设置时才转发。
    tenant_id str default 否 字符串 Mooncake 租户命名空间。缺失、null、空值或仅含空白字符的值将使用 default;首尾空白字符会被移除。所有共享 KV 条目的 Prefill、Decode、调度器和副本实例必须使用相同的租户 ID。

    SSD 卸载与 SSD 预取是相互独立的。在 enable_ssd_offload 设为 true 后,将以下字段添加到同一个 mooncake.json 中,以便在 exist 时将仅存在于 SSD 的对象预取回 DRAM。语义与 Mooncake SSD 预取 一致(Mooncake PR 4272;概念来自 RFC 2213):

    {
        "enable_ssd_prefetch": true,
        "ssd_prefetch_cooldown_sec": 5,
        "ssd_prefetch_dedup_ttl_sec": 30
    }
    

    ssd_prefetch_cooldown_sec 和 ssd_prefetch_dedup_ttl_sec 仅在字段存在于 mooncake.json 中时才会转发给 MooncakeDistributedStore.setup()。省略某个字段将保留 Mooncake 的默认值(5 秒和 30 秒)。当 mooncake.json 设置了任意预取参数时,连接器会使用 setup() 的配置字典形式;该重载无法接收 engine,因此存储会创建自己的 TransferEngine,而不是共享全局的 TransferEngine。在不支持 ExistOptions 的 Mooncake 构建上,这些参数不会被传递,预取保持关闭。

  2. 启动 mooncake_master(只需在一个节点上运行):

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

    mooncake_master 参数

    参数 类型 默认值 是否必填 取值范围 描述
    port int 无默认值 是 端口号,必须与 mooncake.json 中 master_server_address 的端口一致 Master 服务监听端口。
    eviction_high_watermark_ratio float 无默认值 否 比例,[0, 1] Mooncake Store 执行驱逐的水位线。
    eviction_ratio float 无默认值 否 比例,[0, 1] 要驱逐的已存储对象比例。
    default_kv_lease_ttl int 无默认值 否 毫秒;必须大于 ASCEND_CONNECT_TIMEOUT 和 ASCEND_TRANSFER_TIMEOUT KV 对象的默认租约 TTL(毫秒)。
    enable_offload bool false 启用 SSD offload 时必填 true / false 设置为 true 以在 master 中启用 SSD offload。
    client_ttl int 10 否 整数(秒) 客户端在最后一次 Ping 后保持存活的秒数。参见“FAQ - 问题 2:SEGMENT_NOT_FOUND(SSD Offload)”。
    enable_multi_tenants bool false 否 true / false 启用严格多租户模式。
    tenant_quota_connector_type str 无默认值 启用多租户时必填 file / etcd 租户配额连接器类型。
    tenant_quota_connector_uri str 无默认值 启用多租户时必填 配额文件路径或 etcd 端点 租户配额文件路径或 etcd 端点。

步骤 3:(可选)多租户配置

  1. 要启用严格多租户隔离,请使用以下方式启动:

    mooncake_master \
        --port 50088 \
        --enable_multi_tenants=true \
        --tenant_quota_connector_type=file \
        --tenant_quota_connector_uri=/etc/mooncake/tenant_quotas.yaml
    

    租户配额文件示例(/etc/mooncake/tenant_quotas.yaml):

    version: 1
    
    tenants:
      - name: tenant-a
        quota: 200GB
      - name: tenant-b
        quota: 200GB
      - name: default
        quota: 100GB
    

    多租户模式说明:

    • 当严格多租户模式未启用时,租户 ID 在对象放置时会被忽略,对象仍保留在 default 命名空间中。
    • 严格模式会拒绝未注册租户(包括 default)的写入,因此 vLLM-Ascend 使用的每个租户都必须出现在策略中。
    • 当 Mooncake 使用 STORE_USE_ETCD=ON 构建时,文件连接器可以替换为 etcd;此时需将 tenant_quota_connector_uri 设置为 etcd 端点。
    • tenant_id 是实例级命名空间和配额标识,而非认证机制。能够访问 Mooncake 的客户端仍可声明租户 ID。即使启用了租户隔离,也应将不兼容的模型、模型版本、量化格式和 KV 布局放在不同的模型或发布命名空间中。
  2. Mooncake 通过 master 指标 HTTP 端口(默认 9003)暴露租户配额快照:

    curl -s http://<master_host>:9003/api/v1/tenant_quotas
    curl -s "http://<master_host>:9003/api/v1/tenant_quotas?tenant_id=tenant-a"
    

步骤 4:启动 vLLM 推理服务

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

  1. 对于 Atlas A3系列产品和 Ascend 950PR&950DT系列产品的 Store/PD 流量分离,请在 prefill 和 decode 节点上都设置 ASCEND_GLOBAL_RESOURCE_CONFIG。顶层资源配置控制 MooncakeConnectorV1 的 PD 流量,store 部分控制 AscendStoreConnector 的 Mooncake Store 流量,从而使这两类流量不会在同一物理链路上竞争。

    run_prefill.sh / run_decode.sh
    #!/bin/bash
    
    # prefill / decode
    ROLE="prefill"
    # A2 (800I/800T A2) or A3 (800I/800T A3) or 950PR&950DT Products
    HARDWARE_SERIES="A2"
    # Link type: ROCE or HCCS in A3 series.
    LINK_TYPE="ROCE"
    LOCAL_IP="<local_ip>"
    NIC_NAME="<nic_name>"
    
    MODEL_PATH="<model_path>/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
    
    # parameters required for kv pool and Mooncake
    export PYTHONHASHSEED=0
    export MOONCAKE_CONFIG_PATH="<config_dir>/mooncake.json"
    
    if [ "$ROLE" == "prefill" ]; then
        KV_ROLE="kv_producer"
        KV_PORT="20001"
        LOOKUP_RPC_PORT="0"
        API_PORT="8100"
    else
        KV_ROLE="kv_consumer"
        KV_PORT="20002"
        LOOKUP_RPC_PORT="1"
        API_PORT="8200"
    fi
    
    echo "Starting vLLM on Series: $HARDWARE_SERIES, Role: $ROLE"
    
    rm -rf /root/ascend/log/*
    rm -rf ./connector.log
    
    # See Configuration Parameters section for detailed parameter descriptions
    if [ "$HARDWARE_SERIES" == "A2" ] || { [ "$HARDWARE_SERIES" == "A3" ] && [ "$LINK_TYPE" == "ROCE" ]; }; 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
        export HCCL_INTRA_ROCE_ENABLE=1
    
    elif [ "$HARDWARE_SERIES" == "A3" ] && [ "$LINK_TYPE" == "HCCS" ]; then
        export ACL_OP_INIT_MODE=1
        export ASCEND_ENABLE_USE_FABRIC_MEM=1
    elif [ "$HARDWARE_SERIES" == "A5" ]; then
        # 950PR&950DT Products UBOE
        export ASCEND_GLOBAL_RESOURCE_CONFIG='{"comm_resource_config.protocol_desc":["uboe:device"]}'
        # 950PR&950DT Products UB
        export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}'
    else
        echo "Error: Invalid HARDWARE_SERIES. Set to 'A2', 'A3', or 'A5'."
        exit 1
    fi
    
    source /usr/local/Ascend/ascend-toolkit/set_env.sh
    source /usr/local/Ascend/nnal/atb/set_env.sh
    
    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": "mooncake",
              "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 "$API_PORT"
      --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(连接 Prefill 和 Decode 节点),将 localhost 替换为实际 IP 地址:

    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
    
  3. 要使 Decode 节点的 KV Cache 存储可供 MLA 模型的 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"
        }
    }
    
  4. 要在保持 Prefill 写入禁用的同时发布完整的 Decode 块,请在消费者端设置 save_decode_cache: true。首次 Decode 保存会检查对齐的、可达的 Prefill 前缀,并填充缺失的祖先块。后续保存会从 worker 上次成功的偏移量继续;失败的范围会在下一个完成块边界处重新检查。此模式要求非逐层传输。它会将 KV 写入 Store 以供复用,并且不会释放活动请求的 NPU KV。

    {
        "kv_connector": "AscendStoreConnector",
        "kv_role": "kv_consumer",
        "kv_load_failure_policy": "recompute",
        "kv_connector_extra_config": {
            "lookup_rpc_port": "0",
            "backend": "mooncake",
            "save_decode_cache": true
        }
    }
    

    当 Prefill 使用 PP 时,请按照前面的示例配置 prefill_pp_size 或 prefill_pp_layer_partition,以便 Decode 写入兼容的分区键。

pd_mix.sh
#!/bin/bash

# A2 (800I/800T A2) or A3 (800I/800T A3) or 950PR&950DT Products
HARDWARE_SERIES="A2"
# Link type: ROCE or HCCS in A3 series.
LINK_TYPE="ROCE"
LOCAL_IP="<local_ip>"
NIC_NAME="<nic_name>"

MODEL_PATH="<model_path>/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

# parameters required for kv pool and Mooncake
export PYTHONHASHSEED=0
export MOONCAKE_CONFIG_PATH="<config_dir>/mooncake.json"

echo "Starting vLLM on Series: $HARDWARE_SERIES"

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

# See Configuration Parameters section for detailed parameter descriptions
if [ "$HARDWARE_SERIES" == "A2" ] || { [ "$HARDWARE_SERIES" == "A3" ] && [ "$LINK_TYPE" == "ROCE" ]; }; 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
    export HCCL_INTRA_ROCE_ENABLE=1

elif [ "$HARDWARE_SERIES" == "A3" ] && [ "$LINK_TYPE" == "HCCS" ]; then
    export ACL_OP_INIT_MODE=1
    export ASCEND_ENABLE_USE_FABRIC_MEM=1
elif [ "$HARDWARE_SERIES" == "A5" ]; then
    # 950PR&950DT Products UBOE
    export ASCEND_GLOBAL_RESOURCE_CONFIG='{"comm_resource_config.protocol_desc":["uboe:device"]}'
    # 950PR&950DT Products UB
    export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}'
else
    echo "Error: Invalid HARDWARE_SERIES. Set to 'A2', 'A3', or 'A5'."
    exit 1
fi

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

KV_CONFIG='{
  "kv_connector": "AscendStoreConnector",
  "kv_role": "kv_both",
  "kv_connector_extra_config": {
    "backend": "mooncake",
    "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 8100
  --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"

注意: 对于启用了 ASCEND_BUFFER_POOL 的 MooncakeStore,建议在运行实际性能基准测试之前先执行预热阶段。由于 HCCS 单边通信连接是在实例启动后惰性创建的,全互联连接需要一次性开销(每个连接 4 MB 设备内存)。预热建议:输入序列长度 8k,输出序列长度 1,总请求数为设备数量的 2-3 倍。

# Example warm-up request
curl -s http://localhost:8100/v1/completions -H "Content-Type: application/json" -d '{ "model": "qwen3", "prompt": "Hello.", "max_completion_tokens": 1, "temperature":0.0 }'

上述脚本中使用的 kv_connector_extra_config 字段记录在 kv-transfer-config 通用参数中。

步骤 5:MooncakeStore SSD 卸载(嵌入式真实客户端模式)

在模式 A(嵌入式真实客户端)中,Mooncake 嵌入在 vLLM 中。当 vLLM 启动时,AscendStoreConnector/MooncakeBackend 会使用 mooncake.json 中的设置自动调用 MooncakeDistributedStore.setup(),无需单独的 mooncake_client 进程。

低驱逐水位线: 对于 100 GB 的 DRAM 池,eviction_high_watermark_ratio=0.5 会在 50 GB 时触发驱逐。如果预热工作集超过此阈值,数据可能在异步 SSD 写入完成之前就被驱逐,导致基准测试处于冷缓存状态,初始命中率偏低。

为了在内存压力下保留预热数据,请在 mooncake.json 中设置 enable_ssd_offload=true,并在 master 上启用驱逐时卸载(offload-on-evict):

mooncake_master \
    --port 50088 \
    --eviction_high_watermark_ratio 0.5 \
    --eviction_ratio 0.1 \
    --default_kv_lease_ttl 11000 \
    --enable_offload=true \
    --offload_on_evict=true \
    --offload_force_evict=false \
    --client_ttl=120

offload_on_evict 默认为 false。启用后,驱逐操作会将没有 LOCAL_DISK 副本的对象排队等待卸载,并在卸载挂起期间固定一个内存副本。保持 offload_force_evict=false,以便在无法排队卸载时推迟驱逐。在暴露 offloading_queue_limit 的 Mooncake 构建中,请根据需要提高每个本地磁盘段的待处理对象上限(例如 --offloading_queue_limit=200000),并为待处理写入预留 DRAM 余量。

只有 worker 客户端拥有本地 SSD 存储。每个 worker 使用 ssd_offload_path/rank_<global_rank>/,其中全局 rank 包含 DP 偏移量以及 TP/PP/CP rank。调度器客户端不启用本地 SSD 卸载。在单节点 DP=2 部署中,两个副本可以使用相同的 mooncake.json:它们的 worker 使用不同的 rank 子目录,且它们的调度器不会占用共享的根目录。全局 rank 重叠的独立 vLLM 服务必须使用不同的 ssd_offload_path 根目录。

如果启动时报告 storage_path already held by another live client,说明另一个客户端持有本地目录锁。此消息来自 Mooncake 的客户端 bucket 后端。请检查 vLLM 加载的 Mooncake 包和原生库,以及正在使用所报告目录的活动客户端;仅凭 mooncake_master 版本无法确定客户端的加锁实现。Mooncake SSD offload enabled 日志会报告实际的 worker 子目录。请参阅 Mooncake SSD 所有权契约。

SSD 磁盘使用控制环境变量:

# 800 GB total disk, 8 TP 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

MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 风险:如果未对齐到 1 GB(A3 + FabricMem 场景),可能会导致 adxl MallocMem 失败或 FileStorage init 段错误。请始终设置为 1 GB 的倍数。

注意:--max-num-batched-tokens 仅对 prefill 计算进行分块;它不会减少 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 所需的内存。

Mooncake SSD 环境变量
参数 类型 默认值 是否必填 取值范围 描述
MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES int(字节) 1342177280 (1280 MB) 否 当 A3 + ASCEND_ENABLE_USE_FABRIC_MEM=1 时必须对齐到 1 GB 每个 rank 的 SSD 读/写缓冲区大小(字节)。无法在 mooncake.json 中配置。当出现 BUFFER_OVERFLOW 时增大该值。
MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE int(字节) 0 否 字节;0 表示物理磁盘容量的 90% 驱逐阈值(字节)。设置显式值以精确控制磁盘使用量。
MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY str none 否 none / fifo / lru SSD 驱逐策略:none(写满时写入失败)、fifo 或 lru。
MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES int(字节) 2199023255552 (2 TB) 强烈建议显式设置 必须与实际磁盘容量匹配 报告给 Mooncake master 的每个 rank 最大磁盘使用量,由 master 跨客户端聚合(约为 2 TB × rank 数量)。默认值远超实际磁盘容量;必须覆盖。

验证

短问题:

curl -s http://localhost:8000/v1/completions -H "Content-Type: application/json" -d '{ "model": "qwen3", "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": "qwen3", "prompt": "Given the accelerating impacts of climate change\u2014including rising sea levels, increasing frequency of extreme weather events, loss of biodiversity, and adverse effects on agriculture and human health\u2014there 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 }'

预期输出:返回符合 OpenAI Completions API 规范的 JSON 响应,包含 id、choices(含 text 和 finish_reason)、usage 等字段。

短问题:

curl -s http://localhost:8100/v1/completions -H "Content-Type: application/json" -d '{ "model": "qwen3", "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": "qwen3", "prompt": "Given the accelerating impacts of climate change\u2014including rising sea levels, increasing frequency of extreme weather events, loss of biodiversity, and adverse effects on agriculture and human health\u2014there 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 }'

预期输出:返回 OpenAI Completions API 格式的 JSON 响应。

调优

大页清理与设置

在 Ascend 950PR&950DT系列产品上,残留的大页会降低 Mooncake 和 Memcache 的性能。启动服务前,请清理 1GB 和 2MB 大页:

# Clean up 1GB huge pages
for n in 0 1 2 3; do
    echo 0 > /sys/devices/system/node/node${n}/hugepages/hugepages-1048576kB/nr_hugepages
done

# Clean up 2MB huge pages
for n in 0 1 2 3; do
    echo 0 > /sys/devices/system/node/node${n}/hugepages/hugepages-2048kB/nr_hugepages
done

清理后验证:

# Verify 1GB huge pages are clean
for n in 0 1 2 3; do
    echo -n "node$n: "
    cat /sys/devices/system/node/node${n}/hugepages/hugepages-1048576kB/nr_hugepages
done

# Verify 2MB huge pages are clean
for n in 0 1 2 3; do
    echo -n "node$n: "
    cat /sys/devices/system/node/node${n}/hugepages/hugepages-2048kB/nr_hugepages
done

Mooncake SSD 卸载参数调优

  • 当出现 BUFFER_OVERFLOW 时增大 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES,但不要超过 vLLM Worker 日志中的 Available KV cache memory 值。仅使用字节字面量(例如 10737418240);不支持 10G/10GB。
  • 在 A3 上使用 ASCEND_ENABLE_USE_FABRIC_MEM=1 时,MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 必须对齐到 1 GB(1073741824 的倍数);避免使用 1280MB、512MB 或 1.5GB 等未对齐的值。在 fabric mem 模式下不使用 mooncake.json 中的 local_buffer_size。
  • Fabric mem 预算公式(每个 rank):
fabric_memory.max_capacity >= global_segment_size + MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES (+ headroom)

如果配额不足,某些 rank 可能会在 global_segment_size 成功后因 MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 分配失败而报错 Memory_Allocation_Failure(EL0004)。 - MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES 默认为 2 TB,远超实际磁盘容量。请始终将其设置为实际的每个 rank 预算。例如,对于 800 GB 磁盘和 8 个 TP 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
  • 主机内存预算:
host_memory_for_mooncake ~ TP x (global_segment_size + MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES + local_buffer_size)
  • 调优后验证:每个 rank 在启动时打印 AlignedClientBufferAllocator: allocated <N> bytes;在负载下没有 BUFFER_OVERFLOW / Failed to get ... keys out of ... error_codes=[-10]。如果使用大缓冲区仍持续失败,请检查重叠加载(load_async)。

MooncakeStore 预热

对于启用了 ASCEND_BUFFER_POOL 的 MooncakeStore,在运行实际性能基准测试之前,请先执行预热阶段。由于 HCCS 单边通信连接是在实例启动后延迟创建的,全互联连接会产生一次性开销(每个连接占用 4 MB 设备内存)。预热建议:输入序列长度 8k,输出序列长度 1,总请求数为设备数量的 2-3 倍。

场景 2:Memcache 后端

配置示例

环境准备

  1. 确认环境中存在 hccn.conf。使用 Docker 时,请将其挂载到容器中:

    cat /etc/hccn.conf
    

    Ascend 950PR&950DT系列产品需要额外挂载设备和配置:/dev/ummu、/dev/uburma、/usr/bin/urma_admin、/lib/route.conf、/etc/hccl_rootinfo.json。

  2. 在所有节点间同步 PYTHONHASHSEED:

    export PYTHONHASHSEED=0
    

步骤 1:前置检查

  1. 检查内存:

    free -h
    

    如果 free -h 显示过多的缓存占用影响了可用的 KV cache 池大小,您可以选择运行以下命令来释放缓存并整理内存碎片:

    # Release pagecache/dentry/inode to free contiguous physical memory
    echo 3 > /proc/sys/vm/drop_caches
    # Trigger memory compaction to reduce fragmentation
    echo 1 > /proc/sys/vm/compact_memory
    
  2. 仅 A3:扫描可用内存:

    python3 mem_scan.py                   # 1GB specification scan
    python3 mem_scan.py -m 2              # 2MB huge page scan
    

    脚本位置:mem_scan.py

  3. 仅 Ascend 950PR&950DT系列产品(禁用签名验证 + 挂载关键路径 + 安装内核包):

    # Step 1: Disable HDK signature verification (only needs to be executed once per machine)
    for i in {0..7}; do npu-smi set -t custom-op-secverify-enable -i $i -d 1; done;
    for i in {0..7}; do npu-smi set -t custom-op-secverify-mode -i $i -d 0; done;
    

    Docker 容器需要挂载关键路径。示例命令:

    docker run -u root -it -d --name ${NAME} --net=host --privileged=true \
        --device=/dev/davinci_manager --device=/dev/hisi_hdc --device=/dev/ummu --device=/dev/uburma \
        --device=/dev/davinci0 --device=/dev/davinci1 --device=/dev/davinci2 --device=/dev/davinci3 \
        --device=/dev/davinci4 --device=/dev/davinci5 --device=/dev/davinci6 --device=/dev/davinci7 \
        -v /usr/bin/urma_admin:/usr/bin/urma_admin \
        -v /lib/route.conf:/lib/route.conf \
        -v /etc/hccl_rootinfo.json:/etc/hccl_rootinfo.json \
        -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
        -v /usr/local/sbin:/usr/local/sbin \
        -v /usr/local/dcmi:/usr/local/dcmi \
        -v /var/log/npu/:/usr/slog \
        -v /etc/hccn.conf:/etc/hccn.conf \
        -v /etc/hixlep:/etc/hixlep \
        -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
        -w /home \
        ${IMAGES_ID} \
        bash
    

    更新容器内的 /lib/route.conf。

  4. 启用 SSD 前检查磁盘状态:

    lsblk /dev/nvme1n1                    # No partitions expected
    mount | grep nvme1n1                  # No mount points expected
    blkid /dev/nvme1n1                    # No filesystem signature expected
    

    如果没有可用的物理磁盘,可使用 loop 设备进行模拟:

    dd if=/dev/zero of=/data/boostio_disk.img bs=1G count=640 status=progress
    LOOP_DEV=$(losetup --find --show --direct-io=on /data/boostio_disk.img)
    echo "${LOOP_DEV}"
    

步骤 2:软件安装

MemCache 后端需要同时满足 memcache-hybrid >= 1.3.0 和 memfabric-hybrid >= 1.3.0。

pip install "memfabric-hybrid>=1.3.0"
pip install "memcache-hybrid>=1.3.0"

步骤 3:配置 Memcache 配置文件

查找安装路径:

pip show memcache_hybrid

使用 {INSTALL_PATH} 表示输出中的 Location 值。

mmc-meta.conf
ock.mmc.meta_service_url = tcp://<meta_service_ip>:5000
ock.mmc.meta_service.config_store_url = tcp://<meta_service_ip>:6000
ock.mmc.meta_service.metrics_url = http://<meta_service_ip>:8000
ock.mmc.log_level = info
# Tune the following parameters when SSD is enabled to improve SSD cache hit rate
ock.mmc.evict_threshold_high = 70
ock.mmc.evict_threshold_low = 60
mmc-meta.conf 参数
参数 类型 默认值 是否必填 取值范围 描述
ock.mmc.meta_service_url str tcp://127.0.0.1:5000 是 tcp://:,端口 [1025, 65535] MetaService 地址。P 节点和 D 节点必须使用相同的端点。Host 支持 IP 和域名。
ock.mmc.meta_service.config_store_url str tcp://127.0.0.1:6000 是 tcp://:,端口 [1025, 65535] 配置存储 URL。
ock.mmc.meta_service.metrics_url str http://127.0.0.1:8000 是 http(s)://:,端口 [1025, 65535] 指标 URL。
ock.mmc.log_level str info 是 debug / info / warn / error 日志级别;由 MetaService 和 LocalService 共享。
ock.mmc.evict_threshold_high int 90 否 [1, 99](百分比) 二级(L2)池的高水位线;达到此水位线时触发驱逐,且仅在 usedSize * 100 > totalSize * threshold 时触发。启用 SSD 时,建议设置为 70 以提高 SSD 缓存命中率。
ock.mmc.evict_threshold_low int 80 否 [1, 98](百分比) 二级(L2)池的低水位线;驱逐在此水位线停止。启用 SSD 时,建议设置为 60。
mmc-local.conf
ock.mmc.meta_service_url = tcp://<meta_service_ip>:5000
ock.mmc.local_service.config_store_url = tcp://<meta_service_ip>:6000
ock.mmc.log_level = info
ock.mmc.local_service.world_size = 256
ock.mmc.local_service.protocol = device_sdma
ock.mmc.local_service.dram.size = 1GB
ock.mmc.local_service.max.dram.size = 1024GB
# SSD feature related parameters below
ock.mmc.local_service.storage.enabled = false
ubsio.disk.path = /dev/nvmexn1:/dev/nvmexn2p1:/dev/loopX
ubsio.mem.size_in_gb = 10
ubsio.standalone.device_count = 8
ubsio.standalone.force_new_disk = true
mmc-local.conf 参数
参数 类型 默认值 是否必填 取值范围 描述
ock.mmc.meta_service_url str tcp://127.0.0.1:5000 否 tcp://:,端口 [1025, 65535] 必须与 mmc-meta.conf 匹配(在 HA 部署中 host 为 cluster-ip 或域名)。
ock.mmc.local_service.config_store_url str tcp://127.0.0.1:6000 否 tcp://:,端口 [1025, 65535] 必须与 mmc-meta.conf 中的 ock.mmc.meta_service.config_store_url 匹配。
ock.mmc.local_service.world_size int 256 否 [1, 1024] 支持的最大 LocalService 数量(包括未来新增的)。一旦 rank 连接完成,就不允许再修改——需要重启 meta。
ock.mmc.local_service.protocol str host_rdma 是 host_rdma / host_urma / host_tcp / host_shm / device_sdma / device_rdma / device_urma / device_uboe 通信协议。A2 推荐:device_rdma(RoCE);A3 HCCS 推荐:device_sdma(需要灵衢计算网络 >= 1.5);Ascend 950PR&950DT系列产品 UB:device_urma;UBOE:device_uboe。host_shm 要求 DRAM > 0 且 HBM = 0。
ock.mmc.local_service.dram.size int 1GB 是 [0, 1TB],自动对齐到 2MB(host_* 协议)或 1GB(device_* 协议) 每个 die 分配的 DRAM 大小;支持 134217728、2048KB、200MB、2.5GB 或 1TB 等格式。例如,在 A3 上,要将 640GB 分配为 KV 池,请将此参数设置为 640/16=40GB。当 HCCS 可用时,A3 设置为 0GB。
ock.mmc.local_service.max.dram.size int 1TB 否 [0, 1TB] 最大 DRAM 大小。当各 rank 贡献不同大小的 DRAM 时需要设置。默认值 1TB 为二进制 1024^4 字节。
ock.mmc.local_service.storage.enabled bool false 否 true / false 启用 SSD 缓存。
ubsio.disk.path str 无默认值 启用 SSD 时必填 绝对路径,多个路径以 : 分隔 SSD 块设备、分区或 loop 设备路径。设备必须专用,不能有挂载点或文件系统签名。不建议使用 /dev/sd*。
ubsio.mem.size_in_gb int 10 否 整数 [0, 3072];SSD 缓存要求 >= 5 UBS IO 每个 die(即每个 LocalService/进程)请求的 DRAM 大小,单位为 GB。数据存储流程:HBM → 二级池化 DRAM → 三级池化 DRAM → SSD。总分配量不得超过为操作系统、vLLM 和 Memcache DRAM 池预留内存后节点可用的内存。通常为 10;分离部署时建议为 50。
ubsio.standalone.device_count int 无默认值 是 正整数 启用 DRAM 的 LocalService 数量,即环境中 vLLM 进程的数量(A2 上为 8,A3 上为 16;如果实际使用的卡数较少,请配置实际进程数,例如仅占用 4 张卡时配置为 4)。
ubsio.standalone.force_new_disk bool true 否 true / false 每次启动服务时清除已挂载的磁盘。当前版本不支持故障恢复;建议保持为 true。

步骤 4:运行 MetaService

export MMC_META_CONFIG_PATH={INSTALL_PATH}/memcache_hybrid/config/mmc-meta.conf

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

预期输出:MetaService 成功启动,无错误。

步骤 5:启动 vLLM 推理服务

run_prefill.sh / run_decode.sh
#!/bin/bash

# prefill / decode
ROLE="prefill"
# A2 (800I/800T A2) or A3 (800I/800T A3) or 950PR&950DT Products
HARDWARE_SERIES="A2"
# Link type: ROCE or HCCS in A3 series.
LINK_TYPE="ROCE"
LOCAL_IP="<local_ip>"
NIC_NAME="<nic_name>"

MODEL_PATH="<model_path>/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

# parameters required for kv pool and memcache
export PYTHONHASHSEED=0
export MMC_LOCAL_CONFIG_PATH={INSTALL_PATH}/memcache_hybrid/config/mmc-local.conf
export LD_LIBRARY_PATH={INSTALL_PATH}/memcache_hybrid/lib:${PYTHON_LIB_DIR}:${LD_LIBRARY_PATH}

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

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

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

# See Configuration Parameters section for detailed parameter descriptions
if [ "$HARDWARE_SERIES" == "A2" ] || { [ "$HARDWARE_SERIES" == "A3" ] && [ "$LINK_TYPE" == "ROCE" ]; }; 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
    export HCCL_INTRA_ROCE_ENABLE=1

elif [ "$HARDWARE_SERIES" == "A3" ] && [ "$LINK_TYPE" == "HCCS" ]; then
    export ACL_OP_INIT_MODE=1
    export ASCEND_ENABLE_USE_FABRIC_MEM=1
elif [ "$HARDWARE_SERIES" == "A5" ]; then
    # 950PR&950DT Products UBOE
    export ASCEND_GLOBAL_RESOURCE_CONFIG='{"comm_resource_config.protocol_desc":["uboe:device"]}'
    # 950PR&950DT Products UB
    export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}'
else
    echo "Error: Invalid HARDWARE_SERIES. Set to 'A2', 'A3', or 'A5'."
    exit 1
fi

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

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'",
          "use_layerwise": false
        }
      }
    ]
  }
}'

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 "$API_PORT"
  --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"

use_layerwise 可设置为 true 以启用逐层 KV 访问,Mooncake 和 Memcache 后端均支持;仅在 Prefill 节点上支持。consumer_is_to_put 和 consumer_is_to_load 也可以通过 kv_connector_extra_config 进行配置。

要启动 proxy_server 并运行推理,请参考场景 1:Mooncake 后端中"PD 分离场景"的相应子步骤。

预期输出:与 Mooncake 场景相同,返回 OpenAI Completions API JSON 响应。

pd_mix.sh
#!/bin/bash

# A2 (800I/800T A2) or A3 (800I/800T A3) or 950PR&950DT Products
HARDWARE_SERIES="A2"
# Link type: ROCE or HCCS in A3 series.
LINK_TYPE="ROCE"
LOCAL_IP="<local_ip>"
NIC_NAME="<nic_name>"

MODEL_PATH="<model_path>/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

# parameters required for kv pool and memcache
export PYTHONHASHSEED=0
export MMC_LOCAL_CONFIG_PATH={INSTALL_PATH}/memcache_hybrid/config/mmc-local.conf
export LD_LIBRARY_PATH={INSTALL_PATH}/memcache_hybrid/lib:${PYTHON_LIB_DIR}:${LD_LIBRARY_PATH}

echo "Starting vLLM on Series: $HARDWARE_SERIES"

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

# See Configuration Parameters section for detailed parameter descriptions
if [ "$HARDWARE_SERIES" == "A2" ] || { [ "$HARDWARE_SERIES" == "A3" ] && [ "$LINK_TYPE" == "ROCE" ]; }; 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
    export HCCL_INTRA_ROCE_ENABLE=1

elif [ "$HARDWARE_SERIES" == "A3" ] && [ "$LINK_TYPE" == "HCCS" ]; then
    export ACL_OP_INIT_MODE=1
    export ASCEND_ENABLE_USE_FABRIC_MEM=1
elif [ "$HARDWARE_SERIES" == "A5" ]; then
    # 950PR&950DT Products UBOE
    export ASCEND_GLOBAL_RESOURCE_CONFIG='{"comm_resource_config.protocol_desc":["uboe:device"]}'
    # 950PR&950DT Products UB
    export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}'
else
    echo "Error: Invalid HARDWARE_SERIES. Set to 'A2', 'A3', or 'A5'."
    exit 1
fi

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

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

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 8100
  --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"

推理命令请参考场景 1:Mooncake 后端中的"PD 混合场景"。

上述脚本中使用的 kv_connector_extra_config 字段记录在 kv-transfer-config 通用参数中。

步骤 6:Memcache 与 vLLM 分离部署

此部署模式将 MemCache 和 vLLM 运行在不同的进程中(与 vLLM PD 分离不同)。在默认的同机部署模式下,vLLM 在 KV 连接器初始化 MemCache 之前加载模型权重,因此 MemCache 可能无法从剩余可用空间中预留足够的内存。在 vLLM 之前启动独立的 MemCache 进程可以让 MemCache 预留更大的内存池。

准备两个具有相同连接和协议设置的 LocalService 配置文件:vLLM 进程使用的配置不贡献 DRAM(dram.size = 0GB),独立 MemCache 进程使用的配置指定要贡献的 DRAM 大小。将 ock.mmc.local_service.max.dram.size 设置为能够容纳 LocalService 进程使用的最大 dram.size。

步骤:

  1. 启动 MetaService(同上)。
  2. 使用以下 mmc-local-standalone.conf 配置在每个节点上启动独立的 Memcache 进程:

    ock.mmc.local_service.dram.size = 600GB
    ock.mmc.local_service.max.dram.size = 1024GB
    
  3. 等待所有节点报告初始化成功。

  4. 使用以下 mmc-local.conf 配置(dram.size = 0GB)启动 vLLM:

    ock.mmc.local_service.dram.size = 0GB
    ock.mmc.local_service.max.dram.size = 1024GB
    

启动脚本参考:Memcache + vLLM + A3 分离部署案例

步骤 7:启用 Memcache SSD 缓存

在分离部署场景中启用 SSD 缓存时,请参考以下配置:

mmc-local.conf(由 vLLM 进程使用,不贡献 DRAM)
ock.mmc.meta_service_url = tcp://<meta_service_ip>:5000
ock.mmc.local_service.config_store_url = tcp://<meta_service_ip>:6000
ock.mmc.log_level = info
ock.mmc.local_service.world_size = 256
ock.mmc.local_service.protocol = device_sdma
ock.mmc.local_service.dram.size = 0GB
ock.mmc.local_service.max.dram.size = 1024GB
mmc-local-standalone.conf(由独立 MemCache 进程使用)
ock.mmc.meta_service_url = tcp://<meta_service_ip>:5000
ock.mmc.local_service.config_store_url = tcp://<meta_service_ip>:6000
ock.mmc.log_level = info
ock.mmc.local_service.world_size = 256
ock.mmc.local_service.protocol = device_sdma
ock.mmc.local_service.dram.size = 600GB
ock.mmc.local_service.max.dram.size = 1024GB
# SSD feature related parameters below
ock.mmc.local_service.storage.enabled = true
ubsio.disk.path = /dev/nvmexn1:/dev/nvmexn2p1:/dev/loopX
ubsio.mem.size_in_gb = 50
ubsio.standalone.device_count = 1
ubsio.standalone.force_new_disk = true

调整 ubsio.mem.size_in_gb 时,将 UBS IO 可用的节点内存除以启用 DRAM 的本地服务数量,向下取整,并将结果上限设为 3072,以计算每个进程允许的最大值:

maximum ubsio.mem.size_in_gb = min(3072, floor(available node memory for UBS IO (GB) / number of DRAM-enabled local services))

例如,如果 UBS IO 可用 200 GB,且有四个本地服务启用了 DRAM,则每个进程的上限为 50 GB。如果计算出的上限小于 5,请释放更多节点内存或减少启用 DRAM 的本地服务数量。

对于 MemCache 独立部署场景,建议为单个进程配置 50 GB。其他场景建议配置 10 GB。如需使用 L2.5 内存缓存能力,可在上述限制范围内增大 ubsio.mem.size_in_gb,并相应调整 ubsio.wcache.evict_water_level。

关于磁盘配置、淘汰水位线及其他 UBS IO 参数,请参见 DRAM + SSD 多级池化配置指南。

验证

短问题:

curl -s http://localhost:8000/v1/completions -H "Content-Type: application/json" -d '{ "model": "qwen3", "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": "qwen3", "prompt": "Given the accelerating impacts of climate change\u2014including rising sea levels, increasing frequency of extreme weather events, loss of biodiversity, and adverse effects on agriculture and human health\u2014there 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 }'

预期输出:返回符合 OpenAI Completions API 规范的 JSON 响应,包含 id、choices(含 text 和 finish_reason)、usage 等字段。

短问题:

curl -s http://localhost:8100/v1/completions -H "Content-Type: application/json" -d '{ "model": "qwen3", "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": "qwen3", "prompt": "Given the accelerating impacts of climate change\u2014including rising sea levels, increasing frequency of extreme weather events, loss of biodiversity, and adverse effects on agriculture and human health\u2014there 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 }'

预期输出:返回 OpenAI Completions API 格式的 JSON 响应。

调优

大页清理与设置

在 Ascend 950PR&950DT系列产品上,残留的大页会降低 Mooncake 和 Memcache 的性能。启动服务前,请清理 1GB 和 2MB 大页:

# Clean up 1GB huge pages
for n in 0 1 2 3; do
    echo 0 > /sys/devices/system/node/node${n}/hugepages/hugepages-1048576kB/nr_hugepages
done

# Clean up 2MB huge pages
for n in 0 1 2 3; do
    echo 0 > /sys/devices/system/node/node${n}/hugepages/hugepages-2048kB/nr_hugepages
done

清理后验证:

# Verify 1GB huge pages are clean
for n in 0 1 2 3; do
    echo -n "node$n: "
    cat /sys/devices/system/node/node${n}/hugepages/hugepages-1048576kB/nr_hugepages
done

# Verify 2MB huge pages are clean
for n in 0 1 2 3; do
    echo -n "node$n: "
    cat /sys/devices/system/node/node${n}/hugepages/hugepages-2048kB/nr_hugepages
done

Memcache UBS IO 内存池调优

  • ubsio.mem.size_in_gb 上限计算公式:
maximum ubsio.mem.size_in_gb = min(3072, floor(available node memory for UBS IO (GB) / number of DRAM-enabled local services))
  • 独立部署建议:每进程 50 GB;其他场景:10 GB。
  • 如需使用 L2.5 内存缓存,请在限制范围内增大 ubsio.mem.size_in_gb,并调整 ubsio.wcache.evict_water_level。

场景 3:Yuanrong 后端

配置示例

环境准备

  1. 确认环境中存在 hccn.conf。使用 Docker 时,请将其挂载到容器中:

    cat /etc/hccn.conf
    

    Ascend 950PR&950DT系列产品需要额外挂载设备和配置:/dev/ummu、/dev/uburma、/usr/bin/urma_admin、/lib/route.conf、/etc/hccl_rootinfo.json。

  2. 在所有节点间同步 PYTHONHASHSEED:

    export PYTHONHASHSEED=0
    

步骤 1:安装 Yuanrong Datasystem

pip install openyuanrong-datasystem
python -c "import yr.datasystem; print('Yuanrong Datasystem is ready')"
dscli --version

预期输出:

  • Yuanrong Datasystem is ready
  • dscli 显示的版本号。

如果预编译包与 CANN 或驱动版本不匹配,请从源码构建 Yuanrong Datasystem:Yuanrong Datasystem。

步骤 2:选择服务发现后端

COORDINATOR_ADDRESS="<coordinator_ip>:31511"

dscli start -c \
  --coordinator_address "${COORDINATOR_ADDRESS}"

预期输出:Start coordinator service ... success。

单节点快速启动(一步启动 Coordinator + Worker):

dscli start -a \
  --coordinator_address "127.0.0.1:31511" \
  --worker_address "127.0.0.1:31501" \
  --shared_memory_size_mb 4096
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

预期输出:etcdctl put key "value" 返回 OK;etcdctl get key 返回 key->value。

生产环境请参考 etcd 官方集群文档:etcd 集群指南。

多节点部署

在每个节点上安装 Yuanrong Datasystem。每个节点运行一个 Datasystem Worker,并使用唯一且可达的 worker_address。所有 Worker 必须使用相同的服务发现后端和后端地址。

使用 Coordinator 的多节点部署(以 Coordinator 节点地址 192.168.1.10 为例):

# Run once on the Coordinator node.
dscli start -c \
  --coordinator_address "192.168.1.10:31511"
# Run on every Worker node. Set WORKER_IP to that node's own IP;
# keep COORDINATOR_ADDRESS identical on all nodes.
WORKER_IP="<this_node_ip>"
COORDINATOR_ADDRESS="192.168.1.10:31511"

dscli start -w \
  --worker_address "${WORKER_IP}:31501" \
  --coordinator_address "${COORDINATOR_ADDRESS}" \
  --shared_memory_size_mb 4096

使用 etcd 的多节点部署:启动一个所有 Worker 均可访问的 etcd 服务或集群,然后在每个节点上启动一个 Worker。将 WORKER_IP 设置为该节点自身的 IP,并确保所有节点上的 ETCD_ADDRESS 保持一致:

# Run on every Worker node.
WORKER_IP="<this_node_ip>"
ETCD_ADDRESS="192.168.1.10:2379"

dscli start -w \
  --worker_address "${WORKER_IP}:31501" \
  --etcd_address "${ETCD_ADDRESS}" \
  --shared_memory_size_mb 4096

对于两种后端:

  • 在多节点部署中,不要使用 127.0.0.1 或 0.0.0.0 作为 Worker 地址。其他 Worker 必须能够连接到所公布的 IP。
  • 允许对 Coordinator 端口(31511)或 etcd 客户端端口(2379)以及每个 Worker 端口(本示例中为 31501)的网络访问。
  • 在每个节点上,将 yuanrong.json 中的 worker_addr 设置为该节点本地的 WORKER_IP:31501。因此配置文件因节点而异。

对于生产环境控制平面的高可用,请部署多个 Coordinator,使用静态 Raft 对等节点,为每个 Coordinator 设置唯一的 coordinator_address 和 coordinator_raft_data_dir,并使用相同的 coordinator_raft_initial_peers 列表。请参见 Yuanrong Datasystem dscli 文档。

步骤 3:启动 Datasystem Worker

COORDINATOR_ADDRESS="<coordinator_ip>:31511"
WORKER_IP="<worker_ip>"
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" \
  --coordinator_address "${COORDINATOR_ADDRESS}" \
  --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 成功启动且无错误。Worker 日志(包括基本名称通常为 datasystem_worker 的文件)写入 --log_dir 目录下。请使用绝对路径,以便日志位置不依赖于 worker 进程的当前目录。

--worker_address 的值稍后会作为 yuanrong.json 中的 worker_addr 使用,因此请确保同一节点上的主机和端口保持一致。为 Worker 仅配置一个协调后端:使用 Coordinator 时,不要同时设置 etcd_address 或 metastore_address。

当不再需要 Worker 时,停止该 Worker。只有在所有 Worker 都停止后,才能停止所选的服务发现后端。对于独立的 etcd 集群,请遵循其常规的集群维护流程:

dscli stop --worker_address "${WORKER_IP}:31501"
# Coordinator option only:
dscli stop --coordinator_address "${COORDINATOR_ADDRESS}"
Yuanrong dscli Worker 参数
参数 类型 默认值 是否必填 取值范围 描述
worker_address str 无默认值 是 <host>:<port> Worker 地址,必须与 yuanrong.json 中的 worker_addr 一致。
coordinator_address str 无默认值 选项 1 <ip>:31511 Coordinator 地址。
etcd_address str 无默认值 选项 2 <ip>:2379 etcd 地址。
log_dir str 无默认值 否 绝对路径 Worker 日志目录,请使用绝对路径。启动前请创建该目录并授予 worker 进程写权限。
shared_memory_size_mb int 无默认值 是 正整数(MB) 共享内存大小(MB)。示例:40960(40 GB)。
arena_per_tenant int 无默认值 否 正整数 每个租户的共享内存 arena 数量。保守的起始值:1。
enable_huge_tlb bool 无默认值 否 true / false 为共享内存使用 HugeTLB 页。启动 worker 前请预留足够的 2 MiB 大页。
enable_fallocate bool 无默认值 否 true / false 对共享内存文件执行 fallocate。与 HugeTLB 一起使用时建议设为 false。
rpc_thread_num int 无默认值 否 正整数 RPC/ZMQ 服务并发数。
oc_thread_num int 无默认值 否 正整数 Object Cache 业务线程池大小。
enable_worker_worker_batch_get bool 无默认值 否 true / false 启用 Worker 之间的批量 Object Cache 读取。
sc_regular_socket_num int 0 否 >= 0 Stream Cache 常规 socket 数量。当 KV Pool 不使用 Stream Cache 时保持为 0。
sc_stream_socket_num int 0 否 >= 0 Stream Cache 流式 socket 数量。当 KV Pool 不使用 Stream Cache 时保持为 0。
remote_h2d_device_ids str 空 否 逗号分隔的设备 ID,例如 "0,1,2,3,4,5,6,7" 非空时启用 worker 侧的 Remote H2D。建议使用多个可用的 NPU 设备 ID。
remote_h2d_link_type str ROCE 否 ROCE / HCCS(区分大小写) 链路类型。ROCE 映射到客户端 P2P_TRANSFER;HCCS 映射到客户端 HIXL(涵盖 buffer-pool、HIXL RoCE direct 和 FabricMem 子模式)。对于 HCCS,客户端进程还必须在启动 vLLM 前导出 DS_RH2D_LINK_TYPE=HCCS(后端不会自动导出);ROCE 是 datasystem 的默认值,无需设置环境变量。
remote_h2d_hccs_buffer_pool str 4:8 否 <count>:<size> HIXL buffer-pool 参数,仅在 link_type=HCCS 时使用。在 HIXL RoCE direct 模式(HCCL_INTRA_ROCE_ENABLE=1)下会被忽略。

步骤 4:配置环境变量和 yuanrong.json

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}"
Yuanrong 环境变量
变量 类型 默认值 是否必填 取值范围 说明
PYTHONHASHSEED int 0 是 整数(所有节点保持一致) 必须在所有节点上保持一致,以保证哈希生成的一致性。
DS_WORKER_ADDR str N/A 是 <host>:<port> Datasystem Worker 地址,必须与本地 dscli start --worker_address 的值一致。
DATASYSTEM_CLIENT_LOG_DIR str ~/.datasystem/logs 否 目录路径 Yuanrong 客户端 SDK 日志目录(基本名称通常为 ds_client)。必须在启动 vLLM 前设置;请使用与 worker 日志分开的目录。
DS_ENABLE_EXCLUSIVE_CONNECTION int 0 否 0 / 1 传递给 Yuanrong HeteroClient.enable_exclusive_connection。当你的部署需要时,使用 1 启用独占连接模式。
DS_ENABLE_REMOTE_H2D int 0 否 0 / 1 传递给 Yuanrong HeteroClient.enable_remote_h2d。只有在满足 Remote H2D 要求后才使用 1。

在启动 vLLM 前设置 DATASYSTEM_CLIENT_LOG_DIR,因为 Yuanrong 客户端在日志初始化期间会读取它。客户端 SDK 日志(基本名称通常为 ds_client)会写入该目录。请使用与 worker 日志分开的目录。

配置 yuanrong.json(由 YR_CONFIG_PATH 指向):

{
    "worker_addr": "<worker_ip>:31501",
    "connect_timeout_ms": 9000,
    "request_timeout_ms": 0,
    "get_sub_timeout_ms": 0,
    "enable_remote_h2d": false,
    "remote_h2d_transport_backend": "HIXL",
    "enable_fabric_mem": false,
    "enable_dev_mem_pregister": false,
    "use_layerwise": false
}
yuanrong.json 字段
字段 类型 默认值 是否必填 取值范围 说明
worker_addr str 无默认值 是 <host>:<port> Datasystem Worker 地址,必须与 dscli start --worker_address 一致。
connect_timeout_ms int 9000 否 整数 >= 500 连接建立超时时间(毫秒)。
request_timeout_ms int 0 否 0 或正整数(毫秒) 请求超时时间(毫秒)。0 保留 Yuanrong SDK 使用 connect_timeout_ms 作为请求超时的行为;设置正值可独立控制请求超时。
get_sub_timeout_ms int 0 否 0 或正整数(毫秒) mget_h2d_from_multi_buffers 等待对象就绪的超时时间(毫秒);0 表示不等待。它可以大于 request_timeout_ms;Yuanrong Get 路径会扩展该调用的 RPC 超时,以适应所配置的对象就绪等待时间。
enable_remote_h2d bool false 否 true / false 传递给 Yuanrong HeteroClient.enable_remote_h2d。仅在满足 Remote H2D 要求后才可使用 true。
remote_h2d_transport_backend str HIXL 否 HIXL / P2P_TRANSFER vLLM 侧的传输名称,对应 Worker 的 --remote_h2d_link_type(HCCS ↔ HIXL,ROCE ↔ P2P_TRANSFER)。在 HIXL 下,除非 enable_fabric_mem 为 true,否则后端会预注册设备内存;在 P2P_TRANSFER 下则跳过预注册。
enable_fabric_mem bool false 否 true / false 选择 HIXL FabricMem 模式,在该模式下 HIXL OPTION_ENABLE_USE_FABRIC_MEM 会自动处理 Fabric 可共享句柄交换,后端会跳过客户端侧的 pre_register_device_memory。仅在 remote_h2d_transport_backend="HIXL" 时才有意义。FabricMem 需要 datasystem 侧支持(HIXL FabricMem 构建以及相应的 datasystem 环境变量);启用此标志前请查阅 datasystem 文档。
enable_dev_mem_pregister bool false 否 true / false 客户端侧设备内存预注册(pre_register_device_memory)的总开关。要实际执行预注册,此标志必须为 true 且满足自动条件:enable_remote_h2d=true、remote_h2d_transport_backend="HIXL" 且 enable_fabric_mem=false。在 P2P_TRANSFER 或 FabricMem 模式下,无论此开关如何设置,预注册都会被跳过。对于需要客户端侧设备内存注册的 HIXL HCCS Remote H2D 部署,请将其设置为 true。
use_layerwise bool false 否 true / false 必须与 kv_connector_extra_config.use_layerwise 一致。当为 false 时,调度器侧的 Yuanrong 存储会跳过初始化,因为非分层查找被委托给 TP0 worker。当为 true 时,调度器会初始化一个仅含元数据、且禁用 Remote H2D 的 Yuanrong 客户端,因此不会创建 HIXL 引擎。

worker_addr 必须与本地 dscli start --worker_address 的值一致。

Remote H2D 要求与验证

仅当在 Yuanrong Datasystem 部署中启用并验证了 Remote Host-to-Device 传输后,才将 DS_ENABLE_REMOTE_H2D 设置为 1(或在 yuanrong.json 中将 enable_remote_h2d 设置为 true):

  • 在启动 worker 之前预留足够的 2 MiB HugeTLB 页。对于 40 GiB 共享内存,至少预留 20480 个 2 MiB 大页。
  • 在启用 Remote H2D 的情况下启动每个 Datasystem worker。worker 启动命令必须包含 --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" \
  --coordinator_address "${COORDINATOR_ADDRESS}" \
  --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"

对于 HIXL HCCS 链路(具备 HCCS 可达性的 Atlas A3),请设置 --remote_h2d_link_type "HCCS" 以及 HIXL 缓冲池参数。--worker_address 中的 IP 也会用作 HIXL 端点 IP,因此请使用可达的地址,而不是 127.0.0.1 或 0.0.0.0。HIXL RoCE 直连模式是 HCCS 的子模式,通过在两端设置 HCCL_INTRA_ROCE_ENABLE=1 来选择,并且额外要求可达的 RoCE 链路:

dscli start --interleave 0-7 -w \
  --worker_address "${WORKER_IP}:31501" \
  --coordinator_address "${COORDINATOR_ADDRESS}" \
  --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" \
  --remote_h2d_link_type "HCCS" \
  --remote_h2d_hccs_buffer_pool "4:8"
  • 确保 Yuanrong Remote H2D 所需的 NPU 驱动、固件和 CANN 工具包已安装,并且对 worker 进程可见。在容器中,请挂载昇腾驱动路径、npu-smi、hccn_tool、/etc/hccn.conf、/etc/ascend_install.info 以及所需的 /dev/davinci* 设备。
  • 当 worker 使用 --remote_h2d_link_type "HCCS" 时,客户端进程还必须在启动 vLLM 之前导出 DS_RH2D_LINK_TYPE=HCCS(后端不会自动导出);ROCE 是 datasystem 的默认值,无需设置环境变量。
  • 在启用客户端标志之前,请验证 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 传输路径。

步骤 5:运行 AscendStoreConnector(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",
        "use_layerwise": false
    }
}'

lookup_rpc_port 标识池化调度器进程与 worker 进程之间使用的本地 IPC 端点。同一个 vLLM 服务内的 DP 副本会自动使用独立的 IPC 端点。共享同一 RPC 基础目录的独立启动服务必须使用不同的 lookup_rpc_port 值。

注意: Yuanrong 后端在调用 Datasystem 之前会对 KV 键进行规范化。支持的、长度不超过 1024 字节的 ASCII 键会被保留。较长的键或包含不支持字符的键会被重写为最多 1024 个字符并附加哈希后缀,因此在调试后端存储时不要依赖原始键字符串。无需额外的缓冲区预注册步骤。

上述脚本中使用的 kv_connector_extra_config 字段记录在 kv-transfer-config 通用参数 中。

预期输出:vLLM 成功启动,OpenAI API 服务已就绪。

验证

请参考配置示例中步骤 1–5 的验证操作。

调优

Yuanrong Worker 参数调优

  • rpc_thread_num 和 oc_thread_num 等线程数是调优的起点。请根据可用的 CPU 核心数和实测的请求吞吐量进行调整。
  • 当 shared_memory_size_mb=40960 时,至少预留 20480 个 2 MiB 大页:
grep -E "HugePages_Total|HugePages_Free|Hugepagesize" /proc/meminfo
  • Worker 的 -w 会消费后续的命令行参数。所有 dscli start 选项(例如 --timeout)都必须放在 -w 之前。

参考

kv-transfer-config 通用参数

参数 类型 默认值 是否必填 取值范围 描述
kv_load_failure_policy str fail 否 recompute / fail KV 加载失败时的行为:recompute 会回滚并重新计算(暂不支持 DeepSeekV4、Qwen 3.5 等混合注意力模型),fail 会终止请求。使用 MultiConnector 时,请在顶层 kv-transfer-config 中配置。
lookup_rpc_port str 无默认值 是 不同的服务标识符(例如 "0"、"1") 池化调度器与 worker 进程之间的本地 IPC 标识符。服务内的 DP 副本会自动隔离;共享 RPC 基础目录的独立启动服务需要唯一值。旧名称 mooncake_rpc_port 已弃用;请使用 lookup_rpc_port。
load_async bool false 否 true / false 是否启用异步加载。
backend str mooncake 否 mooncake / memcache / yuanrong KV Pool 存储后端。
consumer_is_to_put bool false 否 true / false Decode 节点是否将 KV Cache 写入 KV Pool。
save_decode_cache bool false 否 true / false 保存完整的 Decode KV 块。消费者可以在不启用 consumer_is_to_put 的情况下启用此项,从而保持 Prefill 写入禁用;此消费者模式要求 use_layerwise=false。
consumer_is_to_load bool false 否 true / false Decode 节点是否从 KV Pool 加载 KV Cache。
use_layerwise bool false 否 true / false 逐层 KV 保存/加载,Mooncake 和 Memcache 后端均支持。仅在 Prefill 节点上支持。
prefill_pp_size int 1 当 Prefill PP + 消费者写入时必填 正整数 Prefill PP 大小。
prefill_pp_layer_partition str 无默认值 否 逗号分隔的层编号,例如 "30,31" Prefill PP 层划分。如果未配置,则按 prefill_pp_size 平均划分层。
qos_priority int 0 否 [0, 4](整数,越大优先级越高) KV Pool 传输 QoS 优先级。

注意: 当 AscendStoreConnector 与 MooncakeConnector(V1)或 MooncakeConnectorV2 一起使用时,当前的 TCP 端口分配仍可能与其他 worker 或组件预留的端口重叠。这包括 V1 worker 握手端口和 V2 调度器控制端口。不同的 DP 索引并不保证 TCP 端口范围互不重叠;部署前请对照 worker 和组件的端口预留检查这些分配。lookup_rpc_port 仅标识本地 IPC 端点,并不能解决这些 TCP 端口冲突。

ASCEND_GLOBAL_RESOURCE_CONFIG

ASCEND_GLOBAL_RESOURCE_CONFIG 是传递给 HIXL 的 JSON 字符串。常见字段如下:

字段 类型 默认值 是否必填 取值范围 描述
comm_resource_config.protocol_desc 字符串数组 无默认值 否 例如 ["hccs:device"]、["roce:device"]、["uboe:device"] 顶层 Mooncake 传输引擎的协议描述符。在 PD 分离中,它控制 MooncakeConnectorV1 的 PD 传输路径。
store.comm_resource_config.protocol_desc 字符串数组 无默认值 否 例如 ["roce:device"] AscendStoreConnector 使用的 Mooncake Store 流量的协议描述符。在 A3 上,可以将其设置为 ["roce:device"],而 PD 传输使用 HCCS。
comm_resource_config.listen_port int 16666 否 端口号 单边通信监听端口。独立运行的 mooncake_client 进程请使用不同的端口,以避免与内嵌客户端冲突。
fabric_memory.max_capacity int 无默认值 仅当 fabric 内存预算不足时 整数(每进程 GB) Fabric 内存配额。

HDK 与 CANN 版本兼容性参考

硬件系列 HDK 要求 CANN 要求 其他依赖
Ascend 950PR&950DT系列产品 >= 25.6(搭配 Mooncake >= v0.3.11) >= 9.1.0 需要 UBOE/UB 设备及配置挂载
800 I/T A3 >= 26.0 或 >= 25.5(搭配 Mooncake >= v0.3.11) >= 9.1.0 灵衢计算网络 >= 1.5(Mooncake FabricMem 和 Memcache device_sdma 均需要);建议设置 ASCEND_ENABLE_USE_FABRIC_MEM=1
800 I/T A2 建议 >= 25.5 >= 9.1.0 HCCL_INTRA_ROCE_ENABLE=1 直接传输

QoS 配置

Mooncake 和 Memcache 后端均支持配置传输 QoS。有效范围为 0-4(仅限整数),未配置时默认值为 0。值越大表示传输优先级越高。无效值(非整数、超出范围)会导致启动时快速失败并报出校验错误。

QoS 可通过 kv_connector_extra_config 进行配置,该配置会自动注入到后端特定的配置中:

{
    "kv_connector": "AscendStoreConnector",
    "kv_role": "kv_both",
    "kv_connector_extra_config": {
        "qos_priority": 1,
        "lookup_rpc_port": "1",
        "backend": "mooncake",
        "use_layerwise": false
    }
}
参数 类型 默认值 是否必填 取值范围 描述
qos_priority int 0 否 [0, 4](整数,越大优先级越高) Mooncake 和 Memcache 后端均支持。无效值(非整数、超出范围)会导致启动快速失败。

kv_connector_extra_config 中的值优先于环境变量;发生覆盖时会输出 WARN 日志。对于 Mooncake 后端,qos_priority 会合并到现有的 ASCEND_GLOBAL_RESOURCE_CONFIG 中(其他字段保持不变)。当未设置 ASCEND_GLOBAL_RESOURCE_CONFIG 时,配置 qos_priority 也会创建它。

常见问题

有关常见的环境、安装和通用参数问题,请参阅公共 FAQ。本章仅涵盖此功能特有的问题。

公共 FAQ 参考:

问题 1:put/get key 失败

问题描述: vLLM 报告 put 或 get 操作失败。

根因分析: 首先判断该错误是否由 Mooncake 自身上报:

  • put 失败:Mooncake 日志显示 NO_AVAILABLE_HANDLE 或 BatchPut failed ... due to insufficient space。这通常意味着驱逐后剩余空间不足以容纳一次 BatchPut 请求。
  • get 失败:Mooncake 日志显示 lease_expired_before_data_transfer_completed key=... 或返回 LEASE_EXPIRED。KV 对象的租约在数据传输完成前已过期。

解决步骤:

  1. 确定错误来源。如果是 Mooncake 报告的 put 失败,请确保驱逐策略的剩余空间(例如 --eviction_ratio)能够容纳一次批量 put,或者增加容量、增加驱逐余量,或减小批量大小。
  2. 如果是 get 失败,请增大 mooncake_master 的 --default_kv_lease_ttl,并使其大于 ASCEND_CONNECT_TIMEOUT 和 ASCEND_TRANSFER_TIMEOUT。
  3. 如果不是 Mooncake 报告的,则很可能是 HIXL(ascend_direct)传输层问题。请收集 /root/ascend/log/debug/plog 下的 plog 文件以进行调查。

问题 2:SEGMENT_NOT_FOUND(SSD 卸载)

问题描述: 客户端日志显示 OffloadObjectHeartbeat failed, error code is SEGMENT_NOT_FOUND。该 rank 的 SSD 卸载会停止,直到该 segment 重新注册。

根因分析: Master 已卸载该 rank 的 LOCAL_DISK segment(通常发生在 client_expired 之后,此时 Ping 停止刷新 TTL)。当 enable_cpu_binding=true 时常见触发场景:Mooncake 在初始化期间启动 Ping,随后 vLLM-Ascend 的 bind_cpus() 执行 migratepages/IRQ 绑定;Ping 线程未被绑定,在默认 client_ttl=10 下会漏掉心跳。

解决步骤:

  1. 临时方案:增大 Master TTL,例如 mooncake_master ... --client_ttl=120。根据你的初始化/预热窗口进行调整(60-120 通常足够)。
  2. 恢复方案:将 Mooncake 升级到 > v0.3.11(main 分支),该版本可以重新挂载 LOCAL_DISK 并重新扫描元数据。
  3. 根本修复:将存储 Ping 线程绑定到 release/隔离的 CPU(需在 Mooncake 侧修改)。
  4. 调试重启时,请将 Master 与 vLLM 一起重启,以避免残留的 segment_already_exists 状态。

问题 3:Fabric 内存未对齐导致分配失败

问题描述: adxl MallocMem / aclrtMapMem 报错 Invalid_Argument。在启用 SSD 卸载时,MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 分配失败可能导致 FileStorage init 段错误并使 vLLM 启动中止。

根因分析: 在 A3 上启用 ASCEND_ENABLE_USE_FABRIC_MEM=1 时,每次 fabric 内存分配必须是 1 GB 的整数倍。Mooncake 不会向上取整,而默认的 1280 MB(1.25 GB)未对齐。

解决步骤: 关于缓冲区对齐和 fabric 内存配额配置,请参见“调优建议 - Mooncake SSD 卸载参数调优”。

问题 4:MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES 过小(BUFFER_OVERFLOW)

问题描述: 在 FileStorage::AllocateBatch 期间,SSD 读取失败并报 BUFFER_OVERFLOW(error_code=-10),当 kv_load_failure_policy=fail 时 vLLM 可能会失败。

根因分析: 当 enable_ssd_offload=true 时,Mooncake 会为每个 rank 分配独立的 SSD 读/写缓冲区。该缓冲区独立于 mooncake.json 中的 global_segment_size——增大 segment 并不能解决 BUFFER_OVERFLOW。

解决步骤: 关于如何增大缓冲区以及调优后如何验证,请参见“调优建议 - Mooncake SSD 卸载参数调优”。

问题 5:Memcache 相关问题

操作前检查(内存检查、A3 可用内存扫描、Ascend 950PR&950DT系列产品签名校验禁用与容器挂载、SSD 磁盘状态检查)在场景 2:Memcache 后端的“步骤 1:前置检查”中描述。有关 Memcache 故障排查,请参阅 Memcache FAQ。

问题 6:DSv4 部署注意事项

为 DSv4 启用 KV Pool 时请注意以下事项。其他历史已知问题已修复(详情请参见 vllm-ascend issue #9975):

  • 启动时必须添加 --no-disable-hybrid-kv-cache-manager;否则服务在启动期间会遇到 OOM 问题。
  • DSv4 会完整存储所有压缩比族的状态,完整存储一个 1M token 的序列大约需要 300GB 空间。这是预期行为,与上游 vLLM 的行为一致;进一步的优化取决于 vLLM 社区。

问题 7:AscendStore KV Pool 已知问题(v0.23.0)

关于 v0.23.0 AscendStore KV Pool 的已知问题,请参见 vllm-ascend issue #12390。