オペレーター フュージョン

tokamax.ops.op_fusion を使用すると、JAX Pallas Fuser を介して、周囲の JAX オペレーション(プロローグとエピローグ)を融合可能な Tokamax Pallas TPU カーネルに直接融合できます。正規化またはアクティベーションとカスタム カーネルの間で中間アクティベーションを HBM にマテリアライズする代わりに、融合されたオペレーションはカーネルループ内の各タイルの VMEM で実行されます。

@op_fusion.fuse の使用

基本的な使用方法(プロローグとエピローグ)

tokamax.ops から op_fusion をインポートし、融合可能な Tokamax 演算子を含む関数を @op_fusion.fuse でラップします(通常は @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: トレースされた融合 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 ブロックごとに 1 つの融合可能オペレーション

JAX Pallas Fuser は、@op_fusion.fuse スコープごとに 1 つの融合可能なカーネルをサポートします。複数のカーネルを連結する場合(たとえば、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)

Bare Fusible Kernel の使用

下位互換性を維持し、入力の正規化、自動チューニング、メタデータのシリアル化を保持するには、ベアの融合可能なカーネルと @jax.experimental.pallas.fuser.fuse よりも、Tokamax 演算子ラッパー(tokamax.ragged_dot または PallasMosaicTpuV2RaggedDot)を含む @op_fusion.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 があります。fuser ブロック仕様ルールがないオペレーション(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 は Fusion でサポートされていません。
    • gmm_v2 の融合 rhs は、fuse_act またはサブバイト パックされた重みと一緒にはサポートされていません。

Fusion 互換のカーネルと演算子の作成

アーキテクチャの概要

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 など)は、_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)とその 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 を使用して Fusion をアンパックし、BlockSpec を変換する

低レベルの fuser API を直接呼び出すのではなく、tokamax._src.ops.fuser_adapter の共有ヘルパーを使用します。

  • 入力プロローグを解凍する:

    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 を push および pull する:

    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 とともに渡します。
    • 融合されたオペランド(lhs_val_specs とペア)の代わりに、入力プロローグ values が使用されます。
    • 出力エピローグのサイド入力(out_values、エピローグ バイアスや残差など)は、out_fusion_input_specs とペアになった読み取り専用の HBM カーネル入力として渡されるため、pltpu.emit_pipeline はタイルを VMEM にプリフェッチします。融合されていない場合は、refs と specs の両方に空のタプル () を渡します(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 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 push/pull ルールがないため、融合仕様の prepare() メソッドの早い段階で整列要件を検証し、Fusion オブジェクトをパディングするのではなく、サポートされていない形状に対して NotImplementedError を発生させます。
  • _fusible_fwd 内のヘルパー Op: call_fusible_op は、default_config の解決中および _fusible_fwd 内で in_op_fusion_context() を一時停止します。そのため、_fusible_fwd 内で融合されていないヘルパー Op を呼び出すと、ネストされた融合エラーをトリガーすることなく、通常の _fwd パスが実行されます。

テストのチェックリスト

演算子に融合サポートを追加する場合は、以下をカバーします。

  1. プロローグ融合(ポイントワイズとフル軸の縮小(RMSNorm など))、エピローグ融合(バイアスや残差などの外部サイド入力の有無)、プロローグとエピローグの組み合わせ。
  2. 融合なしのパリティ: 周囲のオペレーション(プレーン、@op_fusion.fuse、@fuser.fuse)なしで融合可能なエントリポイントを呼び出すと、融合されていないカーネルとビット単位で同一の出力(chex.assert_trees_all_equal)が生成されることを確認します。
  3. 明示的な @jax.custom_vjp 勾配: 順方向の値と勾配が、融合されていない参照と一致することを確認します。
  4. NotImplementedErrorサポートされていない組み合わせ: 整合性のない形状や互換性のないカーネル オプションに関する明確なメッセージを確認します。

リファレンス実装