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 mencakupgmm_v2forward/dlhs dantgmm_v2drhs). - 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, danreduce_sumdi seluruh sumbu blok penuh (sepertiRMSNorm). Operasi tanpa aturan spesifikasi blok fuser—sepertilax.pad, alur kontrol (scan/while/cond), danreduce_max/reduce_min—tidak dapat digabungkan. - Batasan penggabungan
PallasMosaicTpuV2RaggedDot:size_mharus diselaraskan dengan tiling sublane TPU (size_lhs_sublane) saatlhsatauoutdigabungkan dalamgmm_v2(dan saatlhsataurhsdigabungkan dalamtgmm_v2).- Saat
outdigabungkan,out_size_n(dansize_kuntuktgmm_v2) harus diselaraskan dengannum_lanes(128) / ukuran ubin, dan hanya epilog output tunggal yang didukung. partial_sumtidak didukung dengan fusi.rhsgabungan digmm_v2tidak didukung bersama denganfuse_actatau 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:
tokamax/ops/op_fusion.pymengekspor ulangfusesebagai titik entri publik.tokamax._src.ops.fuser_adaptermenetapkan flag konteks pengguna JAX (in_op_fusion_context()) di sekitarjax.experimental.pallas.fuser.fuse.- Saat
Op.__call__berjalan di dalam konteks tersebut, class ini akan memeriksa apakah subclass mengganti_fusible_fwd(meningkatkanNotImplementedErrorjika tidak) dan mendelegasikan kefuser_adapter.call_fusible_op. call_fusible_opmenangguhkan konteks fusi saat menyelesaikanbound_args.default_config, mengikat primitiffuser.fusibledi atas daun array, mewujudkan argumen apa pun yang tidak tercantum dalamOp.fusible_argnames, dan memanggilOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)di dalambound_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):
- Tetapkan
fusible_argnameske nama parameter yang daun array-nya harus tetap berupa closurefuser.Fusion. Semua argumen array lainnya (seperti metadata, indeks, ataugroup_sizes) otomatis diwujudkan menjadijax.Arrayreguler olehcall_fusible_opsebelum_fusible_fwdberjalan. - Ganti
_fusible_fwd. Tidak seperti_fwd(yang menampilkan(out, residuals)),_fusible_fwdmenampilkan outputTsecara langsung dan menerimaout_fusionsdanconfigyang di-resolve. - Untuk operand PyTree gabungan yang daunnya tidak boleh digabungkan (misalnya,
bobot
QArray(qvalue, scale)yang telah dikuantisasi sebelumnya), materialisasikan secara eksplisit denganfuser_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.fuserdi luar file kernel inti agar kernel yang tidak digabungkan tetap mandiri dan mudah dibaca. Buka penutupan
fuser.Fusiontrivial 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 xfuser.fusiblemenggabungkan setiap leaf array input dalamFusion, meskipun operand tersebut tidak memiliki operasi produsen. Membuka closure trivial akan mempertahankan operand yang tidak tersentuh pada jalurBlockSpecyang tidak digabungkan dan tidak dimodifikasi tanpa overhead runtime.Jika kernel dasar Anda dihiasi dengan
@jax.jit, panggilinspect.unwrap(base_kernel)pada jalur yang dapat digabungkan—@jax.jitmenolak argumenfuser.Fusion.Jika pemanggil bare-kernel juga harus dapat memanggil titik entri fusible Anda langsung di dalam
@fuser.fuse, deteksi panggilanjax.Arraybare dan ikatfuser.fusiblesecara otomatis (seperti yang dilakukangmm_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)denganvaluesadalah tuple array HBM yang ditutup oleh prolog danvalues_typemenyimpanShapeDtypeStruct-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 memunculkanNotImplementedErrorpada epilog multi-output.Menarik input
BlockSpecmundur 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
BlockSpecmelalui 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_specmenangani pengurangan yang mempertahankan bentuk dengan siaran ukuran 1 (seperti epilogRMSNormyang memicufuser.push_block_specmentah), memverifikasi bahwa spesifikasi yang ditarik cocok denganout_speckernel 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
- Teruskan input HBM yang diambil bersama dengan
BlockSpecyang ditarik:- Input prolog
valuesmenggantikan operand gabungan (yang dipasangkan denganlhs_val_specs). - Input samping epilog output (
out_values, seperti bias epilog atau residual) diteruskan sebagai input kernel HBM hanya baca yang dipasangkan denganout_fusion_input_specssehinggapltpu.emit_pipelinemengambil data ubinnya ke VMEM. Jika tidak digabungkan, teruskan tuple kosong()untuk referensi dan spesifikasi (0 daun PyTree).
- Input prolog
- Gunakan jenis PyTree yang berbeda per mode fusi:
pltpu.emit_pipelinememetakanjax.tree.map(..., in_specs, in_refs), sehingga setiap container referensi input dan containerin_spec-nya harus memiliki jenis PyTree@jax.tree_util.register_dataclassyang sama persis (misalnya,LhsRef[T]untuklhsyang tidak digabungkan vs.FusedLhsRef[T]untuklhsyang digabungkan dengan prolog).
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), teruskanpids = step.index(jika tidak,tuple(pl.program_id(i) for i in range(grid_len))) dan()saatnum_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)- Setiap fungsi yang ditarik memiliki tanda tangan
Kesalahan Umum
pl.BoundedSlicedanreshape: Aturan pull reshape Pallas Fuser menolakpl.BoundedSlice. Jika kernel yang tidak digabungkan membentuk ulang input HBM 2D menjadi ref ubin sublane 3D sebelumemit_pipeline, konversikan spesifikasi keBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)2D sebelum menarik atau mendorong melalui operand yang digabungkan (lihat_to_2d_bounded_specdigmm_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_fnsebelum menerapkan mask nol sehingga epilog non-nol (seperti+ bias) tidak merusak baris yang disamarkan. pl.kerneldenganSequenceout_type:pl.kernelmengekstraktupleataulistout_typemenjadi beberapa argumenout_refposisi. Penggunaanfuser_adapter.unpack_output_fusionmempertahankanout_initoutput tunggal sebagaiShapeDtypeStructkosong.- Padding sisi host vs. bentuk gabungan: Karena Pallas Fuser tidak memiliki aturan
lax.padatau aturan push/pulllax.sliceyang tidak selaras, validasi persyaratan penyelarasan di awal metodeprepare()spesifikasi penggabungan Anda dan naikkanNotImplementedErroruntuk bentuk yang tidak didukung, bukan objekFusionpadding. Ophelper di dalam_fusible_fwd:call_fusible_opmenangguhkanin_op_fusion_context()selama resolusidefault_configdan di dalam_fusible_fwd, sehingga memanggilOphelper yang tidak digabungkan di dalam_fusible_fwdakan menjalankan jalur_fwdnormalnya tanpa memicu error penggabungan bertingkat.
Checklist Pengujian
Saat menambahkan dukungan penggabungan ke operator, cakup:
- 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. - 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. - Gradien
@jax.custom_vjpeksplisit: Memverifikasi bahwa nilai dan gradien maju cocok dengan referensi yang tidak digabungkan. - Kombinasi yang tidak didukung: Verifikasi pesan
NotImplementedErroryang jelas untuk bentuk yang tidak selaras atau opsi kernel yang tidak kompatibel.
Implementasi Referensi
- Facade publik:
tokamax/ops/op_fusion.py Opdispatch dan helper bersama:tokamax/_src/ops/fuser_adapter.py- Integrasi fuser kernel (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py - Integrasi
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - Pengujian fusi kernel dan
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pydantokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py