算子融合

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",涵盖前向/dlhs gmm_v2 和 drhs tgmm_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 模块:

  1. tokamax/ops/op_fusion.py 会将 fuse 重新导出为公共入口点。
  2. tokamax._src.ops.fuser_adapter 会在 jax.experimental.pallas.fuser.fuse 周围设置 JAX 用户上下文标志 (in_op_fusion_context())。
  3. 当 Op.__call__ 在该上下文中运行时,它会检查子类是否替换了 _fusible_fwd(如果没有,则引发 NotImplementedError),并委托给 fuser_adapter.call_fusible_op。
  4. 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):

  1. 将 fusible_argnames 设置为数组叶应保持为 fuser.Fusion 闭包的参数名称。所有其他数组参数(例如元数据、索引或 group_sizes)都会在 _fusible_fwd 运行之前由 call_fusible_op 自动具体化为常规 jax.Array。
  2. 覆盖 _fusible_fwd。与 _fwd(返回 (out, residuals))不同,_fusible_fwd 直接返回输出 T,并接收 out_fusions 和已解析的 config。
  3. 对于叶不应融合的复合 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 x
    

    fuser.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 内核

  1. 传递捕获的 HBM 输入及其提取的 BlockSpec:
    • 输入序言 values 替换融合的操作数(与 lhs_val_specs 配对)。
    • 输出尾声旁路输入(out_values,例如尾声偏差或残差)作为只读 HBM 内核输入与 out_fusion_input_specs 配对传递,因此 pltpu.emit_pipeline 会将其图块预提取到 VMEM 中。未融合时,为引用和规范传递一个空元组 ()(0 个 PyTree 叶)。
  2. 为每种融合模式使用不同的 PyTree 类型:
    • pltpu.emit_pipeline 映射 jax.tree.map(..., in_specs, in_refs),因此每个输入 ref 容器及其 in_spec 容器必须共享完全相同的 @jax.tree_util.register_dataclass PyTree 类型(例如,未融合的 lhs 为 LhsRef[T],而 prologue 融合的 lhs 为 FusedLhsRef[T])。
  3. 评估内核主体内 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 子通道平铺引用,请先将规范转换为 2D BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...),然后再通过融合操作数进行拉取或推送(请参阅 gmm_fuser.py 中的 _to_2d_bounded_spec)。
  • 具有行遮盖的尾声排序:如果您的内核将组外行或填充行遮盖为零,并跨步骤组合部分子通道图块,请在应用零遮盖之前运行 out_fn,以便非零尾声(例如 + bias)不会损坏遮盖的行。
  • pl.kernel 与 Sequence out_type:pl.kernel 会将 tuple 或 list out_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 路径,而不会触发嵌套融合错误。

测试核对清单

为算子添加融合支持时,请涵盖以下内容:

  1. Prologue 融合(逐点和全轴归约,例如 RMSNorm)、Epilogue 融合(有和没有外部辅助输入,例如偏差或残差)以及Prologue + Epilogue 组合。
  2. 无融合奇偶校验:验证调用不含周围操作(普通、@op_fusion.fuse 和 @fuser.fuse)的可融合入口点是否会产生与未融合内核按位相同的输出 (chex.assert_trees_all_equal)。
  3. 显式 @jax.custom_vjp 梯度:验证前向值和梯度是否与未融合的参考值匹配。
  4. 不受支持的组合:验证是否有关于形状未对齐或内核选项不兼容的明确 NotImplementedError 消息。

参考实现