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/dlhs gmm_v2 als auch drhs tgmm_v2 ab).
  • 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/split und reduce_sum über eine vollständige Blockachse (z. B. RMSNorm). Vorgänge ohne Fuser-Block-Spezifikationsregeln wie lax.pad, Kontrollfluss (scan/while/cond) und reduce_max/reduce_min können nicht zusammengeführt werden.
  • PallasMosaicTpuV2RaggedDot-Fusionsbeschränkungen:
    • size_m muss an der TPU-Sublane-Kachelung (size_lhs_sublane) ausgerichtet sein, wenn lhs oder out in gmm_v2 zusammengeführt wird (und wenn lhs oder rhs in tgmm_v2 zusammengeführt wird).
    • Wenn out zusammengeführt wird, müssen out_size_n (und size_k für tgmm_v2) an num_lanes (128) / Kachelgröße ausgerichtet sein. Es werden nur Epiloge mit einer einzelnen Ausgabe unterstützt.
    • partial_sum wird mit Fusion nicht unterstützt.
    • Zusammengeführte rhs in gmm_v2 werden nicht zusammen mit fuse_act oder 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:

  1. tokamax/ops/op_fusion.py exportiert fuse als öffentlichen Einstiegspunkt neu.
  2. tokamax._src.ops.fuser_adapter legt ein JAX-Nutzerkontext-Flag (in_op_fusion_context()) um jax.experimental.pallas.fuser.fuse fest.
  3. Wenn Op.__call__ in diesem Kontext ausgeführt wird, wird geprüft, ob die abgeleitete Klasse _fusible_fwd überschreibt (wenn nicht, wird NotImplementedError ausgelöst) und an fuser_adapter.call_fusible_op delegiert.
  4. call_fusible_op setzt den Fusionskontext aus, während bound_args.default_config aufgelöst wird, bindet ein fuser.fusible-Primitive über die Array-Blätter, materialisiert alle Argumente, die nicht in Op.fusible_argnames aufgeführt sind, und ruft Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) innerhalb von bound_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):

  1. Legen Sie für fusible_argnames die Parameternamen fest, deren Array-Blätter fuser.Fusion-Closures bleiben sollen. Alle anderen Array-Argumente (z. B. Metadaten, Indexe oder group_sizes) werden von call_fusible_op automatisch in reguläre jax.Arrays materialisiert, bevor _fusible_fwd ausgeführt wird.
  2. _fusible_fwd überschreiben. Im Gegensatz zu _fwd (gibt (out, residuals) zurück) gibt _fusible_fwd die Ausgabe T direkt zurück und empfängt out_fusions und die aufgelöste config.
  3. Für zusammengesetzte PyTree-Operanden, deren Blätter nicht zusammengeführt werden sollen (z. B. vorquantisierte QArray(qvalue, scale)-Gewichtungen), materialisieren Sie sie explizit mit 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
    )

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 x
    

    fuser.fusible umschließt jedes Blatt des Eingabearrays in einem Fusion, auch wenn dieser Operand keine Producer-Ops hat. Durch das Entpacken trivialer Closures bleiben unberührte Operanden auf dem unveränderten, nicht zusammengeführten BlockSpec-Pfad ohne Laufzeit-Overhead.

  • Wenn Ihr Basis-Kernel mit @jax.jit versehen ist, rufen Sie inspect.unwrap(base_kernel) im fusionierbaren Pfad auf. @jax.jit lehnt fuser.Fusion-Argumente ab.

  • Wenn Bare-Kernel-Aufrufer auch in der Lage sein sollen, Ihren fusionierbaren Einstiegspunkt direkt in @fuser.fuse aufzurufen, erkennen Sie Bare-jax.Array-Aufrufe und binden Sie fuser.fusible automatisch (wie es gmm_fuser.gmm_v2_fusible tut).

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, wobei values das Tupel von HBM-Arrays ist, die vom Prolog geschlossen werden, und values_type die zugehörigen ShapeDtypeStructs 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 Ausgaben NotImplementedError aus.

  • Eingabe BlockSpec durch 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_spec verarbeitet formwahrende Reduzierungen mit Broadcasts der Größe 1 (z. B. RMSNorm-Epiloge, die rohe fuser.push_block_spec auslösen), prüft, ob die abgerufene Spezifikation mit dem vom Kernel geschriebenen out_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

  1. Übergeben Sie die erfassten HBM-Eingaben zusammen mit den abgerufenen BlockSpecs:
    • Eingabeprolog values-Fahrt anstelle des zusammengeführten Operanden (gepaart mit lhs_val_specs).
    • Ausgabe-Epilog-Nebeneingaben (out_values, z. B. ein Epilog-Bias oder ein Residuum) werden als schreibgeschützte HBM-Kernel-Eingaben übergeben, die mit out_fusion_input_specs gekoppelt sind, sodass pltpu.emit_pipeline ihre Kacheln in den VMEM vorabruft. Wenn nicht zusammengeführt, übergeben Sie ein leeres Tupel () für Referenzen und Spezifikationen (0 PyTree-Blätter).
  2. Verwenden Sie unterschiedliche PyTree-Typen pro Zusammenführungsmodus:
    • pltpu.emit_pipeline ordnet jax.tree.map(..., in_specs, in_refs) zu, sodass jeder Eingabe-Ref-Container und sein in_spec-Container genau denselben @jax.tree_util.register_dataclass-PyTree-Typ haben müssen (z. B. LhsRef[T] für nicht fusionierte lhs im Vergleich zu FusedLhsRef[T] für Prolog-fusionierte lhs).
  3. 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 (andernfalls tuple(pl.program_id(i) for i in range(grid_len))) und (), wenn 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)
    

