[New features] Add truncated-normal initialization as default

[JiwenJ]

PR Category

User Experience

PR Types

New features

Description

将模型权重的默认初始化方式改为截断正态分布（truncated normal），无需任何开关，默认生效。

改动内容：

• utils.py: 使用 truncated_init_method_normal(sigma)，基于 paddle.nn.init.trunc_normal_ 实现截断正态初始化，并在初始化时使用 fp32 default dtype guard，避免低精度默认 dtype 下的数值问题。
• transformer_config.py: 在 __post_init__ 中，当用户未显式传入 init_method 时，默认使用截断正态初始化：
  • 权重分布为 W ~ TruncNormal(0, sigma^2)，截断区间为 [-3*sigma, 3*sigma]
  • sigma = 0.5 / sqrt(hidden_size)，方差 sigma^2 = 0.25 / hidden_size
• init_method_std 默认值由 0.02 改为 None，用于区分「用户显式指定」与「使用默认值」：
  • 用户显式传入 init_method_std 时保留该值，不被默认逻辑覆盖
  • 未显式传入且 hidden_size > 0 时，使用 0.5 / sqrt(hidden_size)
  • hidden_size == 0 时回退到 0.02，保证仅构造 config 的轻量用例不受影响
• 保留并尊重用户显式传入的 init_method / output_layer_init_method / embedding_init_method / embedding_init_method_std，默认逻辑不会覆盖这些自定义初始化方法。
• magic_init 在 __post_init__ 中被强制置为 False，即当前统一走截断正态初始化，magic_init=True 不再生效（分支代码保留，便于后续需要时恢复）。
• 补充单测：默认 sigma 计算、hidden_size=0 回退、显式 init_method_std / embedding_init_method_std 保留、显式 output/embedding init 保留、magic_init 被强制关闭。

是否引起精度变化

是

对于未显式指定 init_method / init_method_std 的模型，默认初始化分布由原来的普通正态（std=0.02）变为截断正态 TruncNormal(0, (0.5/sqrt(hidden_size))^2)，会改变权重初始化，进而可能影响训练初期 loss、收敛轨迹和最终精度。此外，原先依赖 magic_init=True 的模型现在会改走截断正态初始化，初始化分布也会随之变化。显式指定初始化方式的模型行为保持不变。

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ JiwenJ
❌ jiangjiwen

---

jiangjiwen seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov-commenter]

Codecov Report

❌ Patch coverage is 89.65517% with 3 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (develop@a8168fa). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/paddlefleet/transformer/transformer_config.py	85.00%	3 Missing ⚠️

❌ Your patch status has failed because the patch coverage (89.65%) is below the target coverage (90.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             develop    #1371   +/-   ##
==========================================
  Coverage           ?   84.12%           
==========================================
  Files              ?        6           
  Lines              ?       63           
  Branches           ?        5           
==========================================
  Hits               ?       53           
  Misses             ?       10           
  Partials           ?        0           

Flag	Coverage Δ
coverage_combine	84.12% <89.65%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/paddlefleet/utils.py	100.00% <100.00%> (ø)
src/paddlefleet/transformer/transformer_config.py	85.00% <85.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Paddle-CI-Bot]

PaddleFleet Log Analysis

Run #28590357703 · Attempt 1

日志分析报告

流水线名称	问题标签	修复建议	日志片段
Unit test (single card)	单测断言失败：test_zero_hidden_layers 期待 ZeroDivisionError 未抛出	修改 transformer_config.py，当 num_hidden_layers=0 时确保仍然触发 ZeroDivisionError，或更新测试断言以匹配新行为	报错代码
Integration test (H20, single card)	Loss 对齐失败（GLM4.5 single-card，diff=0.062644）	更新 GT loss 基线，或确认截断正态初始化导致的 loss 变化在可接受范围内并获取精度审批	报错代码
Integration test (A100)	Loss 对齐失败（GLM4.5 pt/sft/lora/dpo 全部偏离 GT，最大 diff=5.844）；精度变更未获审批（exit 6）	更新各子任务 GT loss 基线；请 XieYunshen/From00/risemeup1/tianlef/lugimzzz/zjjlivein/swgu98 中的对应 reviewer 审批本 PR 精度变更	报错代码
Integration test (H20, multi-card)	Loss 对齐失败（GLM4.5 pt/sft/sft-cp/lora/dpo/fp8/grouped-gemm/EP4 全部偏离 GT，最大 diff=6.296）；精度变更未获审批	同 A100：更新各子任务 GT loss 基线并获取精度审批	报错代码
Coverage Upload And Check	增量覆盖率不达标（89% < 90%，transformer_config.py lines 1068-1070 未覆盖）	为 transformer_config.py 第 1068-1070 行新增单测覆盖	报错代码

失败的测试case:

# Unit test (single card)
tests/single_card_tests/ai_edited_test/transformer/test_ai_transformer_config.py::TestTransformerConfigEdgeCases::test_zero_hidden_layers

