Qwen3-MoE

模型描述

Qwen3 是 Qwen 系列最新一代的大型语言模型。基于广泛的训练，Qwen3 在推理、指令跟随、代理能力和多语言支持方面实现了突破性进展。Qwen3-MoE 是 Qwen3 的高效混合专家版本，采用稀疏激活架构，在保持强大性能的同时显著降低计算成本。Qwen3-MoE 通过动态路由机制，仅激活部分专家网络，实现更高的推理效率，适用于大规模部署和高并发场景，同时延续了 Qwen3 在多任务处理、多语言理解和复杂推理上的卓越表现。

@misc{qwen3technicalreport,
      title={Qwen3 Technical Report},
      author={Qwen Team},
      year={2025},
      eprint={2505.09388},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2505.09388},
}

支持规格

说明：

• 模型架构：Mcore 表示 1.6.0 发布的新模型架构，Legacy 表示原有模型架构。详见架构说明。
• 模型级别：训练和推理各分为5个级别，分别代表该模型遵循不同的标准上线。每个级别的介绍详见模型级别介绍。

版本配套

Qwen3 当前支持的版本配套如下。

使用样例

MindSpore Transformers 支持使用 Qwen3 进行推理。各任务的整体使用流程如下：

前期准备

环境安装

按照上述版本配套，参考环境安装指南安装运行环境。

模型下载

用户可以从Modelers、Hugging Face、ModelScope等开源社区下载所需的模型文件，包括模型权重、Tokenizer、配置等（重头预训练不需加载权重）。链接如下：

数据集下载

MindSpore Transformers 以下面的数据集为例提供了 Qwen3 的预训练流程的使用案例，实际训练时可参考数据集章节制作数据集。请在执行任务前提前下载所需数据集。链接如下：

预训练样例

预训练是指在大规模无标注数据上训练模型，使其能够全面捕捉语言的广泛特性。在MindSpore官网提供了详细的指导。

1. 数据预处理

MindSpore Transformers 预训练阶段当前已支持Megatron格式的数据集。用户可以参考数据集章节，使用 MindSpore 提供的工具将原始数据集转换为 Megatron 格式。

制作Megatron格式数据集，需要经过两个步骤。首先将原始文本数据集转换为jsonl格式数据，然后使用MindSpore Transformers提供的脚本将jsonl格式数据转换为Megatron格式的.bin和.idx文件。

• wiki.train.tokens 转为 jsonl格式数据

用户需要自行将wiki.train.tokens数据集处理成jsonl格式的文件。作为参考，文档末尾的FAQ部分提供了一个临时转换方案，用户需要根据实际需求自行开发和验证转换逻辑。

下面是jsonl格式文件的示例：

{"src": "www.nvidia.com", "text": "The quick brown fox", "type": "Eng", "id": "0", "title": "First Part"}
{"src": "The Internet", "text": "jumps over the lazy dog", "type": "Eng", "id": "42", "title": "Second Part"}
...

• jsonl格式数据 转为 bin格式数据

MindSpore Transformers提供了数据预处理脚本toolkit/data_preprocess/megatron/preprocess_indexed_dataset.py用于将jsonl格式的原始文本预料转换成.bin或.idx文件。

这里需要提前下载Qwen3-30B模型的tokenizer文件。

例如：

python toolkit/data_preprocess/megatron/preprocess_indexed_dataset.py \
  --input /path/to/data.jsonl \
  --output-prefix /path/to/wiki103-megatron \
  --tokenizer-type HuggingFaceTokenizer \
  --tokenizer-dir /path/to/Qwen3-30B-A3B # 其他规格的模型可以调整为对应的tokenizer路径

运行完成后会生成/path/to/wiki103-megatron_text_document.bin和/path/to/wiki103-megatron_text_document.idx文件。 填写数据集路径时需要使用/path/to/wiki103-megatron_text_document，不需要带后缀名。

2. 修改任务配置

MindSpore Transformers 提供了预训练任务的配置文件，用户可以根据实际情况修改配置文件。以下是一个示例配置文件片段，用户需要根据自己的数据集路径和其他参数进行相应修改。

• 数据集配置

