GLM-4.7 接入 UCM 外部 KV Cache：vLLM-Ascend（Atlas 800 A2）与 vLLM（H100）双平台部署实战

本文基于 UCM（unified-cache-management）仓库中 Model Tour 的 GLM 文档，完整演示如何在 Ascend Atlas 800 A2 与 NVIDIA H100 两类硬件上，将 GLM-4.7 模型部署为带 UCM 外部 KV Cache 持久化能力的 vLLM / vLLM-Ascend 推理服务：从 Docker 容器启动、UCM YAML 配置、--kv-transfer-config 接线到 API 验证，并对照仓库源码解释每个关键参数与配置加载链路，帮助读者直接复制运行并理解 UCM 在 vLLM 中的集成机制。

一、适用场景与支持范围

UCM 的 Model Tour 按模型家族组织部署教程，GLM 家族页面提供两条完整部署路线：

• Atlas 800 A2（Ascend NPU）：部署 GLM-4.7-W8A8-floatmtp（W8A8 量化 + float MTP 权重，可在 ModelScope 的 Eco-Tech/GLM-4.7-W8A8-floatmtp 获取），推理引擎为 vLLM-Ascend，使用预构建的 UCM Docker 镜像；
• NVIDIA H100（CUDA）：部署 GLM-4.7-FP8（FP8 权重），推理引擎为 vLLM，同样使用预构建 UCM 镜像。

仓库的支持矩阵（docs/docs-site/docs/en/user-guide/support-matrix/index.md）中，GLM-4.x 在 vLLM、vLLM-Ascend、SGLang 三个引擎列均标记为 Supported；计算平台覆盖 CANN（910C、910B、950PR、950DT）与 CUDA（H100、H20、L40、L20）。GLM-4.7 属于 GLM-4.x 系列，与本页教程一致。

两条路线的共同骨架是：

1. 宿主机上启动 UCM 预构建镜像容器，挂载模型权重与缓存目录；
2. 容器内生成 UCM 配置文件（Cache|Posix 管线：主机内存缓存 + Posix 文件系统持久化）；
3. 通过 vLLM 的 --kv-transfer-config 参数接入 UCMConnector，指定 UCM_CONFIG_FILE；
4. 用 OpenAI 兼容 API 验证服务。

下文按两条路线分别给出全部可复制命令，并在最后结合仓库源码统一解析关键参数。

二、路线一：vLLM-Ascend + GLM-4.7-W8A8-floatmtp（Atlas 800 A2）

2.1 启动 Docker 容器

将 MODEL_PATH 设为宿主机上的本地模型目录，并从 Quickstart 中复制一个支持 GLM-4.7 且匹配你 Ascend 硬件的 UCM 镜像引用到 IMAGE。以下命令在宿主机上执行：

export MODEL_PATH=/data/weights/GLM-4.7-W8A8-floatmtp
export IMAGE='<full Ascend UCM image reference from Quickstart>'
export CONTAINER_NAME=glm47-ucm

mkdir -p /data/ucm/cache /data/ucm/log
docker pull "$IMAGE"

docker run --rm -it \
    --name "$CONTAINER_NAME" \
    --network host \
    --ipc=host \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci2 \
    --device /dev/davinci3 \
    --device /dev/davinci4 \
    --device /dev/davinci5 \
    --device /dev/davinci6 \
    --device /dev/davinci7 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi:ro \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool:ro \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi:ro \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
    -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
    -v /etc/hccn.conf:/etc/hccn.conf:ro \
    -v "$MODEL_PATH:/data/weights/GLM-4.7-W8A8-floatmtp:ro" \
    -v /data/ucm:/data/ucm \
    -e ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
    -e ENABLE_UCM_PATCH=1 \
    -e UCM_LOG_PATH=/data/ucm/log \
    --workdir /workspace \
    --entrypoint /bin/bash \
    "$IMAGE"

要点说明：