# Integration test (H20, single card)
GLM4.5 single-card (glm45_single_card.sh, step 10: Log=11.031, GT=11.093, diff=0.062644)

# Integration test (A100)
GLM4.5 pt       (step 10: Log=11.056, GT=11.923, diff=0.867)
GLM4.5 sft      (step 10: Log=5.873,  GT=0.028,  diff=5.844)
GLM4.5 lora     (step 10: Log=4.264,  GT=6.754,  diff=2.490)
GLM4.5 dpo      (step 10: Log=0.657,  GT=0.742,  diff=0.085)
Qwen pt         (step 10: Log=11.338, GT=11.403, diff=0.066)
Qwen sft        (step 10: Log=10.754, GT=9.835,  diff=0.919)
Qwen lora       (step 10: Log=10.563, GT=9.506,  diff=1.057)

# Integration test (H20, multi-card)
GLM4.5 pre-train        (step 10: Log=11.012, GT=11.397, diff=0.386)
GLM4.5 sft              (step 10: Log=6.357,  GT=0.060,  diff=6.296)
GLM4.5 sft cp           (step 10: Log=6.345,  GT=0.050,  diff=6.296)
GLM4.5 lora             (step 10: Log=4.811,  GT=0.005,  diff=4.806)
GLM4.5 dpo              (step 10: Log=0.648,  GT=0.606,  diff=0.042)
GLM4.5 fp8              (Loss match OK)
GLM4.5 pre-train (Grouped GEMM)  (step 10: Log=11.012, GT=11.397, diff=0.385)
GLM4.5 pre-train (EP4)           (step 10: Log=11.011, GT=11.396, diff=0.386)
Qwen pre-train/sft/lora          (Loss match OK)

根本原因分析:

PR #1371 将默认权重初始化从 Normal(0, 0.02) 改为 TruncNormal(0, (0.5/sqrt(hidden_size))²) 并关闭了 magic_init，导致所有未显式指定 init_method 的任务（GLM4.5 pt/sft/lora/dpo 等）初始化分布变化，训练前 10 步 loss 与原 GT 基线不再对齐；同时 transformer_config.py 中 hidden_size=0 时的逻辑改动使原单测 test_zero_hidden_layers（期待 ZeroDivisionError）失效；增量覆盖率因 transformer_config.py 1068-1070 行的新逻辑未被测试覆盖而降至 89%。

修复建议:

1. 单测修复：test_zero_hidden_layers 需与新逻辑对齐——新代码在 hidden_size=0 时 fallback 到 init_method_std=0.02 而不再抛异常，删除该 assertRaises(ZeroDivisionError) 断言，改为验证 init_method_std == 0.02。

2. 覆盖率补全：在 tests/single_card_tests/test_transformer_config.py 中补充对 transformer_config.py 第 1068-1070 行的测试（对应 hidden_size > 0 时 sigma 计算的边界分支），使增量覆盖率 ≥ 90%。

3. GT 基线更新：初始化分布变化属于预期精度改动，需在 BOS 上更新各子任务的 GT loss 文件（glm45_pt_multi_card_gt_loss.txt、glm45_sft_gt_loss.txt 等），对齐新初始化下的 step-10 loss。

4. 精度审批：PR 描述已明确说明精度会变化，需在 GitHub 上由 XieYunshen/From00/risemeup1/tianlef（列表1）、lugimzzz/zjjlivein/tianlef（列表2）、tianlef/swgu98（列表3）各提供一个 Approved Review，CI 的 check_precision_approval.sh 才会放行。

---

🔍 准确性记录：请点击评论底部 😊 图标，选择 👍（准确）或 👎（有误），将自动记录到 CI 监控系统

_{🔄 每次 Re-run 后自动更新}

[PaddlePaddle-bot]

🤖 Paddle-CI-Agent | pr_review | 2026-07-02 23:34:42

📋 Review 摘要

PR 概述：将 Transformer 默认权重初始化切换为 truncated normal，并调整初始化相关单测/基线。
变更范围：src/paddlefleet/transformer/transformer_config.py、src/paddlefleet/utils.py、单/多卡模型初始化相关测试
影响面 Tag：TransformerConfig Models Tests

问题

未发现新增的非历史行级问题。PR 规范问题在下面章节报,不要在这里重复

历史 Findings 修复情况

Finding	问题	状态
F1	显式 embedding_init_method_std 仍会被默认 embedding_init_method 提前覆盖	⚠️ 仍存在
F2	init_method_std 默认语义变更和 magic_init 强制关闭的兼容性提醒	⚠️ 仍存在

📝 PR 规范检查

符合规范。标题使用 [New features]，描述包含 ### PR Category / ### PR Types / ### Description 且内容非空。

总体评价

本轮按风险优先审查了初始化默认逻辑、显式初始化配置保留分支，以及新增测试覆盖。没有发现新的独立行级问题，但历史 F1 的实现顺序问题仍在当前代码中，历史 F2 对应的默认语义变更也仍未见发布说明同步；因此本轮保持 Request Changes。