Penggabungan Operator

tokamax.ops.op_fusion memungkinkan Anda menggabungkan operasi JAX di sekitarnya (prolog dan epilog) langsung ke dalam kernel TPU Tokamax Pallas yang dapat digabungkan melalui JAX Pallas Fuser. Alih-alih mewujudkan aktivasi perantara ke HBM antara normalisasi atau aktivasi dan kernel kustom, operasi gabungan berjalan di VMEM pada setiap ubin di dalam loop kernel.

Menggunakan @op_fusion.fuse

Penggunaan Dasar (Prologue dan Epilogue)

Impor op_fusion dari tokamax.ops dan gabungkan fungsi yang berisi operator Tokamax yang dapat digabungkan dengan @op_fusion.fuse (biasanya di dalam @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)

Anda dapat memanggil API fungsional tingkat tinggi dengan implementasi fusible eksplisit (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) atau instance tokamax.Op tertentu secara langsung (seperti PallasMosaicTpuV2RaggedDot). Jika operator di dalam @op_fusion.fuse tidak mendukung fusi, Tokamax akan memunculkan NotImplementedError.

Opsi Dekorator

op_fusion.fuse meneruskan argumen kata kuncinya ke 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: Menandai argumen Python non-array (misalnya, nilai konfigurasi skalar atau flag boolean) sebagai statis saat memanggil fungsi gabungan.
  • debug=True: Mencetak jaxpr fusi yang dilacak untuk membantu mendiagnosis alasan operasi tidak bergabung atau gagal dalam propagasi spesifikasi blok.
  • strict_mode: Mengontrol pemeriksaan kesetaraan spesifikasi blok yang ketat dari Pallas Fuser.

Input Terkuantisasi dan Aktivasi Kernel Bawaan

Prolog gabungan disusun dengan kuantisasi aktivasi on-the-fly (AsQArray), bobot yang telah dikuantisasi (qwix.QArray), dan aktivasi gate/up gabungan bawaan pada 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,
  )

Satu Fusible Op per Blok @op_fusion.fuse

JAX Pallas Fuser mendukung satu kernel yang dapat digabungkan per cakupan @op_fusion.fuse. Saat merangkai beberapa kernel (misalnya, gate_up diikuti dengan down dalam blok MoE), gabungkan setiap tahap yang dapat digabungkan dalam fungsi @op_fusion.fuse-nya sendiri di dalam @jax.jit luar:

@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,
  )

Diferensiasi Otomatis dengan @jax.custom_vjp Eksplisit

@op_fusion.fuse menggabungkan blok komputasi maju dan tidak otomatis menyintesis penerusan mundur gabungan melalui jax.grad. Saat membedakan blok gabungan, gabungkan panggilan maju dan mundur dalam @jax.custom_vjp eksplisit sehingga Anda dapat menggabungkan prolog/epilog ke dalam kernel maju dan mundur (drhs / dlhs) secara independen:

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)

Menggunakan Bare Fusible Kernel

Pilih @op_fusion.fuse dengan wrapper operator Tokamax (tokamax.ragged_dot atau PallasMosaicTpuV2RaggedDot) daripada kernel fusible bare dan @jax.experimental.pallas.fuser.fuse untuk mempertahankan kompatibilitas mundur dan mempertahankan kanonikalisasi input, penyesuaian otomatis, dan serialisasi metadata. Jika Anda memanggil kernel gmm_v2 / tgmm_v2 tingkat rendah secara langsung, gunakan gmm_fuser.gmm_v2_fusible atau gmm_fuser.tgmm_v2_fusible di dalam @op_fusion.fuse atau @jax.experimental.pallas.fuser.fuse:

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)

Jika tidak ada operasi prolog atau epilog yang mengelilingi gmm_v2_fusible / tgmm_v2_fusible, penggabungan 0 persamaan yang sederhana akan dibuka sehingga kernel yang dikompilasi mengambil jalur yang tidak digabungkan secara tepat.

Operasi dan Batasan yang Didukung

  • Operasi Tokamax yang saat ini didukung: PallasMosaicTpuV2RaggedDot (implementation="mosaic_tpu_v2", yang mencakup gmm_v2 forward/dlhs dan tgmm_v2 drhs).
  • Primitif JAX prolog/epilog yang didukung: Diatur oleh JAX Pallas Fuser. Operasi yang umumnya didukung mencakup matematika unari/biner per titik, select/clamp, transmisi dtype, broadcast_in_dim, transpose, concatenate/stack/split, dan reduce_sum di seluruh sumbu blok penuh (seperti RMSNorm). Operasi tanpa aturan spesifikasi blok fuser—seperti lax.pad, alur kontrol (scan/while/cond), dan reduce_max/reduce_min—tidak dapat digabungkan.
  • Batasan penggabungan PallasMosaicTpuV2RaggedDot:
    • size_m harus diselaraskan dengan tiling sublane TPU (size_lhs_sublane) saat lhs atau out digabungkan dalam gmm_v2 (dan saat lhs atau rhs digabungkan dalam tgmm_v2).
    • Saat out digabungkan, out_size_n (dan size_k untuk tgmm_v2) harus diselaraskan dengan num_lanes (128) / ukuran ubin, dan hanya epilog output tunggal yang didukung.
    • partial_sum tidak didukung dengan fusi.
    • rhs gabungan di gmm_v2 tidak didukung bersama dengan fuse_act atau bobot yang dipaketkan sub-byte.

