介绍

Qwen3是Qwen系列中最新一代的大型语言模型，提供了密集和混合专家(MoE)模型的全面套件。基于广泛的训练，Qwen3在推理、指令遵循、代理功能和多语言支持方面取得了很大的进展，主要具有以下功能：

• 思维模式（用于复杂的逻辑推理、数学和编码）和非思维模式（用于高效、通用的对话）在单个模型内无缝切换，确保跨各种场景的最佳性能。
• 增强了推理能力在数学、代码生成和常识逻辑推理方面超过了之前的QwQ（思维模式）和Qwen2.5（非思维模式）。
• 人类偏好调整，擅长创意写作、角色扮演、多轮对话和指令跟随，提供更自然、更吸引人、更沉浸式的对话体验。
• 在代理能力方面的专业知识，能够在思考模式和非思考模式下与外部工具精确集成，在基于代理的复杂任务中实现开源模型中的领先性能。
• 支持100多种语言和方言，具有强大多语言教学能力和翻译能力。

训练

本教程将指导从环境准备到模型训练的完整过程，确保快速上手并顺利跑通Qwen3模型。下文示例qwen3-1.7B的运行步骤，以下是详细说明：

硬件要求

类型	硬件	配置
预训练	NPU	8 x Ascend NPUs

环境搭建

• 驱动和固件安装
  下载驱动固件，请根据系统和硬件产品型号选择对应版本的driver和firmware。参考安装NPU驱动固件或执行以下命令安装：

bash Ascend-hdk-910b-npu-firmware_7.5.0.1.129.run --full
bash Ascend-hdk-910b-npu-driver_24.1.rc3_linux-aarch64.run --full --force 

• CANN安装
  下载CANN，请根据根据系统选择aarch64或x86_64对应版本的cann-toolkit、cann-kernel和cann-nnal。参考CANN安装或执行以下命令安装：

# 因为版本迭代，包名存在出入，根据实际修改
bash Ascend-cann-toolkit_8.0.RC3_linux-aarch64.run --install
bash Ascend-cann-kernels-910b_8.0.RC3_linux-aarch64.run --install
source /usr/local/Ascend/ascend-toolkit/set_env.sh # 安装nnal包需要source环境变量
bash Ascend-cann-nnal_8.0.RC4_linux-aarch64.run --install
# 设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

• PTA安装
  准备torch_npu和apex，参考Ascend Extension for PyTorch 配置与安装或执行以下命令安装：

# 安装torch和torch_npu
pip install torch-2.1.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl 
pip install torch_npu-2.1.0.post8-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

# apex for Ascend 构建参考 https://gitee.com/ascend/apex
pip install apex-0.1.dev20241015+ascend-cp38-cp38-linux_aarch64.whl

• MindSpeed-LLM及相关依赖安装

# 使能环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

# 安装MindSpeed加速库
git clone https://gitee.com/ascend/MindSpeed.git
cd MindSpeed
git checkout 2c085cc9  # checkout commit from MindSpeed core_r0.8.0 in 2025.04.01
pip install -r requirements.txt 
pip3 install -e .
cd ..

# 准备MindSpeed-LLM及Megatron-LM源码
git clone https://gitee.com/ascend/MindSpeed-LLM.git 
git clone https://github.com/NVIDIA/Megatron-LM.git  # megatron从github下载，请确保网络能访问
cd Megatron-LM
git checkout core_r0.8.0
cp -r megatron ../MindSpeed-LLM/
cd ../MindSpeed-LLM

pip install -r requirements.txt  # 安装其余依赖库

• 注意：由于首发最新版本支持，要求transformers版本为4.51.3,用户需执行以下命令：

  pip install transformers == 4.51.3

权重转换

• 权重下载
  从huggingface或者魔乐社区下载权重和配置文件
• 权重转换
  提供脚本将huggingface开源权重转换为mcore权重，用于训练、推理、评估等任务。
  使用方法如下，请根据实际需要的TP/PP等切分策略和权重路径修改权重转换脚本

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-1.7b/ckpt_convert_qwen3_1.7b_hf2mcore.sh

