Fusione degli operatori

tokamax.ops.op_fusion ti consente di unire le operazioni JAX circostanti (prologhi ed epiloghi) direttamente in un kernel TPU Tokamax Pallas unibile tramite JAX Pallas Fuser. Invece di materializzare le attivazioni intermedie in HBM tra una normalizzazione o un'attivazione e un kernel personalizzato, le operazioni fuse vengono eseguite in VMEM su ogni tile all'interno del loop del kernel.

In uso: @op_fusion.fuse

Utilizzo di base (prologo ed epilogo)

Importa op_fusion da tokamax.ops e aggrega la funzione contenente un operatore Tokamax fusibile con @op_fusion.fuse (in genere all'interno di @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)

Puoi chiamare l'API funzionale di alto livello con un'implementazione fusibile esplicita (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) o un'istanza tokamax.Op specifica direttamente (ad esempio PallasMosaicTpuV2RaggedDot). Se un operatore all'interno di @op_fusion.fuse non supporta la fusione, Tokamax genera NotImplementedError.

Opzioni di decorazione

op_fusion.fuse inoltra i suoi argomenti delle parole chiave a 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: contrassegna gli argomenti Python non array (ad esempio valori di configurazione scalari o flag booleani) come statici quando chiami una funzione fusa.
  • debug=True: stampa i jaxpr di fusione tracciati per diagnosticare il motivo per cui un'operazione non è stata fusa o non è riuscita la propagazione della specifica del blocco.
  • strict_mode: controlla i controlli di equivalenza rigorosi delle specifiche dei blocchi di Pallas Fuser.

Input quantizzati e attivazioni del kernel integrate

I prologhi fusi si compongono con la quantizzazione dell'attivazione on-the-fly (AsQArray), i pesi pre-quantizzati (qwix.QArray) e le attivazioni gate/up fuse integrate su 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,
  )

Un'operazione fusibile per blocco @op_fusion.fuse

JAX Pallas Fuser supporta un singolo kernel fusibile per ambito @op_fusion.fuse. Quando concateni più kernel (ad esempio, gate_up seguito da down in un blocco MoE), racchiudi ogni fase fusibile nella propria funzione @op_fusion.fuse all'interno di un @jax.jit esterno:

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

Differenziazione automatica con @jax.custom_vjp esplicito

@op_fusion.fuse unisce il blocco di calcolo in avanti e non sintetizza automaticamente i passaggi all'indietro uniti tramite jax.grad. Quando differenzi un blocco fuso, racchiudi le chiamate forward e backward in un @jax.custom_vjp esplicito in modo da poter fondere i prologhi/epiloghi nei kernel forward e backward (drhs/dlhs) in modo indipendente:

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)

Utilizzo di Bare Fusible Kernels

Preferisci @op_fusion.fuse con wrapper degli operatori Tokamax (tokamax.ragged_dot o PallasMosaicTpuV2RaggedDot) rispetto ai kernel fusibili nudi e @jax.experimental.pallas.fuser.fuse per mantenere la compatibilità con le versioni precedenti e conservare la canonicalizzazione degli input, l'ottimizzazione automatica e la serializzazione dei metadati. Se richiami direttamente i kernel gmm_v2/tgmm_v2 di basso livello, utilizza gmm_fuser.gmm_v2_fusible o gmm_fuser.tgmm_v2_fusible all'interno di @op_fusion.fuse o @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)

Quando non sono presenti operazioni di prologo o epilogo intorno a gmm_v2_fusible/tgmm_v2_fusible, le fusioni banali di 0 equazioni vengono scompattate in modo che il kernel compilato segua il percorso esatto non fuso.

Operazioni e vincoli supportati

  • Operazioni Tokamax attualmente supportate: PallasMosaicTpuV2RaggedDot (implementation="mosaic_tpu_v2", che copre sia forward/dlhs gmm_v2 sia drhs tgmm_v2).
  • Primitive JAX di prologo/epilogo supportate: gestite da JAX Pallas Fuser. Le operazioni comunemente supportate includono operazioni matematiche unarie/binarie puntuali, select/clamp, cast dtype, broadcast_in_dim, transpose, concatenate/stack/split e reduce_sum su un intero asse del blocco (ad esempio RMSNorm). Le operazioni senza regole di specifica del blocco del fuser, come lax.pad, flusso di controllo (scan/while/cond) e reduce_max/reduce_min, non possono essere fuse.
  • Vincoli di fusione di PallasMosaicTpuV2RaggedDot:
    • size_m deve essere allineato al tiling della sublane TPU (size_lhs_sublane) quando lhs o out è fuso in gmm_v2 (e quando lhs o rhs è fuso in tgmm_v2).
    • Quando out è fuso, out_size_n (e size_k per tgmm_v2) deve essere allineato a num_lanes (128) / dimensione tile e sono supportati solo gli epiloghi con un singolo output.
    • partial_sum non è supportato con la fusione.
    • rhs fuso in gmm_v2 non è supportato insieme a fuse_act o pesi compressi in sub-byte.

