一、前言

在基于 MindSpore-Transformers 开展大模型预训练、微调、推理等任务时，训练轮次、batch size、学习率、并行策略、模型路径、数据集配置等参数繁多。如果全部硬编码写在 Python 脚本中，会带来版本管理混乱、参数修改麻烦、多任务实验对比困难等问题。

YAML 作为可读性强、结构简洁的配置文件格式，非常适合管理模型任务参数。MindSpore-Transformers 原生支持加载 YAML 配置，将任务参数与业务代码解耦。开发者只需维护 yaml 文件，无需修改 Python 代码，即可快速切换不同实验任务。本文介绍 YAML 配置的设计思路、参数分类、加载方式、实操示例、参数校验与踩坑实践，帮助大家在昇腾平台上快速落地基于 yaml 的参数化任务开发。

二、MindSpore-Transformers YAML 配置核心原理

2.1 配置解耦思想

将任务参数划分为模型参数、训练参数、数据集参数、昇腾硬件 & 并行参数、日志与保存参数，全部写入 yaml 文件。Python 主程序仅负责：读取 yaml → 解析参数 → 构建模型 / 数据集 / 优化器 → 启动任务。

● 优点：多组实验直接复制 yaml 文件，修改配置即可；实验参数可归档，便于复现；参数集中管理，减少代码改动引入 bug。

● MindSpore-Transformers 提供mindspore_transformers.utils.config工具，支持 yaml 加载、参数合并、参数校验，支持命令行参数覆盖 yaml 配置。

2.2 配置加载流程

1. 定义task_config.yaml，填写所有任务参数；

2. 代码中调用工具函数读取 yaml 文件，解析为 Python 字典 / Config 对象；

3. 命令行参数可覆盖 yaml 内参数（例如启动时指定--epochs=10覆盖 yaml 里 epochs）；

4. 把解析后的参数传入模型、数据处理、训练器 Trainer；

5. 任务启动，自动读取并行策略、NPU 设备参数、checkpoint 保存路径等。

重要特性：支持分层继承。可以写基础公共 yaml（base.yaml），多个任务 yaml 继承公共配置，只重写差异参数，减少重复配置。

三、YAML 配置文件结构与参数说明

3.1 完整 task_config.yaml 示例

# task_config.yaml 任务总配置
# 基础任务信息
task_type: "sft"
model_name_or_path: "./llama2-7b-ms"
tokenizer_name: "./llama2-7b-ms"

# 模型参数
model:
  model_type: "llama2"
  hidden_size: 4096
  num_hidden_layers: 32
  num_attention_heads: 32
  seq_len: 2048
  load_checkpoint: True
  checkpoint_path: "./ckpt/llama2_pretrain.ckpt"

# 数据集参数
dataset:
  data_path: "./data/sft_data.jsonl"
  batch_size: 4
  shuffle: True
  num_workers: 8
  max_seq_length: 2048

# 训练超参
training:
  epochs: 3
  lr: 2.0e-5
  weight_decay: 0.01
  warmup_ratio: 0.03
  loss_scale: 1024
  gradient_accumulation_steps: 2

# 昇腾并行配置（适配NPU多卡训练）
parallel:
  dp: 4
  tp: 2
  pp: 1
  use_sequence_parallel: True
  recompute: True

# 日志 & 保存
output:
  output_dir: "./output/sft_run1"
  save_steps: 200
  log_steps: 10
  save_total_limit: 3
  do_eval: True
  eval_steps: 500

3.2 参数分类说明

1. 基础任务参数：任务类型（pretrain/sft/inference）、模型权重路径、分词器路径；

2. 模型参数：网络结构、序列长度、预训练权重加载开关与路径；

3. 数据集参数：数据文件路径、batch、序列截断长度、数据加载进程数；

4. 训练超参数：epoch、学习率、权重衰减、warmup、梯度累积、loss scale；

5. 昇腾并行参数：数据并行 dp、张量并行 tp、流水线并行 pp、重计算开关，适配多 NPU 分布式训练；

6. 输出保存参数：输出目录、日志打印步、checkpoint 保存间隔、评估开关。

四、代码实操：YAML 配置加载与使用

4.1 环境依赖准备

# 安装依赖
pip install mindspore-transformers pyyaml

4.2 Python 加载 yaml 配置代码

import yaml
from mindspore_transformers import Trainer
from mindspore_transformers.utils import Config