数据预处理

数据集处理使用方法如下，请根据实际需要修改以下参数
–input：数据集路径
–tokenizer-name-or-path：模型tokenizer目录
–output-prefix：数据集处理完的输出路径及前缀名

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-1.7b/data_convert_qwen3_1.7b_pretrain.sh

启动训练

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-1.7b/pretrain_qwen3_1.7b_ptd.sh

用户需要根据实际情况修改脚本中以下变量：
MASTER_ADDR： 多机情况下主节点IP
NODE_RANK： 多机下，各机对应节点序号
CKPT_SAVE_DIR： 训练中权重保存路径
DATA_PATH： 数据预处理后的数据路径
TOKENIZER_PATH： qwen3 tokenizer目录
CKPT_LOAD_DIR： 权重转换保存的权重路径，为初始加载的权重，如无初始权重则随机初始化

定性测试

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-1.7b/generate_qwen3_1.7b_ptd.sh

用户需要根据实际情况修改脚本中以下变量：
MASTER_ADDR： 多机情况下主节点IP
NODE_RANK： 多机下，各机对应节点序号
CHECKPOINT： 训练保存的权重路径
TOKENIZER_PATH： qwen3 tokenizer目录

定量评估

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-1.7b/evaluate_qwen3_1.7b_ptd.sh

用户需要根据实际情况修改脚本中以下变量：
MASTER_ADDR： 多机情况下主节点IP
NODE_RANK： 多机下，各机对应节点序号
TOKENIZER_PATH： qwen3 tokenizer目录
CKPT_LOAD_DIR： 权重转换保存的权重路径，为初始加载的权重，如无初始权重则随机初始化
DATA_PATH： 评估采用的数据集路径，当前推荐使用MMLU
TASK： 评估采用的数据集，当前推荐使用MMLU

推理部署

加载镜像

前往昇腾社区/开发资源下载适配本模型的镜像包mindie:2.0.T17.B010-800I-A2-py3.11-openeuler24.03-lts-aarch64.tar.gz

docker load -i mindie_2.0.T17.B010-800I-A2-py3.11-openeuler24.03-lts-aarch64.tar.gz(下载的镜像名称与标签)

完成加载镜像后，请使用docker images命令确认查找具体镜像名称与标签。

约束条件

• 当前支持TP=1/2/4/8推理
• /usr/local/Ascend/mindie/latest/mindie-service/conf/config.json
  的权限默认为640, 请不要更改该文件权限。

新建容器

目前提供的MindIE镜像预置了Qwen3-1.7B-Base模型推理脚本，无需再额外下载魔乐仓库承载的模型适配代码，直接新建容器即可。

执行以下启动命令（参考）： 如果您使用的是root用户镜像（例如从Ascend Hub上取得），并且可以使用特权容器，请使用以下命令启动容器：

docker run -it -d --net=host --shm-size=1g \
    --privileged \
    --name <container-name> \
    --device=/dev/davinci_manager \
    --device=/dev/hisi_hdc \
    --device=/dev/devmm_svm \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
    -v /usr/local/sbin:/usr/local/sbin:ro \
    -v /path-to-weights:/path-to-weights:ro \
    mindie:2.0.T17.B010-800I-A2-py3.11-openeuler24.03-lts-aarch64 bash

如果您希望使用自行构建的普通用户镜像，并且规避容器相关权限风险，可以使用以下命令指定用户与设备：

docker run -it -d --net=host --shm-size=1g \
    --user mindieuser:<HDK-user-group> \
    --name <container-name> \
    --device=/dev/davinci_manager \
    --device=/dev/hisi_hdc \
    --device=/dev/devmm_svm \
    --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/local/Ascend/driver:/usr/local/Ascend/driver:ro \
    -v /usr/local/sbin:/usr/local/sbin:ro \
    -v /path-to-weights:/path-to-weights:ro \
    mindie:2.0.T17.B010-800I-A2-py3.11-openeuler24.03-lts-aarch64 bash

