Pynative 模式配置说明

本文档对 pynative.yaml 中的各项配置进行详细说明，并标注与 graph.yaml（Graph 模式）中对应配置项的关系。

注意：graph.yaml 中 model.model_config 的配置可以直接复用到 pynative.yaml 的 model 字段中，详见 model 配置章节。

---

1. checkpoint（检查点配置）

配置模型训练过程中的检查点保存与加载行为。

1.1 配置项说明

配置项	类型	说明
enable_save	bool	是否启用检查点保存功能。设为 False 时不会保存任何检查点。
save_path	str	检查点保存的目录路径。
save_max	int	最多保留的检查点数量，超出后自动删除最旧的检查点。
save_interleaved_steps	int	每隔多少训练步数保存一次检查点。
no_save_optim	bool	是否不保存优化器状态。设为 True 可减少检查点体积，但无法恢复优化器状态继续训练。
async_save	bool	是否异步保存检查点。异步保存不阻塞训练流程，可提升训练效率。
prefix	str	检查点文件名的前缀，用于区分不同实验的检查点。
remove_redundancy	bool	是否移除检查点中的冗余参数（如 ZeRO 分片后的冗余数据）。
load_path	str	加载检查点的路径，用于断点续训或微调。
load_balanced	bool	加载检查点时是否进行负载均衡分布。
no_load_optim	bool	是否不加载优化器状态。设为 True 时仅加载模型权重，适用于微调场景。
load_worker_number	int	加载检查点时使用的并行工作线程数。

---

2. training（训练配置）

配置训练过程的核心超参数。

2.1 配置项说明

配置项	类型	说明
steps	int	训练的总步数。
local_batch_size	int	每个 rank（设备）上的批次大小，即单卡一次前向计算的样本数。
global_batch_size	int	所有 rank 合计的全局批次大小。用于计算梯度累积步数：gradient_accumulation_steps = global_batch_size / (local_batch_size × data_parallel_size)。
seed	int	随机种子，用于保证训练可复现性。
deterministic	bool	是否启用确定性训练。启用后框架会使用确定性算法，确保相同输入产生完全相同的输出，但可能影响性能。

2.2 与 Graph 模式对应关系

Pynative（pynative.yaml）	Graph（graph.yaml）	说明
training.local_batch_size	runner_config.batch_size	功能一致，单卡的批次大小。
training.seed	seed	功能一致，全局随机种子。
training.steps	—	Graph 模式使用 runner_config.epochs 控制训练轮数，而非直接指定步数。
training.global_batch_size	—	Graph 模式无直接对应项，梯度累积通过 micro_batch_num 控制。
training.deterministic	—	Graph 模式无直接对应项。

---

3. optimizer（优化器配置）

配置模型参数优化器。

3.1 配置项说明

配置项	类型	说明
type	str	优化器类型，如 AdamW。
betas	list[float]	Adam 类优化器的动量参数，通常为 [β1, β2]。
eps	float	数值稳定性参数，防止除零错误。
weight_decay	float	权重衰减系数（L2 正则化）。

3.2 与 Graph 模式对应关系

Pynative（pynative.yaml）	Graph（graph.yaml）	说明
optimizer.type	optimizer.type	完全一致。
optimizer.betas	optimizer.betas	完全一致。
optimizer.eps	optimizer.eps	完全一致。
optimizer.weight_decay	optimizer.weight_decay	完全一致。
—	optimizer.swap	Pynative 模式无此配置。

---

4. lr_scheduler（学习率调度器配置）

配置学习率的变化策略。

4.1 配置项说明

配置项	类型	说明
type	str	学习率调度器类型，如 ConstantWarmUpLR（带预热的恒定学习率）。
learning_rate	float	基础学习率。
warmup_ratio	float	预热阶段占总训练步数的比例。例如 0.1 表示前 10% 的步数为预热阶段。

4.2 与 Graph 模式对应关系

Pynative（pynative.yaml）	Graph（graph.yaml）	说明
lr_scheduler.type	lr_schedule.type	功能一致，调度器类型。
lr_scheduler.learning_rate	lr_schedule.learning_rate	功能一致，基础学习率。
lr_scheduler.warmup_ratio	lr_schedule.warmup_steps	Pynative 使用比例控制预热，Graph 使用绝对步数控制预热。
—	lr_schedule.lr_end	Pynative 模式无此配置。
—	lr_schedule.warmup_lr_init	Pynative 模式无此配置。
—	lr_schedule.total_steps	Pynative 模式无此配置。

