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/dlhsgmm_v2como drhstgmm_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/splityreduce_sumen un eje de bloque completo (comoRMSNorm). Las operaciones sin reglas de especificación de bloques de fuser, comolax.pad, flujo de control (scan/while/cond) yreduce_max/reduce_min, no se pueden fusionar. - Restricciones de fusión de
PallasMosaicTpuV2RaggedDot:size_mdebe alinearse con la división en mosaicos de la sublínea de la TPU (size_lhs_sublane) cuandolhsooutse fusionan engmm_v2(y cuandolhsorhsse fusionan entgmm_v2).- Cuando se fusiona
out,out_size_n(ysize_kparatgmm_v2) deben alinearse connum_lanes(128) / tamaño de mosaico, y solo se admiten epílogos de salida única. partial_sumno es compatible con la fusión.rhsfusionado engmm_v2no se admite junto confuse_actni 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:
tokamax/ops/op_fusion.pyvuelve a exportarfusecomo el punto de entrada público.tokamax._src.ops.fuser_adapterestablece una marca de contexto del usuario de JAX (in_op_fusion_context()) alrededor dejax.experimental.pallas.fuser.fuse.- Cuando
Op.__call__se ejecuta dentro de ese contexto, verifica si la subclase anula_fusible_fwd(generaNotImplementedErrorsi no es así) y delega afuser_adapter.call_fusible_op. call_fusible_opsuspende el contexto de fusión mientras resuelvebound_args.default_config, vincula una primitivafuser.fusiblesobre las hojas del array, materializa cualquier argumento que no aparezca enOp.fusible_argnamesy, luego, invocaOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)dentro debound_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:
- Establece
fusible_argnamesen los nombres de los parámetros cuyas hojas de array deben permanecer como cierres defuser.Fusion. Todos los demás argumentos de array (como metadatos, índices ogroup_sizes) se materializan automáticamente enjax.Arraynormales concall_fusible_opantes de que se ejecute_fusible_fwd. - Anula
_fusible_fwd. A diferencia de_fwd(que devuelve(out, residuals)),_fusible_fwddevuelve el resultadoTdirectamente y recibeout_fusionsy elconfigresuelto. - 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 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
)
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.fuserfuera 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.Fusionde 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 xfuser.fusibleune cada hoja del array de entrada en unFusion, incluso cuando ese operando no tiene operaciones de productor. Desencapsular cierres triviales mantiene los operandos sin tocar en la ruta de accesoBlockSpecsin modificar y sin fusionar con cero sobrecarga del entorno de ejecución.Si tu kernel base está decorado con
@jax.jit, llama ainspect.unwrap(base_kernel)en la ruta de acceso fusible;@jax.jitrechaza los argumentosfuser.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 ajax.Arraybásicas y vinculafuser.fusibleautomáticamente (como lo hacegmm_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), dondevalueses la tupla de arrays de HBM cerrados por el prólogo yvalues_typecontiene susShapeDtypeStruct.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 generaNotImplementedErroren epílogos de varias salidas.Extrae una entrada
BlockSpechacia 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
BlockSpeca 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_speccontrola las reducciones que preservan la forma con transmisiones de tamaño 1 (como los epílogos deRMSNormque activanfuser.push_block_specsin procesar), verifica que la especificación extraída coincida con elout_specescrito 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
- Pasa las entradas de HBM capturadas junto con sus
BlockSpecextraídos:- Prólogo de entrada
valuesen lugar del operando fusionado (vinculado conlhs_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 conout_fusion_input_specspara quepltpu.emit_pipelinerecupere 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).
- Prólogo de entrada
- Usa tipos de PyTree distintos por modo de fusión:
pltpu.emit_pipelineasignajax.tree.map(..., in_specs, in_refs), por lo que cada contenedor de referencia de entrada y su contenedorin_specdeben compartir el mismo tipo de PyTree@jax.tree_util.register_dataclass(por ejemplo,LhsRef[T]paralhssin fusionar en comparación conFusedLhsRef[T]paralhsfusionado con prólogo).
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), pasapids = step.index(de lo contrario,tuple(pl.program_id(i) for i in range(grid_len))) y()cuandonum_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)- Cada función extraída tiene la firma
Errores comunes
pl.BoundedSliceyreshape: La regla de extracción de cambio de forma de Pallas Fuser rechazapl.BoundedSlice. Si tu kernel no fusionado cambia la forma de las entradas de HBM en 2D a referencias de subcarriles en 3D antes deemit_pipeline, convierte la especificación en unaBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)en 2D antes de extraer o enviar a través de operandos fusionados (consulta_to_2d_bounded_specengmm_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_fnantes de aplicar la máscara cero para que los epílogos que no sean cero (como+ bias) no dañen las filas enmascaradas. pl.kernelconSequenceout_type:pl.kerneldescompone untupleolistout_typeen varios argumentos posicionalesout_ref. Si usasfuser_adapter.unpack_output_fusion, se mantiene elout_initde salida única como unShapeDtypeStructsimple.- Relleno del lado del host frente a formas fusionadas: Debido a que Pallas Fuser no tiene una regla
lax.padni reglas de envío/extracciónlax.sliceno alineadas, valida los requisitos de alineación al principio del métodoprepare()de tu especificación de fusión y generaNotImplementedErrorpara las formas no admitidas en lugar de rellenar los objetosFusion. Opauxiliares dentro de_fusible_fwd:call_fusible_opsuspendein_op_fusion_context()durante la resolución dedefault_configy dentro de_fusible_fwd, por lo que llamar a unOpauxiliar no fusionado dentro de_fusible_fwdejecuta su ruta de acceso_fwdnormal 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:
- 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. - Paridad sin fusión: Verifica que llamar al punto de entrada fusionable sin operaciones circundantes (sin formato,
@op_fusion.fusey@fuser.fuse) produzca un resultado idéntico a nivel de bits (chex.assert_trees_all_equal) al kernel no fusionado. - Gradientes
@jax.custom_vjpexplícitos: Verifica que los valores y gradientes de avance coincidan con la referencia no fusionada. - Combinaciones no admitidas: Verifica los mensajes claros de
NotImplementedErrorpara ver si hay formas no alineadas o opciones de kernel incompatibles.
Implementación de referencia
- Fachada pública:
tokamax/ops/op_fusion.py - Asistentes de envío y uso compartido de
Op:tokamax/_src/ops/fuser_adapter.py - Integración del fuser del kernel (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py - Integración de
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - Pruebas de fusión de kernel y
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyytokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py