拓冰网站定制 
TorchTitan 开发指南构建测试流程、数值验证规范与代码风格约定【免费下载链接】torchtitanA PyTorch native platform for training generative AI models项目地址: https://gitcode.com/GitHub_Trending/to/torchtitan本文为 TorchTitanMeta 的 PyTorch 原生生成式模型训练平台贡献者与核心维护者的系统性开发指南。它以仓库根目录的 AGENTS.md 为主体结合 .pre-commit-config.yaml、scripts/loss_compare.py、torchtitan/config/configs.py 等源码逐一展开读完后可掌握 TorchTitan 的依赖安装与 Lint 流程、GPU 集成测试与性能测试的正确姿势、基于 bit-wise 一致的 loss 数值验证方法以及项目的核心工程原则与命名、置位、错误处理等代码风格细则。环境搭建与构建测试流程TorchTitan 要求PyTorch 原生的训练技术栈开发与测试流程也围绕这一点组织。仓库给出的标准命令为# 安装开发依赖 pip install -r requirements.txt -r requirements-dev.txt # Lint 与格式化任何 PR 之前必须执行 pre-commit run --all-files # 运行单元测试 pytest tests/ -x依赖清单本身可以印证原生 观测的定位requirements.txt 中包含grain、datasets、tensorboard、tyro、tokenizers、spmd_types、attn-gym[linear]以及一个 pin 到特定 commit 的torch_remat要求与 pyproject.toml 同步requirements-dev.txt 则补充了pytest7.3.2、pre-commit、pyrefly0.45.1、helion等开发期工具。Lint 到底检查什么pre-commit run --all-files的具体内容由 .pre-commit-config.yaml 定义包括基础卫生检查pre-commit-hookstrailing-whitespace、check-ast、check-merge-conflict、no-commit-to-branchmain 分支保护、check-added-large-files500 KB 上限、end-of-file-fixerLicense 头检查对所有.py文件自动插入 assets/license_header.txt 中的 BSD 风格许可头flake8配置在 .flake8附加插件flake8-bugbear、pep8-naming、torchfix、flake8-pep585、flake8-new-union-typesufmtblack22.12.0usort1.0.5负责代码格式与 import 排序pydoclint检查 docstring 与签名一致性配置读取自 pyproject.tomlcodespell拼写检查pyrefly-check类型检查--remove-unused-ignores --summarize-errors即开发依赖中固定版本的pyrefly0.45.1lychee-link-checker本地 hook对 Markdown 与 Python 文件中的链接做可达性检查仅在 404 时失败未安装 lychee 时降级为警告跳过。AGENTS.md 对 PR 的第一条期望即是先 Lint在请求评审前必须修复全部pre-commit run --all-files问题——CI 中的 Lint 失败会浪费所有人的时间。GPU 集成测试AGENTS.md 指出集成测试针对 Llama 3 debug 模型会覆盖默认配置具体定义见 tests/integration_tests/ 目录下的OverrideDefinitions。从源码结构看tests/integration_tests/features.py 与 tests/integration_tests/models.py 中通过OverrideDefinitions为不同 GPU 机型如 h100.py、b200.py声明各特性组合下的模型配置与训练参数覆盖。PR 时需注意验证 CI 确实运行了预期的测试配置检查--model.name等 flag——这正是 AGENTS.md 第 5 条 PR 期望中特别提醒的一点。性能测试至少 10 步AGENTS.md 对性能测试给出了一个容易被忽视的经验法则至少跑 10 个训练步如--training.steps 10以避免启动与 warmup 阶段主导测量结果。这是针对大张量并行训练平台的典型要求——首次迭代包含算子编译、通信建连、缓存分配等一次性开销。数值验证bit-wise 一致的 loss 与 grad_norm这是 AGENTS.md 中最具实战价值、也最容易被外部贡献者忽略的章节。其核心规则分两类非计算类改动激活检查点、重构等必须在前/后产生完全相同的 loss运行参数为--debug.seed42和--debug.deterministic计算类改动则要求在代表性数据集如 C4上展示 loss 收敛性。在相同的并行配置、GPU 配置与 debug 选项下两次运行应当产生 bit-wise 一致的 loss 与 grad_norm。但 stdout 只打印有效的前 5 位数字不足以判定是否一致因此仓库提供了 scripts/loss_compare.py 作为权威工具。loss_compare.py 的工作机制该脚本对比两个 git commit 或两种训练配置下的训练 loss其关键设计在源码中清晰可见固定的确定性选项scripts/loss_compare.py 中定义了FIXED_OPTIONS --debug.deterministic --debug.seed42 --metrics.enable_tensorboard --metrics.log_freq1即无论比较哪两边都会强制开启--debug.deterministic与--debug.seed42并开启 TensorBoard、每步记录一次指标从 TensorBoard 事件文件读取全精度值TB_TAGS 将loss映射到loss_metrics/global_avg_loss标量、grad_norm映射到grad_norm标量用EventAccumulator从事件文件解析——这解决了stdout 只有 5 位有效数字的问题seed checkpoint 默认开启通过--checkpoint.enable --checkpoint.export_dtypebfloat16 --checkpoint.load_only加载同一份初始权重保证不同并行度下初始权重一致可用--no-seed-checkpoint关闭以加速比较。这与 docs/debugging.md 中的Seed-Checkpoint-based Reproducibility一节一致因为 TorchTitan 中模型参数是先分片再各自初始化不同并行度下的初始化并不等价seed checkpoint 借助 DCP resharding 保证各运行加载同一权重CI 断言模式--assert-equal用于 CI 中验证两边 loss 完全相等不一致时以非零状态码退出配合--import-resultexpected_losses.txt可在只跑 baseline 的情况下与黄金结果文件比较--export-resultbaseline_losses.txt则可导出全精度 loss 供后续导入导出用repr()保留往返精度。常用命令形态摘自脚本 docstring# 1. 比较两个 commit 的默认配置 loss_compare.py main my_branch # 2. 指定配置与覆盖项 loss_compare.py main my_branch \ --baseline-configllama3_8b \ --baseline-options--parallelism.tensor_parallel_degree2 \ --output-foldermy_comparison # 5. 同一 commit 下比较不同并行配置 loss_compare.py . . \ --baseline-options--parallelism.dp1 \ --test-options--parallelism.dp2 # 6. CI 断言两边 loss 相等 loss_compare.py main my_branch --assert-equal # 7-8. baseline-only 模式与导入的黄金 loss 比较 loss_compare.py . . --assert-equal --import-resultexpected_losses.txt这些底层训练调用最终都走 run_train.sh它通过NGPU、MODULE、CONFIG环境变量控制进程数与模型模块默认NGPU8 MODULEllama3 CONFIGllama3_debugmodel正常模式下经torchrun拉起并支持COMM_MODEfake_backend无 GPU 干跑验证配置。为什么禁止使用 --debug.deterministic_warn_onlyAGENTS.md 以一句 You should NEVER use--debug.deterministic_warn_only 收尾。从源码看该选项定义在 DebugConfigdeterministic尽可能使用确定性算法可能更慢与deterministic_warn_only仅对无确定性实现的 op 告警而非报错。实际生效点在 torchtitan/distributed/utils.pyif debug_config.deterministic: torch.use_deterministic_algorithms( True, warn_onlydebug_config.deterministic_warn_only ) torch.backends.cudnn.deterministic True torch.backends.cudnn.benchmark False即deterministicTrue时强制 CUDA 全算子走确定性算法、关闭 cuDNN benchmarkwarn_onlyTrue只会对缺失确定性实现的算子打印警告而不中断——此时bit-wise 一致这一结论已不可信所以数值验证流程明确禁用该选项。仓库测试也固化了这一点tests/unit_tests/cpu/test_config_manager.py 验证 SDC replay 场景要求debug.deterministicTrue且deterministic_warn_onlyFalse否则抛出ValueErrortests/unit_tests/cpu/test_no_new_cli_options.py 中也将debug.deterministic_warn_only列入受控 CLI 选项名单。核心工程原则AGENTS.md 的 Core Principles 一节列出了 7 条开发哲学逐条对应到仓库结构可以看得更具体PyTorch 原生技术栈。核心训练基础设施与并行代码不得依赖非 PyTorch 库中大型复杂度的技术应进入对应上游仓库并行方案进 pytorch/pytorch数据加载进 pytorch/data。这解释了为何 requirements.txt 依赖极少且刻意 pin 了spmd_types、attn-gym这类小型官方生态组件。先查根因再打补丁。不落地创可贴式修复如果某个改动看似有效却无法解释原因要深挖。复用优先于重复。写新代码前先确认现有实现是否已覆盖跨模型统一相似代码路径而不是为每个模型写包装器若 torchao 或 PyTorch 上游已提供功能直接使用。实验不得污染核心。torchtitan/experiments/ 目录的存在就是为隔离实验代码不允许为实验需求修改核心文件例如不得在核心文件中添加if experiment_x:分支。废弃文件应当删除而非继续维护。仓库中 torchtitan/experiments/graph_trainer/、torchtitan/experiments/rl/、torchtitan/experiments/torchft/ 等各自独立成域正是该原则的体现。保护久经考验的代码路径。修改已收敛行为要谨慎标记出可能静默破坏现有用户代码或 checkpoint 的风险拿不准时先问。审计所有调用点。修改共享代码公共模型组件、config 字段、分布式工具时必须检查并更新所有调用点——包括全部模型变体。AGENTS.md 原文列举 llama3、llama4、qwen3、deepseek_v3、gpt_oss、flux对照当前 torchtitan/models/ 目录实际维护的模型族还包括 gpt_oss、kimi_k2_7、kimi_k3、muse_glimmer、qwen3_5、qwen3_6、deepseek_v4 等审计范围以仓库现状为准。不做投机性防御检查。不添加以防万一的检查、cast、回退或转换只显式校验契约、面向用户的配置以及失败后会静默或难以定位的不变量。代码风格细则Unicode新增注释与 docstring 仅限 ASCIIAGENTS.md 规定新增加或重写的注释、docstring 只能使用 ASCII 字符不得引入智能引号、em dash、箭头、非 ASCII 字母等 Unicode 字符应使用 ASCII 等价写法-表示右箭头、-表示左箭头、-表示双向箭头、--表示 em dash。已有注释中的既有 Unicode 保持不动规则仅约束你新增或重写的部分。命名规范名字必须准确、有描述性、反映真实作用域。生产代码中不得出现 toy/test/temp 之类字样——这类上下文放进 docstring。遵循上游惯例与 torchao、PyTorch 命名对齐。例如 torchao 叫Float8Linear本项目就用Float8Linear而不是Float8Config。计数用num_前缀如num_expert_groups而非n_expert_groups除非直接对齐上游 API。axis与dim严格分工。axis/axes指DeviceMesh上的一条具体轴TP 轴、dp_shard轴、某个 spec 引用的轴列表dim/dimensional用于描述 mesh 的形状1D mesh、multi-dimensional SPMD mesh以及张量维度裸dim单独出现时应指张量维度。例外是调用 PyTorch 上游 APIDeviceMesh.mesh_dim_names、DataParallelMeshDims等时调用点保持上游拼法值进入本项目代码后应赋给本地命名的mesh_axis_names。形状后缀张量命名。模型代码中张量带形状后缀Noam Shazeer 的 shape-suffixes 约定如x_BLD、q_BLHK、out_THV。大写后缀表示逻辑张量维度而非物理分片布局——routed_input_RD无论R在 EP/SP 下是否为本地分片后缀保持不变。字母按模块作用域生效而非全局每个使用后缀的模块在文件顶部注释给出字母图例且不要假设字母跨文件含义一致例如N在attention.py中是 num heads在moe.py中是 routed tokens。此规则适用于新写或重写的模型张量代码不要为补后缀而改动无关代码。代码放置代码放在最通用、适用的位置AGENTS.md 给出三级映射与模型无关的并行工具 - torchtitan/distributed/共享模型组件attention、MoE、embedding 等- torchtitan/models/common/模型专属代码 - 对应模型目录如 torchtitan/models/llama3/、torchtitan/models/qwen3/。反面原则同样被强调不要仅仅因为你最初在这里需要它就把与模型无关的功能塞进模型专属文件。断言与错误处理面向用户的错误配置错误、非法输入用ValueErrorassert只用于表示程序员错误的内部不变量分布式代码中总是显式校验 mesh 轴、张量 placement 与配置值——不得假设 1D mesh 或特定 placement当某条代码路径静默跳过了用户配置时必须发出 warning。参数与配置重要参数在前次要参数在后首个位置参数之后优先使用 keyword-only 参数必需配置字段不允许None默认值注意dataclasses.replace()是浅拷贝嵌套 dataclass 与 list/dict 字段按引用共享需要深拷贝时显式处理。注释与文档只为真正不明显的内容写注释维度语义、并行下的梯度 placement、workaround 存在的原因已知限制用 TODO 注释并附简要说明描述写进 docstring 而不是变量名。PR 期望AGENTS.md 最后给出 5 条 PR 验收标准先 Lint。跑pre-commit run --all-files并修复所有问题后再请求评审。给出数值证明。任何非平凡改动都要附 loss 对比——即前文所述的 scripts/loss_compare.py 流程与--debug.seed42 --debug.deterministic组合。描述中解释为什么而不仅是做了什么。补测试。新功能至少要 CPU 单元测试涉及并行时还需要 GPU 集成测试并核实 CI 确实执行了预期配置检查--model.name等 flag。保持模型代码最小化。模型改动后确认原始 checkpoint 仍能被正确加载并在文档中说明模型改动的原因。小结TorchTitan 的贡献规范可以概括为一条主线以 bit-wise 可复现的数值验证作为正确性判据以PyTorch 原生、实验隔离、调用点全审计作为工程纪律以 pre-commit 全量 Lint 与分层测试CPU 单元测试 GPU 集成测试作为流程护栏。对贡献者而言实操上最关键的三件工具是pre-commit run --all-files、pytest tests/ -x和loss_compare.py——任何改动在能回答loss 与 grad_norm 是否 bit-wise 一致或在 C4 上收敛之前都不应进入 PR 流程。【免费下载链接】torchtitanA PyTorch native platform for training generative AI models项目地址: https://gitcode.com/GitHub_Trending/to/torchtitan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TorchTitan 开发指南：构建测试流程、数值验证规范与代码风格约定
TorchTitan 开发指南构建测试流程、数值验证规范与代码风格约定【免费下载链接】torchtitanA PyTorch native platform for training generative AI models项目地址: https://gitcode.com/GitHub_Trending/to/torchtitan本文为 TorchTitanMeta 的 PyTorch 原生生成式模型训练平台贡献者与核心维护者的系统性开发指南。它以仓库根目录的 AGENTS.md 为主体结合 .pre-commit-config.yaml、scripts/loss_compare.py、torchtitan/config/configs.py 等源码逐一展开读完后可掌握 TorchTitan 的依赖安装与 Lint 流程、GPU 集成测试与性能测试的正确姿势、基于 bit-wise 一致的 loss 数值验证方法以及项目的核心工程原则与命名、置位、错误处理等代码风格细则。环境搭建与构建测试流程TorchTitan 要求PyTorch 原生的训练技术栈开发与测试流程也围绕这一点组织。仓库给出的标准命令为# 安装开发依赖 pip install -r requirements.txt -r requirements-dev.txt # Lint 与格式化任何 PR 之前必须执行 pre-commit run --all-files # 运行单元测试 pytest tests/ -x依赖清单本身可以印证原生 观测的定位requirements.txt 中包含grain、datasets、tensorboard、tyro、tokenizers、spmd_types、attn-gym[linear]以及一个 pin 到特定 commit 的torch_remat要求与 pyproject.toml 同步requirements-dev.txt 则补充了pytest7.3.2、pre-commit、pyrefly0.45.1、helion等开发期工具。Lint 到底检查什么pre-commit run --all-files的具体内容由 .pre-commit-config.yaml 定义包括基础卫生检查pre-commit-hookstrailing-whitespace、check-ast、check-merge-conflict、no-commit-to-branchmain 分支保护、check-added-large-files500 KB 上限、end-of-file-fixerLicense 头检查对所有.py文件自动插入 assets/license_header.txt 中的 BSD 风格许可头flake8配置在 .flake8附加插件flake8-bugbear、pep8-naming、torchfix、flake8-pep585、flake8-new-union-typesufmtblack22.12.0usort1.0.5负责代码格式与 import 排序pydoclint检查 docstring 与签名一致性配置读取自 pyproject.tomlcodespell拼写检查pyrefly-check类型检查--remove-unused-ignores --summarize-errors即开发依赖中固定版本的pyrefly0.45.1lychee-link-checker本地 hook对 Markdown 与 Python 文件中的链接做可达性检查仅在 404 时失败未安装 lychee 时降级为警告跳过。AGENTS.md 对 PR 的第一条期望即是先 Lint在请求评审前必须修复全部pre-commit run --all-files问题——CI 中的 Lint 失败会浪费所有人的时间。GPU 集成测试AGENTS.md 指出集成测试针对 Llama 3 debug 模型会覆盖默认配置具体定义见 tests/integration_tests/ 目录下的OverrideDefinitions。从源码结构看tests/integration_tests/features.py 与 tests/integration_tests/models.py 中通过OverrideDefinitions为不同 GPU 机型如 h100.py、b200.py声明各特性组合下的模型配置与训练参数覆盖。PR 时需注意验证 CI 确实运行了预期的测试配置检查--model.name等 flag——这正是 AGENTS.md 第 5 条 PR 期望中特别提醒的一点。性能测试至少 10 步AGENTS.md 对性能测试给出了一个容易被忽视的经验法则至少跑 10 个训练步如--training.steps 10以避免启动与 warmup 阶段主导测量结果。这是针对大张量并行训练平台的典型要求——首次迭代包含算子编译、通信建连、缓存分配等一次性开销。数值验证bit-wise 一致的 loss 与 grad_norm这是 AGENTS.md 中最具实战价值、也最容易被外部贡献者忽略的章节。其核心规则分两类非计算类改动激活检查点、重构等必须在前/后产生完全相同的 loss运行参数为--debug.seed42和--debug.deterministic计算类改动则要求在代表性数据集如 C4上展示 loss 收敛性。在相同的并行配置、GPU 配置与 debug 选项下两次运行应当产生 bit-wise 一致的 loss 与 grad_norm。但 stdout 只打印有效的前 5 位数字不足以判定是否一致因此仓库提供了 scripts/loss_compare.py 作为权威工具。loss_compare.py 的工作机制该脚本对比两个 git commit 或两种训练配置下的训练 loss其关键设计在源码中清晰可见固定的确定性选项scripts/loss_compare.py 中定义了FIXED_OPTIONS --debug.deterministic --debug.seed42 --metrics.enable_tensorboard --metrics.log_freq1即无论比较哪两边都会强制开启--debug.deterministic与--debug.seed42并开启 TensorBoard、每步记录一次指标从 TensorBoard 事件文件读取全精度值TB_TAGS 将loss映射到loss_metrics/global_avg_loss标量、grad_norm映射到grad_norm标量用EventAccumulator从事件文件解析——这解决了stdout 只有 5 位有效数字的问题seed checkpoint 默认开启通过--checkpoint.enable --checkpoint.export_dtypebfloat16 --checkpoint.load_only加载同一份初始权重保证不同并行度下初始权重一致可用--no-seed-checkpoint关闭以加速比较。这与 docs/debugging.md 中的Seed-Checkpoint-based Reproducibility一节一致因为 TorchTitan 中模型参数是先分片再各自初始化不同并行度下的初始化并不等价seed checkpoint 借助 DCP resharding 保证各运行加载同一权重CI 断言模式--assert-equal用于 CI 中验证两边 loss 完全相等不一致时以非零状态码退出配合--import-resultexpected_losses.txt可在只跑 baseline 的情况下与黄金结果文件比较--export-resultbaseline_losses.txt则可导出全精度 loss 供后续导入导出用repr()保留往返精度。常用命令形态摘自脚本 docstring# 1. 比较两个 commit 的默认配置 loss_compare.py main my_branch # 2. 指定配置与覆盖项 loss_compare.py main my_branch \ --baseline-configllama3_8b \ --baseline-options--parallelism.tensor_parallel_degree2 \ --output-foldermy_comparison # 5. 同一 commit 下比较不同并行配置 loss_compare.py . . \ --baseline-options--parallelism.dp1 \ --test-options--parallelism.dp2 # 6. CI 断言两边 loss 相等 loss_compare.py main my_branch --assert-equal # 7-8. baseline-only 模式与导入的黄金 loss 比较 loss_compare.py . . --assert-equal --import-resultexpected_losses.txt这些底层训练调用最终都走 run_train.sh它通过NGPU、MODULE、CONFIG环境变量控制进程数与模型模块默认NGPU8 MODULEllama3 CONFIGllama3_debugmodel正常模式下经torchrun拉起并支持COMM_MODEfake_backend无 GPU 干跑验证配置。为什么禁止使用 --debug.deterministic_warn_onlyAGENTS.md 以一句 You should NEVER use--debug.deterministic_warn_only 收尾。从源码看该选项定义在 DebugConfigdeterministic尽可能使用确定性算法可能更慢与deterministic_warn_only仅对无确定性实现的 op 告警而非报错。实际生效点在 torchtitan/distributed/utils.pyif debug_config.deterministic: torch.use_deterministic_algorithms( True, warn_onlydebug_config.deterministic_warn_only ) torch.backends.cudnn.deterministic True torch.backends.cudnn.benchmark False即deterministicTrue时强制 CUDA 全算子走确定性算法、关闭 cuDNN benchmarkwarn_onlyTrue只会对缺失确定性实现的算子打印警告而不中断——此时bit-wise 一致这一结论已不可信所以数值验证流程明确禁用该选项。仓库测试也固化了这一点tests/unit_tests/cpu/test_config_manager.py 验证 SDC replay 场景要求debug.deterministicTrue且deterministic_warn_onlyFalse否则抛出ValueErrortests/unit_tests/cpu/test_no_new_cli_options.py 中也将debug.deterministic_warn_only列入受控 CLI 选项名单。核心工程原则AGENTS.md 的 Core Principles 一节列出了 7 条开发哲学逐条对应到仓库结构可以看得更具体PyTorch 原生技术栈。核心训练基础设施与并行代码不得依赖非 PyTorch 库中大型复杂度的技术应进入对应上游仓库并行方案进 pytorch/pytorch数据加载进 pytorch/data。这解释了为何 requirements.txt 依赖极少且刻意 pin 了spmd_types、attn-gym这类小型官方生态组件。先查根因再打补丁。不落地创可贴式修复如果某个改动看似有效却无法解释原因要深挖。复用优先于重复。写新代码前先确认现有实现是否已覆盖跨模型统一相似代码路径而不是为每个模型写包装器若 torchao 或 PyTorch 上游已提供功能直接使用。实验不得污染核心。torchtitan/experiments/ 目录的存在就是为隔离实验代码不允许为实验需求修改核心文件例如不得在核心文件中添加if experiment_x:分支。废弃文件应当删除而非继续维护。仓库中 torchtitan/experiments/graph_trainer/、torchtitan/experiments/rl/、torchtitan/experiments/torchft/ 等各自独立成域正是该原则的体现。保护久经考验的代码路径。修改已收敛行为要谨慎标记出可能静默破坏现有用户代码或 checkpoint 的风险拿不准时先问。审计所有调用点。修改共享代码公共模型组件、config 字段、分布式工具时必须检查并更新所有调用点——包括全部模型变体。AGENTS.md 原文列举 llama3、llama4、qwen3、deepseek_v3、gpt_oss、flux对照当前 torchtitan/models/ 目录实际维护的模型族还包括 gpt_oss、kimi_k2_7、kimi_k3、muse_glimmer、qwen3_5、qwen3_6、deepseek_v4 等审计范围以仓库现状为准。不做投机性防御检查。不添加以防万一的检查、cast、回退或转换只显式校验契约、面向用户的配置以及失败后会静默或难以定位的不变量。代码风格细则Unicode新增注释与 docstring 仅限 ASCIIAGENTS.md 规定新增加或重写的注释、docstring 只能使用 ASCII 字符不得引入智能引号、em dash、箭头、非 ASCII 字母等 Unicode 字符应使用 ASCII 等价写法-表示右箭头、-表示左箭头、-表示双向箭头、--表示 em dash。已有注释中的既有 Unicode 保持不动规则仅约束你新增或重写的部分。命名规范名字必须准确、有描述性、反映真实作用域。生产代码中不得出现 toy/test/temp 之类字样——这类上下文放进 docstring。遵循上游惯例与 torchao、PyTorch 命名对齐。例如 torchao 叫Float8Linear本项目就用Float8Linear而不是Float8Config。计数用num_前缀如num_expert_groups而非n_expert_groups除非直接对齐上游 API。axis与dim严格分工。axis/axes指DeviceMesh上的一条具体轴TP 轴、dp_shard轴、某个 spec 引用的轴列表dim/dimensional用于描述 mesh 的形状1D mesh、multi-dimensional SPMD mesh以及张量维度裸dim单独出现时应指张量维度。例外是调用 PyTorch 上游 APIDeviceMesh.mesh_dim_names、DataParallelMeshDims等时调用点保持上游拼法值进入本项目代码后应赋给本地命名的mesh_axis_names。形状后缀张量命名。模型代码中张量带形状后缀Noam Shazeer 的 shape-suffixes 约定如x_BLD、q_BLHK、out_THV。大写后缀表示逻辑张量维度而非物理分片布局——routed_input_RD无论R在 EP/SP 下是否为本地分片后缀保持不变。字母按模块作用域生效而非全局每个使用后缀的模块在文件顶部注释给出字母图例且不要假设字母跨文件含义一致例如N在attention.py中是 num heads在moe.py中是 routed tokens。此规则适用于新写或重写的模型张量代码不要为补后缀而改动无关代码。代码放置代码放在最通用、适用的位置AGENTS.md 给出三级映射与模型无关的并行工具 - torchtitan/distributed/共享模型组件attention、MoE、embedding 等- torchtitan/models/common/模型专属代码 - 对应模型目录如 torchtitan/models/llama3/、torchtitan/models/qwen3/。反面原则同样被强调不要仅仅因为你最初在这里需要它就把与模型无关的功能塞进模型专属文件。断言与错误处理面向用户的错误配置错误、非法输入用ValueErrorassert只用于表示程序员错误的内部不变量分布式代码中总是显式校验 mesh 轴、张量 placement 与配置值——不得假设 1D mesh 或特定 placement当某条代码路径静默跳过了用户配置时必须发出 warning。参数与配置重要参数在前次要参数在后首个位置参数之后优先使用 keyword-only 参数必需配置字段不允许None默认值注意dataclasses.replace()是浅拷贝嵌套 dataclass 与 list/dict 字段按引用共享需要深拷贝时显式处理。注释与文档只为真正不明显的内容写注释维度语义、并行下的梯度 placement、workaround 存在的原因已知限制用 TODO 注释并附简要说明描述写进 docstring 而不是变量名。PR 期望AGENTS.md 最后给出 5 条 PR 验收标准先 Lint。跑pre-commit run --all-files并修复所有问题后再请求评审。给出数值证明。任何非平凡改动都要附 loss 对比——即前文所述的 scripts/loss_compare.py 流程与--debug.seed42 --debug.deterministic组合。描述中解释为什么而不仅是做了什么。补测试。新功能至少要 CPU 单元测试涉及并行时还需要 GPU 集成测试并核实 CI 确实执行了预期配置检查--model.name等 flag。保持模型代码最小化。模型改动后确认原始 checkpoint 仍能被正确加载并在文档中说明模型改动的原因。小结TorchTitan 的贡献规范可以概括为一条主线以 bit-wise 可复现的数值验证作为正确性判据以PyTorch 原生、实验隔离、调用点全审计作为工程纪律以 pre-commit 全量 Lint 与分层测试CPU 单元测试 GPU 集成测试作为流程护栏。对贡献者而言实操上最关键的三件工具是pre-commit run --all-files、pytest tests/ -x和loss_compare.py——任何改动在能回答loss 与 grad_norm 是否 bit-wise 一致或在 C4 上收敛之前都不应进入 PR 流程。【免费下载链接】torchtitanA PyTorch native platform for training generative AI models项目地址: https://gitcode.com/GitHub_Trending/to/torchtitan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考