---

5. parallelism（并行配置）

配置模型的分布式并行策略。

5.1 配置项说明

配置项	类型	说明
data_parallel_shard	int	FSDP 参数分片数，控制优化器状态、梯度和参数被切分成多少份。设为 -1 表示自动推断。注意与 Graph 模式中 parallel_config.data_parallel（数据并行度/模型副本数）是不同的概念。
data_parallel_shard_strategy	str	FSDP 分片策略。可选值：optim_grads_params（分片优化器状态、梯度和参数，即 FSDP/ZeRO-3 模式）。
expert_parallel	int	专家并行度（MoE 模型专用），将不同专家分布到不同设备上。
tensor_parallel	int	张量并行度（TP），将单个 Transformer 层的参数切分到多个设备上。

5.2 与 Graph 模式对应关系

Pynative（pynative.yaml）	Graph（graph.yaml）	说明
parallelism.data_parallel_shard	parallel_config.data_parallel	功能相关，均控制数据并行度。Pynative 中 -1 表示自动推断。
parallelism.expert_parallel	parallel_config.expert_parallel	功能一致，专家并行度。
parallelism.tensor_parallel	parallel_config.model_parallel	功能一致，张量并行度。Graph 中称为 model_parallel。
parallelism.data_parallel_shard_strategy	—	Graph 模式无直接对应项。
—	parallel_config.pipeline_stage	Pynative 模式无此配置（不支持流水线并行）。
—	parallel_config.micro_batch_num	Pynative 模式无此配置。
—	parallel_config.use_seq_parallel	Pynative 模式无此配置。
—	parallel_config.gradient_aggregation_group	Pynative 模式无此配置。
—	parallel	Pynative 模式无此配置（并行上下文由框架自动管理）。

---

6. recompute（重计算配置）

配置激活重计算（Activation Checkpointing / Gradient Checkpointing），以时间换空间，减少显存占用。

6.1 配置项说明

配置项	类型	说明
mode	str	重计算模式。可选值：full（全部层重计算）、select（选择性重计算）。
full_recompute_layer	list	需要完整重计算的层索引范围，如 [0-3] 表示第 0 到第 3 层。
select_module	dict	选择性重计算的模块配置。key 为正则表达式匹配模块名，value 为层索引范围。仅在 mode: select 时生效。

mode: select 配置示例：

recompute:
  mode: select
  full_recompute_layer: [0-3]
  select_module:
    'self_attention': [0-1]    # 第0-1层的 self_attention 模块重计算
    '.*\\.matmul': [0-3]       # 第0-3层的 matmul 操作重计算
    'mlp': [2-3]               # 第2-3层的 mlp 模块重计算

6.2 与 Graph 模式对应关系

Pynative（pynative.yaml）	Graph（graph.yaml）	说明
recompute.mode: full	recompute_config.recompute: True + recompute_config.select_recompute: False	功能一致，全部层重计算。
recompute.mode: select	recompute_config.recompute: True + recompute_config.select_recompute: True	功能一致，选择性重计算。
recompute.full_recompute_layer	—	Graph 模式无直接对应项，Graph 中重计算范围由框架自动决定。
recompute.select_module	—	Graph 模式无直接对应项。

---

7. recompute_comm（重计算通信配置）

配置通信操作的重计算行为，用于进一步优化显存。

7.1 配置项说明

配置项	类型	说明
enable	bool	是否启用通信重计算。启用后，通信操作的结果不会被保存，反向传播时重新计算。
select_module	dict	需要重计算的通信模块配置。key 为模块名正则表达式，value 为层索引范围。

7.2 与 Graph 模式对应关系

Pynative（pynative.yaml）	Graph（graph.yaml）	说明
recompute_comm.enable	recompute_config.mp_comm_recompute	功能一致，控制是否重计算模型并行通信操作。
recompute_comm.select_module	—	Graph 模式无直接对应项。

---

8. train_dataset（训练数据集配置）

配置训练数据集的加载与处理方式。

8.1 配置项说明

dataloader

