Operator Fusion
Mit tokamax.ops.op_fusion können Sie umgebende JAX-Vorgänge (Prologe und Epiloge) über JAX Pallas Fuser direkt in einen fusionierbaren Tokamax Pallas-TPU-Kernel einbinden.
Anstatt Zwischenaktivierungen zwischen einer Normalisierung oder Aktivierung und einem benutzerdefinierten Kernel in HBM zu materialisieren, werden die fusionierten Vorgänge in VMEM auf jeder Kachel innerhalb der Kernelschleife ausgeführt.
@op_fusion.fuse verwenden
Grundlegende Verwendung (Prolog und Epilog)
Importieren Sie op_fusion aus tokamax.ops und umschließen Sie die Funktion, die einen fusionierbaren Tokamax-Operator enthält, mit @op_fusion.fuse (normalerweise innerhalb von @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)
Sie können entweder die allgemeine funktionale API mit einer expliziten fusionierbaren Implementierung (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) oder eine bestimmte tokamax.Op-Instanz direkt aufrufen (z. B. PallasMosaicTpuV2RaggedDot). Wenn ein Operator in @op_fusion.fuse die Fusion nicht unterstützt, löst Tokamax NotImplementedError aus.
Decorator-Optionen
op_fusion.fuse leitet seine Keyword-Argumente an jax.experimental.pallas.fuser.fuse weiter:
@op_fusion.fuse(
resolve_fusion_dtypes=True,
debug=False,
strict_mode=True,
static_argnums=None,
static_argnames=None,
)
static_argnums/static_argnames: Markieren Sie Python-Argumente, die keine Arrays sind (z. B. skalare Konfigurationswerte oder boolesche Flags), als statisch, wenn Sie eine fusionierte Funktion aufrufen.debug=True: Gibt die verfolgten Fusion-Jaxprs aus, um zu diagnostizieren, warum ein Vorgang nicht fusioniert wurde oder die Block-Spec-Weitergabe fehlgeschlagen ist.strict_mode: Steuert die strengen Block-Spezifikations-Äquivalenzprüfungen von Pallas Fuser.
Quantisierte Eingaben und integrierte Kernel-Aktivierungen
Fused Prologues werden mit On-the-Fly-Aktivierungsquantisierung (AsQArray), vorquantisierten Gewichtungen (qwix.QArray) und integrierten Fused Gate-/Up-Aktivierungen auf PallasMosaicTpuV2RaggedDot kombiniert:
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,
)
Ein Fusible Op pro @op_fusion.fuse-Block
Der JAX Pallas Fuser unterstützt einen einzelnen fusionierbaren Kernel pro @op_fusion.fuse-Bereich.
Wenn Sie mehrere Kernel verketten (z. B. gate_up gefolgt von down in einem MoE-Block), schließen Sie jede fusionierbare Phase in eine eigene @op_fusion.fuse-Funktion innerhalb einer äußeren @jax.jit ein:
@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,
)
Automatische Differenzierung mit explizitem @jax.custom_vjp
@op_fusion.fuse fusioniert den Vorwärtsberechnungsblock und synthetisiert nicht automatisch fusionierte Rückwärtsdurchläufe über jax.grad. Wenn Sie einen verschmolzenen Block differenzieren, umschließen Sie die Vorwärts- und Rückwärtsaufrufe in einem expliziten @jax.custom_vjp, damit Sie Prologe/Epiloge unabhängig voneinander in die Vorwärts- und Rückwärtskerne (drhs / dlhs) verschmelzen können:
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 Kernels verwenden
Bevorzugen Sie @op_fusion.fuse mit Tokamax-Operator-Wrappern (tokamax.ragged_dot oder PallasMosaicTpuV2RaggedDot) gegenüber reinen fusionierbaren Kernels und @jax.experimental.pallas.fuser.fuse, um die Abwärtskompatibilität aufrechtzuerhalten und die Eingabekanonisierung, das Autotuning und die Metadatenserialisierung beizubehalten. Wenn Sie Low-Level-gmm_v2- oder tgmm_v2-Kernel direkt aufrufen, verwenden Sie gmm_fuser.gmm_v2_fusible oder gmm_fuser.tgmm_v2_fusible innerhalb von @op_fusion.fuse oder @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)
Wenn keine Prolog- oder Epilog-Vorgänge um gmm_v2_fusible / tgmm_v2_fusible herum vorhanden sind, werden triviale 0-Gleichungs-Fusionen entpackt, sodass der kompilierte Kernel den genauen nicht fusionierten Pfad nimmt.
Unterstützte Vorgänge und Einschränkungen
- Derzeit unterstützte Tokamax-Vorgänge:
PallasMosaicTpuV2RaggedDot(implementation="mosaic_tpu_v2", deckt sowohl Forward/dlhsgmm_v2als auch drhstgmm_v2ab). - Unterstützte Prolog-/Epilog-JAX-Primitive: Werden von JAX Pallas Fuser gesteuert.
Zu den häufig unterstützten Vorgängen gehören punktweise unäre/binäre Mathematik,
select/clamp, dtype-Casts,broadcast_in_dim,transpose,concatenate/stack/splitundreduce_sumüber eine vollständige Blockachse (z. B.RMSNorm). Vorgänge ohne Fuser-Block-Spezifikationsregeln wielax.pad, Kontrollfluss (scan/while/cond) undreduce_max/reduce_minkönnen nicht zusammengeführt werden. PallasMosaicTpuV2RaggedDot-Fusionsbeschränkungen:size_mmuss an der TPU-Sublane-Kachelung (size_lhs_sublane) ausgerichtet sein, wennlhsoderoutingmm_v2zusammengeführt wird (und wennlhsoderrhsintgmm_v2zusammengeführt wird).- Wenn
outzusammengeführt wird, müssenout_size_n(undsize_kfürtgmm_v2) annum_lanes(128) / Kachelgröße ausgerichtet sein. Es werden nur Epiloge mit einer einzelnen Ausgabe unterstützt. partial_sumwird mit Fusion nicht unterstützt.- Zusammengeführte
rhsingmm_v2werden nicht zusammen mitfuse_actoder gepackten Sub-Byte-Gewichtungen unterstützt.
Fusion-kompatiblen Kernel und Vorgang erstellen
Überblick über die Architektur
Die Fusion-Verteilung ist auf die öffentliche Fassade, den internen Adapter, die Klasse Op und das Companion-Fuser-Modul des Kernels aufgeteilt:
tokamax/ops/op_fusion.pyexportiertfuseals öffentlichen Einstiegspunkt neu.tokamax._src.ops.fuser_adapterlegt ein JAX-Nutzerkontext-Flag (in_op_fusion_context()) umjax.experimental.pallas.fuser.fusefest.- Wenn
Op.__call__in diesem Kontext ausgeführt wird, wird geprüft, ob die abgeleitete Klasse_fusible_fwdüberschreibt (wenn nicht, wirdNotImplementedErrorausgelöst) und anfuser_adapter.call_fusible_opdelegiert. call_fusible_opsetzt den Fusionskontext aus, währendbound_args.default_configaufgelöst wird, bindet einfuser.fusible-Primitive über die Array-Blätter, materialisiert alle Argumente, die nicht inOp.fusible_argnamesaufgeführt sind, und ruftOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)innerhalb vonbound_args._tokamax_metadata(config)auf.
Schritt 1: fusible_argnames deklarieren und _fusible_fwd in der Op überschreiben
In der Backend-Unterklasse Op (eine vollständige Referenz finden Sie unter PallasMosaicTpuV2RaggedDot):
- Legen Sie für
fusible_argnamesdie Parameternamen fest, deren Array-Blätterfuser.Fusion-Closures bleiben sollen. Alle anderen Array-Argumente (z. B. Metadaten, Indexe odergroup_sizes) werden voncall_fusible_opautomatisch in regulärejax.Arrays materialisiert, bevor_fusible_fwdausgeführt wird. _fusible_fwdüberschreiben. Im Gegensatz zu_fwd(gibt(out, residuals)zurück) gibt_fusible_fwddie AusgabeTdirekt zurück und empfängtout_fusionsund die aufgelösteconfig.- Für zusammengesetzte PyTree-Operanden, deren Blätter nicht zusammengeführt werden sollen (z. B. vorquantisierte
QArray(qvalue, scale)-Gewichtungen), materialisieren Sie sie explizit mitfuser_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
)
Schritt 2: Fuser-Integration in einem Companion-*_fuser.py-Modul beibehalten
Folgen Sie der Trennung von Tokamax zwischen dem Kern-Kernel (gmm_v2.py, tgmm_v2.py) und der Fuser-Integration (gmm_fuser.py):
- Halten Sie
jax.experimental.pallas.fuser-Importe aus der Kern-Kernel-Datei heraus, damit der nicht fusionierte Kernel eigenständig und leicht lesbar bleibt. Entpacken Sie triviale
fuser.Fusion-Schließungen mit 0 Gleichungen, bevor Sie die Fusionsspezifikation erstellen:def _unwrap_trivial_input_fusion(x): if isinstance(x, fuser.Fusion) and not jax.make_jaxpr(x)().jaxpr.eqns: return x() return xfuser.fusibleumschließt jedes Blatt des Eingabearrays in einemFusion, auch wenn dieser Operand keine Producer-Ops hat. Durch das Entpacken trivialer Closures bleiben unberührte Operanden auf dem unveränderten, nicht zusammengeführtenBlockSpec-Pfad ohne Laufzeit-Overhead.Wenn Ihr Basis-Kernel mit
@jax.jitversehen ist, rufen Sieinspect.unwrap(base_kernel)im fusionierbaren Pfad auf.@jax.jitlehntfuser.Fusion-Argumente ab.Wenn Bare-Kernel-Aufrufer auch in der Lage sein sollen, Ihren fusionierbaren Einstiegspunkt direkt in
@fuser.fuseaufzurufen, erkennen Sie Bare-jax.Array-Aufrufe und binden Siefuser.fusibleautomatisch (wie esgmm_fuser.gmm_v2_fusibletut).
Schritt 3: Fusions entpacken und BlockSpecs mit fuser_adapter transformieren
Verwenden Sie die freigegebenen Hilfsprogramme in tokamax._src.ops.fuser_adapter, anstatt Low-Level-fuser-APIs direkt aufzurufen:
Eingabeprolog entpacken:
lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)Gibt
(fn, values, values_type)zurück, wobeivaluesdas Tupel von HBM-Arrays ist, die vom Prolog geschlossen werden, undvalues_typedie zugehörigenShapeDtypeStructs enthält.Epilog mit einer einzelnen Ausgabe entpacken:
out_fn, out_values, out_values_type, out_init = ( fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type) )Entpackt die 1-Tupel-Ausgabekonvention von Pallas Fuser in ein einzelnes
ShapeDtypeStruct(out_init) und löst bei Epilogen mit mehreren AusgabenNotImplementedErroraus.Eingabe
BlockSpecdurch einen Prolog zurückziehen: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, )Ausgabe
BlockSpecüber einen Epilog übertragen und abrufen: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_specverarbeitet formwahrende Reduzierungen mit Broadcasts der Größe 1 (z. B.RMSNorm-Epiloge, die rohefuser.push_block_specauslösen), prüft, ob die abgerufene Spezifikation mit dem vom Kernel geschriebenenout_specübereinstimmt, entpackt den Rückgabewert des 1-Tupels und sorgt für Kompatibilität zwischen unterstützten JAX-Releases.
Schritt 4: Abgerufene Spezifikationen und Callbacks in den Pallas-Kernel einbinden
- Übergeben Sie die erfassten HBM-Eingaben zusammen mit den abgerufenen
BlockSpecs:- Eingabeprolog
values-Fahrt anstelle des zusammengeführten Operanden (gepaart mitlhs_val_specs). - Ausgabe-Epilog-Nebeneingaben (
out_values, z. B. ein Epilog-Bias oder ein Residuum) werden als schreibgeschützte HBM-Kernel-Eingaben übergeben, die mitout_fusion_input_specsgekoppelt sind, sodasspltpu.emit_pipelineihre Kacheln in den VMEM vorabruft. Wenn nicht zusammengeführt, übergeben Sie ein leeres Tupel()für Referenzen und Spezifikationen (0 PyTree-Blätter).
- Eingabeprolog
- Verwenden Sie unterschiedliche PyTree-Typen pro Zusammenführungsmodus:
pltpu.emit_pipelineordnetjax.tree.map(..., in_specs, in_refs)zu, sodass jeder Eingabe-Ref-Container und seinin_spec-Container genau denselben@jax.tree_util.register_dataclass-PyTree-Typ haben müssen (z. B.LhsRef[T]für nicht fusioniertelhsim Vergleich zuFusedLhsRef[T]für Prolog-fusioniertelhs).
Bewerten Sie die abgerufenen Callbacks auf VMEM-Kacheln im Kernel-Body:
- Jede abgerufene Funktion hat die Signatur
fn(program_ids, scalar_prefetch, *args). - Übergeben Sie in
pltpu.emit_pipeline(..., _explicit_indices=True)pids = step.index(andernfallstuple(pl.program_id(i) for i in range(grid_len))) und(), wennnum_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)- Jede abgerufene Funktion hat die Signatur
Häufige Fehler
pl.BoundedSliceundreshape: Die Reshape-Pull-Regel von Pallas Fuser lehntpl.BoundedSliceab. Wenn Ihr nicht fusionierter Kernel 2D-HBM-Eingaben voremit_pipelinein 3D-Sublane-Tiled-Referenzen umformt, konvertieren Sie die Spezifikation in eine 2D-BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...), bevor Sie sie durch fusionierte Operanden ziehen oder schieben (siehe_to_2d_bounded_specingmm_fuser.py).- Epilog-Reihenfolge mit Zeilenmaskierung: Wenn Ihr Kernel Zeilen außerhalb der Gruppe oder Padding-Zeilen auf null maskiert und Teil-Sublane-Kacheln über Schritte hinweg kombiniert, führen Sie
out_fnvor dem Anwenden der Nullmaske aus, damit Epiloge, die nicht null sind (z. B.+ bias), maskierte Zeilen nicht beschädigen. pl.kernelmitSequenceout_type:pl.kernelentpackt eintuple- oderlist-out_typein mehrere Positionsargumente vom Typout_ref. Wenn Siefuser_adapter.unpack_output_fusionverwenden, bleibt dieout_initmit einer einzelnen Ausgabe als einfacheShapeDtypeStructerhalten.- Hostseitiges Padding im Vergleich zu verschmolzenen Formen: Da Pallas Fuser keine
lax.pad-Regel oder nicht ausgerichtetelax.slice-Push/Pull-Regeln hat, sollten Sie die Ausrichtungsanforderungen frühzeitig in derprepare()-Methode Ihrer Verschmelzungsspezifikation validieren undNotImplementedErrorfür nicht unterstützte Formen auslösen, anstattFusion-Objekte zu füllen. - Hilfs-
Ops in_fusible_fwd:call_fusible_opsetztin_op_fusion_context()während der Auflösung vondefault_configund in_fusible_fwdaus. Wenn also ein nicht fusionierter Hilfs-Opin_fusible_fwdaufgerufen wird, wird der normale_fwd-Pfad ausgeführt, ohne dass verschachtelte Fusionsfehler ausgelöst werden.
Checkliste für Tests
Wenn Sie einem Operator Unterstützung für die Zusammenführung hinzufügen, sollten Sie Folgendes berücksichtigen:
- Prolog-Fusion (punktweise und vollachsige Reduzierung wie
RMSNorm), Epilog-Fusion (mit und ohne externe Nebeneingaben wie Bias oder Residuum) und kombinierter Prolog + Epilog. - Parität ohne Fusion: Prüfen Sie, ob der Aufruf des fusionierbaren Einstiegspunkts ohne umgebende Vorgänge (einfach,
@op_fusion.fuseund@fuser.fuse) eine bitweise identische Ausgabe (chex.assert_trees_all_equal) wie der nicht fusionierte Kernel erzeugt. - Explizite
@jax.custom_vjp-Gradienten: Prüfen Sie, ob die Vorwärtswerte und Gradienten mit der nicht fusionierten Referenz übereinstimmen. - Nicht unterstützte Kombinationen: Prüfen Sie, ob klare
NotImplementedError-Meldungen für nicht ausgerichtete Formen oder inkompatible Kernel-Optionen vorhanden sind.
Referenzimplementierung
- Öffentliche Fassade:
tokamax/ops/op_fusion.py Op-Dispatch und freigegebene Hilfsprogramme:tokamax/_src/ops/fuser_adapter.py- Kernel-Fuser-Integration (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py Op._fusible_fwd-Integration:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py- Kernel- und
Op-Fusionstests:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyundtokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py