Creazione di un kernel e di un'operazione compatibili con la fusione

Panoramica dell'architettura

Il dispatch di Fusion è suddiviso tra la facciata pubblica, l'adattatore interno, la classe Op e il modulo fuser associato del kernel:

  1. tokamax/ops/op_fusion.py riesporta fuse come entry point pubblico.
  2. tokamax._src.ops.fuser_adapter imposta un flag di contesto utente JAX (in_op_fusion_context()) intorno a jax.experimental.pallas.fuser.fuse.
  3. Quando Op.__call__ viene eseguito in questo contesto, verifica se la sottoclasse esegue l'override di _fusible_fwd (generando NotImplementedError in caso contrario) e delega a fuser_adapter.call_fusible_op.
  4. call_fusible_op sospende il contesto di fusione durante la risoluzione di bound_args.default_config, associa una primitiva fuser.fusible sulle foglie dell'array, materializza qualsiasi argomento non elencato in Op.fusible_argnames e richiama Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) all'interno di bound_args._tokamax_metadata(config).

Passaggio 1: dichiara fusible_argnames ed esegui l'override di _fusible_fwd su Op

Nella sottoclasse Op del backend (consulta PallasMosaicTpuV2RaggedDot per un riferimento completo):

  1. Imposta fusible_argnames sui nomi dei parametri le cui foglie dell'array devono rimanere chiusure fuser.Fusion. Tutti gli altri argomenti dell'array (come metadati, indici o group_sizes) vengono materializzati automaticamente in jax.Array normali da call_fusible_op prima dell'esecuzione di _fusible_fwd.
  2. Esegui l'override di _fusible_fwd. A differenza di _fwd (che restituisce (out, residuals)), _fusible_fwd restituisce direttamente l'output T e riceve out_fusions e il config risolto.
  3. Per gli operandi PyTree compositi le cui foglie non devono essere fuse (ad esempio, pesi QArray(qvalue, scale) pre-quantizzati), materializzali esplicitamente con 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
    )

Passaggio 2: mantieni l'integrazione del fuser in un modulo *_fuser.py companion

Segui la separazione di Tokamax tra il kernel principale (gmm_v2.py, tgmm_v2.py) e la sua integrazione con il fuser (gmm_fuser.py):

  • Tieni le importazioni di jax.experimental.pallas.fuser fuori dal file del kernel principale in modo che il kernel non fuso rimanga autonomo e facile da leggere.
  • Scompatta le chiusure fuser.Fusion banali con 0 equazioni prima di creare la specifica di fusione:

    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 esegue il wrapping di ogni foglia dell'array di input in un Fusion, anche quando l'operando non ha operazioni di produzione. L'unwrapping delle chiusure semplici mantiene gli operandi invariati nel percorso BlockSpec non modificato e non fuso, con un overhead di runtime pari a zero.

  • Se il kernel di base è decorato con @jax.jit, chiama inspect.unwrap(base_kernel) sul percorso fusibile: @jax.jit rifiuta gli argomenti fuser.Fusion.

  • Se i chiamanti bare-kernel devono anche essere in grado di richiamare l'entrypoint fusibile direttamente all'interno di @fuser.fuse, rileva le chiamate jax.Array bare e associa fuser.fusible automaticamente (come fa gmm_fuser.gmm_v2_fusible).

Passaggio 3: apri le Fusioni e trasforma i BlockSpec con fuser_adapter

Utilizza gli helper condivisi in tokamax._src.ops.fuser_adapter anziché chiamare direttamente le API fuser di basso livello:

  • Unpack an input prologue:

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

    Restituisce (fn, values, values_type) dove values è la tupla degli array HBM chiusi dal prologo e values_type contiene i relativi ShapeDtypeStruct.

  • Unpack a single-output epilogue:

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

    Unwraps Pallas Fuser's 1-tuple output convention into a single ShapeDtypeStruct (out_init) and raises NotImplementedError on multi-output epilogues.

  • Esegui il pull di un input BlockSpec all'indietro attraverso un prologo:

    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,
    )
    
  • Esegui il push e il pull di un output BlockSpec tramite un epilogo:

    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 gestisce le riduzioni che preservano la forma con broadcast di dimensione 1 (ad esempio gli epiloghi RMSNorm che attivano fuser.push_block_spec non elaborati), verifica che la specifica estratta corrisponda al out_spec scritto del kernel, annulla l'unwrapping del valore restituito della tupla di 1 elemento e mantiene la compatibilità tra le release JAX supportate.