def load_yaml_config(yaml_path):
    with open(yaml_path, 'r', encoding="utf-8") as f:
        raw_dict = yaml.safe_load(f)
    # 转为Config对象，支持属性访问 config.training.lr
    config = Config(raw_dict)
    return config

if __name__ == "__main__":
    # 加载yaml配置
    config = load_yaml_config("task_config.yaml")
    print(f"任务类型：{config.task_type}")
    print(f"学习率：{config.training.lr}")

    # 初始化Trainer，直接传入配置
    trainer = Trainer(
        model_name_or_path=config.model_name_or_path,
        model_config=config.model,
        dataset_config=config.dataset,
        training_args=config.training,
        parallel_config=config.parallel,
        output_config=config.output
    )
    # 启动训练
    trainer.train()

4.3 命令行覆盖 yaml 参数（常用）

MindSpore-Transformers 支持启动时通过命令行参数覆盖 yaml 内配置，适合快速调参，不用修改 yaml 文件。

python run_sft.py --config task_config.yaml --training.lr=1e-5 --dataset.batch_size=2

执行后，代码会优先使用命令行传入的 lr 和 batch_size，覆盖 yaml 文件中原有的参数。

4.4 多配置继承（公共 base.yaml）

当多个实验共享大量参数时，可以抽取公共配置 base.yaml，子任务 yaml 继承 base。
base.yaml 存放公共参数（模型结构、并行策略），sft_run2.yaml 只写改动的参数。

# sft_run2.yaml
_base_: "./base.yaml"
training:
  lr: 1e-5
  epochs: 5
dataset:
  batch_size: 2

加载时工具会自动合并 base 配置与当前 yaml 的参数，子配置参数优先级更高。

五、YAML 编写规范与校验

5.1 YAML 语法注意事项

1. 缩进必须使用空格，禁止 tab，缩进错误会直接解析失败；

2. 数值不加引号，字符串可加引号；布尔值true/false小写；

3. 注释使用#，仅支持行注释；

4. 路径如果包含特殊字符，建议加双引号。

5.2 参数校验

可以在代码中增加简单校验，防止 yaml 参数非法：

# 简单参数校验示例
assert config.training.lr > 0, "学习率必须大于0"
assert config.dataset.batch_size > 0, "batch_size不能为0"
assert config.parallel.dp * config.parallel.tp * config.parallel.pp == 8, "并行卡数必须等于实际NPU卡数"

MindSpore-Transformers 内置的 Config 类，也支持参数类型校验，捕获参数类型错误。

六、常见踩坑与问题排查

6.1 yaml 缩进错误，加载报yaml.parser.ParserError

原因：使用 Tab 缩进，或者缩进层级混乱。
解决：统一使用 2 空格缩进，检查每一行层级。

6.2 参数读取为 None，找不到 key

原因：yaml 字段名写错，大小写不匹配；或者层级写错。
排查：打印 config 字典，查看完整 key 列表。yaml 区分大小写。

6.3 命令行参数无法覆盖 yaml

原因：参数名层级书写错误，如training.lr写成lr。
解决：命令行参数必须和 yaml 的层级结构保持一致。

6.4 并行配置与实际 NPU 卡数不匹配，任务启动失败

原因：yaml 中 dptppp 不等于DEVICE_NUM。
解决：核对昇腾分布式环境的卡数量，修改 yaml 并行参数。

6.5 多 yaml 继承，参数合并不符合预期

子 yaml 参数优先级高于 base.yaml；列表类型参数默认不会合并，会直接覆盖。如果需要合并列表，需要自定义合并逻辑。

七、最佳实践

1. 实验版本管理：每一组实验单独保存 yaml 文件，文件名带上实验标识，提交到 git，方便复现；

2. 参数分层：公共参数抽离 base.yaml，任务独有参数放在子 yaml，减少重复；

3. 禁止业务硬编码：所有可调整超参、路径、并行策略全部放入 yaml，代码只写固定逻辑；

4. 环境隔离：推理、SFT、预训练使用独立 yaml，避免互相干扰；

5. 启动前校验：代码增加参数合法性校验，提前捕获非法参数，避免 NPU 长时间启动后才报错。

八、总结

MindSpore-Transformers 通过 YAML 文件管理任务参数，实现配置与代码解耦。开发者将模型、数据集、训练、昇腾并行等参数写入 yaml，借助内置 Config 工具完成加载、参数合并、命令行覆盖。
这套方案极大简化多组对比实验，提升大模型训练 / 推理任务的可维护性与可复现性。在昇腾 NPU 集群开展多轮调优实验时，yaml 配置是工程化落地的推荐方案。