# Dataset configuration
train_dataset: &train_dataset
  data_loader:
    ...
    sizes:
      - 8000  # 数据集的大小，可以根据实际数据集大小进行调整
      ...
    config:
      ...
      data_path:  # 采样比例和Megatron格式数据集路径
        - '1'
        - "/path/to/wiki103-megatron_text_document" # 替换为实际的Megatron格式数据集路径，此处不带后缀名

数据集路径需要替换为实际的Megatron格式数据集路径。

不同规格和序列长度的并行配置可参考并行配置建议。

3. 启动预训练任务

通过指定模型路径和配置文件configs/qwen3_moe/pretrain_qwen3_30b_a3b_4k.yaml以msrun的方式启动run_mindformer.py脚本，进行16卡分布式训练。您可参考如下方式，拉起两台Atlas 800T A2（64G）训练。

在每台服务器上执行如下命令。设置master_ip为主节点IP地址，即Rank 0服务器的IP；node_rank为每个节点的序号；port为当前进程的端口号（可在50000~65536中选择）。

master_ip=192.168.1.1
node_rank=0
port=50001
bash scripts/msrun_launcher.sh "run_mindformer.py \
--config configs/qwen3_moe/pretrain_qwen3_30b_a3b_4k.yaml \
--auto_trans_ckpt False \
--use_parallel True \
--run_mode train" \
16 8 $master_ip $port $node_rank output/msrun_log False 7200

此处样例代码假设主节点为192.168.1.1、当前Rank序号为0。实际执行时请将master_ip设置为实际的主节点IP地址；将node_rank设置为当前节点的Rank序号；将port设置为当前进程的端口号。

上述命令执行完毕后，训练任务将在后台执行，过程日志保存在./output/msrun_log下，使用以下命令可查看训练状态（由于开启了流水并行，真实loss只显示在最后一个pipeline stage的日志中，其余pipeline stage会显示loss为0）

tail -f ./output/msrun_log/worker_15.log

训练过程中的权重checkpoint将会保存在./output/checkpoint下。

如有关于Qwen3预训练的相关问题，可以在MindSpore Transformers的AtomGit仓库中提交ISSUE以获取支持。

推理样例

推理是指在预训练模型的基础上，利用已学习到的语言知识对新的输入数据进行预测或生成。在MindSpore官网提供了详细的指导。

1. 修改任务配置

MindSpore Transformers 提供了推理任务的配置文件，用户可以根据实际情况修改此配置文件中的权重路径和其他参数。

当前推理可以直接复用Hugging Face的配置文件和tokenizer，并且在线加载Hugging Face的safetensors格式的权重，使用时配置修改如下：

pretrained_model_dir: '/path/hf_dir'
parallel_config:
  data_parallel: 1
  model_parallel: 1

参数说明：

• pretrained_model_dir：Hugging Face模型目录路径，放置模型配置、Tokenizer等文件。/path/hf_dir中的内容如下：

📂Qwen3-0.6B
├── 📄config.json
├── 📄generation_config.json
├── 📄merges.txt
├── 📄model-xxx.safetensors
├── 📄model-xxx.safetensors
├── 📄model.safetensors.index.json
├── 📄tokenizer.json
├── 📄tokenizer_config.json
└── 📄vocab.json

• data_parallel：数据并行，当前推理并不支持此并行策略，默认为1；
• model_parallel：模型并行，默认值为 1。需根据实际模型规模及硬件资源情况，调整该参数为相应的device_nu（即实际使用的卡数）。

不同规格和序列长度的并行配置可参考并行配置建议。

2. 启动推理任务

使用 run_mindformer 统一脚本执行推理任务。

单卡推理可以直接执行run_mindformer.py脚本，多卡推理需要借助scripts/msrun_launcher.sh来启动。

run_mindformer.py的参数说明如下：

msrun_launcher.sh包括run_mindformer.py命令和推理卡数两个参数。

单卡推理：

当使用完整权重推理时，推荐使用默认配置，执行以下命令即可启动推理任务：

python run_mindformer.py \
--config configs/qwen3_moe/predict_qwen3_moe.yaml \
--run_mode predict \
--use_parallel False \
--pretrained_model_dir '/path/hf_dir' \
--parallel_config.data_parallel 1 \
--parallel_config.model_parallel 1 \
--predict_data '帮助我制定一份去上海的旅游攻略'