Passaggio 4: collega le specifiche e i callback estratti al kernel Pallas

  1. Passa gli input HBM acquisiti insieme ai relativi BlockSpec estratti:
    • Input prologue values ride in place of the fused operand (paired with lhs_val_specs).
    • Gli input laterali dell'epilogo di output (out_values, ad esempio un bias o un residuo dell'epilogo) vengono passati come input del kernel HBM di sola lettura accoppiati a out_fusion_input_specs, in modo che pltpu.emit_pipeline esegua il precaricamento dei relativi tile in VMEM. Quando non sono fuse, passa una tupla vuota () sia per i riferimenti che per le specifiche (0 foglie PyTree).
  2. Utilizza tipi PyTree distinti per modalità di fusione:
    • pltpu.emit_pipeline mappa jax.tree.map(..., in_specs, in_refs), quindi ogni container di riferimento di input e il relativo container in_spec devono condividere lo stesso tipo di PyTree @jax.tree_util.register_dataclass (ad esempio, LhsRef[T] per lhs non fuso rispetto a FusedLhsRef[T] per lhs fuso con prologo).
  3. Valuta i callback estratti sui tile VMEM all'interno del corpo del kernel:

    • Ogni funzione estratta ha la firma fn(program_ids, scalar_prefetch, *args).
    • All'interno di pltpu.emit_pipeline(..., _explicit_indices=True), passa pids = step.index (altrimenti tuple(pl.program_id(i) for i in range(grid_len))) e () quando 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)
    

Errori comuni

  • pl.BoundedSlice e reshape: la regola di pull di rimodellamento di Pallas Fuser rifiuta pl.BoundedSlice. Se il kernel non fuso rimodella gli input HBM 2D in riferimenti con tiling in sottocorsie 3D prima di emit_pipeline, converti la specifica in un BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) 2D prima di eseguire il pull o il push tramite operandi fusi (vedi _to_2d_bounded_spec in gmm_fuser.py).
  • Ordinamento dell'epilogo con mascheramento delle righe: se il kernel maschera le righe esterne al gruppo o di spaziatura interna impostandole su zero e combina i tile di sublane parziali tra i passaggi, esegui out_fn prima di applicare la maschera zero in modo che gli epiloghi diversi da zero (come + bias) non danneggino le righe mascherate.
  • pl.kernel con Sequence out_type: pl.kernel scompatta un tuple o list out_type in più argomenti out_ref posizionali. L'utilizzo di fuser_adapter.unpack_output_fusion mantiene out_init con un singolo output come ShapeDtypeStruct semplice.
  • Padding lato host e forme fuse: poiché Pallas Fuser non ha una regola lax.pad o regole di push/pull lax.slice non allineate, convalida i requisiti di allineamento in anticipo nel metodo prepare() della specifica di fusione e genera NotImplementedError per le forme non supportate anziché eseguire il padding degli oggetti Fusion.
  • Op helper all'interno di _fusible_fwd: call_fusible_op sospende in_op_fusion_context() durante la risoluzione di default_config e all'interno di _fusible_fwd, quindi la chiamata a un Op helper non fuso all'interno di _fusible_fwd esegue il suo percorso _fwd normale senza attivare errori di fusione nidificati.

Elenco di controllo per i test

Quando aggiungi il supporto della fusione a un operatore, copri:

  1. Fusione del prologo (riduzione puntuale e su tutto l'asse come RMSNorm), fusione dell'epilogo (con e senza input esterni come bias o residuo) e prologo + epilogo combinati.
  2. No-fusion parity: verifica che la chiamata all'entrypoint fusibile senza operazioni circostanti (plain, @op_fusion.fuse e @fuser.fuse) produca un output bitwise-identical (chex.assert_trees_all_equal) rispetto al kernel non fuso.
  3. Gradienti @jax.custom_vjp espliciti: verifica che i valori e i gradienti in avanti corrispondano al riferimento non fuso.
  4. Combinazioni non supportate: verifica i messaggi NotImplementedError chiari per forme non allineate o opzioni del kernel incompatibili.

Implementazione dei riferimenti