1. 项目简介

本项目基于 MindSpore 与 MindSpore Transformers，以 Qwen3-0.6B 预训练模型为基础，构建了一套面向多层级文本分类任务的完整开发流程。项目覆盖从数据标注处理、模型微调训练，到模型推理的全链路实现，旨在为社区开发者提供一个清晰、可复用的优秀实践范例。

本项目适用于单句文本在多个独立层级上同时进行分类预测的场景。模型能够对同一输入句子在多个不同层级（如 L0~L4）上并行执行分类任务，每个层级均为独立的单标签分类，且支持自定义类别数量。例如：

层级	类别数
L0	13
L1	32
L2	76
L3	48
L4	5

输入一个句子后，模型将同时输出其在每个层级上的分类结果，实现高效的多任务联合预测。

通过本项目，开发者可快速理解如何基于 MindSpore 生态构建自定义分类任务，大幅降低模型开发与落地的技术门槛，适用于政务、客服、内容审核等多种文本理解场景。

本项目基于Atlas 800T A2单张NPU进行实现，提供了两种方式对数据进行训练：unpacking和packing的处理方式。对于unpacking的处理方式，处理后每条input_ids为一条数据，数据长度少于max_length，则对数据进行padding，而packing的处理方式，允许每条packing后的input_ids包含多条数据，采用<input_ids1><pad><eod><input_ids2><pad><eod>...将多条数据拼接起来，从而避免资源的浪费。

1.1 项目结构

本项目的目录结构如下：

Qwen3-0.6B-classification/
  ├── qwen_preprocess.py # 数据集处理脚本
  ├── qwen_preprocess_packing.py # packing数据集处理脚本
  ├── finetune_qwen3_classification.yaml # 训练参数配置文件
  ├── finetune_qwen3_classification_packing.yaml # packing数据集训练参数配置文件
  ├── mindformers1.7.0.tar # 镜像文件
  ├── modeling_qwen3_classification.py # 多分类模型脚本
  ├── predict_qwen3_classification.py # 推理脚本
  └── README.md

点击页面右上角“下载模型”，将项目下载到本地。

2. 快速开始

2.1 准备运行环境

本项目基于MindSpore Transformers 1.7.0版本进行实验。项目文件中提供了1.7.0版本的镜像，按照以下步骤创建容器（确保已经安装并启动了Docker）：

加载镜像

docker load -i mindformers1.7.0.tar

创建并启动容器

docker run -itd \
  --hostname $(hostname -I | awk '{print $1}' | tr '.' '-') \
  --ipc=host \
  --network=host \
  --device=/dev/davinci0:rwm \
  --device=/dev/davinci_manager:rwm \
  --device=/dev/devmm_svm:rwm \
  --device=/dev/hisi_hdc:rwm \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /var/log/npu/:/usr/slog \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /usr/bin/hccn_tool:/usr/bin/hccn_tool \
  -v /usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/common \
  -v /usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/driver/lib64/driver \
  -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -v /etc/hccn.conf:/etc/hccn.conf \
  -v /etc/localtime:/etc/localtime \
  --name 容器名称 \
  镜像名称 \
  /bin/bash

其中--device=/dev/davinci0:rwm \表示容器只挂载第0张NPU，根据需要修改挂载的NPU。

将其中容器名称和镜像名称替换成实际值。启动后mindformers源码目录在容器内的/home/work/mindformers。

本项目提供的镜像仅作为体验使用，切勿用于生产环境。手动安装MindSpore Transformers以及配套软件的安装可参考安装指南。准备好源码mindformers/目录。

2.2 准备预训练模型

从HuggingFace或ModelScope下载Qwen3-0.6B预训练模型，保存在./Qwen3-0.6B，目录结构为：

Qwen3-0.6B/
  ├── .gitattributes
  ├── LICENSE
  ├── README.md
  ├── config.json # 模型配置
  ├── generation_config.json
  ├── merges.txt # tokenizer所需文件
  ├── model.safetensors # 模型权重
  ├── tokenizer.json # tokenizer所需文件
  ├── tokenizer_config.json # tokenizer配置文件
  └── vocab.json # tokenizer所需文件

2.3 准备训练数据集

训练需要准备指定格式、并且已标注的本地xlsx数据集，文件格式如下所示：