注意，以上启动命令仅供参考，请根据需求自行修改再启动容器，尤其需要注意：

• –user，如果您的环境中HDK是通过普通用户安装（例如默认的HwHiAiUser，可以通过id HwHiAiUser命令查看该用户组ID），请设置好对应的用户组，例如用户组1001可以使用HDK，则–user mindieuser:1001，镜像中默认使用的是用户组1000。如果您的HDK是由root用户安装，且指定了–install-for-all参数，则无需指定–user参数。

• 设定容器名称–name与镜像名称，例如800I A2服务器使用mindie:2.0.T17.B010-800I-A2-py3.11-openeuler24.03-lts-aarch64。

• 设定想要使用的卡号–device。

• 设定权重挂载的路径，-v /path-to-weights:/path-to-weights:ro，注意，如果使用普通用户镜像，权重路径所属应为镜像内默认的1000用户，且权限可设置为750。可使用以下命令进行修改：
  bash chown -R 1000:1000 /path-to-weights chmod -R 750 /path-to-weights

• 在普通用户镜像中，注意所有文件均在 /home/mindieuser 下，请勿直接挂载 /home 目录，以免宿主机上存在相同目录，将容器内文件覆盖清除。

进入容器

docker exec -it ${容器名称} bash

纯模型推理

对话测试

进入atb-models路径, 并打开日志

ATB_SPEED_HOME_PATH默认/usr/local/Ascend/atb-models,以情况而定

cd $ATB_SPEED_HOME_PATH
export MINDIE_LOG_TO_STDOUT=1

执行对话测试

torchrun --nproc_per_node 2 \
         --master_port 20037 \
         -m examples.run_pa \
         --model_path {权重路径} \
         --trust_remote_code
         --max_output_length 256

性能测试

进入ModelTest路径

cd $ATB_SPEED_HOME_PATH/tests/modeltest/

运行测试脚本

bash run.sh pa_[data_type] performance [case_pair] [batch_size] ([prefill_batch_size]) [model_name] ([is_chat_model]) (lora [lora_data_path]) [weight_dir] ([trust_remote_code]) [chip_num] ([parallel_params]) ([max_position_embedding/max_sequence_length])

具体执行batch=1, 输入长度256, 输出长度256用例的2卡并行性能测试命令为：

bash run.sh pa_bf16 performance [[256,256]] 1 qwen ${weight_path} 2

注：ModelTest为大模型的性能和精度提供测试功能。使用文档请参考${ATB_SPEED_HOME_PATH}/tests/modeltest/README.md

服务化推理

• 打开配置文件

 vim /usr/local/Ascend/mindie/latest/mindie-service/conf/config.json

• 更改配置文件

{
...
"ServerConfig" :
{
...
"port" : 1040, #自定义
"managementPort" : 1041, #自定义
"metricsPort" : 1042, #自定义
...
"httpsEnabled" : false,
...
},

"BackendConfig": {
...
"npuDeviceIds" : [[0,1]],
...
"ModelDeployConfig":
{
"truncation" : false,
"ModelConfig" : [
{
...
"modelName" : "qwen3",
"modelWeightPath" : "/data/datasets/Qwen3-1.7B-Base",
"worldSize" : 2,
...
}
]
},
}
}

• 拉起服务化

cd /usr/local/Ascend/mindie/latest/mindie-service/bin
./mindieservice_daemon

• 新建窗口测试(OpenAI接口)

curl -X POST 127.0.0.1:1040/v1/chat/completions \
-d '{
"messages": [
{"role": "system", "content": "you are a helpful assistant."},
{"role": "user", "content": "How many r are in the word \"strawberry\""}
],
"max_tokens": 256,
"stream": false,
"do_sample": true,
"temperature": 0.6,
"top_p": 0.95,
"top_k": 20,
"model": "qwen3"
}'