Operator Fusion

tokamax.ops.op_fusion te permite fusionar las operaciones de JAX circundantes (prólogos y epílogos) directamente en un kernel de TPU de Tokamax Pallas fusionable a través de JAX Pallas Fuser. En lugar de materializar activaciones intermedias en la HBM entre una normalización o activación y un kernel personalizado, las operaciones fusionadas se ejecutan en la VMEM en cada mosaico dentro del bucle del kernel.

Usa @op_fusion.fuse

Uso básico (prólogo y epílogo)

Importa op_fusion desde tokamax.ops y une la función que contiene un operador de Tokamax fusionable con @op_fusion.fuse (por lo general, dentro de @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)

Puedes llamar a la API funcional de alto nivel con una implementación fusible explícita (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) o una instancia tokamax.Op específica directamente (como PallasMosaicTpuV2RaggedDot). Si un operador dentro de @op_fusion.fuse no admite la fusión, Tokamax genera NotImplementedError.

Opciones de decorador

op_fusion.fuse reenvía sus argumentos de palabra clave 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: Marca los argumentos de Python que no son matrices (por ejemplo, valores de configuración escalares o indicadores booleanos) como estáticos al llamar a una función fusionada.
  • debug=True: Imprime los jaxprs de fusión con seguimiento para ayudar a diagnosticar por qué una operación no se fusionó o falló la propagación de block-spec.
  • strict_mode: Controla las verificaciones estrictas de equivalencia de block-spec de Pallas Fuser.

Entradas cuantizadas y activaciones de kernel integradas

Los prólogos fusionados se componen con la cuantización de activación sobre la marcha (AsQArray), los pesos cuantizados previamente (qwix.QArray) y las activaciones de compuerta/actualización fusionadas integradas en 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,
  )

Una Fusible Op por bloque de @op_fusion.fuse

El JAX Pallas Fuser admite un solo kernel fusionable por cada permiso de @op_fusion.fuse. Cuando encadenes varios kernels (por ejemplo, gate_up seguido de down en un bloque de MoE), une cada etapa fusible en su propia función @op_fusion.fuse dentro de un @jax.jit externo:

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

Diferenciación automática con @jax.custom_vjp explícito

@op_fusion.fuse fusiona el bloque de cálculo hacia delante y no sintetiza automáticamente los pases hacia atrás fusionados a través de jax.grad. Cuando diferencies un bloque fusionado, une las llamadas hacia adelante y hacia atrás en un @jax.custom_vjp explícito para que puedas fusionar prólogos y epílogos en los kernels hacia adelante y hacia atrás (drhs/dlhs) de forma independiente:

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)

Usa kernels fusibles básicos

Se prefiere @op_fusion.fuse con wrappers de operadores de Tokamax (tokamax.ragged_dot o PallasMosaicTpuV2RaggedDot) en lugar de kernels fusibles básicos y @jax.experimental.pallas.fuser.fuse para mantener la retrocompatibilidad y conservar la canonicalización de entrada, el ajuste automático y la serialización de metadatos. Si invocas kernels de bajo nivel de gmm_v2 o tgmm_v2 directamente, usa gmm_fuser.gmm_v2_fusible o gmm_fuser.tgmm_v2_fusible dentro de @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)

Cuando no hay operaciones de prólogo o epílogo que rodeen a gmm_v2_fusible o tgmm_v2_fusible, las fusiones triviales de 0 ecuaciones se desenvuelven para que el kernel compilado tome la ruta exacta sin fusionar.

Operaciones y restricciones admitidas

  • Operaciones de Tokamax admitidas actualmente: PallasMosaicTpuV2RaggedDot (implementation="mosaic_tpu_v2", que abarca tanto forward/dlhs gmm_v2 como drhs tgmm_v2).
  • Primitivas de JAX de prólogo y epílogo compatibles: Se rigen por JAX Pallas Fuser. Las operaciones que se admiten comúnmente incluyen operaciones matemáticas unarias o binarias puntuales, select/clamp, conversiones de dtype, broadcast_in_dim, transpose, concatenate/stack/split y reduce_sum en un eje de bloque completo (como RMSNorm). Las operaciones sin reglas de especificación de bloques de fuser, como lax.pad, flujo de control (scan/while/cond) y reduce_max/reduce_min, no se pueden fusionar.
  • Restricciones de fusión de PallasMosaicTpuV2RaggedDot:
    • size_m debe alinearse con la división en mosaicos de la sublínea de la TPU (size_lhs_sublane) cuando lhs o out se fusionan en gmm_v2 (y cuando lhs o rhs se fusionan en tgmm_v2).
    • Cuando se fusiona out, out_size_n (y size_k para tgmm_v2) deben alinearse con num_lanes (128) / tamaño de mosaico, y solo se admiten epílogos de salida única.
    • partial_sum no es compatible con la fusión.
    • rhs fusionado en gmm_v2 no se admite junto con fuse_act ni con pesos empaquetados de subbytes.

