启动任务

概述

MindSpore Transformers提供了一键启动脚本run_mindformer.py和分布式任务拉起脚本msrun_launcher.sh。

• run_mindformer.py脚本用于在单卡上拉起任务，其提供了预训练、微调和推理任务的一键启动能力；

• msrun_launcher.sh脚本用于在单机多卡或多机多卡上拉起分布式任务，其通过msrun工具在每张卡上拉起任务。

run_mindformer一键启动脚本

在MindSpore Transformers代码根目录下，使用Python执行run_mindformer.py脚本拉起任务，脚本支持的参数如下。当可选参数未设置或设置为None时，取yaml配置文件中的同名配置。

基础参数

参数	参数说明	取值说明	适用场景
--config	任务yaml配置文件的路径。	str，必选	预训练/微调/推理
--mode	设置后端执行模式。	int，可选，0为GRAPH_MODE，1为PYNATIVE_MODE，当前仅支持GRAPH_MODE	预训练/微调/推理
--device_id	设置执行设备ID，其值必须在可用设备范围内。	int，可选	预训练/微调/推理
--device_target	设置后端执行设备，MindSpore Transformers仅支持在Ascend设备上运行。	str，可选	预训练/微调/推理
--run_mode	设置模型的运行模式，可选train、finetune或predict。	str，可选	预训练/微调/推理
--load_checkpoint	加载的权重文件或文件夹路径，详细使用方式参考权重转换功能。	str，可选	预训练/微调/推理
--use_parallel	是否开启并行模式。	bool，可选	预训练/微调/推理
--output_dir	设置保存日志、权重、切分策略等文件的路径。	str，可选	预训练/微调/推理
--register_path	外挂代码所在目录的绝对路径。比如research目录下的模型目录。	str，可选	预训练/微调/推理
--seed	设置全局种子，详情可参考mindspore.set_seed。	int，可选	预训练/微调/推理
--trust_remote_code	Hugging Face AutoTokenizer是否信任远程代码。	bool，可选	预训练/微调/推理

权重切分

参数	参数说明	取值说明	适用场景
--src_strategy_path_or_dir	权重的策略文件路径。	str，可选	预训练/微调/推理
--auto_trans_ckpt	是否开启在线权重自动转换功能，详情可参考权重转换功能。	bool，可选	预训练/微调/推理
--transform_process_num	负责权重转换的进程数。	int，可选	预训练/微调/推理
--only_save_strategy	是否仅保存切分策略文件。	bool，可选，为true时任务在保存策略文件后直接退出	预训练/微调/推理

训练

参数	参数说明	取值说明	适用场景
--train_dataset_dir	预训练/微调的数据集目录。	str，可选	预训练/微调
--resume_training	是否开启断点续训功能，详情可参考断点续训功能。	bool，可选	预训练/微调
--epochs	训练轮次。	int，可选	预训练/微调
--batch_size	批处理数据的样本数。	int，可选	预训练/微调
--gradient_accumulation_steps	梯度累积步数。	int，可选	预训练/微调
--num_samples	使用的数据集样本数量。	int，可选	预训练/微调

推理

参数	参数说明	取值说明	适用场景
--predict_data	推理的输入数据。	str，可选，可以是推理的输入（单batch推理）或包含多行文本的txt文件路径（多batch推理）。	推理
--predict_batch_size	多batch推理的batch_size大小。	int，可选	推理
--do_sample	推理选择token时是否使用随机采样。	bool，可选，True 表示使用随机采样，False 代表使用贪心搜索。	推理

分布式任务拉起脚本

分布式任务拉起脚本msrun_launcher.sh位于scripts/目录下，可根据输入的参数自动使用msrun命令启动分布式多进程任务。该脚本有如下几种使用方式：

1. 默认使用单机8卡运行：

bash msrun_launcher.sh [EXECUTE_ORDER]

2. 在单机上仅指定卡数快速运行：

bash msrun_launcher.sh [EXECUTE_ORDER] [WORKER_NUM]

3. 单机自定义运行：

bash msrun_launcher.sh [EXECUTE_ORDER] [WORKER_NUM] [MASTER_PORT] [LOG_DIR] [JOIN] [CLUSTER_TIME_OUT]

4. 多机自定义运行：

bash msrun_launcher.sh [EXECUTE_ORDER] [WORKER_NUM] [LOCAL_WORKER] [MASTER_ADDR] [MASTER_PORT] [NODE_RANK] [LOG_DIR] [JOIN] [CLUSTER_TIME_OUT]

脚本的参数说明如下：

参数	参数说明	取值说明
EXECUTE_ORDER	要分布式执行的Python脚本命令参数。	str，必选，设置为包含要执行的Python脚本和脚本参数的字符串
WORKER_NUM	参与分布式任务的Worker进程总数。	int，可选，默认值：8
LOCAL_WORKER	当前节点上拉起的Worker进程数。	int，可选，默认值：8
MASTER_ADDR	指定Scheduler的IP地址或者主机名。	str，可选，默认值："127.0.0.1"
MASTER_PORT	指定Scheduler绑定端口号。	int，可选，默认值：8118
NODE_RANK	当前节点的索引。	int，可选，默认值：0
LOG_DIR	Worker以及Scheduler日志输出路径。	str，可选，默认值："output/msrun_log"
JOIN	msrun是否等待Worker以及Scheduler退出。	bool，可选，默认值：False
CLUSTER_TIME_OUT	集群组网超时时间，单位为秒。	int，可选，默认值：7200