A	B	C	D	E	F	G	H	I	J	K	L
会话ID	消息详情	一级标签	一级标签编码	二级标签	二级标签编码	三级标签	三级标签编码	四级标签	四级标签编码	五级标签	五级标签编码

对于其他格式的数据，请自行修改本项目中的数据处理脚本qwen_preprocess.py或者qwen_preprocess_packing.py。

使用数据处理脚本对数据集进行预处理，读取xlsx文件并提取输入和标签，将其中数据进行tokenize、pad、truncate等操作，最终保存为mindrecord格式文件：

# unpacking
python qwen_preprocess.py \
    --input_dir_or_file /path/to/dataset \
    --output_file /path/to/processed_data \
    --tokenizer_path /path/to/Qwen3-0.6B/ \
    --max_length 512

#packing 
python qwen_preprocess_packing.py \
    --input_dir_or_file /path/to/dataset \
    --output_dir /path/to/processed_data \
    --tokenizer_path /path/to/Qwen3-0.6B/ \
    --max_length 4096 \
    --max_seq_length 512

参数说明：

--input_dir_or_file: xlsx数据集文件或包含其的文件夹，若为文件夹则自动加载该文件夹内所有xlsx文件。
--output_file: 处理后数据文件的保存文件夹。
--tokenizer_path: 包含tokenizer文件的Qwen模型目录。
--max_length: 生成数据的序列长度，**需要和训练时yaml中配置的seq_length一致**。
--max_seq_length: 未packing之前每条数据tokenizer编码的最大长度。

2.4 准备微调配置

MindSpore Transformers使用YAML文件配置训练的所有参数，基于本项目提供的两个配置文件finetune_qwen3_classification.yaml或finetune_qwen3_classification_packing.yaml，用户可根据需求选择一个配置文件修改部分配置为真实路径，即可进行微调。其中，finetune_qwen3_classification.yaml为对unpacking数据集进行微调的配置，即对数据tokenizer后长度超过seq_len的部分进行截断，长度短于seq_len则padding至seq_len，而finetune_qwen3_classification_packing.yaml为对packing后的数据集进行微调的配置，即，允许每条packing后的input_ids包含多条数据，采用<input_ids1><pad><eod><input_ids2><pad><eod>...将多条数据拼接起来。

提供的配置基于特定序列长度进行了微调，提高了显存利用率以获得较优性能。如果需要增加序列长度，则需要调整重计算策略，或减小batch size，以避免OOM。重计算策略配置方法请参考重计算说明。进一步地，还可以通过修改其中的学习率、优化器、训练轮次、批次大小等配置自定义训练。配置文件中所有参数的说明可以参考配置文件说明。

以下展示对配置文件最基本的修改（省略了其他配置）：

...
pretrained_model_dir: /path/to/Qwen3-0.6B # 修改为Qwen3-0.6B模型目录的绝对路径
...
train_dataset: &train_dataset
  data_loader:
    ...
    dataset_dir: "/path/to/processed_data" # 修改为保存数据集mindrecord文件的文件夹绝对路径
...

2.5 启动训练

使用MindSpore Transformers统一的启动脚本 run_mindformer.py启动单卡训练，启动命令如下：

cd mindformers
# unpacking
python run_mindformer.py \
    --config /path/to/Qwen3-0.6B-Classification/finetune_qwen3_classification.yaml \
    --register_path /path/to/Qwen3-0.6B-Classification
    
# packing
python run_mindformer.py \
    --config /path/to/Qwen3-0.6B-Classification/finetune_qwen3_classification_packing.yaml \
    --register_path /path/to/Qwen3-0.6B-Classification

参数说明：

--config: 任务配置文件，设置为微调配置文件的绝对路径。
--register_path: 外挂模块的注册路径，设置为本项目的绝对路径，用于查找并注册分类模型的模块，以便训练流程可以自动构建分类模型。

微调后的模型权重将保存在当前目录下的./output/checkpoint目录中，可以修改配置文件中的output_dir自定义保存路径、修改save_checkpoint_steps修改保存间隔。

2.6 模型推理

执行predict_qwen3_classification.py进行推理，结果保存在result_file指定的json文件中：