• 8 张 910 系列 NPU 通过 --device /dev/davinci{0..7} 逐个直通，ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 让运行时可见全部 8 卡，与后面 --tensor-parallel-size 8 对应；
• ENABLE_UCM_PATCH=1 是关键开关：它触发 UCM 对 vLLM 的运行时 monkey patch。从源码看，ucm/integration/vllm/patch/apply_patch.py 中读取该环境变量（值为 1/true 时启用），用于替代手工 git apply，把 UCM 需要的引擎改造打进当前 vLLM 进程；
• UCM_LOG_PATH=/data/ucm/log 指定 UCM 日志目录；/data/ucm 挂载进容器，其中 cache 子目录用于 KV 数据落盘；
• 宿主机 Ascend 驱动（/usr/local/Ascend/driver、ascend_install.info、hccn.conf 等）以只读方式挂入容器。

2.2 配置 UCM

进入容器内执行，创建 /workspace/ucm_config_example.yaml：

cat > /workspace/ucm_config_example.yaml <<'EOF'
ucm_connectors:
  - ucm_connector_name: "UcmPipelineStore"
    ucm_connector_config:
      store_pipeline: "Cache|Posix"
      storage_backends: "/data/ucm/cache"
      io_direct: false
      cache_buffer_capacity_gb: 64
      posix_capacity_gb: 0
      use_gdr: false

enable_event_sync: true
use_layerwise: true
enable_record_traces: false
use_lite: false
persist_token_threshold: 0
EOF

该配置与仓库示例 examples/ucm_config_example.yaml 结构一致，各字段含义（完整字段定义见 Configuration Parameters）：

• ucm_connector_name: UcmPipelineStore：选择 Pipeline Store，其 store_pipeline 在 ucm/store/pipeline/connector.py 中注册，Cache|Posix 属于正常生产用例；
• store_pipeline: "Cache|Posix"：KV 数据先经过主机内存缓存（Cache 级），再持久化到 Posix 文件系统（/data/ucm/cache），实现"快路径命中 + 冷数据落盘"的两级布局；
• io_direct: false：走 OS PageCache 而非 Direct I/O（默认值为 true，即绕过 PageCache）；
• cache_buffer_capacity_gb: 64：显式为 Cache 级设置 64 GiB 主机缓冲预算。若不显式配置，vLLM connector 在共享缓冲启用时会取 128 GiB 默认值，显式正容量会覆盖该默认；
• posix_capacity_gb: 0：关闭基于容量的 Posix 垃圾回收（GC 触发条件为已用量 >= posix_capacity_gb * posix_gc_trigger_threshold_ratio，取 0 即不触发）；注意它不会禁止文件系统写入，只是不做容量回收；
• 根级开关：enable_event_sync: true（性能优化开关，推荐开启）、use_layerwise: true（逐层 load/save 模式，推荐值）、use_lite: false（Lite 模式只存/查元数据不搬 KV 数据，仅用于估算命中率）、persist_token_threshold: 0（请求长度低于该阈值时 UCM 不处理，0 表示不限制）。

2.3 启动推理服务

服务参数需参考 vLLM-Ascend 官方文档的 GLM4.x 指南。以下命令在容器内执行：

export MODEL_PATH=/data/weights/GLM-4.7-W8A8-floatmtp
export ENABLE_UCM_PATCH=1
export VLLM_CPU_AFFINITY=1
export HCCL_BUFFSIZE=512

export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_OP_EXPANSION_MODE=AIV

export VLLM_ASCEND_BALANCE_SCHEDULING=1
export VLLM_ASCEND_ENABLE_TOPK_OPTIMIZE=1

