運算子融合

tokamax.ops.op_fusion 可讓您透過 JAX Pallas Fuser,將周圍的 JAX 作業 (前置和後置作業) 直接融合至可融合的 Tokamax Pallas TPU 核心。融合運算會在核心迴圈內每個圖塊的 VMEM 中執行,而不是在正規化或活化與自訂核心之間,將中繼活化具體化至 HBM。

使用@op_fusion.fuse

基本用法 (序言和結語)

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

您可以呼叫具有明確可融合實作的高階功能 API (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")),或直接呼叫特定 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:列印追蹤的融合 jaxprs,協助診斷運算未融合或區塊規格傳播失敗的原因。
  • strict_mode:控管 Pallas Fuser 的嚴格區塊規格等效檢查。

量化輸入和內建核心活化

融合前置作業會與即時活化量化 (AsQArray)、預先量化權重 (qwix.QArray),以及 PallasMosaicTpuV2RaggedDot 上的內建融合閘/向上活化作業組合:

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)

使用裸可融合核心

建議使用 @op_fusion.fuse 搭配 Tokamax 運算子包裝函式 (tokamax.ragged_dot 或 PallasMosaicTpuV2RaggedDot),而非裸熔核心和 @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",涵蓋 forward/dlhs gmm_v2 和 drhs tgmm_v2)。
  • 支援的前置/後置 JAX 原始物件:由 JAX Pallas Fuser 管理。常見的支援運算包括逐點一元/二元數學、select/clamp、dtype 轉換、broadcast_in_dim、transpose、concatenate/stack/split,以及跨完整區塊軸的 reduce_sum (例如 RMSNorm)。沒有融合器區塊規格規則的運算 (例如 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) / 圖塊大小對齊,且僅支援單一輸出結尾。
    • 融合功能不支援partial_sum。
    • gmm_v2 中的融合 rhs 不支援 fuse_act 或子位元組封裝權重。

編寫與融合相容的核心和運算

架構總覽

Fusion 調度作業分為公開外觀、內部轉接器、Op 類別,以及核心的隨附融合器模組:

  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) 都會由 call_fusible_op 自動具體化為一般 jax.Array,然後 _fusible_fwd 才會執行。
  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) 與其 Fuser 整合 (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 是由前置作業關閉的 HBM 陣列元組,而 values_type 則保留其 ShapeDtypeStruct。

  • 解壓縮單一輸出結尾:

    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),並在多輸出結尾引發 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,
    )
    
  • 透過結語推送及提取輸出內容 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),因此每個輸入參照容器及其 in_spec 容器必須共用完全相同的 @jax.tree_util.register_dataclass PyTree 類型 (例如,未融合 lhs 的 LhsRef[T] 與前置融合 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 提取規則會拒絕 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 訊息。

參考實作