任务启动教程

下面以Qwen3-8B微调为例，进行单卡、单机和多机任务使用方式说明。

单卡

在MindSpore Transformers代码根目录下执行Python脚本，进行单卡微调。命令中的路径需替换为真实路径。

1. 根据使用节点数等信息，修改相应的配置文件configs/qwen3/finetune_qwen3.yaml：

   pretrained_model_dir: '/path/to/Qwen3-8B'
   ...
   train_dataset: &train_dataset
     ...
     data_loader:
       type: HFDataLoader
       path: "llm-wizard/alpaca-gpt4-data-zh" # alpaca风格数据集，确保网络环境能够访问huggingface，以实现自动下载数据集功能。
       # path: "json"  # 如果使用本地json文件离线加载数据集，可以取消注释下面两行，并注释掉上面一行
       # data_files: '/path/to/alpaca_gpt4_data_zh.json'
       ...
       handler:
         - type: take # 调用datasets库的take方法，取前n条数据用于示例
           n: 2000    # 取前2000条数据用于示例，实际使用时可以去掉这一行和上面一行
   model:
     model_config:
       num_hidden_layers: 4
       ...
   parallel_config:
     data_parallel: 1
     model_parallel: 1
     pipeline_stage: 1
     use_seq_parallel: False
     micro_batch_num: 1
   

2. 执行run_mindformer.py启动单卡的微调任务，下面提供了一个使用示例：

   python run_mindformer.py \
    --config configs/qwen3/finetune_qwen3.yaml \
    --use_parallel False \
    --run_mode finetune
   

单机

在MindSpore Transformers代码根目录下执行msrun启动脚本，进行单机微调。命令中的路径需替换为真实路径。

1. 根据使用节点数等信息，修改相应的配置文件configs/qwen3/finetune_qwen3.yaml：

   pretrained_model_dir: '/path/to/Qwen3-8B'
   ...
   train_dataset: &train_dataset
     data_loader:
       type: HFDataLoader
       path: "llm-wizard/alpaca-gpt4-data-zh" # alpaca风格数据集，确保网络环境能够访问huggingface，以实现自动下载数据集功能。
       # path: "json"  # 如果使用本地json文件离线加载数据集，可以取消注释下面两行，并注释掉上面一行
       # data_files: '/path/to/alpaca_gpt4_data_zh.json'
       ...
       handler:
         - type: take # 调用datasets库的take方法，取前n条数据用于示例
           n: 2000    # 取前2000条数据用于示例，实际使用时可以去掉这一行和上面一行
   parallel_config:
     data_parallel: 1
     model_parallel: 4
     pipeline_stage: 2
     micro_batch_num: 2
   

2. 执行以下msrun启动脚本，进行8卡分布式训练：

   total_rank_num=8
   bash scripts/msrun_launcher.sh "run_mindformer.py \
   --config configs/qwen3/finetune_qwen3.yaml \
   --auto_trans_ckpt True \
   --use_parallel True \
   --run_mode finetune" \
   $total_rank_num
   

多机

以Qwen3-8B为例，进行2机16卡微调。

1. 根据使用节点数等信息，修改相应的配置文件configs/qwen3/finetune_qwen3.yaml：

   pretrained_model_dir: '/path/to/Qwen3-8B'
   ...
   train_dataset: &train_dataset
     data_loader:
       type: HFDataLoader
       path: "llm-wizard/alpaca-gpt4-data-zh" # alpaca风格数据集，确保网络环境能够访问huggingface，以实现自动下载数据集功能。
       # path: "json"  # 如果使用本地json文件离线加载数据集，可以取消注释下面两行，并注释掉上面一行
       # data_files: '/path/to/alpaca_gpt4_data_zh.json'
       ...
       handler:
         - type: take # 调用datasets库的take方法，取前n条数据用于示例
           n: 2000    # 取前2000条数据用于示例，实际使用时可以去掉这一行和上面一行
   

   如使用节点数和卡数改变需要修改data_parallel、 model_parallel、 pipeline_stage满足实际运行的卡数 device_num=data_parallel×model_parallel×pipeline_stage，同时满足micro_batch_num >= pipeline_stage。

2. 执行msrun启动脚本：

   多机多卡执行脚本进行分布式任务需要分别在不同节点运行脚本，并将参数MASTER_ADDR设置为主节点的ip地址，所有节点设置的ip地址相同，不同节点之间仅参数NODE_RANK不同。

   # 节点0作为主节点, {master_addr}处填写节点0实际ip, 总共16卡且每个节点8卡
   bash scripts/msrun_launcher.sh "run_mindformer.py \
     --config configs/qwen3/finetune_qwen3.yaml \
     --run_mode finetune" \
     16 8 {master_addr} 8118 0 output/msrun_log False 300
   
   
   # 节点1，{master_addr}处填写节点0实际ip，节点0与节点1启动命令仅参数NODE_RANK不同
   bash scripts/msrun_launcher.sh "run_mindformer.py \
     --config configs/qwen3/finetune_qwen3.yaml \
     --run_mode finetune" \
     16 8 {master_addr} 8118 1 output/msrun_log False 300