オペレーター フュージョン
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"、フォワード / dlhsgmm_v2と drhstgmm_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 クラス、カーネルのコンパニオン フューザー モジュールに分割されます。
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)とその 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 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 を使用して 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 カーネルに接続する
- キャプチャした HBM 入力を、取得した
BlockSpecとともに渡します。- 融合されたオペランド(
lhs_val_specsとペア)の代わりに、入力プロローグvaluesが使用されます。 - 出力エピローグのサイド入力(
out_values、エピローグ バイアスや残差など)は、out_fusion_input_specsとペアになった読み取り専用の HBM カーネル入力として渡されるため、pltpu.emit_pipelineはタイルを VMEM にプリフェッチします。融合されていない場合は、refs と specs の両方に空のタプル()を渡します(0 個の PyTree リーフ)。
- 融合されたオペランド(
- 融合モードごとに異なる PyTree タイプを使用する:
pltpu.emit_pipelineはjax.tree.map(..., in_specs, in_refs)をマッピングするため、各入力参照コンテナとそのin_specコンテナは、まったく同じ@jax.tree_util.register_dataclassPyTree タイプを共有する必要があります(たとえば、融合されていないlhsの場合はLhsRef[T]、プロローグ融合された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.slicepush/pull ルールがないため、融合仕様のprepare()メソッドの早い段階で整列要件を検証し、Fusionオブジェクトをパディングするのではなく、サポートされていない形状に対してNotImplementedErrorを発生させます。 _fusible_fwd内のヘルパーOp:call_fusible_opは、default_configの解決中および_fusible_fwd内でin_op_fusion_context()を一時停止します。そのため、_fusible_fwd内で融合されていないヘルパーOpを呼び出すと、ネストされた融合エラーをトリガーすることなく、通常の_fwdパスが実行されます。
テストのチェックリスト
演算子に融合サポートを追加する場合は、以下をカバーします。
- プロローグ融合(ポイントワイズとフル軸の縮小(
RMSNormなど))、エピローグ融合(バイアスや残差などの外部サイド入力の有無)、プロローグとエピローグの組み合わせ。 - 融合なしのパリティ: 周囲のオペレーション(プレーン、
@op_fusion.fuse、@fuser.fuse)なしで融合可能なエントリポイントを呼び出すと、融合されていないカーネルとビット単位で同一の出力(chex.assert_trees_all_equal)が生成されることを確認します。 - 明示的な
@jax.custom_vjp勾配: 順方向の値と勾配が、融合されていない参照と一致することを確認します。 NotImplementedErrorサポートされていない組み合わせ: 整合性のない形状や互換性のないカーネル オプションに関する明確なメッセージを確認します。
リファレンス実装
- 公開ファサード:
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