配置项	类型	说明
type	str	数据加载器类型，如 BlendedMegatronDatasetDataLoader。
datasets_type	str	数据集类型，如 GPTDataset。
sizes	list[int]	训练集、测试集、验证集的样本数量。
column_names	list[str]	数据集中各列的名称，如 ["input_ids", "labels", "loss_mask", "position_ids"]。
shuffle	bool	是否打乱数据集。
python_multiprocessing	bool	是否使用 Python 多进程方式加载数据。

dataloader.config（GPTDataset 配置）

配置项	类型	说明
split	str	训练/测试/验证集的划分比例，如 "1, 0, 0" 表示全部用于训练。
seq_length	int	数据序列长度。
eod_mask_loss	bool	是否在 EOD（End of Document）位置计算 loss。
reset_position_ids	bool	是否在 EOD 位置重置 position_ids。
create_attention_mask	bool	是否返回 attention_mask。
reset_attention_mask	bool	是否在 EOD 位置重置 attention_mask。
create_compressed_eod_mask	bool	是否返回压缩的 attention_mask。
eod_pad_length	int	压缩 attention_mask 的长度。
eod	int	数据集中 EOD 对应的 token id。
pad	int	数据集中 PAD 对应的 token id。
data_path	list	数据集路径和采样权重，格式为 [权重, 路径]。

顶层配置

配置项	类型	说明
drop_remainder	bool	是否丢弃最后一个不完整的 batch。
num_parallel_workers	int	数据加载的并行工作线程数。
prefetch_size	int	预取 batch 的数量，用于数据加载与训练的计算重叠。
numa_enable	bool	是否启用 NUMA 感知的数据加载。

8.2 与 Graph 模式对应关系

Pynative（pynative.yaml）	Graph（graph.yaml）	说明
train_dataset.dataloader.type	train_dataset.data_loader.type	功能一致。
train_dataset.dataloader.datasets_type	train_dataset.data_loader.datasets_type	功能一致。
train_dataset.dataloader.sizes	train_dataset.data_loader.sizes	功能一致。
train_dataset.dataloader.shuffle	train_dataset.data_loader.shuffle	功能一致。
train_dataset.dataloader.config.*	train_dataset.data_loader.config.*	完全一致，GPTDataset 配置项一一对应。
train_dataset.num_parallel_workers	train_dataset.num_parallel_workers	功能一致。
train_dataset.python_multiprocessing	train_dataset.python_multiprocessing	功能一致。
train_dataset.drop_remainder	train_dataset.drop_remainder	功能一致。
train_dataset.dataloader.column_names	—	Graph 模式无此配置。
train_dataset.prefetch_size	—	Graph 模式无此配置。
train_dataset.numa_enable	—	Graph 模式无此配置。
—	train_dataset.data_loader.config.seed	Pynative 模式无此配置。
—	train_dataset.data_loader.config.num_dataset_builder_threads	Pynative 模式无此配置。
—	train_dataset_task	Pynative 模式无此配置。

---

9. model（模型配置）

配置模型的结构与超参数。

9.1 重要说明

graph.yaml 中的 model.model_config 可以直接复用到 pynative.yaml 的 model 字段中。

在 Graph 模式下，模型配置嵌套在 model.model_config 下：

# graph.yaml
model:
  model_config:
    model_type: "deepseek_v3"
    hidden_size: 7168
    ...

在 Pynative 模式下，模型配置直接放在 model 下（无需 model_config 包裹）：

# pynative.yaml
model:
  model_type: "deepseek_v3"
  hidden_size: 1792
  ...

迁移时只需将 model.model_config 下的内容平铺到 model 下即可。

---

10. 完整配置样例

以下是一个完整的 pynative.yaml 配置样例，可直接用于 DeepSeek-V3 模型的 8 卡 Pynative 模式训练：

# ============================================================
# Pynative 模式完整配置样例（DeepSeek-V3 8卡训练）
# ============================================================

# 检查点配置
checkpoint:
  enable_save: True
  save_path: "./output/checkpoints"
  save_max: 3
  save_interleaved_steps: 100
  no_save_optim: False
  async_save: True
  prefix: "deepseekv3_pynative"
  remove_redundancy: False
  load_path: ""
  load_balanced: False
  no_load_optim: True
  load_worker_number: 1

