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/dlhs gmm_v2 et drhs tgmm_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/split et reduce_sum sur un axe de bloc complet (tel que RMSNorm). Les opérations sans règles de spécification de bloc de fusion, telles que lax.pad, le flux de contrôle (scan/while/cond) et reduce_max/reduce_min, ne peuvent pas être fusionnées.
  • Contraintes de fusion PallasMosaicTpuV2RaggedDot :
    • size_m doit être aligné sur la segmentation des sous-voies TPU (size_lhs_sublane) lorsque lhs ou out est fusionné dans gmm_v2 (et lorsque lhs ou rhs est fusionné dans tgmm_v2).
    • Lorsque out est fusionné, out_size_n (et size_k pour tgmm_v2) doit être aligné sur num_lanes (128) / taille de la tuile, et seuls les épilogues à sortie unique sont acceptés.
    • partial_sum n'est pas compatible avec la fusion.
    • La fusion de rhs dans gmm_v2 n'est pas compatible avec fuse_act ou 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 :

  1. tokamax/ops/op_fusion.py réexporte fuse en tant que point d'entrée public.
  2. tokamax._src.ops.fuser_adapter définit un indicateur de contexte utilisateur JAX (in_op_fusion_context()) autour de jax.experimental.pallas.fuser.fuse.
  3. Lorsque Op.__call__ s'exécute dans ce contexte, il vérifie si la sous-classe remplace _fusible_fwd (en générant NotImplementedError si ce n'est pas le cas) et délègue à fuser_adapter.call_fusible_op.
  4. call_fusible_op suspend le contexte de fusion lors de la résolution de bound_args.default_config, lie une primitive fuser.fusible sur les feuilles du tableau, matérialise tout argument non listé dans Op.fusible_argnames et appelle Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) dans bound_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) :

  1. Définissez fusible_argnames sur les noms de paramètres dont les feuilles de tableau doivent rester des fermetures fuser.Fusion. Tous les autres arguments de tableau (tels que les métadonnées, les indices ou group_sizes) sont automatiquement matérialisés en jax.Array standards par call_fusible_op avant l'exécution de _fusible_fwd.
  2. Ignorez _fusible_fwd. Contrairement à _fwd (qui renvoie (out, residuals)), _fusible_fwd renvoie directement la sortie T et reçoit out_fusions et le config résolu.
  3. 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 avec 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
    )

É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.fuser en dehors du fichier de kernel principal afin que le kernel non fusionné reste autonome et facile à lire.
  • Décompressez les fermetures fuser.Fusion triviales à 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 x
    

    fuser.fusible encapsule chaque feuille de tableau d'entrée dans un Fusion, 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 chemin BlockSpec non fusionné et non modifié, sans frais d'exécution.

  • Si votre kernel de base est décoré avec @jax.jit, appelez inspect.unwrap(base_kernel) sur le chemin d'accès fusible. @jax.jit rejette les arguments fuser.Fusion.

  • Si les appelants de noyau nu doivent également pouvoir appeler votre point d'entrée fusible directement dans @fuser.fuse, détectez les appels jax.Array nus et liez fuser.fusible automatiquement (comme le fait gmm_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ù values est le tuple des tableaux HBM fermés par le prologue et values_type contient leurs ShapeDtypeStruct.

  • 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ère NotImplementedError sur les épilogues à sorties multiples.

  • Extraire une entrée BlockSpec vers 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 BlockSpec via 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_spec gère les réductions préservant la forme avec des diffusions de taille 1 (comme les épilogues RMSNorm qui déclenchent un fuser.push_block_spec brut), vérifie que la spécification extraite correspond au out_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

  1. Transmettez les entrées HBM capturées avec leurs BlockSpec extraits :
    • 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_specs afin que pltpu.emit_pipeline pré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).
  2. Utilisez des types PyTree distincts par mode de fusion :
    • pltpu.emit_pipeline mappe jax.tree.map(..., in_specs, in_refs). Par conséquent, chaque conteneur de référence d'entrée et son conteneur in_spec doivent partager exactement le même type de PyTree @jax.tree_util.register_dataclass (par exemple, LhsRef[T] pour lhs non fusionné et FusedLhsRef[T] pour lhs fusionné avec prologue).
  3. É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), transmettez pids = step.index (sinon tuple(pl.program_id(i) for i in range(grid_len))) et () lorsque 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)
    

Écueils les plus courants

  • pl.BoundedSlice et reshapepl.BoundedSlice et reshape : la règle de retrait de remodelage de Pallas Fuser rejette pl.BoundedSlice. Si votre noyau non fusionné remodèle les entrées HBM 2D en références 3D en mosaïque de sous-voies avant emit_pipeline, convertissez la spécification en BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) 2D avant d'extraire ou de transférer des opérandes fusionnés (voir _to_2d_bounded_spec dans gmm_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_fn avant d'appliquer le masque zéro afin que les épilogues non nuls (comme + bias) ne corrompent pas les lignes masquées.
  • pl.kernel avec Sequence out_type : pl.kernel décompresse un out_type tuple ou list en plusieurs arguments out_ref positionnels. L'utilisation de fuser_adapter.unpack_output_fusion conserve la sortie unique out_init en tant que ShapeDtypeStruct brut.
  • Remplissage côté hôte et formes fusionnées : comme Pallas Fuser ne dispose pas d'une règle lax.pad ni de règles push/pull lax.slice non alignées, validez les exigences d'alignement au début de la méthode prepare() de votre spécification de fusion et déclenchez NotImplementedError pour les formes non compatibles plutôt que de remplir les objets Fusion.
  • Op d'assistance dans _fusible_fwd : call_fusible_op suspend in_op_fusion_context() pendant la résolution de default_config et dans _fusible_fwd. Par conséquent, l'appel d'un Op d'assistance non fusionné dans _fusible_fwd exécute son chemin d'accès _fwd normal 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 :

  1. 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.
  2. Parité sans fusion : vérifiez que l'appel du point d'entrée fusible sans opérations environnantes (simple, @op_fusion.fuse et @fuser.fuse) produit une sortie identique au niveau du bit (chex.assert_trees_all_equal) au noyau non fusionné.
  3. Gradients @jax.custom_vjp explicites : vérifiez que les valeurs et les gradients de propagation correspondent à la référence non fusionnée.
  4. Combinaisons non compatibles : vérifiez les messages NotImplementedError clairs pour les formes non alignées ou les options de kernel incompatibles.

Implémentation de référence