vllm serve "$MODEL_PATH" \
    --host 0.0.0.0 \
    --port 7800 \
    --data-parallel-size 1 \
    --tensor-parallel-size 8 \
    --enable-expert-parallel \
    --seed 1024 \
    --served-model-name glm \
    --max-model-len 133000 \
    --max-num-batched-tokens 8192 \
    --max-num-seqs 16 \
    --async-scheduling \
    --quantization ascend \
    --trust-remote-code \
    --gpu-memory-utilization 0.9 \
    --speculative-config '{"num_speculative_tokens":3,"method":"mtp"}' \
    --compilation-config '{"cudagraph_capture_sizes":[1,2,4,8,16,32,64,128,256,512],"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --additional-config '{"enable_cpu_binding":false,"enable_shared_expert_dp":true,"ascend_fusion_config":{"fusion_ops_gmmswigluquant":false}}' \
    --kv-transfer-config '{
        "kv_connector": "UCMConnector",
        "kv_connector_module_path": "ucm.integration.vllm.ucm_connector",
        "kv_role": "kv_both",
        "kv_connector_extra_config": {
            "UCM_CONFIG_FILE": "/workspace/ucm_config_example.yaml"
        }
    }'

关键参数解读：

• --quantization ascend：匹配 W8A8 量化权重在 NPU 上的反量化路径；
• --tensor-parallel-size 8 + --enable-expert-parallel：8 卡 TP，并对 MoE 专家启用专家并行；
• --speculative-config '{"num_speculative_tokens":3,"method":"mtp"}：启用 MTP（Multi-Token Prediction）投机解码，与 floatmtp 权重配套；
• --max-model-len 133000：约 133K 上下文，是长上下文 KV 复用场景的主要收益来源。

--kv-transfer-config 是 vLLM 与 UCM 的接线点：

字段	作用
kv_connector	选择 UCMConnector。
kv_connector_module_path	指定 connector 模块：ucm.integration.vllm.ucm_connector。
kv_role	kv_both 同时启用 KV Cache 的加载（load）与保存（save）。
kv_connector_extra_config.UCM_CONFIG_FILE	指向第 2.2 步创建的 /workspace/ucm_config_example.yaml。

2.4 调用 API 验证

服务就绪后，打开宿主机上的第二个终端：

curl --fail http://127.0.0.1:7800/health
curl --fail http://127.0.0.1:7800/v1/models

curl --fail-with-body http://127.0.0.1:7800/v1/chat/completions \
    -H 'Content-Type: application/json' \
    -d '{
        "model": "glm",
        "messages": [
            {
                "role": "user",
                "content": "Explain the role of KV cache in large language model inference."
            }
        ],
        "max_completion_tokens": 1024,
        "temperature": 0
    }'

预期结果：HTTP 200、/v1/models 返回模型列表中包含 glm、chat completion 响应包含 choices 字段。注意 HTTP 服务就绪只说明引擎启动成功，并不等于 UCM 缓存命中；要确认外部缓存生效，请按 Quickstart 的验证方法，用跨越多个 128-token block 的可复现长前缀重放请求，并检查 ucm: 前缀的 metrics 与外部命中计数。

三、路线二：vLLM + GLM-4.7-FP8（NVIDIA H100）

3.1 启动 Docker 容器

在宿主机设置 MODEL_PATH 为本地模型目录，并从 Quickstart 复制一个支持该模型与 H100 的 CUDA UCM 镜像引用到 IMAGE：

export MODEL_PATH=/data/weights/GLM-4.7-FP8
export IMAGE='<full CUDA UCM image reference from Quickstart>'
export CONTAINER_NAME=glm47-ucm-h100

mkdir -p /data/ucm/cache /data/ucm/log
docker pull "$IMAGE"

docker run --rm -it \
    --name "$CONTAINER_NAME" \
    --gpus '"device=0,1,2,3,4,5,6,7"' \
    --ipc=host \
    --network=host \
    -v "$MODEL_PATH:/data/weights/GLM-4.7-FP8:ro" \
    -v /data/ucm:/data/ucm \
    --workdir /workspace \
    --entrypoint /bin/bash \
    "$IMAGE"