# 训练配置
training:
  steps: 1000
  local_batch_size: 1
  global_batch_size: 2
  seed: 42
  deterministic: True

# 优化器配置
optimizer:
  type: AdamW
  betas:
    - 0.9
    - 0.95
  eps: 1.e-8
  weight_decay: 0.01

# 学习率调度器
lr_scheduler:
  type: ConstantWarmUpLR
  learning_rate: 1.e-5
  warmup_ratio: 0

# 并行配置（8卡：TP=2, EP=1, DP=4）
parallelism:
  data_parallel_shard: -1
  data_parallel_shard_strategy: "optim_grads_params"
  expert_parallel: 1
  tensor_parallel: 2

# 重计算配置
recompute:
  mode: full
  full_recompute_layer: [0-3]

# 通信重计算
recompute_comm:
  enable: False
  select_module:
    'mlp.router.all_gather': [0-3]

# 数据集配置
train_dataset:
  dataloader:
    type: BlendedMegatronDatasetDataLoader
    datasets_type: GPTDataset
    sizes:
      - 8000
      - 0
      - 0
    config:
      split: "1, 0, 0"
      seq_length: 4096
      eod_mask_loss: false
      reset_position_ids: false
      create_attention_mask: false
      reset_attention_mask: false
      create_compressed_eod_mask: false
      eod_pad_length: 128
      eod: 1
      pad: -1
      data_path:
        - "1"
        - "/home/data/datasets/deepseek-datasets/mmap_deepseekv3_datasets_text_document"
    column_names: ["input_ids", "labels", "loss_mask", "position_ids"]
    shuffle: false
    python_multiprocessing: False
  drop_remainder: True
  num_parallel_workers: 8
  prefetch_size: 1
  numa_enable: False

# 模型配置（可直接复用 graph.yaml 中 model.model_config 的内容）
model:
  model_type: deepseek_v3
  architectures: DeepseekV3ForCausalLM
  vocab_size: 129280
  seq_length: 4096
  hidden_size: 1792
  intermediate_size: 3072
  num_hidden_layers: 16
  max_position_embeddings: 163840
  hidden_act: "silu"
  num_attention_heads: 4
  rms_norm_eps: 1.e-6
  add_bias_linear: False
  use_flash_attention: True
  multi_latent_attention: True
  mla_qkv_concat: True
  kv_lora_rank: 512
  q_lora_rank: 1536
  qk_rope_head_dim: 64
  v_head_dim: 192
  qk_nope_head_dim: 128
  qk_layernorm: True
  attention_dropout: 0.0
  hidden_dropout: 0.0
  params_dtype: "float32"
  compute_dtype: "bfloat16"
  layernorm_compute_dtype: "float32"
  softmax_compute_dtype: "float32"
  rotary_dtype: "float32"
  initializer_range: 0.01
  num_nextn_predict_layers: 0
  mtp_loss_scaling_factor: 0.3
  position_embedding_type: "yarn"
  scaling_factor: 40
  beta_fast: 32
  beta_slow: 1
  mscale: 1
  mscale_all_dim: 1
  rope_theta: 10000
  # MoE 配置
  router_dense_type: "float32"
  gated_linear_unit: True
  moe_intermediate_size: 1024
  routed_scaling_factor: 2.5
  first_k_dense_replace: 1
  n_routed_experts: 8
  num_experts_per_tok: 4
  n_shared_experts: 1
  moe_shared_expert_intermediate_size: 1024
  moe_token_dispatcher_type: "alltoall"
  moe_grouped_gemm: True
  moe_router_load_balancing_type: "seq_aux_loss"
  moe_aux_loss_coeff: 0.01
  scoring_func: "sigmoid"
  norm_topk_prob: True
  moe_token_drop_policy: probs
  moe_router_enable_expert_bias: True
  moe_router_bias_update_rate: 0.001
  use_pad_tokens: True
  topk_group: 2
  n_group: 4

---

11. 启动训练

11.1 启动命令

使用项目提供的 msrun_launcher.sh 脚本启动多卡训练。该脚本内部调用 MindSpore 的 msrun 命令拉起分布式进程。

8 卡训练启动命令：

bash scripts/msrun_launcher.sh "run_mindformer.py --mode 1 --config guide/pynative.yaml" 8

