DeepSeek-V4 Inference on NPU

概述

DeepSeek团队发布了最新的模型DeepSeek-V4，本实践基于DeepSeek开源代码进行迁移，并在CANN平台上完成性能优化，支持在昇腾Atlas A3 Pod平台和950PR/DT平台部署。

本实践的优化特性和性能Benchmark可参见NPU DeepSeek-V4推理优化实践。

硬件要求

产品型号：Atlas A3 Pod 系列

操作系统：Linux ARM

镜像版本：cann9.0_pt2.8.0_ds_aarch_image:v1.2

驱动版本：Ascend HDK 25.5.1

npu-smi info 检查Ascend NPU固件和驱动是否正确安装。如果已安装，通过命令npu-smi info确认版本是否为25.5.1。如果未安装或者版本不是25.5.1，请先下载固件和驱动包，并根据指导自行安装。

CANNLab一站式开发平台指南

CANNLab一站式开发平台已预置部署运行环境，使用CANNLab一站式开发平台时请以本章节为准，无需执行标准流程中的 docker 相关步骤。

模型支持：CANNLab一站式开发平台环境为 Atlas A3 8卡环境，仅支持部署 DeepSeek-V4 Flash。
环境部署：平台已搭建好运行环境，无需获取 docker 镜像，也无需拉起 docker 容器。
CANN 路径：CANN 安装路径为 /home/developer/Ascend/cann，涉及 cann_path 的脚本（如权重转换前的 source 命令）均需使用此路径。
YAML 配置：CANNLab一站式开发平台请使用 ci_a3/deepseek_v4_flash_rank_16_16ep_w8a8_platform.yaml 作为配置文件。由于CANNLab一站式开发平台和 A3 Pod 硬件核数差异，本实践不支持多流控核，yaml 配置中 enable_limit_core 需设置为 False。

以下快速启动章节中各步骤的标准操作适用于非CANNLab一站式开发平台环境，CANNLab一站式开发平台用户请根据上述差异调整对应步骤。

快速启动

下载源码

在各个节点上执行如下命令下载 cann-recipes-infer 源码。

mkdir -p /home/code; cd /home/code/
git clone https://gitcode.com/cann/cann-recipes-infer.git
cd cann-recipes-infer

下载数据集

从链接中下载长序列输入数据集longbook_qa_eng，并上传到各个节点上新建的路径dataset/InfiniteBench下。

mkdir -p dataset/InfiniteBench

下载权重

下载DeepSeek-V4-Flash原始Hybrid FP8-MXFP4权重或DeepSeek-V4-Pro原始Hybrid FP8-MXFP4权重，并上传到各节点的某个固定的路径下，比如/data/models/deepseek_v4_hybrid_fp8_mxfp4。

获取 docker 镜像

从ARM镜像地址中下载 docker 镜像，然后上传到A3服务器的每个节点上，并通过命令导入镜像 docker load -i cann9.0_pt2.8.0_ds_aarch_image_v1.2.tar。

拉起 docker 容器

在各个节点上通过如下脚本拉起容器，默认容器名为 cann_recipes_infer。注意：需要将权重路径和源码路径挂载到容器里。

# A3 容器拉起脚本
docker run -u root -itd --name cann_recipes_infer --ulimit nproc=65535:65535 --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/davinci8     --device=/dev/davinci9 \
    --device=/dev/davinci10    --device=/dev/davinci11 \
    --device=/dev/davinci12    --device=/dev/davinci13 \
    --device=/dev/davinci14    --device=/dev/davinci15 \
    --device=/dev/davinci_manager --device=/dev/devmm_svm \
    --device=/dev/hisi_hdc \
    -v /home/:/home \
    -v /data:/data \
    -v /etc/localtime:/etc/localtime \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -v /etc/ascend_install.info:/etc/ascend_install.info -v /var/log/npu/:/usr/slog \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
    -v /usr/local/dcmi:/usr/local/dcmi -v /usr/local/sbin:/usr/local/sbin \
    -v /etc/hccn.conf:/etc/hccn.conf -v /root/.pip:/root/.pip -v /etc/hosts:/etc/hosts \
    -v /usr/bin/hostname:/usr/bin/hostname \
    --net=host \
    --shm-size=128g \
    --privileged \
    cann9.0_pt2.8.0_ds_aarch_image:v1.2 /bin/bash

在各个节点上通过如下命令进入容器：

docker attach cann_recipes_infer
cd /home/code/cann-recipes-infer/models/deepseek_v4

转换权重中的config.json

