TorchTPU分布式训练完整指南:DDP、FSDP到8K芯片多Slice扩展实战
TorchTPU分布式训练完整指南:DDP、FSDP到8K芯片多Slice扩展实战
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 集合通信执行。
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,会打断编译图 | 存量代码可用,性能尚待优化 |
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。
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"+ 2DDeviceMesh)。把 FSDP 分片硬拉到 DCN 上会产生大量低带宽网络流量,是新手最常踩的坑。
六、新手避坑清单:6 条最佳实践
- 编译整个训练步:
torch.compile(backend="tpu")包住 forward + loss + backward,XLA 才能自动重叠通信与计算;至少也要编译这三者,只编译模型模块收益有限。 - 每个分片层加激活检查点:
torch.utils.checkpoint.checkpoint(..., use_reentrant=False),让 unsharded 权重在每层前向后立即释放,拿到真正的 ZeRO-3 内存行为。 - 分片维度能被 mesh 整除:手动 FSDP 是硬要求;SimpleFSDP 对过小的参数会自动退化为复制,也可用
shard_dim指定分片维。 - 每个 rank 用不同随机种子初始化分片权重:
torch.manual_seed(base_seed + dist.get_rank()),否则完整权重会变成同一随机块的重复拼接,损害收敛。 - 所有 rank 跑同一份程序:不要在
if rank == 0分支里放.item()等强制物化操作(SPMD 铁律)。 - 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!