11.2 参数说明

参数	说明
scripts/msrun_launcher.sh	分布式启动脚本，位于项目 scripts/ 目录下。
run_mindformer.py	MindFormers 训练入口脚本。
--mode 1	运行模式，1 表示 Pynative 模式（0 为 Graph 模式）。
--config guide/pynative.yaml	指定 Pynative 模式的配置文件路径。
8	使用的卡数（WORKER_NUM），此处为 8 卡。

11.3 其他常用启动方式

# 单卡训练（直接使用 python 启动，无需 msrun）
python run_mindformer.py --mode 1 --config guide/pynative.yaml

# 4 卡训练
bash scripts/msrun_launcher.sh "run_mindformer.py --mode 1 --config guide/pynative.yaml" 4

# 自定义 master_port 和日志目录
bash scripts/msrun_launcher.sh \
  "run_mindformer.py --mode 1 --config guide/pynative.yaml" \
  8 8118 "output/msrun_log" "False" 7200

# 多机多卡（示例：2 机每机 8 卡，共 16 卡，在 node0 上执行）
bash scripts/msrun_launcher.sh \
  "run_mindformer.py --mode 1 --config guide/pynative.yaml" \
  16 8 "192.168.1.1" 8118 0 "output/msrun_log" "False" 7200

11.4 并行度配置与卡数关系

Pynative 模式下，data_parallel_shard 与 Graph 模式中的 data_parallel 是不同的概念：

• data_parallel（Graph 模式）：数据并行度，即模型副本数，每个副本处理不同的 batch 数据。由 parallel_config.data_parallel 显式指定。
• data_parallel_shard（Pynative 模式）：FSDP 参数分片数，控制优化器状态、梯度和参数被切分成多少份。设为 -1 时由框架自动推断。

Pynative 模式中，实际的数据并行度（data_parallel）由框架根据总卡数和其余并行度隐式计算：

总卡数 = tensor_parallel × expert_parallel × data_parallel

其中 data_parallel 是隐式数据并行度，data_parallel_shard 则控制 FSDP 的分片粒度（通常与 data_parallel 取值相同或设为 -1 自动推断）。

以 8 卡为例，常见配置组合：

总卡数	tensor_parallel	expert_parallel	data_parallel（隐式）	data_parallel_shard	适用场景
8	2	1	4	-1	小模型或调试
8	4	1	2	-1	中等 TP 并行
8	8	1	1	-1	纯张量并行
8	1	2	4	-1	MoE 模型专家并行
8	2	2	2	-1	MoE 模型 TP+EP 混合

注意：data_parallel_shard 设为 -1 时，框架会自动将其设置为与隐式 data_parallel 相同的值。若需手动控制 FSDP 分片粒度（如将分片数设为小于 data_parallel 的值以减小通信开销），可显式指定该值。

---

附录：Pynative 独有配置项汇总

以下配置项仅在 pynative.yaml 中存在，graph.yaml 中无对应配置：

所属模块	配置项
checkpoint	no_save_optim、remove_redundancy、load_balanced、no_load_optim、load_worker_number
training	steps、global_batch_size、deterministic
parallelism	data_parallel_shard_strategy
recompute	full_recompute_layer、select_module
recompute_comm	select_module
train_dataset	dataloader.column_names、prefetch_size、numa_enable
model	max_position_embeddings、hidden_act、num_attention_heads、rms_norm_eps、MLA 细粒度参数、YaRN 位置编码参数、MoE 细粒度参数等

附录：Graph 独有配置项汇总（Pynative 中不存在）

以下配置项仅在 graph.yaml 中存在，在 Pynative 模式下无需关注：

• output_dir、load_ckpt_format、src_strategy_path_or_dir、auto_trans_ckpt、only_save_strategy、resume_training、use_parallel、run_mode、train_precision_sync
• trainer、runner_config（除 batch_size 外）、train_dataset_task
• context（Pynative 模式由框架自动管理）
• parallel_config（除 expert_parallel、model_parallel 外）、parallel
• callbacks、runner_wrapper
• profile 系列配置
• model.model_config.offset、pp_interleave_num、use_attn_mask_compression、apply_rope_fusion、bias_swiglu_fusion、use_fused_ops_topkrouter