TorchTitan 测试体系详解Fake PG / Real PG 集成测试、数值守卫与单元/集成测试运行指南【免费下载链接】torchtitanA PyTorch native platform for training generative AI models项目地址: https://gitcode.com/GitHub_Trending/to/torchtitan本篇指南围绕 torchtitan 仓库的 测试体系文档 展开系统讲解其单元测试 集成测试 数值测试三层测试架构、基于 Fake PGFakeProcessGroup与 Real PG真实进程组的 CI 设计原则以及各类测试的完整运行命令。读完本文你将能够在本机或 CI 环境中复现 torchtitan 的 A10G 完整测试矩阵、理解 golden 数值文件的校验机制并掌握如何为项目新增一个集成测试用例。测试目录结构torchtitan 的全部测试位于tests/目录下按硬件需求与测试粒度分层组织tests/unit_tests/cpu/无需 GPU 即可运行的单元测试tests/unit_tests/gpu/需要 GPU 的测试其中多卡测试使用 pytest 的multi_gpu标记markertests/integration_tests/组合多个组件进行端到端验证的集成测试features.pytorchtitan 核心特性与组合性composability测试flux.pyFLUX 模型测试h100.pyH100 GPU 上的测试用例b200.py需要 SM100 或 SM103 GPUB200 级别的测试用例models.py各模型架构的测试tests/assets/测试资产与 fixturelosses/数值守卫numerics guards用的 golden 损失与梯度范数曲线按fake_pg/与real_pg/两个模式目录存放tokenizer/测试用的分词器配置与词表文件custom_schedule.csv测试用的自定义 PP流水线并行调度表。每个集成测试套件的测试条目定义OverrideDefinitions列表与对应的Trainer.Config构建函数分离存放套件清单在tests/integration_tests/下而配置本体位于 torchtitan_recipes/tests/ 目录每个套件对应一个模块features.py、models.py、h100.py、b200.py等。这种清单与配置分离的设计使得同一套硬件套件可以同时被 CI 的 A10G 通道与 ROCm 等可复用工作流引用。CI 设计集成测试目标E2E 组合性原则尽可能使用 Fake PGtorchtitan 的 CI 遵循一个核心原则在 pull request 上尽可能使用 Fake PG以获得快速而广泛的功能覆盖。每一个启用的测试都会在代码合入前执行与 Fake PG 兼容的测试只使用1 块物理 GPUtorch.distributed的 FakeProcessGroup 在单卡上模拟任意 world size 的通信标记了use_real_pgTrue的测试使用8 块物理 GPU定期调度schedule与合入后post-merge运行则以 Real PG 执行完整测试套件。从源码看这一机制在 run_tests.py 中落地当use_fake_pg为真时runner 通过环境变量COMM_MODEfake_backend切换通信后端并将NGPU设为测试声明的逻辑卡数而实际只占用 1 块物理 GPU见run_single_test中的base_env[COMM_MODE] fake_backend分支。同时init.py 中的validate_fake_pg_compatibility会对每个配置做兼容性校验如果配置启用了 checkpointing、流水线并行pipeline_parallel_degree 1或显式非 Fake 通信后端等已知不兼容项而测试又未标记use_real_pgTrue校验会直接抛出ValueError。这保证了哪些测试能在 Fake PG 上跑这一约束由代码强制执行而非依赖约定。CI 触发节奏Cadence1 GPU Fake PG 节奏pull request 的 open、update、reopen 或 ready-for-review 事件均触发。可复用工作流reusable workflow的调用方默认运行 Fake PG8 GPU Real PG 节奏上述任一 PR 事件都会将标记use_real_pgTrue的测试拆分为required subset - features与required subset - models两个独立作业运行。给 PR 打上ciflow/8gpu标签会创建ciflow/8gpu/*标签并以 Real PG 运行full suite - features与full suite - models两个完整套件作业。向main的推送与合并、每 6 小时的计划任务以及手动 dispatch 也会运行这两个完整套件作业。可复用工作流调用方可以显式请求execution_mode: real_pgROCm 工作流即采用这种方式8 GPU H100 节奏携带ciflow/h100.8标签的自选 PR。该通道始终使用 Real PG标签保留期间update 与 reopen 事件会重新运行B200 节奏携带ciflow/b200标签的自选 PR以及main上影响 Kimi K3 的推送。该通道使用 Real PG目前运行 Kimi K3 多模态 FSDP 测试对应 b200.py 中的kimi_k3_mm_fsdp用例。功能测试features 套件提供基础设施组合性的深度Fake PG 运行验证特性组合能够正确配置、变换并完成训练Real PG 运行则额外覆盖真实集合通信与分布式状态。模型测试models 套件提供跨受支持实现的广度。两类定义保持分离以便区分。每个 8 GPU Real PG 套件作为独立 CI 作业运行并拥有独立超时模型作业同时运行 FLUX 集成测试。在 PR 上Fake PG 通道与real_pg_requiredReal PG 范围对启用的 A10G 测试做无重叠切分合入后与计划调度的 Real PG 通道则运行完整选定套件。硬件通过套件编码features与models运行在 A10G 通道h100与b200仅在其各自的工作流中以 Real PG 运行run_tests.py 的main中也会强制校验h100/b200套件不允许fake_pg模式。数值测试目标确定性回归覆盖部分模型集成测试通过设置golden_numerics_path来检查数值确定性。运行器从该文件推导出指标列与步数_read_golden_spec解析 golden 文件的# step loss grad_norm表头为 A10G Real PG 执行创建种子 checkpointseed checkpoint并通过 loss_compare.py 执行集成用例。Fake PG 执行跳过种子 checkpoint 创建走其固定的初始化路径。具体规则A10G 用例在 PR 上以 1 块物理 GPU Fake PG 运行在合入后、计划调度或ciflow/8gpu标签触发时以 8 块物理 A10G Real PG 运行。golden 路径可以用{execution_mode}占位符选择fake_pg/或real_pg/目录共享数值用例在两种模式下使用相同配置Fake PG golden 守卫的是 PyTorch FakeProcessGroup 的确定性合成数值契约并不校验远端 rank 数值或 EP 负载均衡Fake PG 下较大的梯度范数在该合成契约下仍可能是确定性的。非有限non-finite梯度不会被接受——训练会在优化器更新前停止。golden 能捕获对有限合成值的改动但不证明模拟梯度在数值上具有代表性golden 目录标识 PG 模式文件名标识模型与硬件档位而精确的并行计划记录在文件头中。例如 tests/assets/losses/fake_pg/llama3_a10g.txt 的文件头为# config: llama3_debugmodel_fsdp2_tp2_cp2 # ngpu: 8 # parallelism: FSDP2, TP2, CP2 # step loss grad_norm 1 3.742710590362549 847769.4375 ...其中# parallelism:这一行由 runner 在导出数值时自动插入_add_parallelism_header依据配置中的data_parallel_shard_degree、tensor_parallel_degree、context_parallel_degree、expert_parallel_degree、pipeline_parallel_degree生成摘要保证每个 golden 文件自描述其并行拓扑。Qwen3.5 MoE FSDP 4 x TP 2, EP 4没有数值 golden其 A10G Real PG 结果非按位确定性因此该用例只提供端到端覆盖DeepSeek V4 FSDP 2 x TP 2, EP 2 仅为端到端覆盖没有数值 golden。它只在真实进程组上运行use_real_pgTrue在 Fake PG 下其序列并行集合通信返回与输入别名alias的激活值会破坏 saved-for-backward 张量并使第 1 步的 grad_norm 爆炸同一配置在真实的 4 卡 PG 上训练正常。A10G 数值用例拓扑A10G 模型拓扑Fake-PG 与 Real-PGLlama 3FSDP 2 x TP 2 x CP 2Llama 3 SFTFSDP 2DeepSeek V3FSDP 8, EP 8DeepSeek V4FSDP 2 x TP 2, EP 2仅 Real-PGGPT-OSSFSDP 4 x TP 2, EP 4Qwen3FSDP 2 x TP 2 x CP 2, EP 8Muse Glimmer textFSDP 8Qwen3.5 MoE multimodalFSDP 4 x TP 2, EP 4Kimi K2.5 DistMuonFSDP 8, EP 8Kimi K2.5 DistMuon FSDPEP 与 Kimi K2.7 DistMuon PPFSDPEP 均在 A10G 上运行。由于 K2.5 多模态反向传播使用双三次上采样bicubic upsampling其 CUDA 反向没有确定性实现因此 FSDPEP 用例不携带数值 golden。手工对比时loss_compare.py可以用模型等价的 AdamW 配置创建仅模型的种子 checkpoint而被测运行继续保留 DistMuon对应OverrideDefinitions.loss_compare_seed_config字段。仅 Real-PG 的 CP / 流水线通信用例A10G 模型流水线并行拓扑DeepSeek V3FSDP 2 x CP 2 x PP 2, EP 4, Interleaved1F1BLlama 3FSDP 2 x TP 2 x PP 2, 1F1BGPT-OSSFSDP 2 x CP 2 x PP 2, EP 4, Interleaved1F1BKimi K2.7 DistMuonFSDP 2 x PP 2, EP 2, Interleaved1F1B单元测试目标模块功能CPU 与 GPU 需求通过tests/unit_tests/cpu/与tests/unit_tests/gpu/两个目录编码需要多块物理设备的 GPU 测试使用multi_gpupytest 标记1 GPU 通道选择not multi_gpu多卡通道选择multi_gpu两者取自同一 GPU 目录。运行测试前置条件确保已安装全部开发依赖pip install -r requirements-dev.txt pip install -r requirements.txt运行集成测试python -m tests.integration_tests.run_tests output_dir [--test_suite TEST_SUITE[,TEST_SUITE...]] [--execution_mode {fake_pg,real_pg}] [--test_scope {all,real_pg_required}] [--test_name TEST_NAME] [--ngpu NGPU]参数说明含 run_tests.py 中解析的全部选项output_dir必填存放测试输出的目录必须为空目录否则 runner 直接报错--test_suite可选逗号分隔的测试套件列表默认features可选值为features, models, h100, b200多套件时输出目录按套件名分子目录--execution_mode可选使用 Fake PG 或 Real PG 运行默认real_pgh100/b200套件仅支持real_pg--test_scope可选运行全部选定测试或仅use_real_pgTrue的测试默认allreal_pg_required要求--execution_mode real_pg--test_name可选按名称运行特定测试默认all--ngpu可选测试可用的 GPU 数量默认 8。Runner 用 GPU 池把各测试固定到互不相交的物理 GPU 子集上并发执行每个测试通过CUDA_VISIBLE_DEVICES/HIP_VISIBLE_DEVICES固定其分片--export-numerics可选对带golden_numerics_path的测试导出数值结果而不是与其 golden 文件比对--exclude可选逗号分隔的、需要跳过的测试名列表--gpu_arch_type可选cuda或rocm默认cudaROCm 上会跳过标记skip_rocm_test的用例--parallel/--no-parallel可选并发执行默认开启测试按最大需求优先装箱到 GPU 池任一时刻最多占用--ngpu块 GPU。每个测试为其每次运行run指定完整配置runner 把它们作为MODULE与CONFIG环境变量传给 run_train.sh。这些配置位于 torchtitan_recipes/tests/每个套件对应一个模块。要运行别的内容只需在那里添加一个配置再添加一个引用它的测试条目。示例# 运行全部功能集成测试features 是默认套件 python -m tests.integration_tests.run_tests test_output # 用 Fake PG 在 1 块物理 GPU 上运行完整 A10G 矩阵 python -m tests.integration_tests.run_tests test_output --test_suite features,models --execution_mode fake_pg --ngpu 1 # 用真实进程组运行完整 A10G 矩阵 python -m tests.integration_tests.run_tests test_output --test_suite features,models --execution_mode real_pg --ngpu 8 # 只运行显式要求真实进程组的用例 python -m tests.integration_tests.run_tests test_output --test_suite features,models --execution_mode real_pg --test_scope real_pg_required --ngpu 8 # 用真实进程组运行 H100 专属用例 python -m tests.integration_tests.run_tests test_output --test_suite h100 --execution_mode real_pg --ngpu 8 # 用真实进程组运行 B200 专属用例 python -m tests.integration_tests.run_tests test_output --test_suite b200 --execution_mode real_pg --ngpu 8运行单元测试# CPU 单元测试 pytest -s tests/unit_tests/cpu/ # 单卡 GPU 测试 pytest -s tests/unit_tests/gpu/ -m not multi_gpu # 多卡 GPU 测试 pytest -s tests/unit_tests/gpu/ -m multi_gpu运行指定测试文件与指定测试函数# 指定测试文件 pytest -s tests/unit_tests/cpu/test_config_manager.py # 指定测试函数 pytest -s tests/unit_tests/cpu/test_config_manager.py::TestConfigManager::test_cli_overrides源码深潜Runner 与测试工具测试条目OverrideDefinitions所有集成测试共用 tests/integration_tests/init.py 中的OverrideDefinitions数据类其关键字段包括configs每次运行一个Trainer.Config构建函数runner 通过其__module__/__name__设置MODULE/CONFIG环境变量override_args兼容旧式基础配置 覆盖参数形式的命令行片段保留给torchtitan/experiments下的套件ngpu逻辑 world sizeuse_real_pg是否需要真实通信语义golden_numerics_path数值 golden 路径可含{execution_mode}占位符并约束此类测试必须恰好定义一个配置loss_compare_seed_config供loss_compare.py单卡种子运行使用的模型等价配置当测试配置应用了并行 transform 时需要timeout、disabled、skip_rocm_test超时、禁用与 ROCm 跳过控制。以 features.py 中的full_checkpoint条目为例它依次引用保存与加载两个配置llama3_debugmodel_full_checkpoint_save/..._load并标记use_real_pgTrue——因为 checkpointing 属于 Fake PG 不兼容项这正是validate_fake_pg_compatibility强制要求的用法。数值校验流水线当测试设置了golden_numerics_path时run_tests.py 的run_single_test不会直接调用run_train.sh而是拼装一条scripts/loss_compare.py命令以同一配置的baseline与test双跑保证种子一致用--assert-equal断言 loss/grad_norm 与 golden 完全相等--export-numerics模式则改为--export-result写出新结果并由 runner 补写# parallelism:头行。Real PG 模式使用--baseline-ngpus/--test-ngpus与种子 checkpointFake PG 模式追加--no-seed-checkpoint走固定初始化。loss_compare.py的模块 docstringscripts/loss_compare.py给出了同一脚本的手工用法全集包括跨 commit 对比、--import-result基线模式与--seed-config种子配置。确定性哈希工具tests/utils.py 提供hash_model与hash_gradient两个函数用于跨运行对比模型状态/梯度以验证确定性训练对DTensor先调用to_local()再哈希天然适配 FSDP/TP 切分后的分布式参数分布式环境下仅 rank 0 计算哈希其余 rank 返回空字符串per_tensorTrue时返回张量名 → 十六进制哈希的 JSON 字典便于精确定位第一个发散张量默认对整个模型输出单一 sha256实现上使用t.numpy().tobytes()生成字节流按代码注释这是张量化为字节最快的方式。这些工具与 golden 数值文件、loss_compare.py的--assert-equal一起构成了 torchtitan 从单卡合成数值契约到8 卡真实通信逐位确定性的完整回归防线。小结torchtitan 的测试体系用三层防线保障一个 PyTorch 原生训练平台的正确性CPU/GPU 单元测试覆盖模块功能集成测试以Fake PG 单卡快速全覆盖 Real PG 八卡真实通信的双节奏保证 E2E 组合性数值测试则以 golden loss/grad_norm 曲线加上loss_compare.py的逐位断言对确定性回归形成守卫。其工程要点——测试清单与Trainer.Config分离存放、Fake PG 兼容性由代码强制校验、golden 文件自描述并行拓扑、测试输出目录强制为空——都值得在自建分布式训练项目的 CI 时参考。【免费下载链接】torchtitanA PyTorch native platform for training generative AI models项目地址: https://gitcode.com/GitHub_Trending/to/torchtitan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考