What type of PR is this?
/kind feature

---

What does this PR do / why do we need it:

任务：【开源实习】HyperParallel Trainer新增GLM5系列模型 #2099
地址：https://gitcode.com/mindspore/community/issues/2099

一、这个 PR 提供什么能力

本 PR 在 HyperParallel Trainer 中新增 GLM5 系列模型训练接入，完成 model_type=glm5 的模型构建、forward、loss、backward、checkpoint保存恢复、并行训练接入、配置示例和验证材料，验证包括：仓库内 trainer 功能测试、scaled dense/MoE+MLA+DSA 单卡 vs DP2、MoE 1c vs EP2、DSA 1c vs CP2、DSA 专用 CP wrapper 20-step、Transformers/LLaMAFactory 单卡 loss/logits 对齐、checkpoint/resume。

1.1 模型与训练能力

• 新增 GLM5Config / GLM5ForCausalLM，支持 Trainer 构建 GLM5 CausalLM 训练模型
• 新增 GLM5 dense、MoE、MLA attention、official DSA sparse attention/indexer 路径
• 支持 GLM5 shifted CausalLM loss、ignore_index=-100、position ids、2D/4D attention mask、append-only cached decode
• 支持 GLM-family safetensors 到 HyperParallel state_dict 的加载适配
• 支持 checkpoint 保存恢复，覆盖模型、优化器、scheduler、RNG state、dataloader state
• 支持 GLM5 CP batch prepare：在 token counting 和 forward 前按实际 CP rank 切分 input_ids / labels / attention_mask / position_ids，保证 CP 下本地序列 shard 与 loss token 分母一致

1.2 并行能力矩阵

能力	当前状态	验证证据
Dense CausalLM	支持	scaled dense 单卡训练、跨框架 loss/logits 对齐
FSDP / DP	支持	scaled dense 1c vs DP2，100-step avg diff 6.55615e-05
MoE	支持	MoE 单卡训练、MoE 1c vs EP2
EP	支持	MoE 1c vs EP2，100-step avg diff 4.83024e-05
MLA attention	支持	scaled MoE+MLA+DSA 跨框架与 DP2 对齐
DSA sparse attention	支持	DSA 1c vs CP2、DSA 专用 CP wrapper、跨框架 loss/logits 对齐
CP	支持	DSA 1c vs CP2，100-step avg diff 3.80690e-05
Activation checkpoint	接入	训练配置覆盖
Checkpoint resume	支持	dense / MoE EP2 / DSA CP2 resume 验证
TP	暂不支持	NotImplementedError，避免静默错算

二、用户如何拉起 GLM5 训练

Step 0：环境前提

本 PR 的训练与验证在 Ascend 910B + torch_npu 环境中完成，实际验证环境见第三节。

git clone https://gitcode.com/mindspore/hyper-parallel
cd hyper-parallel
pip install -e .

Step 1：准备 tokenizer 和训练数据

GLM5 默认 vocab size 对齐 GLM-5 tokenizer：

model.tokenizer_path=/path/to/GLM-5-tokenizer

训练数据支持普通 json_file / hf_datasets 路径，整理为 jsonl 后通过--data.train_path=/path/to/train.jsonl 传入即可

Step 2：配置 train.yaml

该 YAML 是 GLM5 训练入口模板，最小可改字段如下：

model:
name: glm5
tokenizer_path: /path/to/GLM-5-tokenizer

data:
type: json_file
train_path: /path/to/train.jsonl
max_seq_len: 256

train:
accelerator:
  dp_shard: 1
  tp: 1
  cp: 1
  ep: 1

Step 3：启动训练

examples/glm5/train.yaml 默认使用 preset_pt，方便复现对齐实验。普通 jsonl 训练需要显式覆盖 data.type：

torchrun --nproc_per_node=<num_devices> scripts/train_lm.py \
examples/glm5/train.yaml \
--model.tokenizer_path=/path/to/GLM-5-tokenizer \
--data.type=json_file \
--data.train_path=/path/to/train.jsonl \
--data.max_seq_len=256 \
--train.checkpoint.output_dir=outputs/glm5

