TorchTPU分布式训练完整指南:DDP、FSDP到8K芯片多Slice扩展实战

原创2026-11-01 15:22:191,870 阅读

TorchTPU分布式训练完整指南:DDP、FSDP到8K芯片多Slice扩展实战

TorchTPU 分布式训练项目横幅:原生 PyTorch TPU 后端

TorchTPU 是 PyTorch 团队与 Google 联合打造的 TPU 原生 PyTorch 后端,支持在 Google Cloud TPU 上运行分布式训练——你只需把 device="cuda" 改成 device="tpu"、把 backend="nccl" 换成 backend="tpu_dist",现有的 DDP、FSDP、DTensor 代码就能直接跑,并可通过 torch.compile(backend="tpu") 从单芯片一路扩展到 8K 芯片的多 Slice(multi-slice) 集群。本文面向新手,手把手带你走通 TorchTPU 分布式训练的每一步:从环境初始化、DDP 入门、SimpleFSDP 实战,到多主机 8K 芯片集群扩展的最佳实践。


一、TPU 分布式为什么和 GPU 不一样?

在 GPU 上,torchrun 拉起的每个进程都能看到全部显卡,各自用 cuda:{local_rank} 认领一块。TPU 的架构完全不同:

对比维度 GPU TPU(TorchTPU)
设备可见性 每进程可枚举全部 GPU 每个 worker 只绑定一块 TPU 设备
通信库 NCCL 等独立通信运行时 无独立通信库,集合通信直接编译成 StableHLO
启动前提 无需额外信息 必须先声明 Slice 拓扑(TORCH_TPU_TOPOLOGY)
执行模型 每进程独立程序 编译器按 SPMD(单程序多数据)编译

具体来说,TorchTPU 在 torch.distributed 的 ProcessGroup 层(c10d::Backend)实现了 tpu_dist 后端:all_reduce、all_gather、reduce_scatter、all_to_all 这些集合操作会被直接降级成 StableHLO 集合算子,由 XLA 编译器编译进 TPU 可执行文件,天然享受编译器级的通信-计算重叠优化。详见 docs/distributed_support.md。

💡 关键心智模型:TPU 上"所有 rank 运行完全相同的程序"(SPMD)是硬约束。如果不同 rank 编译出不同的计算图(比如 if rank == 0: 分支里插入了不同的算子),会导致死锁或内存错乱——这正是后面所有最佳实践的根源。


二、分布式初始化:从环境变量到 torchrun 一键启动

TorchTPU 的初始化流程分为四步:Launcher 拉起进程 → init_process_group("tpu_dist") → C++ ProcessGroup 建立 Rank-to-Device 映射 → DDP/FSDP/DTensor 集合通信执行。

TorchTPU 分布式训练初始化流程图:从 torchrun 启动到 DDP/FSDP 集合通信

2.1 必须设置的两个环境变量

环境变量 含义 示例值
TORCH_TPU_TOPOLOGY TPU Slice 的物理网格几何 "2,2,1"、"4,4,4"
TORCH_TPU_SLICEBUILDER_ADDRESSES 构建 ICI 网格的 host:port 地址(每设备一个) "localhost:8471,..."

好消息是:单机和 GKE 场景下这两个值可以自动探测。在启动 torchrun 之前执行一行命令即可:

eval $(python3 -m torch.tpu.distributed | sed 's/^/export /')
torchrun --nproc_per_node=$WORLD_SIZE train.py

它会自动导出 TORCH_TPU_TOPOLOGY、TORCH_TPU_SLICEBUILDER_ADDRESSES、WORLD_SIZE、NODE_RANK 等全套变量。如果你从 Python 父进程拉起 worker(例如 elastic_launch),可以调用 torch.tpu.distributed.set_tpu_launch_env(),效果相同,且不会覆盖你手动设置过的值。

2.2 Worker 端最小示例

