torchtitan-npu 集成测试基础设施实战指南测试矩阵、Loss 精确回归与 NPU 并行调度【免费下载链接】torchtitan-npuAscend Extension for torchtitan项目地址: https://gitcode.com/cann/torchtitan-npu本篇技术指南系统讲解 CANN torchtitan-npu 仓库中 tests/integration_tests 目录的集成测试基础设施。该目录遵循 Torchtitan 的tests/integration_tests布局负责维护集成测试定义、测试入口以及可选的 loss 精确比较当前覆盖 DeepSeek-V4、DeepSeek-V4.1 与 DeepSeek-V3.2 三个模型。读完本文你将掌握仓库内全部集成测试 case 的组织方式与运行入口、use_golden与check_loss两个独立维度的语义、Golden loss 精确比较与 checkpoint 恢复验证的实现原理以及基于 NPU 设备池的并行调度与调度遥测机制。测试矩阵一份用例全景README 的测试矩阵完整列出了当前仓库注册的全部集成测试 case。下表按原文整理其中编译配置列带aot_eager的 case 启用--compile.enable--compile.backendaot_eager-表示不启用编译Case 名称模型并行配置Rank 数编译配置Check Loss不检查 Loss 原因dsv4_golden_1rankDeepSeek-V41 Rank 参考配置1-是-dsv4_golden_ep2_fsdp2DeepSeek-V4EP2 FSDP22-是-dsv4_muon_swap_ep2_fsdp2DeepSeek-V4NPU 融合算子 DistMuon/AdamW NovaSwap、EP2 FSDP2、2 steps2-否两步训练 smoke未生成 swap 数值 golden也未单独断言 swap actiondsv4_checkpoint_resume_ep2_fsdp2DeepSeek-V4EP2 FSDP2step 2 恢复到 step 42-是含 grad_norm与本次连续训练的 step 3、4 精确比较dsv4_smla_1rank_aot_eagerDeepSeek-V41 Rank1aot_eager否SMLA 暂不支持--debug.deterministicdsv4_smla_ep2_fsdp2DeepSeek-V4EP2 FSDP22aot_eager否SMLA 暂不支持--debug.deterministicdsv4_smla_cp2_ep2_fsdp2DeepSeek-V4CP2 EP2 FSDP24aot_eager否SMLA 暂不支持--debug.deterministicdsv4_mtp_smla_cp2_headtailDeepSeek-V4 MTPCP2 headtail2-否SMLA 暂不支持--debug.deterministicdsv3_2_dsa_1rankDeepSeek-V3.21 RankDSA1-是-dsv3_2_dsa_ep2_fsdp2DeepSeek-V3.2DSA EP2/FSDP22-是-dsv3_2_dsa_cp2DeepSeek-V3.2DSA CP22-否ST 仅验证训练触发CPU metadata oracle 单独覆盖暂未生成 CP2 golden lossdsv4_ema_ep2_fsdp2DeepSeek-V4Golden EP2/FSDP2 EMA CPU offload2-否校验完整 DCP metadata 包含ema_optimizer.*dsv41_golden_2p_ep2_fsdp2DeepSeek-V4.1Golden 调试模型40 层全结构、调试宽度 FSDP2 EP250 步精确 loss2-是多模态 golden 轨迹守护锚定tests/assets/losses/dsv41_golden_2p_ep2_fsdp2.txt8 卡形状作手动 A/B 回归锚不入库从 run_tests.py 的 suite 注册表可以看到这些 case 被组织为 6 个可独立挑选的 suitemodels默认 smoke 套件聚合 V4、V4.1、V3.2 三个模型的全部用例、deepseek_v3_2、deepseek_v4、deepseek_v4_checkpoint、deepseek_v41、ema。每个 case 都是 tests/integration_tests/init.py 中OverrideDefinitions数据类的一个实例其字段override_args、ngpu、use_golden、check_loss、check_resume、expected_steps、timeout、env_vars等完整定义了一个用例的启动参数、设备需求与验证策略。Golden 参考算子与 NPU override两个独立维度README 特别强调了一个容易混淆的关键设计use_golden与check_loss是两个独立维度use_golden仅决定使用 Golden 参考算子还是 SMLA/NPU overridecheck_loss决定是否启用 deterministic、读取参考 loss 并执行精确数值比较。以 deepseek_v4.py 为例两个维度可以自由组合Golden 参考配方GOLDEN_OVERRIDES只导入 RoPE workaround 与 sparse attention golden 算子并使用参考 MoE token dispatcher 路径保证入库的 loss 基线不依赖 NPU 融合 token-dispatcher 实现。NPU 融合配方NPU_OVERRIDES导入 Ascend RMSNorm、complex RoPE、sparse attentionasc_li_metadata / asc_li / asc_metadata / asc、MHCasc_hc_pre / asc_hc_post以及 fused token dispatcher 等一组 override。因此use_goldenTrue, check_lossTrueGolden 算子的确定性轨迹 vs 入库 golden loss逐值精确比较三个 golden case 采用此组合。use_goldenFalse, check_lossFalse覆盖 SMLA/NPU override 的真实构图、编译和训练执行路径四个 SMLA case 与dsv4_muon_swap_ep2_fsdp2采用此组合。对于 check_loss 的 caserunner 会启用--debug.deterministic --debug.seed42见 run_tests.py 的DETERMINISTIC_ARGS。SMLA 场景正因为暂不支持--debug.deterministic而全部设置check_lossFalse。Golden Loss 精确比较机制当前三个 Golden caseV4 两个、V4.1 一个设置check_lossTrue使用固定随机种子和 deterministic 模式比较 TensorBoard 标量loss_metrics/global_avg_loss要求 step 集合和每个浮点值均精确相等不舍入、不使用容差。golden 参考数据存放在 tests/assets/losses 目录每个 check_loss 用例对应一个case名.txt文件内容为step loss两列的纯文本例如 dsv4_golden_1rank.txt 记录了 1~100 步的完整 loss 轨迹。golden 文件路径由 runner 按 case 名自动解析run_tests.py 的_GOLDEN_DIR。比较逻辑在 loss_compare.py 中实现extract_losses_from_tensorboard通过 TensorBoardEventAccumulator读取标量且拒绝重复 step 或非有限值duplicate step or non-finite value即失败。assert_losses_equal基于unittest逐值断言 step 集合与每个浮点值完全相等并在 step 缺失/多余时给出missing_in_test/extra_in_test的显式诊断。值得注意的 torchtitan-npu 扩展loss 不匹配时runner 会以[GOLDEN_MISMATCH]前缀把实际 loss 按参考文件格式 dump 出来方便在有意变更基线时直接重新生成 golden 文件见 run_tests.py。两个 DeepSeek-V3.2 case 同样设置check_lossTrue使用 RoPE workaround 与 Ascend DSA metadata/attention override分别对 1-rank 和 EP2/FSDP2 的 100-step loss 做精确比较对应 dsv3_2_dsa_1rank.txt 与 dsv3_2_dsa_ep2_fsdp2.txt。V4.1 用例的独立性约束README 明确V4.1 模型栈完全独立于deepseek_v4——无继承、无 import、无跨模型 override这一约束由 tests/unit_tests/models/deepseek_v41/test_independence.py 守护golden 参考算子是V41SparseAttention/V41MoE的原生路径套件仅需 RoPE workaround 与 virtual optimizer 两个通用 override。V4.1 golden 用例deepseek_v41.py通过GOLDEN_ENV环境变量MODULEtorchtitan_npu.models.deepseek_v41、CONFIGdeepseek_v41_debugmodel、TORCHTITAN_NPU_VISION_GOLDEN1等把 trainer 路由到 V4.1 多模态调试模型并以 30 步精确 loss 锚定 40 层全结构、调试宽度的确定性轨迹8 卡形状保留为通过run_train.sh手动执行的 A/B 回归其 anchor 有意不入库。用例还设置timeout7200并声明 25/40 步的 LR 调度warmup 25、total 40属于冻结基线的一部分——缩短 smoke 运行时其 30 步必须是该基线精确前缀改动会破坏锚定。Checkpoint 恢复精确对齐dsv4_checkpoint_resume_ep2_fsdp2dsv4_checkpoint_resume_ep2_fsdp2是一个合并了 checkpoint 保存、恢复和精度对齐验证的特殊用例已注册到门禁的modelssuite。其定义见 deepseek_v4.py两卡 EP2 FSDP2Golden 算子设置check_resumeTrue固定 seed42 并开启 deterministic。第一阶段连续训练 4 步--training.steps4--checkpoint.interval2保留 step 2 的完整 checkpoint。第二阶段在新进程中通过--checkpoint.load-step2恢复再训练第 3、4 步。两阶段均设置--training.steps4确保学习率调度一致共用 checkpoint 目录TensorBoard 分别写入tb_phase_0和tb_phase_1。验证时检查loss_metrics/global_avg_loss与grad_norm两个标量步骤集合必须分别为(1, 2, 3, 4)和(3, 4)续训两步的两个标量必须与连续训练逐值精确相等不舍入、不使用容差缺失、重复步骤或非有限值均失败。注意本次连续训练是动态基准——不读取也不更新仓内 golden loss 文件恢复前后的对比只发生在同一次 runner 进程内部compare_checkpoint_metrics实现于 loss_compare.py。单独执行此用例python -m tests.integration_tests.run_tests /tmp/checkpoint_resume_output \ --test_suite models --test_name dsv4_checkpoint_resume_ep2_fsdp2 --ngpu 2各用例的覆盖意图SMLA / NPU override 四件套四个 SMLA case单卡、EP2、CP2EP2、MTPCP2都设置check_lossFalse因此不会启用--debug.deterministic也不会读取 golden loss。它们用于覆盖 SMLA/NPU override 在单卡、EPFSDP、CPEPFSDP 以及 MTPCP 场景下的实际构图、编译和训练执行路径。单卡、EP2 和 CP2EP2 场景均使用aot_eager并默认覆盖 fused MoE token dispatcher。MTPCP 用例dsv4_mtp_smla_cp2_headtail固定使用deepseek_v4_debugmodel、CP2 和 headtail在 C4 packed sequence 上执行完整的 MTP forward、chunked loss 和 backward。Muon NovaSwap 融合路径 smokedsv4_muon_swap_ep2_fsdp2使用 NPU 融合算子Ascend RMSNorm、complex RoPE、sparse attention、MHC、MoE token dispatcher两卡 EP2/FSDP2并追加--optimizer.nameMuon与swap_optimizeroverride见 deepseek_v4.py。它运行两步覆盖 DistMuon 与 AdamW fallback 在融合训练路径中的 swap smoke。该 case 不读取 golden loss、不启用 deterministic、也不单独断言 H2D/D2H action因此不声称与未 swap 或 AdamW 路径数值等价。EMA checkpoint smokedsv4_ema_ep2_fsdp2定义于 ema.py使用 Golden EP2/FSDP2 EMA CPU offload训练 2 步并开启 checkpoint。它以verify_ema_checkpointTrue触发assert_ema_checkpoint_written断言找到最新一份完整的 DCP checkpoint用dcp.FileSystemReader读取 metadata要求其中存在ema_optimizer.*前缀的 key从而验证 EMA 状态确实随 checkpoint 落盘。覆盖边界的说明README 明确指出了 coverage 边界这里的 integration recipe 聚焦 sparse-attention / MHC 回归边界端到端 example 脚本额外启用 Virtual Optimizercheckpoint 保存兼容由 extensionCheckpointManager提供——这些 optimizer state / checkpoint 路径不属于当前 integration loss regression 的覆盖范围。运行入口CI 脚本与 Python runnerCI 入口CI 通过 .ci/smoke_test.sh 启动测试。该脚本会先 source CANN 环境/usr/local/Ascend/cann/set_env.sh把 torchrun 等 launcher 绑定到 CI 提供的 Python 3.12 解释器clone 并安装 requirements.txt 指定版本的 torchtitan 与当前仓库然后依次执行python3 -m pytest -v --tbshort tests/smoke_tests python3 -m tests.integration_tests.run_tests \ ${OUTPUT_DIR} \ --test_suite models \ --module ${MODULE} \ --config ${CONFIG} \ --ngpu ${NGPU}即完整 CI 流程会在此之前先执行tests/smoke_tests随后以--test_suite models --ngpu 4默认值运行集成测试与 CI 的集成测试配置保持一致覆盖 DeepSeek-V4、V4.1 和 V3.2。Python 入口也可以直接运行 Python 入口python -m tests.integration_tests.run_tests \ ./test_reports/integration \ --test_suite models \ --ngpu 4其中./test_reports/integration是必填的测试输出目录运行前需要确保该目录为空run_tests.py 在目录非空时会直接报错Please provide an empty output directory.。命令行参数一览由 run_tests.py 定义参数默认值说明output_dir位置参数必填测试结果输出目录必须为空--test_suitedeepseek_v4可选 suitemodels/deepseek_v3_2/deepseek_v4/deepseek_v4_checkpoint/deepseek_v41/ema--moduletorchtitan_npu.models.deepseek_v4训练使用的模型模块作为MODULE环境变量传给 run_train.sh--configdeepseek_v4_debugmodel训练使用的 config 函数作为CONFIG环境变量传给 run_train.sh--test_nameall仅运行指定 case 名--ngpu8设备池大小上限--excludeNone逗号分隔的排除 case 列表--parallel/--no-parallelTrue并行是否并发调度--no-parallel强制串行每个 case 实际通过bash scripts/run_train.sh --dump_folder outdir启动训练run_tests.pyrunner 以 argv 列表直接调用、不经 shell因此命令行 token 不会被二次切分或插值训练参数经环境变量传递其中NGPU、LOG_RANK始终最后写入以保持优先级per-caseenv_vars覆盖--module/--config。check_loss 的 case 还会附加 run_train.sh 所需的一组默认训练参数--metrics.enable_tensorboard --metrics.log_freq1 --metrics.save_tb_foldertb --dataloader.dataset-pathtests/assets/c4_test --training.disable-cuda-graphs。并行调度GPUPool 与真实可见性runner 的并行调度机制迁移自 torchtitan 的 GPUPool并针对 NPU 环境做了多处关键改造run_tests.py。设备池构造绝不伪造 ID默认将用例并发打包到固定的 NPU 池上每个用例通过ASCEND_RT_VISIBLE_DEVICES绑定到互不相交的物理 NPU 子集任一时刻在用 NPU 数量不超过设备池大小。设备池从真实可见性构造_resolve_npu_pool_ids若运行环境已通过ASCEND_RT_VISIBLE_DEVICES限定可用 NPU 子集如 CI 按任务分配设备池从该子集构造对超出的--ngpu硬报错否则用torch.npu.device_count()枚举运行时实际暴露的物理 ID--ngpu超出实际设备数时告警并截断——绝不按range(--ngpu)伪造 ID。README 解释了伪造 ID 的严重后果不存在的 ID 会让子进程在 CANNGetVisibleDevices阶段即失败torchtitan 设备探测退回 cuda 后以torch._C._cuda_setDeviceAttributeError 崩溃run_tests.py 中记录了首个并行 CI canary 因此失败的现场。调度策略细节池小于某用例需求时该用例被显式 skip而非在acquire()中死锁。用例按ngpu从大到小提交以减少队头阻塞且每个用例独占一个 worker 线程而非 upstream 的min(cases, ngpu)避免被阻塞的大用例占用 executor 槽位导致其后的小用例被串行化。用例输出被整体缓存结束后以带[case 名]前缀的连续块输出避免多用例日志交错_emit_block持有全局输出锁逐块写入。如需强制串行执行传入--no-parallel。用例可通过OverrideDefinitions.timeout设置超时超时后 runner 向子进程所在进程组先发SIGTERM、宽限期默认 10s后再SIGKILL确保torchrun及各 rank 子进程全部退出每个子进程以start_new_sessionTrue独立 session 启动其 pid 即 pgid不会留下占用 NPU 的孤儿进程超时按失败处理并输出已捕获日志_terminate_process_group见 run_tests.py。调度遥测并行结束后 runner 会输出两行调度遥测统计窗口均为首次分配到最后一次释放空闲在首尾不计入、用例间空隙计入池利用率[parallel] pool: window/utilization/busy histogram/allocations含窗口时长、NPU 利用率百分比、各在用等级如4/4 busy的忙碌直方图与分配次数直方图用例重叠[parallel] overlap: sequential vs window、节省时长、并发度直方图将并发 case 数积分得到串行等价时长报告并行节省的时间与 2 并发时长占比。这两行遥测可直接用于核验 CI canary 的打包与重叠效果。README 同时说明调度器本身不设独立单元测试——其正确性设备不重叠、失败/超时释放、并发打包、golden loss 等价由集成测试自身的 canary 运行直接验证。小结torchtitan-npu 的集成测试基础设施以 Torchtitan 的布局与 runner 为基础为三个 DeepSeek 系列模型建立了一套Golden 参考路径 NPU 融合路径双轨、loss 逐值精确回归、checkpoint 恢复对齐、NPU 池并发调度的完整验证体系。理解use_golden与check_loss的维度分离、golden 文件的锚定方式以及调度器从真实设备可见性构造池的设计是扩展新 case、维护基线或排查 CI 失败的关键起点。【免费下载链接】torchtitan-npuAscend Extension for torchtitan项目地址: https://gitcode.com/cann/torchtitan-npu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 torchtitan-npu 集成测试基础设施实战指南：测试矩阵、Loss 精确回归与 NPU 并行调度
torchtitan-npu 集成测试基础设施实战指南测试矩阵、Loss 精确回归与 NPU 并行调度【免费下载链接】torchtitan-npuAscend Extension for torchtitan项目地址: https://gitcode.com/cann/torchtitan-npu本篇技术指南系统讲解 CANN torchtitan-npu 仓库中 tests/integration_tests 目录的集成测试基础设施。该目录遵循 Torchtitan 的tests/integration_tests布局负责维护集成测试定义、测试入口以及可选的 loss 精确比较当前覆盖 DeepSeek-V4、DeepSeek-V4.1 与 DeepSeek-V3.2 三个模型。读完本文你将掌握仓库内全部集成测试 case 的组织方式与运行入口、use_golden与check_loss两个独立维度的语义、Golden loss 精确比较与 checkpoint 恢复验证的实现原理以及基于 NPU 设备池的并行调度与调度遥测机制。测试矩阵一份用例全景README 的测试矩阵完整列出了当前仓库注册的全部集成测试 case。下表按原文整理其中编译配置列带aot_eager的 case 启用--compile.enable--compile.backendaot_eager-表示不启用编译Case 名称模型并行配置Rank 数编译配置Check Loss不检查 Loss 原因dsv4_golden_1rankDeepSeek-V41 Rank 参考配置1-是-dsv4_golden_ep2_fsdp2DeepSeek-V4EP2 FSDP22-是-dsv4_muon_swap_ep2_fsdp2DeepSeek-V4NPU 融合算子 DistMuon/AdamW NovaSwap、EP2 FSDP2、2 steps2-否两步训练 smoke未生成 swap 数值 golden也未单独断言 swap actiondsv4_checkpoint_resume_ep2_fsdp2DeepSeek-V4EP2 FSDP2step 2 恢复到 step 42-是含 grad_norm与本次连续训练的 step 3、4 精确比较dsv4_smla_1rank_aot_eagerDeepSeek-V41 Rank1aot_eager否SMLA 暂不支持--debug.deterministicdsv4_smla_ep2_fsdp2DeepSeek-V4EP2 FSDP22aot_eager否SMLA 暂不支持--debug.deterministicdsv4_smla_cp2_ep2_fsdp2DeepSeek-V4CP2 EP2 FSDP24aot_eager否SMLA 暂不支持--debug.deterministicdsv4_mtp_smla_cp2_headtailDeepSeek-V4 MTPCP2 headtail2-否SMLA 暂不支持--debug.deterministicdsv3_2_dsa_1rankDeepSeek-V3.21 RankDSA1-是-dsv3_2_dsa_ep2_fsdp2DeepSeek-V3.2DSA EP2/FSDP22-是-dsv3_2_dsa_cp2DeepSeek-V3.2DSA CP22-否ST 仅验证训练触发CPU metadata oracle 单独覆盖暂未生成 CP2 golden lossdsv4_ema_ep2_fsdp2DeepSeek-V4Golden EP2/FSDP2 EMA CPU offload2-否校验完整 DCP metadata 包含ema_optimizer.*dsv41_golden_2p_ep2_fsdp2DeepSeek-V4.1Golden 调试模型40 层全结构、调试宽度 FSDP2 EP250 步精确 loss2-是多模态 golden 轨迹守护锚定tests/assets/losses/dsv41_golden_2p_ep2_fsdp2.txt8 卡形状作手动 A/B 回归锚不入库从 run_tests.py 的 suite 注册表可以看到这些 case 被组织为 6 个可独立挑选的 suitemodels默认 smoke 套件聚合 V4、V4.1、V3.2 三个模型的全部用例、deepseek_v3_2、deepseek_v4、deepseek_v4_checkpoint、deepseek_v41、ema。每个 case 都是 tests/integration_tests/init.py 中OverrideDefinitions数据类的一个实例其字段override_args、ngpu、use_golden、check_loss、check_resume、expected_steps、timeout、env_vars等完整定义了一个用例的启动参数、设备需求与验证策略。Golden 参考算子与 NPU override两个独立维度README 特别强调了一个容易混淆的关键设计use_golden与check_loss是两个独立维度use_golden仅决定使用 Golden 参考算子还是 SMLA/NPU overridecheck_loss决定是否启用 deterministic、读取参考 loss 并执行精确数值比较。以 deepseek_v4.py 为例两个维度可以自由组合Golden 参考配方GOLDEN_OVERRIDES只导入 RoPE workaround 与 sparse attention golden 算子并使用参考 MoE token dispatcher 路径保证入库的 loss 基线不依赖 NPU 融合 token-dispatcher 实现。NPU 融合配方NPU_OVERRIDES导入 Ascend RMSNorm、complex RoPE、sparse attentionasc_li_metadata / asc_li / asc_metadata / asc、MHCasc_hc_pre / asc_hc_post以及 fused token dispatcher 等一组 override。因此use_goldenTrue, check_lossTrueGolden 算子的确定性轨迹 vs 入库 golden loss逐值精确比较三个 golden case 采用此组合。use_goldenFalse, check_lossFalse覆盖 SMLA/NPU override 的真实构图、编译和训练执行路径四个 SMLA case 与dsv4_muon_swap_ep2_fsdp2采用此组合。对于 check_loss 的 caserunner 会启用--debug.deterministic --debug.seed42见 run_tests.py 的DETERMINISTIC_ARGS。SMLA 场景正因为暂不支持--debug.deterministic而全部设置check_lossFalse。Golden Loss 精确比较机制当前三个 Golden caseV4 两个、V4.1 一个设置check_lossTrue使用固定随机种子和 deterministic 模式比较 TensorBoard 标量loss_metrics/global_avg_loss要求 step 集合和每个浮点值均精确相等不舍入、不使用容差。golden 参考数据存放在 tests/assets/losses 目录每个 check_loss 用例对应一个case名.txt文件内容为step loss两列的纯文本例如 dsv4_golden_1rank.txt 记录了 1~100 步的完整 loss 轨迹。golden 文件路径由 runner 按 case 名自动解析run_tests.py 的_GOLDEN_DIR。比较逻辑在 loss_compare.py 中实现extract_losses_from_tensorboard通过 TensorBoardEventAccumulator读取标量且拒绝重复 step 或非有限值duplicate step or non-finite value即失败。assert_losses_equal基于unittest逐值断言 step 集合与每个浮点值完全相等并在 step 缺失/多余时给出missing_in_test/extra_in_test的显式诊断。值得注意的 torchtitan-npu 扩展loss 不匹配时runner 会以[GOLDEN_MISMATCH]前缀把实际 loss 按参考文件格式 dump 出来方便在有意变更基线时直接重新生成 golden 文件见 run_tests.py。两个 DeepSeek-V3.2 case 同样设置check_lossTrue使用 RoPE workaround 与 Ascend DSA metadata/attention override分别对 1-rank 和 EP2/FSDP2 的 100-step loss 做精确比较对应 dsv3_2_dsa_1rank.txt 与 dsv3_2_dsa_ep2_fsdp2.txt。V4.1 用例的独立性约束README 明确V4.1 模型栈完全独立于deepseek_v4——无继承、无 import、无跨模型 override这一约束由 tests/unit_tests/models/deepseek_v41/test_independence.py 守护golden 参考算子是V41SparseAttention/V41MoE的原生路径套件仅需 RoPE workaround 与 virtual optimizer 两个通用 override。V4.1 golden 用例deepseek_v41.py通过GOLDEN_ENV环境变量MODULEtorchtitan_npu.models.deepseek_v41、CONFIGdeepseek_v41_debugmodel、TORCHTITAN_NPU_VISION_GOLDEN1等把 trainer 路由到 V4.1 多模态调试模型并以 30 步精确 loss 锚定 40 层全结构、调试宽度的确定性轨迹8 卡形状保留为通过run_train.sh手动执行的 A/B 回归其 anchor 有意不入库。用例还设置timeout7200并声明 25/40 步的 LR 调度warmup 25、total 40属于冻结基线的一部分——缩短 smoke 运行时其 30 步必须是该基线精确前缀改动会破坏锚定。Checkpoint 恢复精确对齐dsv4_checkpoint_resume_ep2_fsdp2dsv4_checkpoint_resume_ep2_fsdp2是一个合并了 checkpoint 保存、恢复和精度对齐验证的特殊用例已注册到门禁的modelssuite。其定义见 deepseek_v4.py两卡 EP2 FSDP2Golden 算子设置check_resumeTrue固定 seed42 并开启 deterministic。第一阶段连续训练 4 步--training.steps4--checkpoint.interval2保留 step 2 的完整 checkpoint。第二阶段在新进程中通过--checkpoint.load-step2恢复再训练第 3、4 步。两阶段均设置--training.steps4确保学习率调度一致共用 checkpoint 目录TensorBoard 分别写入tb_phase_0和tb_phase_1。验证时检查loss_metrics/global_avg_loss与grad_norm两个标量步骤集合必须分别为(1, 2, 3, 4)和(3, 4)续训两步的两个标量必须与连续训练逐值精确相等不舍入、不使用容差缺失、重复步骤或非有限值均失败。注意本次连续训练是动态基准——不读取也不更新仓内 golden loss 文件恢复前后的对比只发生在同一次 runner 进程内部compare_checkpoint_metrics实现于 loss_compare.py。单独执行此用例python -m tests.integration_tests.run_tests /tmp/checkpoint_resume_output \ --test_suite models --test_name dsv4_checkpoint_resume_ep2_fsdp2 --ngpu 2各用例的覆盖意图SMLA / NPU override 四件套四个 SMLA case单卡、EP2、CP2EP2、MTPCP2都设置check_lossFalse因此不会启用--debug.deterministic也不会读取 golden loss。它们用于覆盖 SMLA/NPU override 在单卡、EPFSDP、CPEPFSDP 以及 MTPCP 场景下的实际构图、编译和训练执行路径。单卡、EP2 和 CP2EP2 场景均使用aot_eager并默认覆盖 fused MoE token dispatcher。MTPCP 用例dsv4_mtp_smla_cp2_headtail固定使用deepseek_v4_debugmodel、CP2 和 headtail在 C4 packed sequence 上执行完整的 MTP forward、chunked loss 和 backward。Muon NovaSwap 融合路径 smokedsv4_muon_swap_ep2_fsdp2使用 NPU 融合算子Ascend RMSNorm、complex RoPE、sparse attention、MHC、MoE token dispatcher两卡 EP2/FSDP2并追加--optimizer.nameMuon与swap_optimizeroverride见 deepseek_v4.py。它运行两步覆盖 DistMuon 与 AdamW fallback 在融合训练路径中的 swap smoke。该 case 不读取 golden loss、不启用 deterministic、也不单独断言 H2D/D2H action因此不声称与未 swap 或 AdamW 路径数值等价。EMA checkpoint smokedsv4_ema_ep2_fsdp2定义于 ema.py使用 Golden EP2/FSDP2 EMA CPU offload训练 2 步并开启 checkpoint。它以verify_ema_checkpointTrue触发assert_ema_checkpoint_written断言找到最新一份完整的 DCP checkpoint用dcp.FileSystemReader读取 metadata要求其中存在ema_optimizer.*前缀的 key从而验证 EMA 状态确实随 checkpoint 落盘。覆盖边界的说明README 明确指出了 coverage 边界这里的 integration recipe 聚焦 sparse-attention / MHC 回归边界端到端 example 脚本额外启用 Virtual Optimizercheckpoint 保存兼容由 extensionCheckpointManager提供——这些 optimizer state / checkpoint 路径不属于当前 integration loss regression 的覆盖范围。运行入口CI 脚本与 Python runnerCI 入口CI 通过 .ci/smoke_test.sh 启动测试。该脚本会先 source CANN 环境/usr/local/Ascend/cann/set_env.sh把 torchrun 等 launcher 绑定到 CI 提供的 Python 3.12 解释器clone 并安装 requirements.txt 指定版本的 torchtitan 与当前仓库然后依次执行python3 -m pytest -v --tbshort tests/smoke_tests python3 -m tests.integration_tests.run_tests \ ${OUTPUT_DIR} \ --test_suite models \ --module ${MODULE} \ --config ${CONFIG} \ --ngpu ${NGPU}即完整 CI 流程会在此之前先执行tests/smoke_tests随后以--test_suite models --ngpu 4默认值运行集成测试与 CI 的集成测试配置保持一致覆盖 DeepSeek-V4、V4.1 和 V3.2。Python 入口也可以直接运行 Python 入口python -m tests.integration_tests.run_tests \ ./test_reports/integration \ --test_suite models \ --ngpu 4其中./test_reports/integration是必填的测试输出目录运行前需要确保该目录为空run_tests.py 在目录非空时会直接报错Please provide an empty output directory.。命令行参数一览由 run_tests.py 定义参数默认值说明output_dir位置参数必填测试结果输出目录必须为空--test_suitedeepseek_v4可选 suitemodels/deepseek_v3_2/deepseek_v4/deepseek_v4_checkpoint/deepseek_v41/ema--moduletorchtitan_npu.models.deepseek_v4训练使用的模型模块作为MODULE环境变量传给 run_train.sh--configdeepseek_v4_debugmodel训练使用的 config 函数作为CONFIG环境变量传给 run_train.sh--test_nameall仅运行指定 case 名--ngpu8设备池大小上限--excludeNone逗号分隔的排除 case 列表--parallel/--no-parallelTrue并行是否并发调度--no-parallel强制串行每个 case 实际通过bash scripts/run_train.sh --dump_folder outdir启动训练run_tests.pyrunner 以 argv 列表直接调用、不经 shell因此命令行 token 不会被二次切分或插值训练参数经环境变量传递其中NGPU、LOG_RANK始终最后写入以保持优先级per-caseenv_vars覆盖--module/--config。check_loss 的 case 还会附加 run_train.sh 所需的一组默认训练参数--metrics.enable_tensorboard --metrics.log_freq1 --metrics.save_tb_foldertb --dataloader.dataset-pathtests/assets/c4_test --training.disable-cuda-graphs。并行调度GPUPool 与真实可见性runner 的并行调度机制迁移自 torchtitan 的 GPUPool并针对 NPU 环境做了多处关键改造run_tests.py。设备池构造绝不伪造 ID默认将用例并发打包到固定的 NPU 池上每个用例通过ASCEND_RT_VISIBLE_DEVICES绑定到互不相交的物理 NPU 子集任一时刻在用 NPU 数量不超过设备池大小。设备池从真实可见性构造_resolve_npu_pool_ids若运行环境已通过ASCEND_RT_VISIBLE_DEVICES限定可用 NPU 子集如 CI 按任务分配设备池从该子集构造对超出的--ngpu硬报错否则用torch.npu.device_count()枚举运行时实际暴露的物理 ID--ngpu超出实际设备数时告警并截断——绝不按range(--ngpu)伪造 ID。README 解释了伪造 ID 的严重后果不存在的 ID 会让子进程在 CANNGetVisibleDevices阶段即失败torchtitan 设备探测退回 cuda 后以torch._C._cuda_setDeviceAttributeError 崩溃run_tests.py 中记录了首个并行 CI canary 因此失败的现场。调度策略细节池小于某用例需求时该用例被显式 skip而非在acquire()中死锁。用例按ngpu从大到小提交以减少队头阻塞且每个用例独占一个 worker 线程而非 upstream 的min(cases, ngpu)避免被阻塞的大用例占用 executor 槽位导致其后的小用例被串行化。用例输出被整体缓存结束后以带[case 名]前缀的连续块输出避免多用例日志交错_emit_block持有全局输出锁逐块写入。如需强制串行执行传入--no-parallel。用例可通过OverrideDefinitions.timeout设置超时超时后 runner 向子进程所在进程组先发SIGTERM、宽限期默认 10s后再SIGKILL确保torchrun及各 rank 子进程全部退出每个子进程以start_new_sessionTrue独立 session 启动其 pid 即 pgid不会留下占用 NPU 的孤儿进程超时按失败处理并输出已捕获日志_terminate_process_group见 run_tests.py。调度遥测并行结束后 runner 会输出两行调度遥测统计窗口均为首次分配到最后一次释放空闲在首尾不计入、用例间空隙计入池利用率[parallel] pool: window/utilization/busy histogram/allocations含窗口时长、NPU 利用率百分比、各在用等级如4/4 busy的忙碌直方图与分配次数直方图用例重叠[parallel] overlap: sequential vs window、节省时长、并发度直方图将并发 case 数积分得到串行等价时长报告并行节省的时间与 2 并发时长占比。这两行遥测可直接用于核验 CI canary 的打包与重叠效果。README 同时说明调度器本身不设独立单元测试——其正确性设备不重叠、失败/超时释放、并发打包、golden loss 等价由集成测试自身的 canary 运行直接验证。小结torchtitan-npu 的集成测试基础设施以 Torchtitan 的布局与 runner 为基础为三个 DeepSeek 系列模型建立了一套Golden 参考路径 NPU 融合路径双轨、loss 逐值精确回归、checkpoint 恢复对齐、NPU 池并发调度的完整验证体系。理解use_golden与check_loss的维度分离、golden 文件的锚定方式以及调度器从真实设备可见性构造池的设计是扩展新 case、维护基线或排查 CI 失败的关键起点。【免费下载链接】torchtitan-npuAscend Extension for torchtitan项目地址: https://gitcode.com/cann/torchtitan-npu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考