Qwen3-Coder-Next 模型昇腾（Ascend）NPU 适配指南

本文档详细阐述了如何将 Qwen3-Coder-Next 大型代码模型适配到昇腾（Ascend）NPU 上进行推理和部署的全过程。主要涵盖两种主流方案：MindSpeed LLM 全流程部署和 vLLM Ascend 推理。

模型概述

模型名称: Qwen3-Coder-Next
核心特点: 专为编程和智能体场景打造的超大模型，采用混合专家（MoE）架构，基于 Qwen3-Next-80B-A3B-Base 构建。
主要优势: MoE 架构在保持强大能力的同时，显著降低了推理开销，更适合实际部署。
适配状态: 已完成对昇腾 Atlas A2/A3 系列 NPU 的适配。

方案一：使用 MindSpeed LLM 进行全流程部署

MindSpeed LLM 支持模型的预训练、全参数微调和推理部署，适合构建企业级研发平台。

1. 环境准备

1.1 硬件建议

配置项	建议
NPU 型号	Atlas A2 / A3 系列
卡数	建议 4 卡并行 (tensor_parallel_size=4)
内存	根据上下文长度调整，32K 长度建议单卡 32GB+
驱动/固件	在研版本，需支持新一代算子

1.2 软件依赖

组件	版本要求	说明
CANN Toolkit	在研版本	昇腾计算语言，用于算子加速
Python	3.10	推荐运行环境
PyTorch	2.7.1	需配合 torch_npu
torch_npu	对应版本	昇腾 NPU 的 PyTorch 适配库
MindSpeed	在研版本	核心加速库，自动优化 Transformer、MoE 等模块
NNAL	配套版本	Transformer 专用加速库

2. 部署流程

2.1 拉取代码仓库

# 1. 拉取 MindSpeed-LLM 主仓库
git clone https://atomgit.com/ascend/MindSpeed-LLM.git

# 2. 拉取并配置 Megatron-LM（依赖项）
git clone https://github.com/NVIDIA/Megatron-LM.git
cd Megatron-LM
git checkout core_v0.12.1

# 3. 将 Megatron 拷贝到 MindSpeed-LLM 目录下
cp -r megatron ../MindSpeed-LLM/
cd ../MindSpeed-LLM
git checkout master

2.2 创建 Python 环境并安装依赖

# 创建并激活 Conda 环境
conda create -n qwen3-coder python=3.10
conda activate qwen3-coder

# 安装 PyTorch 和 torch_npu（请确保使用与硬件匹配的 .whl 文件）
pip install torch-2.7.1-cp310-cp310m-manylinux2014_aarch64.whl
pip install torch_npu-2.7.1*-cp310-cp310m-linux_aarch64.whl

# 安装 MindSpeed 加速库
git clone https://atomgit.com/ascend/MindSpeed.git
cd MindSpeed
git checkout master
pip install -r requirements.txt
pip install -e .

2.3 模型权重转换

将原始模型权重转换为 MindSpeed LLM 可用的格式。

cd MindSpeed-LLM
bash examples/mcore/qwen3_coder_next/ckpt_convert_qwen3_coder_next_80b_hf2mcore.sh

此脚本自动完成：

权重切分与并行映射
MoE 专家参数重排
与昇腾并行策略对齐

2.4 模型推理

使用提供的脚本启动推理。

# 执行推理生成脚本
bash examples/mcore/qwen3_coder_next/genarate_qwen3_coder_next_80b_ptd.sh

方案二：使用 vLLM Ascend 进行推理部署

vLLM Ascend 方案更适合高性能、生产环境的在线推理服务。

1. 环境准备

1.1 获取模型权重

从 AtomGit AI 镜像站下载模型。

git clone https://ai.atomgit.com/hf_mirrors/Qwen/Qwen3-Coder-Next

或访问页面手动下载： https://ai.atomgit.com/hf_mirrors/Qwen/Qwen3-Coder-Next

