Skip to content

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 抓住。

三种分片模式的事实来源,以及 P('x') 在 (4,2) 网格上的沉默成本

2. Mesh:把设备排成有名字的网格 ​

python
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)

三个要点:

  1. make_mesh 会依据硬件拓扑挑选更优的设备顺序(官方原文:takes hardware topology into account for the Device order)。直接 Mesh(devices, axis_names) 也能建,但官方建议用 make_mesh。
  2. 轴名(上例的 'x'、'y')是后面所有 PartitionSpec 的词汇表。轴名写错或漏写不会有 Python 报错,只会静默变成复制。
  3. 可以逐轴指定分片模式:jax.make_mesh(shape, names, axis_types=(AxisType.Auto, AxisType.Auto))。官方 explicit 教程示例里显式传这一参数,说明它决定该轴走哪种模式,需要时应当写明而不是靠默认。

配套还有一个作用域写法,省掉反复传 mesh:

python
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:

python
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 里,编译器不会把分片数组拷回单设备,而是按输入的分片决定中间值和输出的分片,必要时自己插入通信,并据此并行化求值。

这意味着两件事:

  1. 你只需要关心数学,分片由编译器推导——但代价是不可预期。全程序优化(GSPMD)意味着局部改一行,整张图的分片决策都可能变。
  2. 给提示的手法是 jax.lax.with_sharding_constraint,它只是约束/提示,不是命令:
python
@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 阶段就能查询。

python
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 把函数按分片映射,每个实例只看到自己那一片:

python
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 或函数内的集合通信里。

两个必须知道的前提:

  1. shard_map 官方标注为实验性 API,签名可能变动;把它用在生产训练循环里要有回归测试。
  2. 函数里若使用 Pallas kernel,check_rep 必须设为 False。

最容易错的就是 out_specs 那半句承诺:以为"没写就是不管",实际是"没写就得保证各分片相同"。分片不等时 check_rep 会在运行时抓出来,这是 Manual 模式相对手写集合通信最大的收益。

8. 多进程:jax.distributed.initialize 的参数与默认值 ​

多机多卡时,JAX 的模型是多控制器:每个 Python 进程(controller)管自己那批 local device,所有进程的 local device 合起来才是 global devices,且 local 集合互不相交。

python
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_idprocess_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多网卡节点需要显式指定,否则协调服务可能只监听一个接口,其他节点连不上

四条容易踩的现场:

  1. 顺序:initialize() 必须在任何设备访问之前调用(jax.devices()、jax.local_devices()、jnp 计算都算访问)。访问设备之后再调用会直接报错。
  2. 代理变量:在只能通过 HTTP_PROXY / HTTPS_PROXY 出网的环境里,initialize 可能超时,需要在启动前 unset 这些变量。
  3. 自动探测:TPU、Slurm、Open MPI 下所有参数可省略;其他 MPI 安装可用 cluster_detection_method="mpi4py"(Open MPI 5 及以上要求 mpi4py);四个关键参数(coordinator/num/process_id/local_device_ids)都给出时,自动探测被跳过。
  4. 故障语义:协调服务承担健康检查,任一进程死亡会让所有进程一起退出;它同时被用于分布式 checkpoint。这跟 torchrun elastic 的"失败即杀全体存活 worker"是同构设计——差别在 JAX 这一侧的重启要由外部调度器发起,不是框架自己拉起。

9. 与 PyTorch 分片体系的结构对照 ​

只做结构对照,不比较性能,也不涉及具体加速卡生态:

维度JAXPyTorch
设备网格jax.make_mesh + 命名轴torch.distributed.device_mesh.init_device_mesh
分片描述PartitionSpec / NamedSharding,写进 jax.typeofDTensor 的 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. 落地检查清单 ​

写代码前打印,出问题后对比:

python
print('global devices =', len(jax.devices()))
print('local  devices =', len(jax.local_devices()))
print('abstract mesh =', jax.sharding.get_abstract_mesh())
  1. 设备数与网格匹配:prod(axis_sizes) == len(jax.devices()),不等就先修 mesh,别往下写。
  2. 看分片而不是猜分片:jax.debug.visualize_array_sharding(x) 逐层打印,重点看参数有没有在某个轴被复制。
  3. 输出加注解:jit(..., out_shardings=NamedSharding(mesh, P(...))),按下游消费方式定。
  4. shard_map 的 out_specs 逐位置核对:函数实际返回的每个数组,与其 spec 的"提及=拼接 / 未提及=承诺相等"逐条对齐。
  5. 多机脚本统一 process_id:从调度器读 rank 映射到稠密整数,别直接透传节点编号。
  6. 与检查点一起设计:分片元数据必须随检查点保存,否则换 mesh 形状后无法恢复;JAX 侧检查点细节本站另篇展开,PyTorch 侧可对照 DCP 分片布局。

相关文章 ​

相关文章 ​

AI-HPC 智算超算专家 · Contact: openaihpc@gmail.com