与 A2 路线相比，CUDA 路线只需 --gpus 设备直通与 --ipc=host（保证共享内存充足），无需 Ascend 驱动挂载。

3.2 配置 UCM

在容器内执行，配置内容与 A2 路线一致，同样使用 Cache|Posix 管线写入 /data/ucm/cache：

mkdir -p /data/ucm/cache /data/ucm/log

cat > /workspace/ucm_config_example.yaml <<'EOF'
ucm_connectors:
  - ucm_connector_name: "UcmPipelineStore"
    ucm_connector_config:
      store_pipeline: "Cache|Posix"
      storage_backends: "/data/ucm/cache"
      io_direct: false
      cache_buffer_capacity_gb: 64
      posix_capacity_gb: 0
      use_gdr: false

enable_event_sync: true
use_layerwise: true
enable_record_traces: false
use_lite: false
persist_token_threshold: 0
EOF

• Cache|Posix：KV 数据经主机内存中转并持久化到 /data/ucm/cache；
• cache_buffer_capacity_gb: 64：主机缓存缓冲预算 64 GiB；
• posix_capacity_gb: 0：关闭容量式 GC，但不影响文件系统写入。

参数完整定义见 Configuration Parameters。

3.3 启动推理服务

在容器内执行：

export MODEL_PATH=/data/weights/GLM-4.7-FP8
export ENABLE_UCM_PATCH=1
export UCM_LOG_PATH=/data/ucm/log

vllm serve "$MODEL_PATH" \
    --host 0.0.0.0 \
    --port 7800 \
    --data-parallel-size 1 \
    --tensor-parallel-size 8 \
    --served-model-name glm47 \
    --max-model-len 32768 \
    --max-num-seqs 8 \
    --max-num-batched-tokens 8192 \
    --trust-remote-code \
    --gpu-memory-utilization 0.90 \
    --enable-prefix-caching \
    --block-size 128 \
    --enable-auto-tool-choice \
    --tool-call-parser glm47 \
    --reasoning-parser glm45 \
    --speculative-config '{"method":"mtp","num_speculative_tokens":1}' \
    --enforce-eager \
    --kv-transfer-config '{
        "kv_connector": "UCMConnector",
        "kv_connector_module_path": "ucm.integration.vllm.ucm_connector",
        "kv_role": "kv_both",
        "kv_connector_extra_config": {
            "UCM_CONFIG_FILE": "/workspace/ucm_config_example.yaml"
        }
    }'

CUDA 路线的模型侧要点：

• --served-model-name glm47：对外模型名与 A2 路线的 glm 不同，调用 API 时务必一致；
• --enable-prefix-caching + --block-size 128：开启引擎内前缀缓存，128 token 的块大小与 UCM 外部缓存的块粒度对齐；
• --tool-call-parser glm47、--reasoning-parser glm45：分别启用 GLM-4.7 的自动工具调用解析与 GLM-4.5 风格的推理内容解析；
• --speculative-config '{"method":"mtp","num_speculative_tokens":1}'：单 token MTP 投机解码；
• --max-model-len 32768：32K 上下文，长于 A2 路线的 133K 设定，可按显存与业务调整。

--kv-transfer-config 各字段作用与 A2 路线表格完全一致（kv_connector、kv_connector_module_path、kv_role: kv_both、UCM_CONFIG_FILE）。

3.4 调用 API 验证

服务就绪后，在宿主机第二个终端执行（注意 model 字段为 glm47）：

curl --fail http://127.0.0.1:7800/health
curl --fail http://127.0.0.1:7800/v1/models

curl --fail-with-body http://127.0.0.1:7800/v1/chat/completions \
    -H 'Content-Type: application/json' \
    -d '{
        "model": "glm47",
        "messages": [
            {
                "role": "user",
                "content": "Explain the role of KV cache in large language model inference."
            }
        ],
        "max_completion_tokens": 1024,
        "temperature": 0
    }'