Step 4：切换并行策略

并行能力均通过 train.accelerator 或模型 config_overrides 切换。基础命令保持不变，只替换对应 override：

torchrun --nproc_per_node=2 scripts/train_lm.py examples/glm5/train.yaml \
--model.tokenizer_path=/path/to/GLM-5-tokenizer \
--data.type=json_file \
--data.train_path=/path/to/train.jsonl \
--data.max_seq_len=256 \
<parallel-overrides> \
--train.checkpoint.output_dir=outputs/glm5_<case>

场景	<parallel-overrides>
FSDP / DP2	--train.accelerator.dp_shard=2
CP2	--train.accelerator.cp=2 --train.optimizer.loss_aggregation=token_weighted
EP2	--model.config_overrides.num_dense_layers=2 --model.config_overrides.num_experts=8 --model.config_overrides.num_experts_per_tok=2 --model.config_overrides.moe_intermediate_size=768 --train.accelerator.ep=2

本节命令与验收训练走同一条主路径：scripts/train_lm.py 调用 HyperParallel Trainer，并构建本 PR 的 GLM5ForCausalLM。对齐实验仅为固定输入，使用 fixed preset_pt batch 和 scaled 配置。

三、测试环境

• Ascend 910B
• Python 3.10.20
• torch: 2.6.0+cpu
• torch_npu: 2.6.0.post3
• npu count: 2
• mindspore: 2.8.0
• CANN 8.5.1
• transformers 5.9.0

四、仓库内功能测试

python -m pytest \
tests/torch/trainer/test_glm5_trainer.py \
tests/ut/trainer/test_checkpoint_callback_config.py \
tests/ut/trainer/test_logging_callback_config.py -q

13 passed

五、验证复现：材料、脚本与对齐实验

5.1 复现材料

验证材料包：

百度网盘链接: https://pan.baidu.com/s/1eeG5EcqXybNSu8qxpaTodA?pwd=ukrn
提取码: ukrn

材料包包含 tokenizer、fixed preset_pt、权重导出脚本、loss 对比脚本和两条复现脚本。解压后按如下方式准备：

cd /data
tar -xzf glm5_review_materials.tar.gz

MATERIAL_ROOT=/data/review_materials
PRESET_BATCH=/data/data/glm5_preset_100step_gbs4_seq256.pt
RUN_ROOT=/data/glm5_review_run_$(date +%Y%m%d_%H%M%S)

cd /root/hyper-parallel
mkdir -p "$RUN_ROOT/logs" "$RUN_ROOT/data"