每个 worker 进程内的代码就是"标准 PyTorch 分布式写法 + 换后端名":

import torch
import torch.distributed as dist

dist.init_process_group(backend="tpu_dist")   # GPU 上是 "nccl"
device = torch.device("tpu")                 # GPU 上是 "cuda"

x = torch.ones(4, 4, device=device) * (dist.get_rank() + 1)
dist.all_reduce(x, op=dist.ReduceOp.SUM)     # 标准集合通信,直接可用

dist.destroy_process_group()

就这么简单——TorchTPU 保持了 torch.distributed 的完整语义,DDP、FSDP、DTensor 这些上层框架全部开箱即用。


三、DDP 实战:最简单的分布式训练

DDP(DistributedDataParallel)是最经典的方案:每个 rank 持有完整模型副本,只在反向传播后对梯度做一次 all_reduce。对于模型能塞进单块 TPU HBM 的场景,这是首选。

TorchTPU 对 DDP 的支持分三档,性能逐档提升:

模式 配置方式 行为 适用场景
Skinny collectives(默认) 无需配置 每个集合通信单独编译成独立模块 通用、MPMD 安全,但通信无法与计算重叠
@spmd_safe 融合 @torch.tpu.distributed.spmd_safe 装饰器 取消集合通信周围的图断点,计算与通信融为单一模块 确定是严格 SPMD 的训练步
Compilation Handshake TORCH_TPU_SPMD_HANDSHAKE_STAGE=COMPILE_STAGE 自动校验各 rank 计算图一致后融合集合通信 不想手动标注 torch.compile 用户

当你确信训练步在所有 rank 上执行完全相同的算子序列时,用 @spmd_safe 让 XLA 把异步通信和矩阵计算重叠调度,DDP 的梯度同步几乎"免费":

@torch.compile
@torch.tpu.distributed.spmd_safe
def train_step(x, weight):
    out = x @ weight
    dist.all_reduce(out, op=dist.ReduceOp.AVG)
    return torch.nn.functional.silu(out)

⚠️ 注意:只对严格 SPMD 的代码使用 @spmd_safe;含 rank 条件分支的代码误用会导致死锁。拿不准时改用 TORCH_TPU_SPMD_HANDSHAKE_STAGE=COMPILE_STAGE 让编译器替你检查。相关实现在 src/torch_tpu/_internal/distributed/spmd_util.py 和 src/torch_tpu/_internal/distributed/handshake.py。


四、FSDP 实战:大模型训练的主流选择

模型超过单卡 HBM 时,就需要 FSDP(Fully Sharded Data Parallel):把参数、梯度、优化器状态分片到各 rank,前向用 all-gather 临时拼回完整权重,反向用 reduce-scatter 合并并重新分片梯度。

TorchTPU 上选择 FSDP 方案的核心原则是:能否与整图编译配合。

方案 特点 建议
SimpleFSDP(simple_fsdp.data_parallel) 编译优先设计,无运行时 hook,整步编译成单一 XLA 程序 ✅ 推荐默认
Manual FSDP(手动集合通信) 通信代码直接写在模型定义旁,便于极致调优 你掌控模型代码且需要深度调优
FSDPv2(fully_shard) 依赖 Python hook,会打断编译图 存量代码可用,性能尚待优化

TorchTPU FLUX 模型零拷贝优化:消除冗余内存拷贝的性能加速图

4.1 SimpleFSDP:一次调用完成分片

SimpleFSDP 最初来自 TorchTitan,TorchTPU 在 examples/fsdp/simple_fsdp.py 内置了自包含实现。它的原理非常优雅:参数以分片的 DTensor 存储,访问参数时通过 parametrization 自动 all-gather,其 autograd 反向天然就是 reduce-scatter——没有 hook,就没有图断点。

四步走:

# 1. 初始化 DeviceMesh
dist.init_process_group(backend="tpu_dist")
mesh = dt.init_device_mesh("tpu", (world_size,), mesh_dim_names=("fsdp",))