Häufige Fehler

  • pl.BoundedSlice und reshape: Die Reshape-Pull-Regel von Pallas Fuser lehnt pl.BoundedSlice ab. Wenn Ihr nicht fusionierter Kernel 2D-HBM-Eingaben vor emit_pipeline in 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_spec in gmm_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_fn vor dem Anwenden der Nullmaske aus, damit Epiloge, die nicht null sind (z. B. + bias), maskierte Zeilen nicht beschädigen.
  • pl.kernel mit Sequence out_type: pl.kernel entpackt ein tuple- oder list-out_type in mehrere Positionsargumente vom Typ out_ref. Wenn Sie fuser_adapter.unpack_output_fusion verwenden, bleibt die out_init mit einer einzelnen Ausgabe als einfache ShapeDtypeStruct erhalten.
  • Hostseitiges Padding im Vergleich zu verschmolzenen Formen: Da Pallas Fuser keine lax.pad-Regel oder nicht ausgerichtete lax.slice-Push/Pull-Regeln hat, sollten Sie die Ausrichtungsanforderungen frühzeitig in der prepare()-Methode Ihrer Verschmelzungsspezifikation validieren und NotImplementedError für nicht unterstützte Formen auslösen, anstatt Fusion-Objekte zu füllen.
  • Hilfs-Ops in _fusible_fwd: call_fusible_op setzt in_op_fusion_context() während der Auflösung von default_config und in _fusible_fwd aus. Wenn also ein nicht fusionierter Hilfs-Op in _fusible_fwd aufgerufen 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:

  1. Prolog-Fusion (punktweise und vollachsige Reduzierung wie RMSNorm), Epilog-Fusion (mit und ohne externe Nebeneingaben wie Bias oder Residuum) und kombinierter Prolog + Epilog.
  2. Parität ohne Fusion: Prüfen Sie, ob der Aufruf des fusionierbaren Einstiegspunkts ohne umgebende Vorgänge (einfach, @op_fusion.fuse und @fuser.fuse) eine bitweise identische Ausgabe (chex.assert_trees_all_equal) wie der nicht fusionierte Kernel erzeugt.
  3. Explizite @jax.custom_vjp-Gradienten: Prüfen Sie, ob die Vorwärtswerte und Gradienten mit der nicht fusionierten Referenz übereinstimmen.
  4. Nicht unterstützte Kombinationen: Prüfen Sie, ob klare NotImplementedError-Meldungen für nicht ausgerichtete Formen oder inkompatible Kernel-Optionen vorhanden sind.

Referenzimplementierung