使用原生Hybrid FP8-MXFP4版本权重执行推理时需要执行这一步骤，其他场景跳过该步骤。需要进入容器并在各个节点上使用utils/convert_config.py 脚本完成权重路径下的config.json转换。

注意： 该步骤不会对权重进行任何处理，仅将新生成的config.json覆盖原始config.json，如需保留原始config.json，请自行备份

如果权重config.json转换的运行环境为NPU，需要先执行：

cann_path=/usr/local/Ascend/cann  # cann包安装路径
source ${cann_path}/bin/setenv.bash

入参介绍：input_fp8_hf_path：原始权重路径；

拉起示例：

python utils/convert_config.py --input_fp8_hf_path /data/models/deepseek_v4

转换权重

原生Hybrid FP8-MXFP4权重执行推理时可跳过这一步骤，若需要使用 INT8、Hybrid INT8-INT4、Hybrid MXFP8-MXFP4 或 Hybrid HiF8-MXFP8-MXFP4 权重执行推理，需要进入容器并在各个节点上使用utils/convert_model.py 脚本完成 Hybrid FP8-MXFP4 到 INT8/Hybrid INT8-INT4 /Hybrid MXFP8-MXFP4 /Hybrid HiF8-MXFP8-MXFP4 权重转换。

入参介绍：input_fp8_hf_path：原始权重路径；output_hf_path：转换后输出的权重路径；quant_type：量化模式；quant_param_path：量化参数文件夹路径（仅适用于DeepSeek-V4-Pro的Hybrid INT8-INT4量化）

如果权重转换的运行环境为NPU，需要先执行：

cann_path=/usr/local/Ascend/cann  # cann包安装路径
source ${cann_path}/bin/setenv.bash

如果想要获取DeepSeek-V4-Pro的Hybrid INT8-INT4 量化权重，需要预先从Hybrid INT8-INT4 量化参数中下载量化参数并解压缩。

权重转换拉起示例：

# 转换为W8A8-INT8权重，适用于Atlas A3 Pod系列
python utils/convert_model.py --input_fp8_hf_path /data/models/deepseek_v4  --output_hf_path /data/models/deepseek_v4_int8_w8a8 --quant_type w8a8-int

# 转换为Hybrid INT8-INT4权重，适用于Atlas A3 Pod系列，DeepSeek-V4-Pro模型
python utils/convert_model.py --input_fp8_hf_path /data/models/deepseek_v4  --output_hf_path /data/models/deepseek_v4_int4_w4a8 --quant_type w4a8-int --quant_param_path /path/to/your_quant_param_folder

# 转换为Hybrid MXFP8-MXFP4权重，适用于950PR/DT系列
python utils/convert_model.py --input_fp8_hf_path /data/models/deepseek_v4  --output_hf_path /data/models/deepseek_v4_hybrid_mxfp8_mxfp4 --quant_type w4a8-mx

# 转换为Hybrid HiF8-MXFP8-MXFP4权重，适用于950PR/DT系列
python utils/convert_model.py --input_fp8_hf_path /data/models/deepseek_v4  --output_hf_path /data/models/deepseek_v4_hybrid_hif8_mxfp8_mxfp4 --quant_type w4a8-mx-hif

修改配置

在各个节点上修改公共环境脚本 cann-recipes-infer/executor/scripts/set_env.sh 中的如下字段:
- IPs：离线模式配置所有节点的IP，按照rank id排序，多个节点的ip通过空格分开，例如：('xxx.xxx.xxx.xxx' 'xxx.xxx.xxx.xxx')。
- PREFILL_IPS / DECODE_IPS：在线 PD 模式分别配置 prefill 和 decode 节点 IP。
- cann_path: CANN软件包安装路径，例如/usr/local/Ascend/cann。
executor/scripts/infer.sh 会先加载公共环境脚本 executor/scripts/set_env.sh；然后再继续加载模型私有环境脚本 models/deepseek_v4/set_env.sh。
在Atlas A3 Pod各个节点上修改 config/ci_a3 路径下需要执行的yaml文件中的 model_config.model_path 真实路径；在950PR/DT各个节点上修改 config/ci_950 路径下需要执行的yaml文件中的 model_config.model_path 路径。通用 YAML 配置说明可参见YAML参数描述。
在 yaml 配置中，默认采用 npugraph_ex 执行方式。这一后端是 NPU 平台全新推出的高性能图计算组件，其基于 CANN 的 AclGraph（对标 CUDAGraph）底层能力，深度融合了一系列 NPU 架构的亲和调度和图优化技术。从落地层面来看，npugraph_ex 具备以下显著优势：可快速接入 PyTorch 生态、能无缝集成到 SGLang、vLLM 等主流推理框架中，同时保障极致的运行性能。

