JAX 分片实战:Mesh、PartitionSpec 与三种分片模式
同一台 8 卡机器,同一份参数量,换个人写就可能是「每张卡都存全量参数」而不是「每张卡存 1/8」。JAX 的分片不是靠"设定一个并行策略对象"完成的,而是靠数组的分片属性加编译器传播完成的:你写的是全局视角的计算,编译器负责把它切成每设备的小程序。理解这一点,才能解释三类完全不同的报错——静默变复制、trace 阶段报错、以及运行结果对不上。
本文只讲工程语义,不做框架优劣判断:三种分片模式的原文对照、Mesh 与 PartitionSpec 的四种写法、device_put 造成的 committed 冲突、jax.distributed.initialize 的参数默认值,最后给一张与 PyTorch 的结构对照表和一份自检清单。
1. 先分清三种分片模式
JAX 官方把这套能力拆成三种风格,差异可以压成一张表(原文见 explicit sharding 教程的模式对照):
| 模式 | 你写的视图 | 分片是否显式 | 集合通信是否显式 |
|---|---|---|---|
| Auto(自动分片) | 全局视图 | 否 | 否 |
| Explicit(分片进类型) | 全局视图 | 是 | 否 |
Manual(shard_map) | 单设备视图 | 是 | 是 |
工程上真正要记住的是分片的事实来源不同,出错时的表现也不同:
- Auto:编译器决定一切。写错不会有异常,只会出现"某轴被复制"或"多了一次 all-gather",代价体现在带宽和显存上,不在报错里。
- Explicit:分片写在类型里(trace 时可查询)。推导不出来的算子会在 trace 阶段直接报错,要求你给
out_sharding。 - Manual:你以单设备视角手写分片和集合通信。
out_specs承诺与实际不符时由check_rep抓住。
2. Mesh:把设备排成有名字的网格
import jax
from jax.sharding import PartitionSpec as P, NamedSharding
mesh = jax.make_mesh((4, 2), ('x', 'y'))
sharding = NamedSharding(mesh, P('x', 'y'))
arr = jax.device_put(data, sharding)三个要点:
make_mesh会依据硬件拓扑挑选更优的设备顺序(官方原文:takes hardware topology into account for theDeviceorder)。直接Mesh(devices, axis_names)也能建,但官方建议用make_mesh。- 轴名(上例的
'x'、'y')是后面所有PartitionSpec的词汇表。轴名写错或漏写不会有 Python 报错,只会静默变成复制。 - 可以逐轴指定分片模式:
jax.make_mesh(shape, names, axis_types=(AxisType.Auto, AxisType.Auto))。官方 explicit 教程示例里显式传这一参数,说明它决定该轴走哪种模式,需要时应当写明而不是靠默认。
配套还有一个作用域写法,省掉反复传 mesh:
with jax.set_mesh(mesh):
... # 作用域内可以直接用 P(...) 构造分片3. PartitionSpec 的四种写法与一个沉默成本
官方教程里把写法讲得很清楚,逐条对应到工程语言:
| 写法 | 含义 | 常见误用 |
|---|---|---|
P('a', 'b') | 第 0 维沿 a 切、第 1 维沿 b 切 | 维度数与数组秩不匹配 |
P('a', None) | 第 0 维沿 a 切,第 1 维不切 | 以为 None 是"不参与",其实是占位 |
P() | 完全复制 | 漏写导致全量复制 |
P(('a', 'b'), None) | 一个逻辑轴跨两个网格轴切 | 在二维网格上误以为只能二选一 |
两条原文规则值得单独记住:
None是占位符,不是"不限"。P('a', None)表示第二维不切;而网格轴'b'因为这个 spec 没提到它,结果是沿'b'复制。- 尾部
None可以省略:P('a', None)等价于P('a')。
沉默成本就在这里:在 (4, 2) 网格上用 P('x'),数据会在 y 方向复制 2 份。参数量不变时,显存占用和集合通信量都可能翻倍,而代码不会报任何错。这也是排查"为什么我的 JAX 训练显存比预算多一倍"时第一个要查的地方。
4. committed 与 uncommitted:一个 ValueError 的根因
JAX 把数组分成两类状态,这条规则解释了大量"加了一行 device_put 就崩"的现场:
- 用
jax.device_put显式放置/分片的数组是 committed,不会被自动搬到别的设备上; jnp.zeros、jnp.arange、jnp.array这类产出的数组是 uncommitted,可以被自动重分片去迁就别的参数。
于是这段代码会直接抛 ValueError:
sharding1 = NamedSharding(Mesh(jax.devices()[:4], 'x'), P('x'))
sharding2 = NamedSharding(Mesh(jax.devices()[4:], 'x'), P('x'))
y = jax.device_put(x, sharding1)
z = jax.device_put(x, sharding2)
y + z # ValueError: 两个 committed 分片互不相容排查口径:看到分片不兼容报错,先找"两个显式 device_put 的结果直接参与同一运算"的情况;如果一个操作数是 jnp 现算的,它不 committed,JAX 会自己搬,不会报错。
5. Auto 模式:computation follows sharding
Auto 模式的核心一句话:计算跟随数据分片。在 jit 里,编译器不会把分片数组拷回单设备,而是按输入的分片决定中间值和输出的分片,必要时自己插入通信,并据此并行化求值。
这意味着两件事:
- 你只需要关心数学,分片由编译器推导——但代价是不可预期。全程序优化(GSPMD)意味着局部改一行,整张图的分片决策都可能变。
- 给提示的手法是
jax.lax.with_sharding_constraint,它只是约束/提示,不是命令:
@jax.jit
def f(x):
x = x + 1
y = jax.lax.with_sharding_constraint(x, NamedSharding(mesh, P('y', 'x')))
return y官方明确建议:至少给计算的输出加注解,依据是这个值下游怎么被消费。因为输出分片一旦是错的,后面每一步都在为它付通信代价。
Auto 模式的真实工作流是"加注解 → 看编译器选了什么 → 再加注解",这是个慢循环。下一节的 Explicit 模式就是为终结这个循环而设计的。
6. Explicit 模式:分片进入类型,trace 时就能断言
Explicit 模式的差别只有一句:每个数组的分片是它 JAX 层类型的一部分,在 trace 阶段就能查询。
print(jax.typeof(x)) # float32[4@X,4@Y]:类型里直接写着沿 X 切 4 份、沿 Y 切 4 份
mesh_types = jax.sharding.get_abstract_mesh() # 查当前 mesh 与各轴模式配套的分片规则是逐算子定义的(以下为官方教程原文的规则归纳):
| 算子类别 | 输出分片规则 |
|---|---|
nullary(jnp.zeros、jnp.arange) | 默认不分片,除非用 out_sharding 覆盖 |
一元逐元素(sin、exp) | 与输入同分片 |
二元(+、-、*) | "zip"维的分片必须一致或为 None;只在单个参数出现的"外积"维跟随各自输入;结果若重复提及同一网格轴则报错 |
reshape | 剥掉 singleton 轴后判断是拆轴还是并轴;若涉及被切的轴则报错,要求给 out_sharding |
规则的价值在于:以前只能靠猜编译器,现在推导不出来会立即在 trace 阶段报错,而不是等到跑起来看带宽。
模式可以混用,粒度是网格轴不是整个 mesh:axis_types 逐轴指定;auto_axes 让某几轴回到 Auto、explicit_axes 让某几轴进入 Explicit。两条硬约束也随之成立:
- 分片(类型里的
@X标记)只能提及 explicit 模式的网格轴; - 集合通信操作只能提及 manual 模式的网格轴。
7. Manual 模式:shard_map 的单设备视角
shard_map 把函数按分片映射,每个实例只看到自己那一片:
from jax.experimental.shard_map import shard_map
f_sharded = shard_map(f, mesh=mesh,
in_specs=(P('x'), P('x', None)),
out_specs=P('x', None),
check_rep=True)参数语义(官方 API 原文):
in_specs:PartitionSpec作为叶子,结构是入参 tuple 的树前缀。位置提到网格轴名 = 该数组轴沿该网格轴切;没提到的轴 = 复制;某个参数的 spec 是None= 该参数完全不分片。out_specs:提到轴名 = 各分片沿该轴拼接;没提到的轴 = 承诺各分片在该轴上的值相等,因此只产出一个值,不拼接。check_rep=True(默认):开启一致性校验与自动微分优化。校验内容正是"out_specs未提及的网格轴上的各分片是否真的一致"。auto=frozenset({}):实验性参数,列出的轴不参与手工分片、交给编译器;这些轴不允许出现在in_specs、out_specs或函数内的集合通信里。
两个必须知道的前提:
shard_map官方标注为实验性 API,签名可能变动;把它用在生产训练循环里要有回归测试。- 函数里若使用 Pallas kernel,
check_rep必须设为False。
最容易错的就是 out_specs 那半句承诺:以为"没写就是不管",实际是"没写就得保证各分片相同"。分片不等时 check_rep 会在运行时抓出来,这是 Manual 模式相对手写集合通信最大的收益。
8. 多进程:jax.distributed.initialize 的参数与默认值
多机多卡时,JAX 的模型是多控制器:每个 Python 进程(controller)管自己那批 local device,所有进程的 local device 合起来才是 global devices,且 local 集合互不相交。
jax.distributed.initialize(coordinator_address='192.168.0.1:8000',
num_processes=4, process_id=0)
print(jax.process_index(), jax.devices(), jax.local_devices())硬约束与默认值(官方 API 页):
| 参数 | 口径 |
|---|---|
coordinator_address | 进程 0 的地址与端口;localhost/127.0.0.1 在多机环境下不可用 |
num_processes / process_id | process_id 必须是稠密的 0..num_processes-1 |
local_device_ids | 限制本进程可见设备;默认全部本地设备可见,但 Slurm / Open MPI 在 GPU 上默认每进程一卡 |
initialization_timeout | 默认 300 秒,超过即初始化失败 |
heartbeat_timeout_seconds | 默认 100 秒,超时未发心跳即判定进程死亡 |
shutdown_timeout_seconds | 默认 300 秒,退出进程等待其他进程退出的时长 |
coordinator_bind_address | 多网卡节点需要显式指定,否则协调服务可能只监听一个接口,其他节点连不上 |
四条容易踩的现场:
- 顺序:
initialize()必须在任何设备访问之前调用(jax.devices()、jax.local_devices()、jnp计算都算访问)。访问设备之后再调用会直接报错。 - 代理变量:在只能通过
HTTP_PROXY/HTTPS_PROXY出网的环境里,initialize可能超时,需要在启动前 unset 这些变量。 - 自动探测:TPU、Slurm、Open MPI 下所有参数可省略;其他 MPI 安装可用
cluster_detection_method="mpi4py"(Open MPI 5 及以上要求mpi4py);四个关键参数(coordinator/num/process_id/local_device_ids)都给出时,自动探测被跳过。 - 故障语义:协调服务承担健康检查,任一进程死亡会让所有进程一起退出;它同时被用于分布式 checkpoint。这跟
torchrun elastic的"失败即杀全体存活 worker"是同构设计——差别在 JAX 这一侧的重启要由外部调度器发起,不是框架自己拉起。
9. 与 PyTorch 分片体系的结构对照
只做结构对照,不比较性能,也不涉及具体加速卡生态:
| 维度 | JAX | PyTorch |
|---|---|---|
| 设备网格 | jax.make_mesh + 命名轴 | torch.distributed.device_mesh.init_device_mesh |
| 分片描述 | PartitionSpec / NamedSharding,写进 jax.typeof | DTensor 的 placement |
| 谁来定分片 | Auto 由编译器、Explicit 由类型与用户、Manual 由用户 | 用户 fully_shard 包装后,由 DTensor 记录 |
| 显式集合通信 | shard_map 内手写(psum 等) | 手写 dist.all_reduce,或交给通信库调度 |
| 检查点 | 协调服务 + 生态检查点库 | torch.distributed.checkpoint |
一句话判断差异的本质:JAX 的分片是编译单元的一部分,可查询、可断言;PyTorch 的分片是运行期挂在张量上的属性。这决定了两边的 debug 手感——JAX 更容易在 trace 阶段抓到错误,PyTorch 更容易在运行期用 hook 观察中间状态。本站 PyTorch 侧的模块包装与检查点写法见 FSDP2 实战 与 分布式 checkpoint 实战。
10. 显存账与六个高频坑
先算一笔可复算的账:70B 参数、bf16(2 字节),纯权重 = 70 × 10⁹ × 2 = 140 GB(十进制)。8 卡均分,每卡 17.5 GB——前提是分片真的沿 8 个设备切开。若 PartitionSpec 漏写某轴导致复制,这笔账立刻翻倍,注意力和激活之外还要加上复制的那份。
六个坑,按现象→根因排:
| 现象 | 根因 |
|---|---|
加一行 device_put 后抛 ValueError | 两个 committed 分片互不相容(第 4 节) |
| 建 mesh 报大小不符 | 各轴大小乘积与可用设备数不匹配 |
check_rep 运行时报告分片不一致 | out_specs 未提及的轴,各分片实际不相等(第 7 节) |
jax.devices() 只看到本机卡 | 先做了 jnp 运算或 devices() 调用,initialize 顺序错了 |
| 多机初始化一直失败 | 用了 localhost,或代理变量未 unset |
| 多机训练只在部分节点跑 | process_id 不稠密,或 local_device_ids 与 mesh 大小不匹配 |
11. 落地检查清单
写代码前打印,出问题后对比:
print('global devices =', len(jax.devices()))
print('local devices =', len(jax.local_devices()))
print('abstract mesh =', jax.sharding.get_abstract_mesh())- 设备数与网格匹配:
prod(axis_sizes) == len(jax.devices()),不等就先修 mesh,别往下写。 - 看分片而不是猜分片:
jax.debug.visualize_array_sharding(x)逐层打印,重点看参数有没有在某个轴被复制。 - 输出加注解:
jit(..., out_shardings=NamedSharding(mesh, P(...))),按下游消费方式定。 shard_map的out_specs逐位置核对:函数实际返回的每个数组,与其 spec 的"提及=拼接 / 未提及=承诺相等"逐条对齐。- 多机脚本统一
process_id:从调度器读 rank 映射到稠密整数,别直接透传节点编号。 - 与检查点一起设计:分片元数据必须随检查点保存,否则换 mesh 形状后无法恢复;JAX 侧检查点细节本站另篇展开,PyTorch 侧可对照 DCP 分片布局。
相关文章
- 训练框架账:Megatron-LM 与 DeepSpeed 的并行抽象
- FSDP2 实战:fully_shard 契约、显存账与 torch.compile 组合
- 分布式 checkpoint 实战:DCP 的分片布局、异步保存与重分片