Crea un kernel y una operación compatibles con Fusion

Descripción general de la arquitectura

El envío de Fusion se divide entre la fachada pública, el adaptador interno, la clase Op y el módulo fuser complementario del kernel:

  1. tokamax/ops/op_fusion.py vuelve a exportar fuse como el punto de entrada público.
  2. tokamax._src.ops.fuser_adapter establece una marca de contexto del usuario de JAX (in_op_fusion_context()) alrededor de jax.experimental.pallas.fuser.fuse.
  3. Cuando Op.__call__ se ejecuta dentro de ese contexto, verifica si la subclase anula _fusible_fwd (genera NotImplementedError si no es así) y delega a fuser_adapter.call_fusible_op.
  4. call_fusible_op suspende el contexto de fusión mientras resuelve bound_args.default_config, vincula una primitiva fuser.fusible sobre las hojas del array, materializa cualquier argumento que no aparezca en Op.fusible_argnames y, luego, invoca Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) dentro de bound_args._tokamax_metadata(config).

Paso 1: Declara fusible_argnames y anula _fusible_fwd en tu Op

En tu subclase de backend Op (consulta PallasMosaicTpuV2RaggedDot para obtener una referencia completa), haz lo siguiente:

  1. Establece fusible_argnames en los nombres de los parámetros cuyas hojas de array deben permanecer como cierres de fuser.Fusion. Todos los demás argumentos de array (como metadatos, índices o group_sizes) se materializan automáticamente en jax.Array normales con call_fusible_op antes de que se ejecute _fusible_fwd.
  2. Anula _fusible_fwd. A diferencia de _fwd (que devuelve (out, residuals)), _fusible_fwd devuelve el resultado T directamente y recibe out_fusions y el config resuelto.
  3. En el caso de los operandos PyTree compuestos cuyas hojas no se deben fusionar (por ejemplo, los pesos QArray(qvalue, scale) cuantificados previamente), materialízalos de forma explícita 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
    )

Paso 2: Mantén la integración de Fuser en un módulo *_fuser.py complementario

Sigue la separación de Tokamax entre el kernel principal (gmm_v2.py, tgmm_v2.py) y su integración de fuser (gmm_fuser.py):

  • Mantén las importaciones de jax.experimental.pallas.fuser fuera del archivo de kernel principal para que el kernel no fusionado siga siendo autónomo y fácil de leer.
  • Desempaqueta los cierres triviales de fuser.Fusion de 0 ecuaciones antes de compilar tu especificación de fusión:

    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 une cada hoja del array de entrada en un Fusion, incluso cuando ese operando no tiene operaciones de productor. Desencapsular cierres triviales mantiene los operandos sin tocar en la ruta de acceso BlockSpec sin modificar y sin fusionar con cero sobrecarga del entorno de ejecución.

  • Si tu kernel base está decorado con @jax.jit, llama a inspect.unwrap(base_kernel) en la ruta de acceso fusible; @jax.jit rechaza los argumentos fuser.Fusion.

  • Si los emisores de kernel básico también deben poder invocar tu punto de entrada fusible directamente dentro de @fuser.fuse, detecta las llamadas a jax.Array básicas y vincula fuser.fusible automáticamente (como lo hace gmm_fuser.gmm_v2_fusible).

Paso 3: Desempaqueta las fusiones y transforma los BlockSpec con fuser_adapter

Usa los ayudantes compartidos en tokamax._src.ops.fuser_adapter en lugar de llamar directamente a las APIs de fuser de bajo nivel:

  • Desempaqueta un prólogo de entrada:

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

    Devuelve (fn, values, values_type), donde values es la tupla de arrays de HBM cerrados por el prólogo y values_type contiene sus ShapeDtypeStruct.

  • Desempaqueta un epílogo de un solo resultado:

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

    Desempaqueta la convención de salida de 1 tupla de Pallas Fuser en un solo ShapeDtypeStruct (out_init) y genera NotImplementedError en epílogos de varias salidas.

  • Extrae una entrada BlockSpec hacia atrás a través de un prólogo:

    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,
    )
    
  • Envía y extrae un resultado BlockSpec a través de un epílogo:

    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 controla las reducciones que preservan la forma con transmisiones de tamaño 1 (como los epílogos de RMSNorm que activan fuser.push_block_spec sin procesar), verifica que la especificación extraída coincida con el out_spec escrito del kernel, desempaqueta el valor de retorno de la tupla de 1 elemento y mantiene la compatibilidad entre las versiones de JAX compatibles.