除框架统一配置之外，DeepSeek-V4 还额外支持以下特性，放置在 YAML 文件 model_config 的 custom_params 字段下：

参数名	类型	默认值	含义
`enable_multi_streams`	bool	`false`	启用模型内多流并行，主要用于 decode 阶段 MLA、Indexer、Compressor、MoE shared expert 等模块的并行调度。
`enable_limit_core`	bool	`false`	在 Atlas A3 上配合多流使用，对部分算子限制 AI Core 数以提升多流重叠效果；开启时要求 `enable_multi_streams=True`，且不支持 `enable_pypto=True`。
`enable_pypto`	bool	`false`	启用 PyPTO 算子路径；当前与 `enable_limit_core` 互斥。
`moe_chunk_max_len`	int	`65536`	MoE token 分发的最大 chunk 长度，用于长序列 prefill 场景规避 OOM。

CANNLab一站式开发平台 A3 场景请使用 ci_a3/deepseek_v4_flash_rank_16_16ep_w8a8_platform.yaml，详见CANNLab一站式开发平台指南。

Note: 在A3环境下，INT8 W8A8场景支持 4~64卡部署。可分别在config下的yaml文件中修改 parallel_config.world_size（chips * 2）配置。

拉起多卡推理

以下命令在仓库根目录执行。统一入口脚本位于 executor/scripts/infer.sh，通过以下参数控制启动：

参数	含义	取值示例
`--model`	模型目录名，对应 `models/` 下的子目录	`deepseek_v4`
`--mode`	推理模式	`offline` / `online`
`--yaml`	离线模式：yaml 文件名，路径相对 `models/deepseek_v4/config/`	`ci_a3/deepseek_v4_flash_rank_128_128ep_w8a8.yaml`
`--pd-role`	在线 PD 模式部署角色	`prefill` / `decode`
`--p-yaml-name`	可选，在线模式 prefill yaml 文件名	`ci_a3/deepseek_v4_pd/prefill.yaml`
`--d-yaml-name`	可选，在线模式 decode yaml 文件名	`ci_a3/deepseek_v4_pd/decode.yaml`

在线模式 IP 等更多配置可参考 executor 设计文档 §5.1 启动方式。

使用方式一：命令行传参

# offline 模式，A3 Flash
bash executor/scripts/infer.sh --model deepseek_v4 --yaml ci_a3/deepseek_v4_flash_rank_128_128ep_w8a8.yaml

# offline 模式，CANNLab A3
bash executor/scripts/infer.sh --model deepseek_v4 --yaml ci_a3/deepseek_v4_flash_rank_16_16ep_w8a8_platform.yaml

# offline 模式，950PR/DT
bash executor/scripts/infer.sh --model deepseek_v4 --yaml ci_950/deepseek_v4_pro_rank_16_16ep.yaml

# online PD 模式，暂时只支持A3机型
bash executor/scripts/infer.sh --model deepseek_v4 --mode online --pd-role prefill --p-yaml-name ci_a3/deepseek_v4_pd/prefill.yaml --d-yaml-name ci_a3/deepseek_v4_pd/decode.yaml
bash executor/scripts/infer.sh --model deepseek_v4 --mode online --pd-role decode --p-yaml-name ci_a3/deepseek_v4_pd/prefill.yaml --d-yaml-name ci_a3/deepseek_v4_pd/decode.yaml

如需查看参数说明，可执行 bash executor/scripts/infer.sh --help。

使用方式二：直接修改脚本默认值后执行 编辑 executor/scripts/infer.sh，按需修改 MODEL / MODE / YAML_FILE / PD_ROLE / P_YAML_NAME / D_YAML_NAME 等参数的默认值，例如：

MODEL=deepseek_v4
MODE=offline
YAML_FILE=ci_a3/deepseek_v4_flash_rank_128_128ep_w8a8.yaml

保存后直接执行：

bash executor/scripts/infer.sh

如果是多机环境，需要在每个节点上同步执行拉起命令。

Note： 不同平台最小部署单元要求如下

平台	模型型号	推荐量化策略	最小部署单元（chips）
950PR/DT	DeepSeek-V4 Flash	Hybrid MXFP8-MXFP4	4
950PR/DT	DeepSeek-V4 Flash	Hybrid HiF8-MXFP8-MXFP4	4
950PR/DT	DeepSeek-V4 Pro	Hybrid MXFP8-MXFP4	16
Atlas A3	DeepSeek-V4 Flash	INT8 W8A8	4
Atlas A3	DeepSeek-V4 Pro	Hybrid INT8-INT4	32