Membuat Kernel dan Op yang Kompatibel dengan Fusion

Ringkasan Arsitektur

Pengiriman fusion dibagi antara facade publik, adaptor internal, class Op, dan modul fuser pendamping kernel:

  1. tokamax/ops/op_fusion.py mengekspor ulang fuse sebagai titik entri publik.
  2. tokamax._src.ops.fuser_adapter menetapkan flag konteks pengguna JAX (in_op_fusion_context()) di sekitar jax.experimental.pallas.fuser.fuse.
  3. Saat Op.__call__ berjalan di dalam konteks tersebut, class ini akan memeriksa apakah subclass mengganti _fusible_fwd (meningkatkan NotImplementedError jika tidak) dan mendelegasikan ke fuser_adapter.call_fusible_op.
  4. call_fusible_op menangguhkan konteks fusi saat menyelesaikan bound_args.default_config, mengikat primitif fuser.fusible di atas daun array, mewujudkan argumen apa pun yang tidak tercantum dalam Op.fusible_argnames, dan memanggil Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) di dalam bound_args._tokamax_metadata(config).

Langkah 1: Deklarasikan fusible_argnames dan Ganti _fusible_fwd di Op Anda

Di subclass Op backend Anda (lihat PallasMosaicTpuV2RaggedDot untuk referensi lengkap):

  1. Tetapkan fusible_argnames ke nama parameter yang daun array-nya harus tetap berupa closure fuser.Fusion. Semua argumen array lainnya (seperti metadata, indeks, atau group_sizes) otomatis diwujudkan menjadi jax.Array reguler oleh call_fusible_op sebelum _fusible_fwd berjalan.
  2. Ganti _fusible_fwd. Tidak seperti _fwd (yang menampilkan (out, residuals)), _fusible_fwd menampilkan output T secara langsung dan menerima out_fusions dan config yang di-resolve.
  3. Untuk operand PyTree gabungan yang daunnya tidak boleh digabungkan (misalnya, bobot QArray(qvalue, scale) yang telah dikuantisasi sebelumnya), materialisasikan secara eksplisit dengan 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
    )

Langkah 2: Pertahankan Integrasi Fuser dalam Modul *_fuser.py Pendamping

Ikuti pemisahan Tokamax antara kernel inti (gmm_v2.py, tgmm_v2.py) dan integrasi fuser-nya (gmm_fuser.py):

  • Simpan impor jax.experimental.pallas.fuser di luar file kernel inti agar kernel yang tidak digabungkan tetap mandiri dan mudah dibaca.
  • Buka penutupan fuser.Fusion trivial 0 persamaan sebelum membuat spesifikasi fusi Anda:

    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 menggabungkan setiap leaf array input dalam Fusion, meskipun operand tersebut tidak memiliki operasi produsen. Membuka closure trivial akan mempertahankan operand yang tidak tersentuh pada jalur BlockSpec yang tidak digabungkan dan tidak dimodifikasi tanpa overhead runtime.

  • Jika kernel dasar Anda dihiasi dengan @jax.jit, panggil inspect.unwrap(base_kernel) pada jalur yang dapat digabungkan—@jax.jit menolak argumen fuser.Fusion.

  • Jika pemanggil bare-kernel juga harus dapat memanggil titik entri fusible Anda langsung di dalam @fuser.fuse, deteksi panggilan jax.Array bare dan ikat fuser.fusible secara otomatis (seperti yang dilakukan gmm_fuser.gmm_v2_fusible).

Langkah 3: Membuka Paket Fusion dan Transformasi BlockSpec dengan fuser_adapter

Gunakan helper bersama di tokamax._src.ops.fuser_adapter, bukan memanggil API fuser tingkat rendah secara langsung:

  • Membongkar prolog input:

    lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)
    

    Menampilkan (fn, values, values_type) dengan values adalah tuple array HBM yang ditutup oleh prolog dan values_type menyimpan ShapeDtypeStruct-nya.

  • Membongkar epilog output tunggal:

    out_fn, out_values, out_values_type, out_init = (
        fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type)
    )
    

    Membuka konvensi output 1-tuple Pallas Fuser menjadi satu ShapeDtypeStruct (out_init) dan memunculkan NotImplementedError pada epilog multi-output.

  • Menarik input BlockSpec mundur melalui prolog:

    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,
    )
    
  • Mendorong dan menarik output BlockSpec melalui epilog:

    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 menangani pengurangan yang mempertahankan bentuk dengan siaran ukuran 1 (seperti epilog RMSNorm yang memicu fuser.push_block_spec mentah), memverifikasi bahwa spesifikasi yang ditarik cocok dengan out_spec kernel yang ditulis, membuka nilai yang ditampilkan tuple 1, dan mempertahankan kompatibilitas di seluruh rilis JAX yang didukung.