# 2. 每个含参数的子层套激活检查点(关键!释放 unsharded 权重)
for layer in model.children():
    if list(layer.parameters()):
        layer.forward = functools.partial(
            checkpoint_utils.checkpoint, layer.forward, use_reentrant=False)

# 3. 一次调用完成整个模型分片
model = simple_fsdp.data_parallel(model, device_mesh=mesh, mode="fully_shard")

# 4. 编译训练步;注意 SimpleFSDP 默认 sum 归约,loss 要除以 world_size
compiled_model = torch.compile(model, backend="tpu")

支持三种模式:"replicate"(即 DDP)、"fully_shard"(FSDP)、"hybrid_shard"(HSDP,2D mesh 上分片+副本混合)。完整教程和 FSDPv2 → SimpleFSDP 迁移指南见 examples/fsdp/fsdp_to_simple_fsdp/fsdp_to_simple_fsdp.md。

4.2 真实案例:Muse Glimmer 30B 训练

仓库内置了一个纯 PyTorch、零自定义 kernel 的 30B LLM 完整训练循环示例(examples/muse_glimmer_30b/pure_pytorch_fsdp_trainloop/),在 4 块 Ironwood TPU(8 TensorCore)上跑 FSDP + torch.compile + 激活检查点,实测 约 2400~2800 TPS/rank(合计 19k~22k TPS,序列长度 5120)。更妙的是:模型代码 model_fsdp.py 完全不绑定设备,TPU 和 GPU 通用——所有 TPU 特定逻辑只集中在 launcher.py 的三行代码里。案例分析见 docs/case_studies_muse_glimmer_30b_training.md。

TorchTPU FLUX 优化第三阶段:torch.compile 编译后的执行 trace 图

4.3 可直接运行的示例速查

示例 启动命令 验证内容
examples/fsdp/fsdp_to_simple_fsdp/ ./run_fsdp_to_simple_fsdp.sh 编译后 FSDPv2 与 SimpleFSDP 损失/预测一致 + 步耗时
examples/fsdp/manual/ ./launch.sh 手动 FSDP 梯度与单卡 CPU 参考一致
examples/tensor_parallel/dtensor_wrapped/ bash ./launch.sh DTensor 声明式张量并行数值校验
examples/muse_glimmer_30b/pure_pytorch_fsdp_trainloop/ kubectl apply -f batchv1_job.yaml 30B 模型完整 FSDP 训练循环

五、多 Slice 扩展:走向 8K 芯片集群

单机 8 设备只是起点。TPU 的扩展路径是:Slice 内走 ICI(片间高速互连,环状/扭环拓扑,带宽数十到数百 GB/s),跨 Slice 走 DCN(数据中心以太网,带宽低、延迟高)。

5.1 并行维度如何摆放?

TorchTPU 提供了 torch.tpu.distributed.topology_aware_mesh(),按物理 ICI 环自动计算最优 rank 布局。摆放原则:通信最频繁的维度放内层(最快的 ICI 环),最不频繁的放外层(跨 Slice 的 DCN):

并行类型 典型集合通信 推荐物理位置
张量并行 TP all_reduce/reduce_scatter(每层都触发) 最快本地 ICI 环(同托盘连续设备)
序列并行 CP/SP all_to_all(Ring Attention) 本地 ICI 轴(Slice 内)
FSDP all_gather + reduce_scatter ICI 轴(Slice 内)
数据并行 DP all_reduce(每步仅一次,只有梯度) 最外层 / DCN 跨 Slice

多 Slice(DCN + ICI 混合)场景下,topology_aware_mesh() 会自动探测 Slice 边界:把最外层非平凡维度(通常是 DP)映射到 DCN 跨 Slice,内层维度放在 Slice 内的 ICI 上——无需手动指定 dcn_mesh_shape。

5.2 GKE 上的多主机 JobSet

