启动任务
MindSpore Transformers 动态图（PyNative）训练提供了一键启动脚本 run_mindformer.py 和分布式任务拉起脚本 msrun_launcher.sh。
run_mindformer.py脚本用于在单卡上拉起任务，其提供了预训练任务的一键启动能力；msrun_launcher.sh脚本用于在单机多卡或多机多卡上拉起分布式任务，其通过msrun工具在每张卡上拉起任务。
一、run_mindformer 一键启动脚本
在 MindSpore Transformers 代码根目录下，使用 Python 执行 run_mindformer.py 脚本拉起任务，脚本支持的参数如下。当可选参数未设置或设置为 None 时，取 YAML 配置文件中的同名配置。
基础参数
参数 |
参数说明 |
取值说明 |
适用场景 |
|---|---|---|---|
|
任务yaml配置文件的路径。 |
str，必选 |
预训练 |
|
设置后端执行模式。 |
int，必选，需要设置 |
预训练 |
|
设置模型的运行模式，可选 |
str，可选 |
预训练 |
|
是否开启并行模式。 |
bool，可选 |
预训练 |
|
设置保存日志、权重、切分策略等文件的路径。 |
str，可选 |
预训练 |
|
设置全局种子，详情可参考mindspore.set_seed。 |
int，可选 |
预训练 |
二、分布式任务拉起脚本
分布式任务拉起脚本 msrun_launcher.sh 位于 scripts/ 目录下，可根据输入的参数自动使用msrun命令启动分布式多进程任务。该脚本有如下几种使用方式：
默认使用单机8卡运行：
bash scripts/msrun_launcher.sh [EXECUTE_ORDER]
在单机上仅指定卡数快速运行：
bash scripts/msrun_launcher.sh [EXECUTE_ORDER] [WORKER_NUM]
单机自定义运行：
bash scripts/msrun_launcher.sh [EXECUTE_ORDER] [WORKER_NUM] [MASTER_PORT] [LOG_DIR] [JOIN] [CLUSTER_TIME_OUT]
多机自定义运行：
bash scripts/msrun_launcher.sh [EXECUTE_ORDER] [WORKER_NUM] [LOCAL_WORKER] [MASTER_ADDR] [MASTER_PORT] [NODE_RANK] [LOG_DIR] [JOIN] [CLUSTER_TIME_OUT]
脚本的参数说明如下：
参数 |
参数说明 |
取值说明 |
|---|---|---|
|
要分布式执行的Python脚本命令参数。 |
str，必选，设置为包含要执行的Python脚本和脚本参数的字符串 |
|
参与分布式任务的Worker进程总数。 |
int，可选，默认值： |
|
当前节点上拉起的Worker进程数。 |
int，可选，默认值： |
|
指定Scheduler的IP地址或者主机名。 |
str，可选，默认值： |
|
指定Scheduler绑定端口号。 |
int，可选，默认值： |
|
当前节点的索引。 |
int，可选，默认值： |
|
Worker以及Scheduler日志输出路径。 |
str，可选，默认值： |
|
msrun是否等待Worker以及Scheduler退出。 |
bool，可选，默认值： |
|
集群组网超时时间，单位为秒。 |
int，可选，默认值： |
三、任务启动教程
下面以动态图场景为例，进行单卡、单机和多机任务使用方式说明。
单卡启动
可通过环境变量 ASCEND_RT_VISIBLE_DEVICES 选择具体某张卡执行任务：
export ASCEND_RT_VISIBLE_DEVICES=7 # 指定选择 7 号卡执行任务
如不通过环境变量指定卡，则默认选择 0 卡执行单卡任务。
在 MindSpore Transformers 代码根目录下执行 Python 脚本，进行单卡训练。单卡启动命令示例如下：
python run_mindformer.py --config /path/to/your.yaml --mode 1
ASCEND_RT_VISIBLE_DEVICES=0表示只让进程看到 0 号物理卡；若想使用 3 号卡则写=3。多卡时可写成=0,1,2,3这样的列表形式。
单机多卡启动
在 MindSpore Transformers 代码根目录下执行 msrun 启动脚本，进行单机训练任务。
并行切分维度（FSDP/HSDP、TP、CP、PP、EP 等）由配置文件中的 parallelism 段决定。下面以单机 8 卡场景为例，切分设置为 fsdp8，其对应的 YAML 文件字段如下示例：
training: # 训练超参数（命名风格沿用 torchtitan）
steps: 10 # 总训练步数
local_batch_size: 1 # 每张卡（per-rank）的批大小
global_batch_size: 8 # 全局每步样本数 = 各 DP 分片之和（用于计算梯度累积步数）
seed: 42
parallelism: # 并行切分
data_parallel_shard: -1 # -1 表示自动根据剩余卡数推导 FSDP 分片度
data_parallel_shard_strategy: "optim_grads_params"
tensor_parallel: 1 # TP
context_parallel: 1 # CP
pipeline_parallel: 1 # PP
expert_parallel: 1 # EP（专家并行，不计入 world_size 乘积，见下方说明）
train_dataset:
dataloader:
type: BlendedMegatronDatasetDataLoader
datasets_type: "GPTDataset"
sizes: [1000, 0, 0]
column_names: ["input_ids", "labels", "loss_mask", "position_ids"]
shuffle: false
config: # 完整字段说明见「数据集」文档
seq_length: 4096
split: "1, 0, 0"
eod: 1
pad: -1
create_attention_mask: False
create_compressed_eod_mask: False
data_path:
- '1'
- "/path/megatron_data_text_document"
drop_remainder: True
num_parallel_workers: 8
配置好 YAML 项后，使用 msrun_launcher.sh 脚本拉起任务：
bash scripts/msrun_launcher.sh "run_mindformer.py \
--config /path/to/your.yaml \
--mode 1" 8
配置切分如何对应 8 卡？ 框架首先计算数据并行度，再将其拆分为 dp_replicate * dp_shard：
data_parallel = world_size / (tensor_parallel * pipeline_parallel * context_parallel)=8 / (1*1*1)=8data_parallel_shard = -1时，自动设置dp_replicate = 1、dp_shard = data_parallel = 8，即 8 张卡全部用于 FSDP 分片梯度累积步数
= global_batch_size / (data_parallel_shard * local_batch_size)=8 / (8*1)=1
world_size 校验：哪些并行度相乘等于卡数
框架要求
dp_replicate * dp_shard * cp * tp * pp == world_size（即--worker_num），若不满足会直接报错。
expert_parallel（EP）不计入该乘积——EP 是在数据并行/张量并行维度内部对专家进行的再切分，不应将其乘入world_size。例如在 2 卡上设置expert_parallel: 2时，仍按dp_shard=2、tp=1、pp=1、cp=1（乘积=2=world_size）通过校验，EP 仅决定专家如何在这 2 张卡之间分布。
多机多卡启动
在多机场景下，每个节点需要各自执行一条 msrun_launcher.sh 命令。通过 NODE_RANK 区分不同节点（主节点为 0、从节点为 1、2），其余参数需满足以下要求：
WORKER_NUM、MASTER_ADDR、MASTER_PORT所有节点必须完全一致LOCAL_WORKER通常也保持一致，仅当各节点卡数不同时才需要逐节点设置不同值NODE_RANK逐节点递增，用于稳定地为各节点分配 rank id
以 2 机 16 卡（每机 8 卡）为例，假设主节点 IP 为 192.168.1.1：
主节点（节点 0）：
# 节点0作为主节点, 总共16卡且每个节点8卡
bash scripts/msrun_launcher.sh "run_mindformer.py \
--config /path/to/your.yaml \
--mode 1" \
16 8 192.168.1.1 8118 0 output/msrun_log False 7200
从节点（节点 1）：
# 节点1，主节点ip为192.168.1.1，节点0与节点1启动命令仅参数NODE_RANK不同
bash scripts/msrun_launcher.sh "run_mindformer.py \
--config /path/to/your.yaml \
--mode 1" \
16 8 192.168.1.1 8118 1 output/msrun_log False 7200
两条命令仅有 NODE_RANK 不同（分别为 0 和 1），其余参数完全一致。若各节点卡数不同，则需要额外调整对应节点的 LOCAL_WORKER，但 WORKER_NUM 仍需保持为全局总卡数。
不设 NODE_RANK 的风险
若不设置
NODE_RANK，MindSpore 会自动分配 rank id（同节点内 rank 连续），但节点间的编号依赖于各节点的拉起顺序，存在错配与不可复现的风险。因此在多机场景下务必显式设置NODE_RANK。
启动多机任务前请确保：各节点间网络互通、MASTER_PORT 未被占用、各节点使用相同的代码、配置与数据集路径；对于大集群，若组网较慢可调大 CLUSTER_TIME_OUT。
四、自定义脚本启动
PyNative 训练支持在自定义脚本里直接构建并启动训练器。例如可编写如下自定义脚本，指定 config 为对应 YAML 地址后，即可启动 PyNative 训练：
from mindformers.pynative.trainer import Trainer as PynativeTrainer
def main():
my_config = "/path/to/your.yaml"
trainer = PynativeTrainer(config=my_config)
trainer.train()
if __name__ == "__main__":
main()
自定义脚本和 run_mindformer 统一入口的区别：
run_mindformer.py --mode 1与「自定义脚本」最终都构建同一个PynativeTrainer并调用train()，运行行为一致。区别仅在于「谁来解析命令行、装配配置」：统一入口由
run_mindformer.py完成；自定义脚本由您自己指定config及其他入参完成，更灵活，便于在脚本里修改配置、进行测试。仓库中的测试用例（如
tests/st/test_multi_cards_cases/test_pynative/test_models/test_deepseek3/run_deepseek3.py）即为自定义脚本，因此按照仓库命令操作时看到的不是--mode 1，而是bash scripts/msrun_launcher.sh "run_deepseek3.py --config xxx.yaml"。
五、启动期排障
初次启动失败大多集中在：组网、端口、单卡与多卡差异等方面，可参考下表快速定位问题：
现象 |
排查方向 |
|---|---|
进程卡在初始化阶段、报「等不到足够 worker」 |
节点未全部拉起或网络不通；检查各节点 |
报端口被占用 / scheduler 启动失败 |
|
多机 rank 错配、训练 hang 在通信阶段 |
未设置 |
HCCL/组网超时、跨机集合通信报错 |
检查节点互通性与 HCCL 配置；适当调大 |
单卡能跑通、多卡运行失败 |
多为并行配置或集合通信问题：首先核对 |
查看日志： msrun 会为每个 worker 在 LOG_DIR 目录下生成独立日志文件（scheduler 与各 worker 分别记录），初次启动报错时应直接查看对应 worker 的日志而非前台聚合输出；当设置 JOIN=True 时，msrun 会解析日志并回收退出码。