出现如下结果，证明推理成功。推理结果也会保存到当前目录下的 text_generation_result.txt 文件中。

'text_generation_text': [帮助我制定一份去上海的旅游攻略，包括景点、美食、住宿等信息...]

多卡推理：

多卡推理的配置要求与单卡存在差异，需参考下面修改配置：

1. 模型并行model_parallel的配置和使用的卡数需保持一致，下文用例为2卡推理，需将model_parallel设置成2；
2. 当前版本的多卡推理不支持数据并行，需将data_parallel设置为1。

当使用完整权重推理时，需要开启在线切分方式加载权重，参考以下命令：

bash scripts/msrun_launcher.sh "run_mindformer.py \
 --config configs/qwen3_moe/predict_qwen3_moe.yaml \
 --run_mode predict \
 --use_parallel True \
 --pretrained_model_dir '/path/hf_dir' \
 --parallel_config.data_parallel 1 \
 --parallel_config.model_parallel 2 \
 --predict_data '帮助我制定一份去上海的旅游攻略'" 2

出现如下结果，证明推理成功。推理结果也会保存到当前目录下的 text_generation_result.txt 文件中。详细日志可通过./output/msrun_log目录查看。

'text_generation_text': [帮助我制定一份去上海的旅游攻略，包括景点、美食、住宿等信息...]

多卡多batch推理：

多卡多batch推理的启动方式可参考上述多卡推理，但是需要增加predict_batch_size的入参，并修改predict_data的入参。

input_predict_data.txt文件的内容和格式是每一行都是一个输入，问题的个数与predict_batch_size一致，可以参考以下格式：

帮助我制定一份去上海的旅游攻略
帮助我制定一份去上海的旅游攻略
帮助我制定一份去上海的旅游攻略
帮助我制定一份去上海的旅游攻略

以完整权重推理为例，可以参考以下命令启动推理任务：

bash scripts/msrun_launcher.sh "run_mindformer.py \
 --config configs/qwen3_moe/predict_qwen3_moe.yaml \
 --run_mode predict \
 --predict_batch_size 4 \
 --use_parallel True \
 --pretrained_model_dir '/path/hf_dir' \
 --parallel_config.data_parallel 1 \
 --parallel_config.model_parallel 2 \
 --predict_data path/to/input_predict_data.txt" 2

推理结果查看方式，与多卡推理相同。

多机多卡推理：

在每台服务器上执行如下命令。设置master_ip为主节点IP地址，即Rank 0服务器的IP；node_rank为每个节点的序号；port为当前进程的端口号（可在50000~65536中选择）。

master_ip=192.168.1.1
node_rank=0
port=50001

bash scripts/msrun_launcher.sh "run_mindformer.py \
 --config configs/qwen3_moe/predict_qwen3_moe.yaml \
 --run_mode predict \
 --use_parallel True \
 --pretrained_model_dir '/path/hf_dir' \
 --parallel_config.data_parallel 1 \
 --parallel_config.model_parallel 2 \
 --predict_data 帮助我制定一份去上海的旅游攻略" $worker_num $local_worker $master_ip $port $node_rank output/msrun_log False 300

此处样例代码假设主节点为192.168.1.1、当前Rank序号为0。实际执行时请将master_ip设置为实际的主节点IP地址；将node_rank设置为当前节点的Rank序号；将$local_worker设置为当前节点上拉起的进程数(当前机器使用的卡数)；将$worker_num设置为参与任务的进程总数(使用的总卡数)；将$port设置为启动任务的端口号。

推理结果查看方式，与多卡推理相同。

附录

模型文件说明

Qwen3-MoE的模型文件包括以下内容：

