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/dlhsgmm_v2sia drhstgmm_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/splitereduce_sumsu un intero asse del blocco (ad esempioRMSNorm). Le operazioni senza regole di specifica del blocco del fuser, comelax.pad, flusso di controllo (scan/while/cond) ereduce_max/reduce_min, non possono essere fuse. - Vincoli di fusione di
PallasMosaicTpuV2RaggedDot:size_mdeve essere allineato al tiling della sublane TPU (size_lhs_sublane) quandolhsooutè fuso ingmm_v2(e quandolhsorhsè fuso intgmm_v2).- Quando
outè fuso,out_size_n(esize_kpertgmm_v2) deve essere allineato anum_lanes(128) / dimensione tile e sono supportati solo gli epiloghi con un singolo output. partial_sumnon è supportato con la fusione.rhsfuso ingmm_v2non è supportato insieme afuse_acto 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:
tokamax/ops/op_fusion.pyriesportafusecome entry point pubblico.tokamax._src.ops.fuser_adapterimposta un flag di contesto utente JAX (in_op_fusion_context()) intorno ajax.experimental.pallas.fuser.fuse.- Quando
Op.__call__viene eseguito in questo contesto, verifica se la sottoclasse esegue l'override di_fusible_fwd(generandoNotImplementedErrorin caso contrario) e delega afuser_adapter.call_fusible_op. call_fusible_opsospende il contesto di fusione durante la risoluzione dibound_args.default_config, associa una primitivafuser.fusiblesulle foglie dell'array, materializza qualsiasi argomento non elencato inOp.fusible_argnamese richiamaOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)all'interno dibound_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):
- Imposta
fusible_argnamessui nomi dei parametri le cui foglie dell'array devono rimanere chiusurefuser.Fusion. Tutti gli altri argomenti dell'array (come metadati, indici ogroup_sizes) vengono materializzati automaticamente injax.Arraynormali dacall_fusible_opprima dell'esecuzione di_fusible_fwd. - Esegui l'override di
_fusible_fwd. A differenza di_fwd(che restituisce(out, residuals)),_fusible_fwdrestituisce direttamente l'outputTe riceveout_fusionse ilconfigrisolto. - Per gli operandi PyTree compositi le cui foglie non devono essere fuse (ad esempio,
pesi
QArray(qvalue, scale)pre-quantizzati), materializzali esplicitamente confuser_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.fuserfuori dal file del kernel principale in modo che il kernel non fuso rimanga autonomo e facile da leggere. Scompatta le chiusure
fuser.Fusionbanali 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 xfuser.fusibleesegue il wrapping di ogni foglia dell'array di input in unFusion, anche quando l'operando non ha operazioni di produzione. L'unwrapping delle chiusure semplici mantiene gli operandi invariati nel percorsoBlockSpecnon modificato e non fuso, con un overhead di runtime pari a zero.Se il kernel di base è decorato con
@jax.jit, chiamainspect.unwrap(base_kernel)sul percorso fusibile:@jax.jitrifiuta gli argomentifuser.Fusion.Se i chiamanti bare-kernel devono anche essere in grado di richiamare l'entrypoint fusibile direttamente all'interno di
@fuser.fuse, rileva le chiamatejax.Arraybare e associafuser.fusibleautomaticamente (come fagmm_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)dovevaluesè la tupla degli array HBM chiusi dal prologo evalues_typecontiene i relativiShapeDtypeStruct.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 raisesNotImplementedErroron multi-output epilogues.Esegui il pull di un input
BlockSpecall'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
BlockSpectramite 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_specgestisce le riduzioni che preservano la forma con broadcast di dimensione 1 (ad esempio gli epiloghiRMSNormche attivanofuser.push_block_specnon elaborati), verifica che la specifica estratta corrisponda alout_specscritto 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
- Passa gli input HBM acquisiti insieme ai relativi
BlockSpecestratti:- Input prologue
valuesride in place of the fused operand (paired withlhs_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 aout_fusion_input_specs, in modo chepltpu.emit_pipelineesegua 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).
- Input prologue
- Utilizza tipi PyTree distinti per modalità di fusione:
pltpu.emit_pipelinemappajax.tree.map(..., in_specs, in_refs), quindi ogni container di riferimento di input e il relativo containerin_specdevono condividere lo stesso tipo di PyTree@jax.tree_util.register_dataclass(ad esempio,LhsRef[T]perlhsnon fuso rispetto aFusedLhsRef[T]perlhsfuso con prologo).
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), passapids = step.index(altrimentituple(pl.program_id(i) for i in range(grid_len))) e()quandonum_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)- Ogni funzione estratta ha la firma
Errori comuni
pl.BoundedSliceereshape: la regola di pull di rimodellamento di Pallas Fuser rifiutapl.BoundedSlice. Se il kernel non fuso rimodella gli input HBM 2D in riferimenti con tiling in sottocorsie 3D prima diemit_pipeline, converti la specifica in unBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)2D prima di eseguire il pull o il push tramite operandi fusi (vedi_to_2d_bounded_specingmm_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_fnprima di applicare la maschera zero in modo che gli epiloghi diversi da zero (come+ bias) non danneggino le righe mascherate. pl.kernelconSequenceout_type:pl.kernelscompatta untupleolistout_typein più argomentiout_refposizionali. L'utilizzo difuser_adapter.unpack_output_fusionmantieneout_initcon un singolo output comeShapeDtypeStructsemplice.- Padding lato host e forme fuse: poiché Pallas Fuser non ha una regola
lax.pado regole di push/pulllax.slicenon allineate, convalida i requisiti di allineamento in anticipo nel metodoprepare()della specifica di fusione e generaNotImplementedErrorper le forme non supportate anziché eseguire il padding degli oggettiFusion. Ophelper all'interno di_fusible_fwd:call_fusible_opsospendein_op_fusion_context()durante la risoluzione didefault_confige all'interno di_fusible_fwd, quindi la chiamata a unOphelper non fuso all'interno di_fusible_fwdesegue il suo percorso_fwdnormale senza attivare errori di fusione nidificati.
Elenco di controllo per i test
Quando aggiungi il supporto della fusione a un operatore, copri:
- 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. - No-fusion parity: verifica che la chiamata all'entrypoint fusibile senza operazioni circostanti (plain,
@op_fusion.fusee@fuser.fuse) produca un output bitwise-identical (chex.assert_trees_all_equal) rispetto al kernel non fuso. - Gradienti
@jax.custom_vjpespliciti: verifica che i valori e i gradienti in avanti corrispondano al riferimento non fuso. - Combinazioni non supportate: verifica i messaggi
NotImplementedErrorchiari per forme non allineate o opzioni del kernel incompatibili.
Implementazione dei riferimenti
- Facciata pubblica:
tokamax/ops/op_fusion.py Opdispatch e helper condivisi:tokamax/_src/ops/fuser_adapter.py- Integrazione del fuser del kernel (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py - Integrazione di
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - Test di fusione di kernel e
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyetokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py