1.2 安装 Triton Ascend

确保环境中已安装 Triton Ascend 以支持模型运行。

pip install triton-ascend==3.2.0

2. 启动 Docker 容器

根据硬件选择对应的 vLLM Ascend 镜像启动容器。

# 对于 Atlas A3 机器
export IMAGE=quay.io/ascend/vllm-ascend:v0.14.0rc1

docker run --rm \
  --shm-size=1g \
  --name qwen3-coder-next \
  --device /dev/davinci0 \
  --device /dev/davinci1 \
  --device /dev/davinci2 \
  --device /dev/davinci3 \
  --device /dev/davinci_manager \
  --device /dev/devmm_svm \
  --device /dev/hisi_hdc \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -p 8000:8000 \
  -it $IMAGE bash

3. 执行推理

3.1 离线推理（Python API）

在容器内创建 Python 脚本（如 infer.py）并执行。

import os
os.environ["VLLM_USE_MODELSCOPE"] = "True"
os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"

from vllm import LLM, SamplingParams

def main():
    prompts = [
        "Write a Python function to implement quick sort:",
    ]

    sampling_params = SamplingParams(max_tokens=100, temperature=0.0)

    llm = LLM(
        model="/path/to/model/Qwen3-Coder-Next/",  # 替换为实际权重路径
        tensor_parallel_size=4,      # 4卡张量并行
        trust_remote_code=True,
        max_model_len=10000,          # 根据NPU显存调整
        gpu_memory_utilization=0.8,
    )

    outputs = llm.generate(prompts, sampling_params)
    for output in outputs:
        generated_text = output.outputs[0].text
        print(f"Generated text: {generated_text!r}")

if __name__ == "__main__":
    main()

运行脚本：

python infer.py

3.2 启动在线 API 服务

在容器内启动兼容 OpenAI API 的推理服务。

vllm serve /path/to/model/Qwen3-Coder-Next/ \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.8

3.3 发送测试请求

使用 curl 命令测试服务。

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a Python function to implement quick sort",
    "max_tokens": 512,
    "temperature": 0.0
  }'

license: apache-2.0

Qwen3-Coder-Next 模型昇腾（Ascend）NPU 适配指南

模型概述

模型名称: Qwen3-Coder-Next
核心特点: 专为编程和智能体场景打造的超大模型，采用混合专家（MoE）架构，基于 Qwen3-Next-80B-A3B-Base 构建。
主要优势: MoE 架构在保持强大能力的同时，显著降低了推理开销，更适合实际部署。
适配状态: 已完成对昇腾 Atlas A2/A3 系列 NPU 的适配。

方案一：使用 MindSpeed LLM 进行全流程部署

MindSpeed LLM 支持模型的预训练、全参数微调和推理部署，适合构建企业级研发平台。

1. 环境准备

1.1 硬件建议

配置项	建议
NPU 型号	Atlas A2 / A3 系列
卡数	建议 4 卡并行 (tensor_parallel_size=4)
内存	根据上下文长度调整，32K 长度建议单卡 32GB+
驱动/固件	在研版本，需支持新一代算子

1.2 软件依赖

组件	版本要求	说明
CANN Toolkit	在研版本	昇腾计算语言，用于算子加速
Python	3.10	推荐运行环境
PyTorch	2.7.1	需配合 torch_npu
torch_npu	对应版本	昇腾 NPU 的 PyTorch 适配库
MindSpeed	在研版本	核心加速库，自动优化 Transformer、MoE 等模块
NNAL	配套版本	Transformer 专用加速库

2. 部署流程

2.1 拉取代码仓库

# 1. 拉取 MindSpeed-LLM 主仓库
git clone https://atomgit.com/ascend/MindSpeed-LLM.git

# 2. 拉取并配置 Megatron-LM（依赖项）
git clone https://github.com/NVIDIA/Megatron-LM.git
cd Megatron-LM
git checkout core_v0.12.1