Langkah 4: Hubungkan Spesifikasi dan Callback yang Ditarik ke dalam Kernel Pallas

  1. Teruskan input HBM yang diambil bersama dengan BlockSpec yang ditarik:
    • Input prolog values menggantikan operand gabungan (yang dipasangkan dengan lhs_val_specs).
    • Input samping epilog output (out_values, seperti bias epilog atau residual) diteruskan sebagai input kernel HBM hanya baca yang dipasangkan dengan out_fusion_input_specs sehingga pltpu.emit_pipeline mengambil data ubinnya ke VMEM. Jika tidak digabungkan, teruskan tuple kosong () untuk referensi dan spesifikasi (0 daun PyTree).
  2. Gunakan jenis PyTree yang berbeda per mode fusi:
    • pltpu.emit_pipeline memetakan jax.tree.map(..., in_specs, in_refs), sehingga setiap container referensi input dan container in_spec-nya harus memiliki jenis PyTree @jax.tree_util.register_dataclass yang sama persis (misalnya, LhsRef[T] untuk lhs yang tidak digabungkan vs. FusedLhsRef[T] untuk lhs yang digabungkan dengan prolog).
  3. Mengevaluasi callback yang ditarik pada tile VMEM di dalam isi kernel:

    • Setiap fungsi yang ditarik memiliki tanda tangan fn(program_ids, scalar_prefetch, *args).
    • Di dalam pltpu.emit_pipeline(..., _explicit_indices=True), teruskan pids = step.index (jika tidak, tuple(pl.program_id(i) for i in range(grid_len))) dan () saat num_scalar_prefetch=0:
    # 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)
    

Kesalahan Umum

  • pl.BoundedSlice dan reshape: Aturan pull reshape Pallas Fuser menolak pl.BoundedSlice. Jika kernel yang tidak digabungkan membentuk ulang input HBM 2D menjadi ref ubin sublane 3D sebelum emit_pipeline, konversikan spesifikasi ke BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) 2D sebelum menarik atau mendorong melalui operand yang digabungkan (lihat _to_2d_bounded_spec di gmm_fuser.py).
  • Pengurutan epilog dengan masking baris: Jika kernel Anda menyamarkan baris di luar grup atau padding ke nol dan menggabungkan ubin subjalur parsial di seluruh langkah, jalankan out_fn sebelum menerapkan mask nol sehingga epilog non-nol (seperti + bias) tidak merusak baris yang disamarkan.
  • pl.kernel dengan Sequence out_type: pl.kernel mengekstrak tuple atau list out_type menjadi beberapa argumen out_ref posisi. Penggunaan fuser_adapter.unpack_output_fusion mempertahankan out_init output tunggal sebagai ShapeDtypeStruct kosong.
  • Padding sisi host vs. bentuk gabungan: Karena Pallas Fuser tidak memiliki aturan lax.pad atau aturan push/pull lax.slice yang tidak selaras, validasi persyaratan penyelarasan di awal metode prepare() spesifikasi penggabungan Anda dan naikkan NotImplementedError untuk bentuk yang tidak didukung, bukan objek Fusion padding.
  • Op helper di dalam _fusible_fwd: call_fusible_op menangguhkan in_op_fusion_context() selama resolusi default_config dan di dalam _fusible_fwd, sehingga memanggil Op helper yang tidak digabungkan di dalam _fusible_fwd akan menjalankan jalur _fwd normalnya tanpa memicu error penggabungan bertingkat.

Checklist Pengujian

Saat menambahkan dukungan penggabungan ke operator, cakup:

  1. Penggabungan prolog (reduksi pointwise dan sumbu penuh seperti RMSNorm), penggabungan epilog (dengan dan tanpa input samping eksternal seperti bias atau residual), dan penggabungan prolog + epilog.
  2. Paritas tanpa penggabungan: Memverifikasi bahwa memanggil titik entri yang dapat digabungkan tanpa operasi di sekitarnya (biasa, @op_fusion.fuse, dan @fuser.fuse) menghasilkan output yang identik secara bitwise (chex.assert_trees_all_equal) dengan kernel yang tidak digabungkan.
  3. Gradien @jax.custom_vjp eksplisit: Memverifikasi bahwa nilai dan gradien maju cocok dengan referensi yang tidak digabungkan.
  4. Kombinasi yang tidak didukung: Verifikasi pesan NotImplementedError yang jelas untuk bentuk yang tidak selaras atau opsi kernel yang tidak kompatibel.

Implementasi Referensi