算子融合
tokamax.ops.op_fusion 允许您通过 JAX Pallas Fuser 将周围的 JAX 操作(前序和后序)直接融合到可融合的 Tokamax Pallas TPU 内核中。融合操作在内核循环内的每个图块上的 VMEM 中运行,而不是在归一化或激活与自定义内核之间将中间激活具体化到 HBM。
使用 @op_fusion.fuse
基本用法(Prologue 和 Epilogue)
从 tokamax.ops 导入 op_fusion,并使用 @op_fusion.fuse 封装包含可融合 Tokamax 算子的函数(通常在 @jax.jit 内):
import jax
import jax.numpy as jnp
import tokamax
from tokamax.ops import op_fusion
def rms_norm(x: jax.Array, weight: jax.Array, eps: float = 1e-6) -> jax.Array:
ms = jnp.mean(jnp.square(x.astype(jnp.float32)), axis=-1, keepdims=True)
return (x.astype(jnp.float32) * jax.lax.rsqrt(ms + eps)).astype(
x.dtype
) * weight
@jax.jit
@op_fusion.fuse
def fused_ragged_dot(x, rms_weight, rhs, out_bias, group_sizes):
# Prologue: fused into the kernel's LHS tile load.
x_norm = rms_norm(x, rms_weight)
out = tokamax.ragged_dot(
x_norm,
rhs,
group_sizes=group_sizes,
implementation="mosaic_tpu_v2",
)
# Epilogue: fused into the kernel's output store.
return jax.nn.silu(out + out_bias)
您可以调用具有显式可融合实现 (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) 的高级函数式 API,也可以直接调用特定的 tokamax.Op 实例(例如 PallasMosaicTpuV2RaggedDot)。如果 @op_fusion.fuse 中的算子不支持融合,Tokamax 会引发 NotImplementedError。
修饰器选项
op_fusion.fuse 会将其关键字实参转发给 jax.experimental.pallas.fuser.fuse:
@op_fusion.fuse(
resolve_fusion_dtypes=True,
debug=False,
strict_mode=True,
static_argnums=None,
static_argnames=None,
)
static_argnums/static_argnames:在调用融合函数时,将非数组 Python 参数(例如标量配置值或布尔标志)标记为静态。debug=True:输出跟踪的融合 jaxpr,以帮助诊断操作未融合或块规范传播失败的原因。strict_mode:控制 Pallas Fuser 的严格块规范等效性检查。
量化输入和内置内核激活
融合前导码由 PallasMosaicTpuV2RaggedDot 上的实时激活量化 (AsQArray)、预量化权重 (qwix.QArray) 和内置融合门/上激活组成:
import jax
import jax.numpy as jnp
import qwix
from tokamax._src import quantization
from tokamax._src.ops.ragged_dot import pallas_mosaic_tpu_v2
from tokamax.ops import op_fusion
gmm_op = pallas_mosaic_tpu_v2.PallasMosaicTpuV2RaggedDot()
@op_fusion.fuse
def fused_rms_norm_gate_up(x, rms_weight, w_q, w_scale, group_sizes):
x_norm = rms_norm(x, rms_weight)
return gmm_op(
quantization.AsQArray(x_norm, jnp.float8_e4m3fn),
qwix.QArray(w_q, w_scale),
group_sizes=group_sizes,
zero_initialize=False,
fuse_gateup_activation="silu",
preferred_element_type=jnp.bfloat16,
)
每个 @op_fusion.fuse 代码块一个可熔式操作
JAX Pallas Fuser 支持每个 @op_fusion.fuse 作用域一个可融合内核。在串联多个内核(例如,MoE 块中的 gate_up 后跟 down)时,请将每个可融合阶段封装在外部 @jax.jit 内其自己的 @op_fusion.fuse 函数中:
@jax.jit
def moe_layer(x, rms_weight, w1_q, w1_scale, w2_q, w2_scale, group_sizes):
mid = fused_rms_norm_gate_up(x, rms_weight, w1_q, w1_scale, group_sizes)
return gmm_op(
quantization.AsQArray(mid, jnp.float8_e4m3fn),
qwix.QArray(w2_q, w2_scale),
group_sizes=group_sizes,
zero_initialize=False,
preferred_element_type=jnp.bfloat16,
)
使用显式 @jax.custom_vjp 进行自动微分
@op_fusion.fuse 会融合前向计算块,并且不会通过 jax.grad 自动合成融合的反向传递。在对融合块进行微分时,请将前向和后向调用封装在显式 @jax.custom_vjp 中,以便您可以将前导/后导分别融合到前向和后向(drhs / dlhs)内核中:
import jax
from tokamax._src.ops.ragged_dot import pallas_mosaic_tpu_v2
from tokamax.ops import op_fusion
op = pallas_mosaic_tpu_v2.PallasMosaicTpuV2RaggedDot()
drhs_op = pallas_mosaic_tpu_v2.PallasMosaicTpuV2RaggedDot(
num_actual_groups=num_groups
)
@op_fusion.fuse
def fused_fwd_kernel(x, w, r, group_sizes):
return op(rms_norm(x, w), r, group_sizes=group_sizes, zero_initialize=True)
@op_fusion.fuse
def fused_drhs_kernel(x, w, dy, group_sizes):
return drhs_op(
rms_norm(x, w),
dy,
group_sizes=group_sizes,
ragged_dot_dimension_numbers=pallas_mosaic_tpu_v2.DRHS_RAGGED_DOT_DIM_NUMS,
preferred_element_type=dy.dtype,
)
@jax.custom_vjp
def fused_gmm(x, w, r, group_sizes):
return fused_fwd_kernel(x, w, r, group_sizes)
def fused_gmm_fwd(x, w, r, group_sizes):
return fused_fwd_kernel(x, w, r, group_sizes), (x, w, r, group_sizes)
def fused_gmm_bwd(residuals, dy):
x, w, r, group_sizes = residuals
dr = fused_drhs_kernel(x, w, dy, group_sizes)
dx_norm = op(
dy,
r,
group_sizes=group_sizes,
ragged_dot_dimension_numbers=pallas_mosaic_tpu_v2.DLHS_RAGGED_DOT_DIM_NUMS,
zero_initialize=True,
)
_, rms_vjp = jax.vjp(rms_norm, x, w)
dx, dw = rms_vjp(dx_norm)
return dx, dw, dr, None
fused_gmm.defvjp(fused_gmm_fwd, fused_gmm_bwd)
使用裸可融合内核
优先使用带有 Tokamax 算子封装容器(tokamax.ragged_dot 或 PallasMosaicTpuV2RaggedDot)的 @op_fusion.fuse,而不是裸可融合内核和 @jax.experimental.pallas.fuser.fuse,以保持向后兼容性并保留输入规范化、自动调优和元数据序列化。如果您直接调用低级 gmm_v2/tgmm_v2 内核,请在 @op_fusion.fuse 或 @jax.experimental.pallas.fuser.fuse 中使用 gmm_fuser.gmm_v2_fusible 或 gmm_fuser.tgmm_v2_fusible:
from jax.experimental.pallas import fuser
from tokamax._src.ops.gmm_v2 import gmm_fuser
@jax.jit
@fuser.fuse
def fused_bare_gmm(x, w, rhs, out_bias, group_sizes):
out = gmm_fuser.gmm_v2_fusible(rms_norm(x, w), rhs, group_sizes)
return jax.nn.silu(out + out_bias)
当 gmm_v2_fusible / tgmm_v2_fusible 周围没有前导或后导操作时,简单的 0 方程融合会被解包,以便编译后的内核采用确切的未融合路径。
支持的操作和限制条件
- 目前支持的 Tokamax 运算:
PallasMosaicTpuV2RaggedDot(implementation="mosaic_tpu_v2",涵盖前向/dlhsgmm_v2和 drhstgmm_v2)。 - 支持的前导/后导 JAX 基元:由 JAX Pallas Fuser 管理。通常支持的操作包括逐点一元/二元数学运算、
select/clamp、dtype 转换、broadcast_in_dim、transpose、concatenate/stack/split,以及跨整个块轴(例如RMSNorm)的reduce_sum。没有融合器块规范规则的操作(例如lax.pad、控制流 [scan/while/cond] 和reduce_max/reduce_min)无法融合。 PallasMosaicTpuV2RaggedDot融合限制:- 当
lhs或out在gmm_v2中融合时(以及当lhs或rhs在tgmm_v2中融合时),size_m必须与 TPU 子通道平铺 (size_lhs_sublane) 对齐。 - 融合
out时,out_size_n(以及tgmm_v2的size_k)必须与num_lanes(128) / 图块大小对齐,并且仅支持单输出 epilogue。 - 融合不支持
partial_sum。 gmm_v2中的融合rhs不支持与fuse_act或子字节打包权重一起使用。
- 当
编写融合兼容内核和算子
架构概览
Fusion 分派分为公共 Facade、内部适配器、Op 类和内核的配套 Fuser 模块:
tokamax/ops/op_fusion.py会将fuse重新导出为公共入口点。tokamax._src.ops.fuser_adapter会在jax.experimental.pallas.fuser.fuse周围设置 JAX 用户上下文标志 (in_op_fusion_context())。- 当
Op.__call__在该上下文中运行时,它会检查子类是否替换了_fusible_fwd(如果没有,则引发NotImplementedError),并委托给fuser_adapter.call_fusible_op。 call_fusible_op会在解析bound_args.default_config时暂停融合上下文,在数组叶上绑定fuser.fusible基元,具体化Op.fusible_argnames中未列出的任何参数,并在bound_args._tokamax_metadata(config)中调用Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)。
第 1 步:在 Op 上声明 fusible_argnames 并替换 _fusible_fwd
在后端 Op 子类中(如需查看完整参考,请参阅 PallasMosaicTpuV2RaggedDot):
- 将
fusible_argnames设置为数组叶应保持为fuser.Fusion闭包的参数名称。所有其他数组参数(例如元数据、索引或group_sizes)都会在_fusible_fwd运行之前由call_fusible_op自动具体化为常规jax.Array。 - 覆盖
_fusible_fwd。与_fwd(返回(out, residuals))不同,_fusible_fwd直接返回输出T,并接收out_fusions和已解析的config。 - 对于叶不应融合的复合 PyTree 操作数(例如,预量化的
QArray(qvalue, scale)权重),请使用fuser_adapter.materialize(...)显式具体化它们。
from typing import ClassVar, override
import jax
from tokamax._src.ops import fuser_adapter
class MyPallasTpuOp(MyBaseOp[Config, None]):
config_cls: ClassVar[type[Config]] = Config
fusible_argnames: ClassVar[tuple[str, ...]] = ("lhs", "rhs")
@override
def _fusible_fwd(
self,
lhs: jax.Array | fuser_adapter.InputFusion,
rhs: jax.Array | fuser_adapter.InputFusion,
*,
out_fusions: fuser_adapter.OutputFusion | None = None,
config: Config,
**kwargs,
) -> jax.Array:
return my_kernel_fusible(
lhs, rhs, config=config, out_fusions=out_fusions, **kwargs
)
第 2 步:将 Fuser 集成保留在配套 *_fuser.py 模块中
遵循 Tokamax 的核心内核(gmm_v2.py、tgmm_v2.py)与其融合器集成 (gmm_fuser.py) 之间的分离:
- 请勿在核心内核文件中导入
jax.experimental.pallas.fuser,以便未融合的内核保持独立且易于阅读。 在构建融合规范之前,请先解开 0 方程平凡
fuser.Fusion闭包:def _unwrap_trivial_input_fusion(x): if isinstance(x, fuser.Fusion) and not jax.make_jaxpr(x)().jaxpr.eqns: return x() return xfuser.fusible会将每个输入数组叶封装在Fusion中,即使该操作数没有生产者操作也是如此。解封装普通闭包可使未修改的未融合BlockSpec路径上的未轻触操作数保持不变,且运行时开销为零。如果您的基础内核使用
@jax.jit修饰,请在可融合路径上调用inspect.unwrap(base_kernel)-@jax.jit会拒绝fuser.Fusion参数。如果裸内核调用方也应该能够直接在
@fuser.fuse内调用可融合入口点,请检测裸jax.Array调用并自动绑定fuser.fusible(就像gmm_fuser.gmm_v2_fusible一样)。
第 3 步:使用 fuser_adapter 解包融合和转换 BlockSpec
使用 tokamax._src.ops.fuser_adapter 中的共享辅助程序,而不是直接调用低级 fuser API:
解包输入前言:
lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)返回
(fn, values, values_type),其中values是由 prologue 闭包的 HBM 数组的元组,values_type包含其ShapeDtypeStruct。解包单输出 epilogue:
out_fn, out_values, out_values_type, out_init = ( fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type) )将 Pallas Fuser 的 1 元组输出惯例解包为单个
ShapeDtypeStruct(out_init),并在多输出 epilogue 上引发NotImplementedError。通过序言向后拉取输入
BlockSpec:pulled_lhs_fn, lhs_val_specs = fuser_adapter.pull_input_spec( lhs_fn, lhs_spec, lhs_values_type, grid_len=grid_len, num_scalar_prefetch=0, )通过 epilogue 推送和拉取输出
BlockSpec:pulled_out_fn, out_fusion_input_specs, final_out_spec = ( fuser_adapter.push_pull_block_spec( out_fn, out_spec, out_values_type, raw_out_type, grid_len=grid_len, num_scalar_prefetch=0, ) )fuser_adapter.push_pull_block_spec处理具有大小为 1 的广播的形状保留缩减(例如触发原始fuser.push_block_spec的RMSNorm尾声),验证提取的规范是否与内核写入的out_spec匹配,解包 1 元组返回值,并保持与受支持的 JAX 版本的兼容性。
第 4 步:将拉取的规范和回调连接到 Pallas 内核
- 传递捕获的 HBM 输入及其提取的
BlockSpec:- 输入序言
values替换融合的操作数(与lhs_val_specs配对)。 - 输出尾声旁路输入(
out_values,例如尾声偏差或残差)作为只读 HBM 内核输入与out_fusion_input_specs配对传递,因此pltpu.emit_pipeline会将其图块预提取到 VMEM 中。未融合时,为引用和规范传递一个空元组()(0 个 PyTree 叶)。
- 输入序言
- 为每种融合模式使用不同的 PyTree 类型:
pltpu.emit_pipeline映射jax.tree.map(..., in_specs, in_refs),因此每个输入 ref 容器及其in_spec容器必须共享完全相同的@jax.tree_util.register_dataclassPyTree 类型(例如,未融合的lhs为LhsRef[T],而 prologue 融合的lhs为FusedLhsRef[T])。
评估内核主体内 VMEM 图块上拉取的回调:
- 每个拉取的函数都具有签名
fn(program_ids, scalar_prefetch, *args)。 - 在
pltpu.emit_pipeline(..., _explicit_indices=True)内,当num_scalar_prefetch=0时,传递pids = step.index(否则传递tuple(pl.program_id(i) for i in range(grid_len)))和():
# Prologue: compute the input tile from prefetched VMEM refs. tiled_lhs = lhs_fn(pids, (), tuple(r[...] for r in lhs_val_refs)) # Epilogue: transform the accumulated output tile before storing. out_vals = tuple(r[...] for r in tiled_out_fusion_input_refs) out_tile = out_fn(pids, (), out_vals, acc_tile)- 每个拉取的函数都具有签名
常见错误
pl.BoundedSlice和reshape:Pallas Fuser 的 reshape pull 规则会拒绝pl.BoundedSlice。如果您的未融合内核在emit_pipeline之前将 2D HBM 输入重塑为 3D 子通道平铺引用,请先将规范转换为 2DBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...),然后再通过融合操作数进行拉取或推送(请参阅gmm_fuser.py中的_to_2d_bounded_spec)。- 具有行遮盖的尾声排序:如果您的内核将组外行或填充行遮盖为零,并跨步骤组合部分子通道图块,请在应用零遮盖之前运行
out_fn,以便非零尾声(例如+ bias)不会损坏遮盖的行。 pl.kernel与Sequenceout_type:pl.kernel会将tuple或listout_type解包为多个位置out_ref实参。使用fuser_adapter.unpack_output_fusion会将单输出out_init保留为裸ShapeDtypeStruct。- 主机端填充与融合形状:由于 Pallas Fuser 没有
lax.pad规则或未对齐的lax.slice推送/拉取规则,因此请在融合规范的prepare()方法中尽早验证对齐要求,并针对不受支持的形状引发NotImplementedError,而不是填充Fusion对象。 _fusible_fwd内的辅助Op:call_fusible_op会在default_config解析期间以及_fusible_fwd内暂停in_op_fusion_context(),因此在_fusible_fwd内调用未融合的辅助Op会运行其正常的_fwd路径,而不会触发嵌套融合错误。
测试核对清单
为算子添加融合支持时,请涵盖以下内容:
- Prologue 融合(逐点和全轴归约,例如
RMSNorm)、Epilogue 融合(有和没有外部辅助输入,例如偏差或残差)以及Prologue + Epilogue 组合。 - 无融合奇偶校验:验证调用不含周围操作(普通、
@op_fusion.fuse和@fuser.fuse)的可融合入口点是否会产生与未融合内核按位相同的输出 (chex.assert_trees_all_equal)。 - 显式
@jax.custom_vjp梯度:验证前向值和梯度是否与未融合的参考值匹配。 - 不受支持的组合:验证是否有关于形状未对齐或内核选项不兼容的明确
NotImplementedError消息。
参考实现
- 公开 Facade:
tokamax/ops/op_fusion.py Op调度和共享辅助程序:tokamax/_src/ops/fuser_adapter.py- 内核融合器集成(
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py Op._fusible_fwd集成:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py- 内核和
Op融合测试:tokamax/_src/ops/gmm_v2/gmm_fuser_test.py和tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py