Hy4-preview（实验性）¶

1 简介¶

Hy4 Preview 是腾讯Hy团队开发的下一代旗舰级混合专家（MoE）模型。该模型总参数量为770B，每个token约激活49B参数。

模型主干包含78层：第一层采用标准Dense FFN，其余77层均采用MoE结构。每个MoE层包含256个路由专家和1个共享专家。对于每个token，模型从256个路由专家中选择Top-8个专家进行计算，同时始终激活共享专家。

除主干外，模型还内置1个原生MTP（多token预测）层以支持投机解码。MTP层总参数量约为10B，每个token约激活0.7B参数。

本文档介绍如何使用vLLM-Ascend在昇腾NPU上基于W8A8量化权重快速部署Hy4模型推理。

Warning

当前状态与限制

Hy4 Preview 通过官方 Docker 镜像 quay.io/ascend/vllm-ascend:hy4-a3 开箱即用。配套代码尚未合并到 vLLM-Ascend 仓库中，因此该模型目前不支持从源码安装（pip install 或从源码构建）。
目前仅支持 Atlas A3 (A3)。其他昇腾硬件（例如 Atlas A2系列产品）不支持 Hy4 Preview。
支持的特性中列出的特性仅为本文件中经过验证的部署命令所启用的特性，并不意味着 Hy4 Preview 支持所有特性。这是一个早期访问版本；性能优化和可靠性验证仍在进行中（参见声明）。

2 支持的特性¶

请参阅支持特性列表获取模型的支持特性矩阵。

请参阅特性指南获取特性的配置方法。

以下特性为第5章中已验证部署命令所启用的特性。

特性	描述	配置
张量并行（TP）	将模型拆分到节点内的全部16个NPU上。	`--tensor-parallel-size 16`
专家并行（EP）	将MoE专家（每层256个路由专家+1个共享专家）分布到各NPU上。	`--enable-expert-parallel`
数据并行 (DP)	跨 2 个节点的多节点 DP，将上下文扩展到 96k。	`--data-parallel-size 2`
W8A8量化	加载W8A8量化权重（昇腾量化）。	`--quantization ascend`
自动前缀缓存	为共享的提示词前缀复用KV缓存。	`--enable-prefix-caching`
投机解码（MTP）	使用原生MTP层进行多token预测。	`--speculative-config '{"method": "mtp", "num_speculative_tokens": 3}'`
解码图捕获	将解码阶段捕获为图以减少内核启动开销。	`--compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}'`
NPUGraph EX	昇腾特有的图执行优化。	`--additional-config '{"ascend_compilation_config": {"enable_npugraph_ex": true}}'`

注意： 上述列出的特性为本文档中已验证部署命令所启用的特性。其他特性，如LoRA、流水线并行和Prefill-Decode分离，未在本文档中验证。

3 前提条件¶

3.1 模型权重¶

模型	权重
Hy4-preview	Hugging Face
Hy4-preview-w8a8	ModelScope

本文档使用量化的Hy4-preview-w8a8权重，大小约为762 GB。请将权重下载到本地磁盘。

路径说明：将模型权重下载到您选择的目录并记录该目录。确保后续部署命令中的模型路径与该目录一致。

3.2 硬件和软件准备¶

硬件	Ascend HDK	CANN版本	torch_npu版本	vLLM	vLLM-Ascend版本
Atlas 800I A3（A3）	25.5.0（推荐）	CANN 9.0.1	2.10.0.post2	基于v0.23.0	基于v0.23.0

Hy4 Preview目前**仅支持Atlas 800I A3（A3）**硬件；其他昇腾硬件（如Atlas 800I A2）不受支持。

开始之前，请确认固件/驱动已正确安装。推荐的HDK版本为25.5.0。运行以下命令进行确认；输出头部显示的版本即为HDK版本。

npu-smi info

由于权重较大，单个 A3 节点仅支持约 1k 上下文。如果需要测试 32k 等长序列，建议使用 2 个 A3 节点。

3.3 验证多节点通信（可选）¶

如果要部署多节点环境，请按照验证节点间连接中的说明验证多节点通信。

4 安装¶

4.1 Docker镜像安装¶

下载Docker镜像¶

docker pull quay.io/ascend/vllm-ascend:hy4-a3

下载成功后，检查现有镜像：

docker images | grep hy4-a3

输出应包含已下载的 quay.io/ascend/vllm-ascend:hy4-a3。

创建Docker容器¶

使用以下命令创建容器。Atlas 800I A3 是16卡设备，因此需要挂载 /dev/davinci[0-15] 和管理设备。同时挂载驱动库和权重目录（本指南假设权重存储在宿主机 /mnt/weight 路径下，并挂载到容器内的相同路径）。