# 3. 将 Megatron 拷贝到 MindSpeed-LLM 目录下
cp -r megatron ../MindSpeed-LLM/
cd ../MindSpeed-LLM
git checkout master

2.2 创建 Python 环境并安装依赖

# 创建并激活 Conda 环境
conda create -n qwen3-coder python=3.10
conda activate qwen3-coder

# 安装 PyTorch 和 torch_npu（请确保使用与硬件匹配的 .whl 文件）
pip install torch-2.7.1-cp310-cp310m-manylinux2014_aarch64.whl
pip install torch_npu-2.7.1*-cp310-cp310m-linux_aarch64.whl

# 安装 MindSpeed 加速库
git clone https://atomgit.com/ascend/MindSpeed.git
cd MindSpeed
git checkout master
pip install -r requirements.txt
pip install -e .

2.3 模型权重转换

将原始模型权重转换为 MindSpeed LLM 可用的格式。

cd MindSpeed-LLM
bash examples/mcore/qwen3_coder_next/ckpt_convert_qwen3_coder_next_80b_hf2mcore.sh

此脚本自动完成：

权重切分与并行映射
MoE 专家参数重排
与昇腾并行策略对齐

2.4 模型推理

使用提供的脚本启动推理。

# 执行推理生成脚本
bash examples/mcore/qwen3_coder_next/genarate_qwen3_coder_next_80b_ptd.sh

方案二：使用 vLLM Ascend 进行推理部署

vLLM Ascend 方案更适合高性能、生产环境的在线推理服务。

1. 环境准备

1.1 获取模型权重

从 AtomGit AI 镜像站下载模型。

git clone https://ai.atomgit.com/hf_mirrors/Qwen/Qwen3-Coder-Next

或访问页面手动下载： https://ai.atomgit.com/hf_mirrors/Qwen/Qwen3-Coder-Next

1.2 安装 Triton Ascend

确保环境中已安装 Triton Ascend 以支持模型运行。

pip install triton-ascend==3.2.0

2. 启动 Docker 容器

根据硬件选择对应的 vLLM Ascend 镜像启动容器。

# 对于 Atlas A3 机器
export IMAGE=quay.io/ascend/vllm-ascend:v0.14.0rc1

docker run --rm \
  --shm-size=1g \
  --name qwen3-coder-next \
  --device /dev/davinci0 \
  --device /dev/davinci1 \
  --device /dev/davinci2 \
  --device /dev/davinci3 \
  --device /dev/davinci_manager \
  --device /dev/devmm_svm \
  --device /dev/hisi_hdc \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -p 8000:8000 \
  -it $IMAGE bash

3. 执行推理

3.1 离线推理（Python API）

在容器内创建 Python 脚本（如 infer.py）并执行。

import os
os.environ["VLLM_USE_MODELSCOPE"] = "True"
os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"

from vllm import LLM, SamplingParams

def main():
    prompts = [
        "Write a Python function to implement quick sort:",
    ]

    sampling_params = SamplingParams(max_tokens=100, temperature=0.0)

    llm = LLM(
        model="/path/to/model/Qwen3-Coder-Next/",  # 替换为实际权重路径
        tensor_parallel_size=4,      # 4卡张量并行
        trust_remote_code=True,
        max_model_len=10000,          # 根据NPU显存调整
        gpu_memory_utilization=0.8,
    )

    outputs = llm.generate(prompts, sampling_params)
    for output in outputs:
        generated_text = output.outputs[0].text
        print(f"Generated text: {generated_text!r}")

if __name__ == "__main__":
    main()

运行脚本：

python infer.py

3.2 启动在线 API 服务

在容器内启动兼容 OpenAI API 的推理服务。

vllm serve /path/to/model/Qwen3-Coder-Next/ \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.8

3.3 发送测试请求

使用 curl 命令测试服务。

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a Python function to implement quick sort",
    "max_tokens": 512,
    "temperature": 0.0
  }'