python predict_qwen3_classification.py \
    --max_seq_len 512 \
    --config_file /path/to/finetune_qwen3_classification.yaml \
    --pretrained_model_dir /path/to/Qwen3-0.6B \
    --register_path /path/to/Qwen3-0.6B-Classification \
    --checkpoint_file /path/to/output/checkpoint/qwen3_XXXX.safetensors \
    --test_data_file /path/to/testdata.xlsx \
    --sheet_name Sheet1 \
    --result_file /path/to/classification_result.json \
    --device_id 0

参数说明：

--max_seq_len: 推理使用的序列长度，默认值512。
--config_file: 配置文件路径，与训练共用同一yaml文件。
--pretrained_model_dir: Qwen3-0.6B模型所在路径。
--register_path: 外挂模块的注册路径，设置为本项目的绝对路径，用于查找并注册分类模型的模块，以便构建分类模型。
--checkpoint_file: 加载的权重路径，设置为训练保存的safetensors文件。
--test_data_file: 测试集路径，格式与训练集相同。
--sheet_name: 指定excel中sheet标签，默认值"sheet1"。
--result_file: 输出的json文件路径。
--device_id: 使用的NPU设备号。

1. 项目简介

层级	类别数
L0	13
L1	32
L2	76
L3	48
L4	5

输入一个句子后，模型将同时输出其在每个层级上的分类结果，实现高效的多任务联合预测。

1.1 项目结构

本项目的目录结构如下：

Qwen3-0.6B-classification/
  ├── qwen_preprocess.py # 数据集处理脚本
  ├── qwen_preprocess_packing.py # packing数据集处理脚本
  ├── finetune_qwen3_classification.yaml # 训练参数配置文件
  ├── finetune_qwen3_classification_packing.yaml # packing数据集训练参数配置文件
  ├── mindformers1.7.0.tar # 镜像文件
  ├── modeling_qwen3_classification.py # 多分类模型脚本
  ├── predict_qwen3_classification.py # 推理脚本
  └── README.md

点击页面右上角“下载模型”，将项目下载到本地。

2. 快速开始

2.1 准备运行环境

本项目基于MindSpore Transformers 1.7.0版本进行实验。项目文件中提供了1.7.0版本的镜像，按照以下步骤创建容器（确保已经安装并启动了Docker）：

加载镜像

docker load -i mindformers1.7.0.tar

创建并启动容器

docker run -itd \
  --hostname $(hostname -I | awk '{print $1}' | tr '.' '-') \
  --ipc=host \
  --network=host \
  --device=/dev/davinci0:rwm \
  --device=/dev/davinci_manager:rwm \
  --device=/dev/devmm_svm:rwm \
  --device=/dev/hisi_hdc:rwm \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /var/log/npu/:/usr/slog \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /usr/bin/hccn_tool:/usr/bin/hccn_tool \
  -v /usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/common \
  -v /usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/driver/lib64/driver \
  -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -v /etc/hccn.conf:/etc/hccn.conf \
  -v /etc/localtime:/etc/localtime \
  --name 容器名称 \
  镜像名称 \
  /bin/bash

其中--device=/dev/davinci0:rwm \表示容器只挂载第0张NPU，根据需要修改挂载的NPU。

将其中容器名称和镜像名称替换成实际值。启动后mindformers源码目录在容器内的/home/work/mindformers。

本项目提供的镜像仅作为体验使用，切勿用于生产环境。手动安装MindSpore Transformers以及配套软件的安装可参考安装指南。准备好源码mindformers/目录。

2.2 准备预训练模型

从HuggingFace或ModelScope下载Qwen3-0.6B预训练模型，保存在./Qwen3-0.6B，目录结构为：

Qwen3-0.6B/
  ├── .gitattributes
  ├── LICENSE
  ├── README.md
  ├── config.json # 模型配置
  ├── generation_config.json
  ├── merges.txt # tokenizer所需文件
  ├── model.safetensors # 模型权重
  ├── tokenizer.json # tokenizer所需文件
  ├── tokenizer_config.json # tokenizer配置文件
  └── vocab.json # tokenizer所需文件

2.3 准备训练数据集

训练需要准备指定格式、并且已标注的本地xlsx数据集，文件格式如下所示：

A	B	C	D	E	F	G	H	I	J	K	L
会话ID	消息详情	一级标签	一级标签编码	二级标签	二级标签编码	三级标签	三级标签编码	四级标签	四级标签编码	五级标签	五级标签编码