预期结果：HTTP 200、模型列表包含 glm47、响应含 choices 字段。

四、配置加载链路与关键实现（源码级）

以上两条路线共用同一套 vLLM 集成机制，结合仓库源码可以看清完整链路：

1. YAML 解析：--kv-transfer-config 传入的 kv_connector_extra_config.UCM_CONFIG_FILE 由 ucm/utils.py 中的 Config._load_config 读取——若存在 UCM_CONFIG_FILE 键则调用 load_ucm_config_from_yaml 加载 YAML 文件（文件缺失或解析失败会记录日志并回退为空配置）；若未提供该键，则退化为直接把 kv_connector_extra_config 作为配置（向后兼容），两者都没有时使用默认的 UcmNfsStore 配置并打印告警。
2. 连接器实例化：ucm/integration/vllm/ucm_connector.py 中的 UCMConnector（继承 vLLM 的 KVConnectorBase_V1 并实现 SupportsHMA）在构造时读取 ENABLE_UCM_PATCH 与 VLLM_CPU_AFFINITY 两个环境变量并打印环境检查日志（L3235-L3243），随后经 Config(vllm_config.kv_transfer_config) 得到 launch_config，即你在 YAML 中写的全部参数。这也是为什么两条路线都要求导出 ENABLE_UCM_PATCH=1：运行时补丁开关与 connector 缺一不可。
3. Store 构建：UcmPipelineStore 由 ucm/store/factory_v1.py 按 ucm_connector_name 映射到 ucm/store/pipeline/connector.py 中的实现类，store_pipeline 字符串再通过 UcmPipelineStoreBuilder.register("Cache|Posix", ...) 注册表（L395）找到对应 builder，按"Cache 级 → Posix 级"组装管线。启动日志中确认出现 create UcmPipelineStore with config: 及预期存储路径，是管线装配成功的直观信号。
4. 角色与容错：kv_role: kv_both 使 connector 同时承担 load/save 职责；源码中还可以看到，对多 KV 分组（hybrid multi-group）模型，UCMConnector 明确拒绝 kv_load_failure_policy='recompute' 组合（L3247-L3270），默认 fail 策略下加载失败的请求会走引擎自身的重算路径。

五、验证、排障与调优建议

• 区分"服务就绪"与"缓存命中"：/health 与 /v1/models 通过只证明引擎起来了。按 Quickstart 的方法，构造跨越多个 128-token block 的可复现长前缀请求发送两次（或保留缓存目录后重启服务再重放），检查 /metrics 中 ucm: 前缀指标的外部命中数、完成加载数与输出正确性；
• 多实例共享存储：posix_capacity_gb 只控制 GC 预算，不预留文件系统空间。多实例共享同一文件系统时，应只让一个实例启用 GC，其余保持 0，避免各自按独立预算回收；
• 命中率评估：需要单独评估 KV Cache 命中率而不实际搬运数据时，可临时设 use_lite: true（只存/查元数据，无加速效果），评估完毕再切回 false；
• 参数修改：存储与后端的更多选项（Mooncake、3FS、压缩、NFS 直连等）见 developer-guide/cache-configuration；命中缺失或加载失败的通用排查见 troubleshooting。

六、小结

GLM 家族的 UCM 部署遵循统一模板：容器挂载权重与缓存目录 → 容器内生成 Cache|Posix 管线 YAML → --kv-transfer-config 指定 UCMConnector 与 UCM_CONFIG_FILE → OpenAI 兼容 API 验证。A2 路线面向 W8A8 + MTP 的 8 卡 NPU 长上下文（133K）部署，H100 路线面向 FP8 权重的 8 卡 GPU 部署，二者的差异集中在量化方式、上下文长度、投机解码规模与工具/推理解析器上，UCM 侧配置则完全一致。掌握这一模板后，替换权重路径与模型专属引擎参数，即可将同一套外部 KV Cache 加速方案平移到 Model Tour 中的其他模型家族。