Paso 4: Conecta las especificaciones y las devoluciones de llamada extraídas al kernel de Pallas

  1. Pasa las entradas de HBM capturadas junto con sus BlockSpec extraídos:
    • Prólogo de entrada values en lugar del operando fusionado (vinculado con lhs_val_specs).
    • Las entradas laterales del epílogo de salida (out_values, como un sesgo o un residuo del epílogo) se pasan como entradas de kernel de HBM de solo lectura vinculadas con out_fusion_input_specs para que pltpu.emit_pipeline recupere previamente sus mosaicos en la VMEM. Cuando no se fusiona, pasa una tupla vacía () para las referencias y las especificaciones (0 hojas de PyTree).
  2. Usa tipos de PyTree distintos por modo de fusión:
    • pltpu.emit_pipeline asigna jax.tree.map(..., in_specs, in_refs), por lo que cada contenedor de referencia de entrada y su contenedor in_spec deben compartir el mismo tipo de PyTree @jax.tree_util.register_dataclass (por ejemplo, LhsRef[T] para lhs sin fusionar en comparación con FusedLhsRef[T] para lhs fusionado con prólogo).
  3. Evalúa las devoluciones de llamada extraídas en las tarjetas de VMEM dentro del cuerpo del kernel:

    • Cada función extraída tiene la firma fn(program_ids, scalar_prefetch, *args).
    • Dentro de pltpu.emit_pipeline(..., _explicit_indices=True), pasa pids = step.index (de lo contrario, tuple(pl.program_id(i) for i in range(grid_len))) y () cuando 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)
    

Errores comunes

  • pl.BoundedSlice y reshape: La regla de extracción de cambio de forma de Pallas Fuser rechaza pl.BoundedSlice. Si tu kernel no fusionado cambia la forma de las entradas de HBM en 2D a referencias de subcarriles en 3D antes de emit_pipeline, convierte la especificación en una BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) en 2D antes de extraer o enviar a través de operandos fusionados (consulta _to_2d_bounded_spec en gmm_fuser.py).
  • Orden del epílogo con enmascaramiento de filas: Si tu kernel enmascara las filas fuera del grupo o de relleno en cero y combina mosaicos de subcarriles parciales en los pasos, ejecuta out_fn antes de aplicar la máscara cero para que los epílogos que no sean cero (como + bias) no dañen las filas enmascaradas.
  • pl.kernel con Sequence out_type: pl.kernel descompone un tuple o list out_type en varios argumentos posicionales out_ref. Si usas fuser_adapter.unpack_output_fusion, se mantiene el out_init de salida única como un ShapeDtypeStruct simple.
  • Relleno del lado del host frente a formas fusionadas: Debido a que Pallas Fuser no tiene una regla lax.pad ni reglas de envío/extracción lax.slice no alineadas, valida los requisitos de alineación al principio del método prepare() de tu especificación de fusión y genera NotImplementedError para las formas no admitidas en lugar de rellenar los objetos Fusion.
  • Op auxiliares dentro de _fusible_fwd: call_fusible_op suspende in_op_fusion_context() durante la resolución de default_config y dentro de _fusible_fwd, por lo que llamar a un Op auxiliar no fusionado dentro de _fusible_fwd ejecuta su ruta de acceso _fwd normal sin activar errores de fusión anidados.

Lista de tareas de prueba

Cuando agregues compatibilidad con la fusión a un operador, incluye lo siguiente:

  1. Fusión de prólogo (reducción puntual y de eje completo, como RMSNorm), fusión de epílogo (con y sin entradas laterales externas, como sesgo o residual) y prólogo y epílogo combinados.
  2. Paridad sin fusión: Verifica que llamar al punto de entrada fusionable sin operaciones circundantes (sin formato, @op_fusion.fuse y @fuser.fuse) produzca un resultado idéntico a nivel de bits (chex.assert_trees_all_equal) al kernel no fusionado.
  3. Gradientes @jax.custom_vjp explícitos: Verifica que los valores y gradientes de avance coincidan con la referencia no fusionada.
  4. Combinaciones no admitidas: Verifica los mensajes claros de NotImplementedError para ver si hay formas no alineadas o opciones de kernel incompatibles.

Implementación de referencia