对于其他格式的数据，请自行修改本项目中的数据处理脚本qwen_preprocess.py或者qwen_preprocess_packing.py。

使用数据处理脚本对数据集进行预处理，读取xlsx文件并提取输入和标签，将其中数据进行tokenize、pad、truncate等操作，最终保存为mindrecord格式文件：

# unpacking
python qwen_preprocess.py \
    --input_dir_or_file /path/to/dataset \
    --output_file /path/to/processed_data \
    --tokenizer_path /path/to/Qwen3-0.6B/ \
    --max_length 512

#packing 
python qwen_preprocess_packing.py \
    --input_dir_or_file /path/to/dataset \
    --output_dir /path/to/processed_data \
    --tokenizer_path /path/to/Qwen3-0.6B/ \
    --max_length 4096 \
    --max_seq_length 512

参数说明：

--input_dir_or_file: xlsx数据集文件或包含其的文件夹，若为文件夹则自动加载该文件夹内所有xlsx文件。
--output_file: 处理后数据文件的保存文件夹。
--tokenizer_path: 包含tokenizer文件的Qwen模型目录。
--max_length: 生成数据的序列长度，**需要和训练时yaml中配置的seq_length一致**。
--max_seq_length: 未packing之前每条数据tokenizer编码的最大长度。

2.4 准备微调配置

提供的配置基于特定序列长度进行了微调，提高了显存利用率以获得较优性能。如果需要增加序列长度，则需要调整重计算策略，或减小batch size，以避免OOM。重计算策略配置方法请参考重计算说明。进一步地，还可以通过修改其中的学习率、优化器、训练轮次、批次大小等配置自定义训练。配置文件中所有参数的说明可以参考配置文件说明。

以下展示对配置文件最基本的修改（省略了其他配置）：

...
pretrained_model_dir: /path/to/Qwen3-0.6B # 修改为Qwen3-0.6B模型目录的绝对路径
...
train_dataset: &train_dataset
  data_loader:
    ...
    dataset_dir: "/path/to/processed_data" # 修改为保存数据集mindrecord文件的文件夹绝对路径
...

2.5 启动训练

使用MindSpore Transformers统一的启动脚本 run_mindformer.py启动单卡训练，启动命令如下：

cd mindformers
# unpacking
python run_mindformer.py \
    --config /path/to/Qwen3-0.6B-Classification/finetune_qwen3_classification.yaml \
    --register_path /path/to/Qwen3-0.6B-Classification
    
# packing
python run_mindformer.py \
    --config /path/to/Qwen3-0.6B-Classification/finetune_qwen3_classification_packing.yaml \
    --register_path /path/to/Qwen3-0.6B-Classification

参数说明：

--config: 任务配置文件，设置为微调配置文件的绝对路径。
--register_path: 外挂模块的注册路径，设置为本项目的绝对路径，用于查找并注册分类模型的模块，以便训练流程可以自动构建分类模型。

2.6 模型推理

执行predict_qwen3_classification.py进行推理，结果保存在result_file指定的json文件中：

python predict_qwen3_classification.py \
    --max_seq_len 512 \
    --config_file /path/to/finetune_qwen3_classification.yaml \
    --pretrained_model_dir /path/to/Qwen3-0.6B \
    --register_path /path/to/Qwen3-0.6B-Classification \
    --checkpoint_file /path/to/output/checkpoint/qwen3_XXXX.safetensors \
    --test_data_file /path/to/testdata.xlsx \
    --sheet_name Sheet1 \
    --result_file /path/to/classification_result.json \
    --device_id 0

参数说明：

--max_seq_len: 推理使用的序列长度，默认值512。
--config_file: 配置文件路径，与训练共用同一yaml文件。
--pretrained_model_dir: Qwen3-0.6B模型所在路径。
--register_path: 外挂模块的注册路径，设置为本项目的绝对路径，用于查找并注册分类模型的模块，以便构建分类模型。
--checkpoint_file: 加载的权重路径，设置为训练保存的safetensors文件。
--test_data_file: 测试集路径，格式与训练集相同。
--sheet_name: 指定excel中sheet标签，默认值"sheet1"。
--result_file: 输出的json文件路径。
--device_id: 使用的NPU设备号。