export IMAGE=quay.io/ascend/vllm-ascend:hy4-a3
export CONTAINER_NAME=vllm_ascend_hy4

# Generate NPU device mount parameters (Atlas 800I A3: /dev/davinci[0-15])
DEVICES=""
for i in $(seq 0 15); do
    DEVICES="${DEVICES} --device /dev/davinci${i}"
done

docker run -itd \
    --name ${CONTAINER_NAME} \
    --shm-size=1000g \
    ${DEVICES} \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /mnt/weight:/mnt/weight \
    ${IMAGE} bash

-v 选项用于映射目录。您应将权重目录映射到容器中，以便在容器内访问权重。本地权重路径为 /mnt/weight；请根据实际情况进行修改。

进入容器交互环境：

docker exec -it ${CONTAINER_NAME} bash

4.2 源码安装¶

Note

Hy4 Preview 目前通过 quay.io/ascend/vllm-ascend:hy4-a3 Docker 镜像开箱即用提供。由于相关支持代码尚未合并到 vLLM-Ascend 仓库中，目前不支持通过源码安装此模型；请按照4.1 Docker 镜像安装中的说明使用 Docker 镜像。

5 在线服务部署¶

5.1 单节点在线部署¶

A3 单节点 TP=16 全卡推理适用于验证和低并发短序列场景。进入容器交互环境后执行以下操作：

export HCCL_BUFFSIZE=128
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export VLLM_LOGGING_LEVEL=INFO

# Ensure the model path matches the directory recorded during download
vllm serve /path/to/Hy4-preview-w8a8 \
  --host 127.0.0.1 --port 8000 \
  --tensor-parallel-size 16 \
  --served-model-name hy4 \
  --max-num-seqs 8 \
  --max-model-len 512 \
  --max-num-batched-tokens 512 \
  --enable-expert-parallel \
  --trust-remote-code \
  --quantization ascend \
  --gpu-memory-utilization 0.92 \
  --seed 1024 \
  --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
  --speculative-config '{"method": "mtp","num_speculative_tokens": 3}' \
  --additional-config '{"enable_mlapo": true, "enable_fused_mc2": 1, "ascend_compilation_config": {"enable_npugraph_ex": true}}'

5.2 多节点协同部署¶

DP=2 跨机器部署，每个节点 TP=16，可将上下文扩展到 96k。节点 1（Node1，演示 IP 192.168.1.1）承载 DP rank 0 和 API，节点 2（Node2，演示 IP 192.168.1.2）为无头工作节点。两个节点通过 --net=host 共享主机网络。使用与 A3 单节点部署相同的命令，在容器内执行。

启动顺序：

首先在节点1的容器中执行以下脚本（rank 0，包括 API）；
看到 Started DP Coordinator process 日志后，在节点2的容器中执行相应的脚本；
大约20分钟后，看到 Application startup complete 表示服务已就绪。启动时间与权重的磁盘读写速度等因素有关。

节点1脚本：

#!/bin/bash
set -u

# === Node network configuration (adjust the NIC name and IP according to the actual environment) ===
NODE1_IP="192.168.1.1"       # Node 1 IP, change to the actual machine IP
NODE2_IP="192.168.1.2"       # Node 2 IP, change to the actual machine IP
NIC="eth0"                   # Change to the NIC name corresponding to NODE1_IP, viewable via the `ifconfig` command
DP_RPC_PORT=12890

# === Service configuration ===
MODEL="/path/to/Hy4-preview-w8a8"  # Change to the actual weight path
PORT=8000

# === Environment variables ===
export HCCL_BUFFSIZE=128
export HCCL_IF_IP=${NODE1_IP}
export HCCL_OP_EXPANSION_MODE=AIV
export HCCL_SOCKET_IFNAME=${NIC}
export GLOO_SOCKET_IFNAME=${NIC}
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Ensure the model path matches the directory recorded during download
vllm serve ${MODEL} \
  --host 0.0.0.0 \
  --port ${PORT} \
  --data-parallel-size 2 \
  --data-parallel-size-local 1 \
  --data-parallel-address ${NODE1_IP} \
  --data-parallel-rpc-port ${DP_RPC_PORT} \
  --tensor-parallel-size 16 \
  --served-model-name hy4 \
  --enable-expert-parallel \
  --max-num-seqs 256 \
  --max-model-len 96000 \
  --max-num-batched-tokens 1024 \
  --trust-remote-code \
  --quantization ascend \
  --gpu-memory-utilization 0.85 \
  --enable-prefix-caching \
  --seed 1024 \
  --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
  --speculative-config '{"method": "mtp","num_speculative_tokens": 3}' \
  --additional-config '{"enable_mlapo": true, "enable_fused_mc2": 1, "ascend_compilation_config": {"enable_npugraph_ex": true}}'