📦mindformers
├── 📂mindformers
│   └── 📂models
│       └── 📂qwen3_moe
│           ├── 📄__init__.py                   # Qwen3模块初始化文件
│           ├── 📄configuration_qwen3_moe.py        # Qwen3模型配置类定义
│           ├── 📄modeling_qwen3_moe.py             # Qwen3模型主体实现
│           ├── 📄modeling_qwen3_moe_infer.py       # Qwen3推理模型实现
│           ├── 📄modeling_qwen3_moe_train.py       # Qwen3训练模型实现
│           └── 📄utils.py                      # Qwen3工具函数和基础类
├── 📂configs
│   └── 📂qwen3_moe
│       ├── 📄pretrain_qwen3_30b_a3b_4k.yaml       # Qwen3-30B-A3B 4k 预训练配置
│       ├── 📄predict_qwen3_moe.yaml               # Qwen3推理配置
│       └── 📄parallel_speed_up.json           # 数据集并行通信配置
└── 📄run_mindformer.py                        # 主要执行脚本

并行配置建议

以下配置为训练或推理场景下，不同模型规格的推荐配置。其中部分配置为经过验证的最佳配置，部分配置为可以运行的配置。用户可根据实际情况选择合适的配置。

注意：max_device_memory 在 Atlas 800T A2 和 Atlas 900 A3 SuperPoD 等机器上一般设置≤60GB，在 Atlas 800I A2 上一般设置≤30GB。

• 预训练：

parallel_config:
  data_parallel: &dp 1
  model_parallel: 4
  pipeline_stage: 4
  micro_batch_num: 4
  vocab_emb_dp: True
  use_seq_parallel: False
  gradient_aggregation_group: 1

recompute_config:
  recompute: True
  select_recompute: False
  parallel_optimizer_comm_recompute: True
  mp_comm_recompute: True

context:
  ...
  max_device_memory: "58GB"

• 推理：

parallel_config:
  data_parallel: &dp 1
  model_parallel: 16

context:
  ...
  max_device_memory: "59GB"

parallel_config:
  data_parallel: &dp 1
  model_parallel: 2

context:
  ...
  max_device_memory: "59GB"

FAQ

Q1：我有两台Atlas 800T A2服务器，如何进行Qwen3的预训练？拉起任务的指令是什么？

A1：根据指导修改配置后，参考如下命令拉起任务：

• 机器1 IP: 192.168.1.1 （作为主节点）

# 机器1的启动指令
master_ip=192.168.1.1
node_rank=0
port=50001

bash scripts/msrun_launcher.sh "run_mindformer.py \
--config configs/qwen3/pretrain_qwen3_32b_4k.yaml \
--auto_trans_ckpt False \
--use_parallel True \
--run_mode train" \
16 8 $master_ip $port $node_rank output/msrun_log False 7200

• 机器2 IP: 192.168.1.2

# 机器2的启动指令
master_ip=192.168.1.1
node_rank=1
port=50001

bash scripts/msrun_launcher.sh "run_mindformer.py \
--config configs/qwen3_moe/pretrain_qwen3_30b_a3b_4k.yaml \
--auto_trans_ckpt False \
--use_parallel True \
--run_mode train" \
16 8 $master_ip $port $node_rank output/msrun_log False 7200

Q2: 数据集准备部分中，应该如何将wiki.train.tokens 转为 jsonl格式数据？

A2: 社区issue中提供了一个临时转换脚本，仅作为参考使用。用户需要根据自己的数据特点和需求，自行开发和验证适合的转换逻辑。

Q3：如果修改了配置中的参数，使用run_mindformer.py拉起任务时，还需要重新传参吗？

A3：根据指导修改配置后，参数值已被修改，无需重复传参，run_mindformer.py会自动读取解析配置中的参数；如果没有修改配置中的参数，则需要在命令中添加参数。

Q4：用户使用同一个服务器拉起多个推理任务时，端口号冲突怎么办？

A4：用户使用同一个服务器拉起多个推理任务时，要注意不能使用相同的端口号，建议将端口号从50000~65536中选取，避免端口号冲突的情况发生。

Q5：我想看看我训练下来的权重效果怎么样，可以直接使用训练权重做推理吗？

A5：当然可以！你可以通过以下两种方式进行推理：

1. 直接使用训练权重进行推理，可以参考《训练后模型进行评测》文档，使用去优化器合并的训练权重进行推理。
2. 反转训练权重为 Hugging Face 格式，复用 Hugging Face 生态进行推理，可以参考 Qwen3-MoE 反转脚本进行权重反转后，再进行推理任务。