Fusion d'opérateurs
tokamax.ops.op_fusion vous permet de fusionner les opérations JAX environnantes (prologues et épilogues) directement dans un noyau TPU Tokamax Pallas fusionnable via JAX Pallas Fuser.
Au lieu de matérialiser les activations intermédiaires en HBM entre une normalisation ou une activation et un kernel personnalisé, les opérations fusionnées s'exécutent dans la VMEM sur chaque tuile à l'intérieur de la boucle du kernel.
Utiliser @op_fusion.fuse
Utilisation de base (prologue et épilogue)
Importez op_fusion depuis tokamax.ops et encapsulez la fonction contenant un opérateur Tokamax fusible avec @op_fusion.fuse (généralement dans @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)
Vous pouvez appeler l'API fonctionnelle de haut niveau avec une implémentation fusible explicite (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) ou une instance tokamax.Op spécifique directement (telle que PallasMosaicTpuV2RaggedDot). Si un opérateur dans @op_fusion.fuse n'est pas compatible avec la fusion, Tokamax génère NotImplementedError.
Options de décorateur
op_fusion.fuse transmet ses arguments de mots clés à 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: marquez les arguments Python qui ne sont pas des tableaux (par exemple, les valeurs de configuration scalaires ou les indicateurs booléens) comme statiques lors de l'appel d'une fonction fusionnée.debug=True: affiche les jaxprs de fusion tracés pour aider à diagnostiquer pourquoi une opération n'a pas fusionné ou a échoué à la propagation de la spécification de bloc.strict_mode: contrôle les vérifications d'équivalence strictes des spécifications de bloc de Pallas Fuser.
Entrées quantifiées et activations de kernel intégrées
Les prologues fusionnés sont composés d'une quantification d'activation à la volée (AsQArray), de pondérations préquantifiées (qwix.QArray) et d'activations de porte/up fusionnées intégrées sur 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,
)
Une opération fusible par bloc @op_fusion.fuse
JAX Pallas Fuser accepte un seul kernel fusible par champ d'application @op_fusion.fuse.
Lorsque vous enchaînez plusieurs noyaux (par exemple, gate_up suivi de down dans un bloc MoE), encapsulez chaque étape fusible dans sa propre fonction @op_fusion.fuse à l'intérieur d'un @jax.jit externe :
@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,
)
Différenciation automatique avec @jax.custom_vjp explicite
@op_fusion.fuse fusionne le bloc de calcul de propagation avant et ne synthétise pas automatiquement les passes de rétropropagation fusionnées via jax.grad. Lorsque vous différenciez un bloc fusionné, encapsulez les appels avant et arrière dans un @jax.custom_vjp explicite afin de pouvoir fusionner les prologues/épilogues dans les noyaux avant et arrière (drhs / dlhs) indépendamment :
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)
Utiliser des kernels Bare Fusible
Privilégiez @op_fusion.fuse avec les wrappers d'opérateurs Tokamax (tokamax.ragged_dot ou PallasMosaicTpuV2RaggedDot) plutôt que les noyaux fusibles nus et @jax.experimental.pallas.fuser.fuse pour maintenir la rétrocompatibilité et conserver la canonisation des entrées, l'autoréglage et la sérialisation des métadonnées. Si vous appelez directement des kernels gmm_v2/tgmm_v2 de bas niveau, utilisez gmm_fuser.gmm_v2_fusible ou gmm_fuser.tgmm_v2_fusible dans @op_fusion.fuse ou @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)
Lorsqu'aucune opération de prologue ou d'épilogue n'entoure gmm_v2_fusible / tgmm_v2_fusible, les fusions triviales à 0 équation sont désencapsulées afin que le kernel compilé emprunte le chemin exact non fusionné.
Opérations et contraintes compatibles
- Opérations Tokamax actuellement compatibles :
PallasMosaicTpuV2RaggedDot(implementation="mosaic_tpu_v2", couvrant à la fois les opérations forward/dlhsgmm_v2et drhstgmm_v2). - Primitives JAX de prologue/épilogue compatibles : régies par JAX Pallas Fuser.
Les opérations couramment acceptées incluent les opérations mathématiques unaires/binaires par point,
select/clamp, les conversions de types de données,broadcast_in_dim,transpose,concatenate/stack/splitetreduce_sumsur un axe de bloc complet (tel queRMSNorm). Les opérations sans règles de spécification de bloc de fusion, telles quelax.pad, le flux de contrôle (scan/while/cond) etreduce_max/reduce_min, ne peuvent pas être fusionnées. - Contraintes de fusion
PallasMosaicTpuV2RaggedDot:size_mdoit être aligné sur la segmentation des sous-voies TPU (size_lhs_sublane) lorsquelhsououtest fusionné dansgmm_v2(et lorsquelhsourhsest fusionné danstgmm_v2).- Lorsque
outest fusionné,out_size_n(etsize_kpourtgmm_v2) doit être aligné surnum_lanes(128) / taille de la tuile, et seuls les épilogues à sortie unique sont acceptés. partial_sumn'est pas compatible avec la fusion.- La fusion de
rhsdansgmm_v2n'est pas compatible avecfuse_actou les pondérations compressées de sous-octets.
Créer un noyau et une opération compatibles avec la fusion
Présentation de l'architecture
La distribution Fusion est répartie entre la façade publique, l'adaptateur interne, la classe Op et le module de fusion associé au noyau :
tokamax/ops/op_fusion.pyréexportefuseen tant que point d'entrée public.tokamax._src.ops.fuser_adapterdéfinit un indicateur de contexte utilisateur JAX (in_op_fusion_context()) autour dejax.experimental.pallas.fuser.fuse.- Lorsque
Op.__call__s'exécute dans ce contexte, il vérifie si la sous-classe remplace_fusible_fwd(en générantNotImplementedErrorsi ce n'est pas le cas) et délègue àfuser_adapter.call_fusible_op. call_fusible_opsuspend le contexte de fusion lors de la résolution debound_args.default_config, lie une primitivefuser.fusiblesur les feuilles du tableau, matérialise tout argument non listé dansOp.fusible_argnameset appelleOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)dansbound_args._tokamax_metadata(config).
Étape 1 : Déclarez fusible_argnames et remplacez _fusible_fwd sur votre Op
Sur votre sous-classe de backend Op (consultez PallasMosaicTpuV2RaggedDot pour obtenir une documentation de référence complète) :
- Définissez
fusible_argnamessur les noms de paramètres dont les feuilles de tableau doivent rester des fermeturesfuser.Fusion. Tous les autres arguments de tableau (tels que les métadonnées, les indices ougroup_sizes) sont automatiquement matérialisés enjax.Arraystandards parcall_fusible_opavant l'exécution de_fusible_fwd. - Ignorez
_fusible_fwd. Contrairement à_fwd(qui renvoie(out, residuals)),_fusible_fwdrenvoie directement la sortieTet reçoitout_fusionset leconfigrésolu. - Pour les opérandes PyTree composites dont les feuilles ne doivent pas être fusionnées (par exemple, les pondérations
QArray(qvalue, scale)préquantifiées), matérialisez-les explicitement avecfuser_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
)
Étape 2 : Conserver l'intégration de Fuser dans un module *_fuser.py associé
Suivez la séparation de Tokamax entre le noyau principal (gmm_v2.py, tgmm_v2.py) et son intégration de fuser (gmm_fuser.py) :
- Conservez les importations
jax.experimental.pallas.fuseren dehors du fichier de kernel principal afin que le kernel non fusionné reste autonome et facile à lire. Décompressez les fermetures
fuser.Fusiontriviales à 0 équation avant de créer votre spécification de fusion :def _unwrap_trivial_input_fusion(x): if isinstance(x, fuser.Fusion) and not jax.make_jaxpr(x)().jaxpr.eqns: return x() return xfuser.fusibleencapsule chaque feuille de tableau d'entrée dans unFusion, même lorsque cet opérande n'a pas d'opérations de producteur. L'unwrapping des fermetures triviales conserve les opérandes intacts sur le cheminBlockSpecnon fusionné et non modifié, sans frais d'exécution.Si votre kernel de base est décoré avec
@jax.jit, appelezinspect.unwrap(base_kernel)sur le chemin d'accès fusible.@jax.jitrejette les argumentsfuser.Fusion.Si les appelants de noyau nu doivent également pouvoir appeler votre point d'entrée fusible directement dans
@fuser.fuse, détectez les appelsjax.Arraynus et liezfuser.fusibleautomatiquement (comme le faitgmm_fuser.gmm_v2_fusible).
Étape 3 : Décompressez les fusions et transformez les BlockSpec avec fuser_adapter
Utilisez les assistants partagés dans tokamax._src.ops.fuser_adapter plutôt que d'appeler directement les API fuser de bas niveau :
Décompressez un prologue d'entrée :
lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)Renvoie
(fn, values, values_type), oùvaluesest le tuple des tableaux HBM fermés par le prologue etvalues_typecontient leursShapeDtypeStruct.Décompresser un épilogue à sortie unique :
out_fn, out_values, out_values_type, out_init = ( fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type) )Décompresse la convention de sortie de tuple unique de Pallas Fuser en un seul
ShapeDtypeStruct(out_init) et génèreNotImplementedErrorsur les épilogues à sorties multiples.Extraire une entrée
BlockSpecvers l'arrière via un prologue :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, )Transférer et extraire une sortie
BlockSpecvia un épilogue :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_specgère les réductions préservant la forme avec des diffusions de taille 1 (comme les épiloguesRMSNormqui déclenchent unfuser.push_block_specbrut), vérifie que la spécification extraite correspond auout_specécrit du noyau, déballe la valeur de retour du 1-tuple et maintient la compatibilité entre les versions JAX compatibles.
Étape 4 : Intégrer les spécifications et les rappels extraits dans le noyau Pallas
- Transmettez les entrées HBM capturées avec leurs
BlockSpecextraits :- Saisissez le prologue
valuesà la place de l'opérande fusionné (associé àlhs_val_specs). - Les entrées secondaires de l'épilogue de sortie (
out_values, telles qu'un biais ou un résidu d'épilogue) sont transmises en tant qu'entrées de noyau HBM en lecture seule associées àout_fusion_input_specsafin quepltpu.emit_pipelineprécharge leurs tuiles dans la VMEM. Lorsqu'il n'est pas fusionné, transmettez un tuple vide()pour les références et les spécifications (0 feuille PyTree).
- Saisissez le prologue
- Utilisez des types PyTree distincts par mode de fusion :
pltpu.emit_pipelinemappejax.tree.map(..., in_specs, in_refs). Par conséquent, chaque conteneur de référence d'entrée et son conteneurin_specdoivent partager exactement le même type de PyTree@jax.tree_util.register_dataclass(par exemple,LhsRef[T]pourlhsnon fusionné etFusedLhsRef[T]pourlhsfusionné avec prologue).
Évaluez les rappels extraits sur les tuiles VMEM dans le corps du noyau :
- Chaque fonction extraite possède la signature
fn(program_ids, scalar_prefetch, *args). - Dans
pltpu.emit_pipeline(..., _explicit_indices=True), transmettezpids = step.index(sinontuple(pl.program_id(i) for i in range(grid_len))) et()lorsquenum_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)- Chaque fonction extraite possède la signature
Écueils les plus courants
pl.BoundedSliceetreshapepl.BoundedSliceetreshape: la règle de retrait de remodelage de Pallas Fuser rejettepl.BoundedSlice. Si votre noyau non fusionné remodèle les entrées HBM 2D en références 3D en mosaïque de sous-voies avantemit_pipeline, convertissez la spécification enBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)2D avant d'extraire ou de transférer des opérandes fusionnés (voir_to_2d_bounded_specdansgmm_fuser.py).- Ordre de l'épilogue avec masquage de ligne : si votre noyau masque les lignes hors groupe ou de marge intérieure à zéro et combine des tuiles de sous-voie partielles entre les étapes, exécutez
out_fnavant d'appliquer le masque zéro afin que les épilogues non nuls (comme+ bias) ne corrompent pas les lignes masquées. pl.kernelavecSequenceout_type:pl.kerneldécompresse unout_typetupleoulisten plusieurs argumentsout_refpositionnels. L'utilisation defuser_adapter.unpack_output_fusionconserve la sortie uniqueout_initen tant queShapeDtypeStructbrut.- Remplissage côté hôte et formes fusionnées : comme Pallas Fuser ne dispose pas d'une règle
lax.padni de règles push/pulllax.slicenon alignées, validez les exigences d'alignement au début de la méthodeprepare()de votre spécification de fusion et déclenchezNotImplementedErrorpour les formes non compatibles plutôt que de remplir les objetsFusion. Opd'assistance dans_fusible_fwd:call_fusible_opsuspendin_op_fusion_context()pendant la résolution dedefault_configet dans_fusible_fwd. Par conséquent, l'appel d'unOpd'assistance non fusionné dans_fusible_fwdexécute son chemin d'accès_fwdnormal sans déclencher d'erreurs de fusion imbriquées.
Checklist pour les tests
Lorsque vous ajoutez la prise en charge de la fusion à un opérateur, tenez compte des points suivants :
- Fusion de prologue (réduction par point et sur l'axe complet, comme
RMSNorm), fusion d'épilogue (avec et sans entrées secondaires externes telles que le biais ou le résidu) et prologue + épilogue combinés. - Parité sans fusion : vérifiez que l'appel du point d'entrée fusible sans opérations environnantes (simple,
@op_fusion.fuseet@fuser.fuse) produit une sortie identique au niveau du bit (chex.assert_trees_all_equal) au noyau non fusionné. - Gradients
@jax.custom_vjpexplicites : vérifiez que les valeurs et les gradients de propagation correspondent à la référence non fusionnée. - Combinaisons non compatibles : vérifiez les messages
NotImplementedErrorclairs pour les formes non alignées ou les options de kernel incompatibles.
Implémentation de référence
- Façade publique :
tokamax/ops/op_fusion.py Op: dispatch et helpers partagés :tokamax/_src/ops/fuser_adapter.py- Intégration du fuser de noyau (
GmmFusionSpec/TgmmFusionSpec) :tokamax/_src/ops/gmm_v2/gmm_fuser.py - Intégration de
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - Tests de fusion du kernel et de
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyettokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py