节点2脚本：

#!/bin/bash
set -u

# === Node network configuration ===
NODE1_IP="192.168.1.1"       # Node 1 IP, change to the actual machine IP
NODE2_IP="192.168.1.2"       # Node 2 IP, change to the actual machine IP
NIC="eth0"                   # Change to the NIC name corresponding to NODE2_IP, viewable via the `ifconfig` command
DP_RPC_PORT=12890

# === Service configuration (consistent with Node 1) ===
MODEL="/path/to/Hy4-preview-w8a8"  # Change to the actual weight path

# === Environment variables (consistent with Node 1) ===
export HCCL_BUFFSIZE=128
export HCCL_IF_IP=${NODE2_IP}
export HCCL_OP_EXPANSION_MODE=AIV
export HCCL_SOCKET_IFNAME=${NIC}
export GLOO_SOCKET_IFNAME=${NIC}
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Ensure the model path matches the directory recorded during download
vllm serve ${MODEL} \
  --headless \
  --data-parallel-start-rank 1 \
  --data-parallel-size 2 \
  --data-parallel-size-local 1 \
  --data-parallel-address ${NODE1_IP} \
  --data-parallel-rpc-port ${DP_RPC_PORT} \
  --tensor-parallel-size 16 \
  --enable-expert-parallel \
  --max-num-seqs 256 \
  --max-model-len 96000 \
  --max-num-batched-tokens 1024 \
  --trust-remote-code \
  --quantization ascend \
  --gpu-memory-utilization 0.85 \
  --enable-prefix-caching \
  --seed 1024 \
  --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
  --speculative-config '{"method": "mtp","num_speculative_tokens": 3}' \
  --additional-config '{"enable_mlapo": true, "enable_fused_mc2": 1, "ascend_compilation_config": {"enable_npugraph_ex": true}}'

注意：--data-parallel-address 在节点1上设置为本地 IP（即协调器），在节点2上设置为头节点 IP；--data-parallel-start-rank 仅在无头节点上设置。

由于权重较大，加载时间与磁盘读取速度相关，首次加载通常需要约10分钟。以下日志表示服务已成功启动：

INFO:     Started server process [PID]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

6 功能验证¶

发送推理请求以测试推理服务，参考以下命令：

curl -sS -X POST http://127.0.0.1:8000/v1/chat/completions -H 'Content-Type: application/json' -d '{
    "model":"hy4",
    "messages":[{
        "role":"user",
        "content":"Who are you?"
    }],
    "max_tokens":256,
    "temperature":0
}'

服务器打印收到的请求日志，类似于：

INFO:     [IP]:[PORT] - "POST /v1/chat/completions HTTP/1.1" 200 OK

预期结果如下：

{"id":"chatcmpl-84c57a059e1d510c","object":"chat.completion","created":1787890448,"model":"hy4","choices":[{"index":0,"message":{"role":"assistant","content":"Okay, I'm the user asking \"Who are you?\" and I need to respond according to my identity and behavioral guidelines. First, my identity is Hunyuan, a large model developed by Tencent. The user's question directly asks about my identity, so I should clearly state who I am without extra information. Based on the core constraints, when the question involves identity confirmation, I need to clearly explain my identity and developer. Also, the user didn't mention any other functions or context, so keeping it concise is fine. Check if there's anything that needs clarification, like whether the user wants to know about features, but the current question is simply an identity inquiry, so a direct answer is enough. Make sure the response meets the format requirements, no markdown, and keep it natural and conversational.</think:opensource>I am Hunyuan, a large model developed by Tencent.","refusal":null,"annotations":null,"audio":null,"function_call":null,"reasoning":null},"logprobs":null,"finish_reason":"stop","stop_reason":null,"token_ids":null,"routed_experts":null}],"service_tier":null,"system_fingerprint":"vllm-0.23.0-tp16-dp2-ep-36628cea","usage":{"prompt_tokens":25,"total_tokens":201,"completion_tokens":176,"prompt_tokens_details":null,"completion_tokens_details":null},"prompt_logprobs":null,"prompt_token_ids":null,"prompt_text":null,"kv_transfer_params":null}

7 精度评估¶

详细信息请参阅使用 AISBench。

8 性能评估¶

详细信息请参阅使用 AISBench 进行性能评估。

更多详细信息请参阅 vllm benchmark。

9 声明¶

当前版本仅用于早期体验，性能优化仍在进行中。
服务可靠性尚未完全验证，不建议直接用于生产环境。