仓库提供了 64 芯片 / 128 设备(16 台主机)的完整 GKE 示例 examples/tensor_parallel/torchtpu_multihost_slice_jobset.yaml:Kubernetes JobSet 每主机一个 Pod,启动脚本 launch_multihost.sh 根据主机在 Slice 中的位置自动推导 rank。提交方式与单机版完全一致:

sed -i "s|<DOCKER_IMAGE>|${DOCKER_IMAGE}|g; s|<NODEPOOL_NAME>|${NODEPOOL_NAME}|g" \
    examples/tensor_parallel/torchtpu_multihost_slice_jobset.yaml
kubectl apply -f examples/tensor_parallel/torchtpu_multihost_slice_jobset.yaml
kubectl get jobset,pods -n default

5.3 8K 芯片的成熟度

根据 docs/feature_set.md,"Multi-slice up to 8K chip" 已列入 Validated(已验证)能力,端到端持续测试覆盖;生产就绪方案中"Fine-tuning(up to ~8K chips)"同样已验证。路线图显示,>8K 芯片的超大规模训练、FSDPv2 性能优化、MPMD 高性能支持属于下一阶段(Near-term / Future)重点。

5.4 跨 Slice 扩展的黄金法则

跨 Slice 走 DCN 时,几乎总是应该跨 Slice 做数据并行(副本复制)、Slice 内做 FSDP 分片——即 HSDP(mode="hybrid_shard" + 2D DeviceMesh)。把 FSDP 分片硬拉到 DCN 上会产生大量低带宽网络流量,是新手最常踩的坑。


六、新手避坑清单:6 条最佳实践

  1. 编译整个训练步:torch.compile(backend="tpu") 包住 forward + loss + backward,XLA 才能自动重叠通信与计算;至少也要编译这三者,只编译模型模块收益有限。
  2. 每个分片层加激活检查点:torch.utils.checkpoint.checkpoint(..., use_reentrant=False),让 unsharded 权重在每层前向后立即释放,拿到真正的 ZeRO-3 内存行为。
  3. 分片维度能被 mesh 整除:手动 FSDP 是硬要求;SimpleFSDP 对过小的参数会自动退化为复制,也可用 shard_dim 指定分片维。
  4. 每个 rank 用不同随机种子初始化分片权重:torch.manual_seed(base_seed + dist.get_rank()),否则完整权重会变成同一随机块的重复拼接,损害收敛。
  5. 所有 rank 跑同一份程序:不要在 if rank == 0 分支里放 .item() 等强制物化操作(SPMD 铁律)。
  6. Scale up 前先验算子和内存:用 assert_close 对比未分片参考实现的数值,测量跨前反向边界的内存留存;仓库内置了 fsdp_to_simple_fsdp_worker.py 的算子校验和 manual_fsdp_memory_test.py 内存测试。

七、核心资料速查

资料 路径
分布式支持官方文档 docs/distributed_support.md
FSDP 最佳实践指南 docs/case_studies_fsdp.md
GKE 多主机部署教程 docs/get_started_on_gke.md
功能集与路线图(8K 芯片验证状态) docs/feature_set.md
Muse Glimmer 30B 训练案例 docs/case_studies_muse_glimmer_30b_training.md
SimpleFSDP 自包含实现 examples/fsdp/simple_fsdp.py
分布式模块源码 src/torch_tpu/_internal/distributed/
多主机 JobSet 清单 examples/tensor_parallel/torchtpu_multihost_slice_jobset.yaml

从一行 init_process_group(backend="tpu_dist") 起步,到 @spmd_safe 通信融合调优,再到 8K 芯片多 Slice 集群——TorchTPU 让你在不改动 PyTorch 心智模型的前提下,把分布式训练的性能潜力完整释放到 TPU 硬件上。现在就可以从 examples/simple_pytorch/ 的单设备示例开始,按本文路径一步步 scale up!

登录后查看全文
torch_tpu