cp "$PRESET_BATCH" "$RUN_ROOT/data/glm5_preset_100step_gbs4_seq256.pt"
cp "$MATERIAL_ROOT"/scripts/*.py examples/glm5/
cp "$MATERIAL_ROOT"/scripts/*.sh examples/glm5/

chmod +x examples/glm5/run_glm5_internal_alignment.sh
chmod +x examples/glm5/run_glm5_cross_framework_alignment.sh

5.2 导出 scaled HF-compatible 权重

python examples/glm5/export_scaled_hf_model.py \
--variant dense \
--tokenizer "$MATERIAL_ROOT/tokenizer" \
--output "$RUN_ROOT/glm5_scaled_dense_hf" \
2>&1 | tee "$RUN_ROOT/logs/export_scaled_dense_hf.log"

python examples/glm5/export_scaled_hf_model.py \
--variant moe_mla \
--tokenizer "$MATERIAL_ROOT/tokenizer" \
--output "$RUN_ROOT/glm5_scaled_moe_mla_hf" \
2>&1 | tee "$RUN_ROOT/logs/export_scaled_moe_mla_hf.log"

导出结果是 Transformers 可直接加载的 scaled checkpoint，用于第 5.4 节外部框架对齐

5.3 仓库内单/多卡自洽

run_glm5_internal_alignment.sh 会拉起四组训练，并用 compare_losses.py 对比逐 step loss。每组训练日志写入 $RUN_ROOT/logs/，验收标准为 pass_avg_5e-3: True

bash examples/glm5/run_glm5_internal_alignment.sh \
"$MATERIAL_ROOT/tokenizer" \
"$RUN_ROOT/data/glm5_preset_100step_gbs4_seq256.pt" \
"$RUN_ROOT"

grep -R "pass_avg_5e-3" "$RUN_ROOT/logs"/*compare*.txt

100-step 对齐结果：

对齐项	目的	结果
scaled dense 1c vs DP2	验证 dense + FSDP/DP	avg diff 6.55615000e-05，max diff 2.77690000e-04
scaled MoE+MLA+DSA 1c vs DP2	验证 MoE / MLA / DSA + FSDP/DP	avg diff 6.64436000e-05，max diff 2.55470000e-04
MoE 1c vs EP2	验证 expert parallel	avg diff 4.83024000e-05，max diff 2.59350000e-04
DSA 1c vs CP2	验证 DSA sparse attention + context parallel	avg diff 3.80690000e-05，max diff 2.98080000e-04

DSA 专用 CP wrapper 验证：attention_type=mla + use_dsa=true + cp=2，日志为 CP applied to GLM5 attention cores: dense=0 dsa=4，20 step 训练完成，无 Traceback / ERROR / nan / inf。

5.4 Transformers / LLaMAFactory 跨框架单卡精度对齐

run_glm5_cross_framework_alignment.sh 会复现 HyperParallel 与外部框架的单卡 loss/logits 对齐。判定阈值：loss abs diff <= 1e-5、logits max abs diff <= 1e-6

bash examples/glm5/run_glm5_cross_framework_alignment.sh \
"$RUN_ROOT/data/glm5_preset_100step_gbs4_seq256.pt" \
"$RUN_ROOT/glm5_scaled_dense_hf" \
"$RUN_ROOT/glm5_scaled_moe_mla_hf" \
"$RUN_ROOT"

验证路径：

外部框架	使用路径	覆盖模块	对齐指标
Transformers	official GlmMoeDsaForCausalLM	Dense / MoE / MLA / DSA	loss + logits
LLaMAFactory	CustomSeq2SeqTrainer.compute_loss	Trainer loss/logits path	loss + logits
HyperParallel	本 PR GLM5ForCausalLM	本仓库实现	loss + logits

实测结果：

对齐项	loss abs diff	logits max abs diff	结果
Transformers scaled dense	0.0	0.0	pass
Transformers scaled MoE+MLA+DSA	1.9073486328125e-06	0.0	pass
LLaMAFactory scaled dense	0.0	0.0	pass
LLaMAFactory scaled MoE+MLA+DSA	3.814697265625e-06	0.0	pass

四组 state_dict diagnostics 均为空：missing_hp_keys=[]、unexpected_hf_keys=[]、shape_mismatch_keys={}

5.5 checkpoint / resume

已验证 dense 100->110、MoE EP2 20->25、DSA CP2 20->25 恢复训练，模型、优化器、scheduler、RNG state、dataloader state 均恢复，训练完成并保存目标 step checkpoint。

---

Self-checklist:（请自检，在[ ]内打上x，我们将检视你的完成情况，否则会导致pr无法合入）

• 设计：PR对应的方案是否已经经过Maintainer评审，方案检视意见是否均已答复并完成方案修改
• 测试：PR中的代码是否已有UT/ST测试用例进行充分的覆盖，新增测试用例是否随本PR一并上库或已经上库
• 验证：PR描述信息中是否已包含对该PR对应的Feature、Refactor、Bugfix的预期目标达成情况的详细验证结果描述
• 接口：是否涉及对外接口变更，相应变更已得到接口评审组织的通过，API对应的注释信息已经刷新正确
• 文档：是否涉及官网文档修改，如果涉及请及时提交资料到Doc仓