Fusão de operadores
O tokamax.ops.op_fusion permite que você combine operações JAX ao redor (prólogos e
epílogos) diretamente em um kernel de TPU Tokamax Pallas combinável usando o
JAX Pallas Fuser.
Em vez de materializar ativações intermediárias para HBM entre uma normalização
ou ativação e um kernel personalizado, as operações combinadas são executadas em VMEM em cada bloco
dentro do loop do kernel.
Como usar o @op_fusion.fuse
Uso básico (prólogo e epílogo)
Importe op_fusion de tokamax.ops e una a função que contém um operador Tokamax
fusível com @op_fusion.fuse (normalmente 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)
É possível chamar a API funcional de alto nível com uma implementação fusível explícita (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) ou uma instância tokamax.Op específica diretamente (como PallasMosaicTpuV2RaggedDot). Se um operador dentro de @op_fusion.fuse não for compatível com a fusão, o Tokamax vai gerar NotImplementedError.
Opções de decorador
op_fusion.fuse encaminha os argumentos de palavra-chave para
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: marque argumentos Python que não são matrizes (por exemplo, valores de configuração escalar ou flags booleanas) como estáticos ao chamar uma função combinada.debug=True: mostra os jaxprs de fusão rastreados para ajudar a diagnosticar por que uma operação não foi fundida ou falhou na propagação de block-spec.strict_mode: controla as verificações rigorosas de equivalência de block-spec do Pallas Fuser.
Entradas quantizadas e ativações de kernel integradas
Os prólogos combinados são compostos com quantização de ativação em tempo real (AsQArray),
pesos pré-quantizados (qwix.QArray) e ativações de porta/ativação combinadas integradas em
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,
)
Uma operação combinável por bloco @op_fusion.fuse
O JAX Pallas Fuser aceita um único kernel fusível por escopo @op_fusion.fuse.
Ao encadear vários kernels (por exemplo, gate_up seguido por down em um
bloco MoE), envolva cada estágio fusível na própria função @op_fusion.fuse dentro
de um @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,
)
Diferenciação automática com @jax.custom_vjp explícito
@op_fusion.fuse combina o bloco de computação de encaminhamento e não sintetiza automaticamente
as passagens de retropropagação combinadas por meio de jax.grad. Ao diferenciar um
bloco fundido, envolva as chamadas de avanço e retrocesso em um
@jax.custom_vjp explícito para que seja possível fundir prólogos/epílogos nos kernels de avanço e
retrocesso (drhs / dlhs) de forma independente:
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)
Como usar kernels fusíveis simples
Dê preferência a @op_fusion.fuse com wrappers de operador Tokamax (tokamax.ragged_dot
ou PallasMosaicTpuV2RaggedDot) em vez de kernels fusíveis simples e
@jax.experimental.pallas.fuser.fuse para manter a compatibilidade com versões anteriores e
reter a canonização de entrada, o ajuste automático e a serialização de metadados. Se você
invocar kernels gmm_v2 / tgmm_v2 de baixo nível diretamente, use
gmm_fuser.gmm_v2_fusible ou gmm_fuser.tgmm_v2_fusible dentro de
@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)
Quando nenhuma operação de prólogo ou epílogo envolve gmm_v2_fusible / tgmm_v2_fusible,
as fusões triviais de equação 0 são desfeitas para que o kernel compilado siga o caminho exato
não fundido.
Operações e restrições compatíveis
- Operações do Tokamax atualmente compatíveis:
PallasMosaicTpuV2RaggedDot(implementation="mosaic_tpu_v2", que abrange tanto ogmm_v2de encaminhamento/dlhs quanto otgmm_v2de drhs). - Primitivas JAX de prólogo / epílogo compatíveis: controladas pelo
JAX Pallas Fuser.
As operações com suporte comum incluem matemática unária/binária pontual,
select/clamp, transmissões dtype,broadcast_in_dim,transpose,concatenate/stack/splitereduce_sumem um eixo de bloco completo (comoRMSNorm). Operações sem regras de especificação de bloco do fuser, comolax.pad, fluxo de controle (scan/while/cond) ereduce_max/reduce_min, não podem ser combinadas. - Restrições de fusão do
PallasMosaicTpuV2RaggedDot:size_mprecisa estar alinhado ao bloco de subfaixa da TPU (size_lhs_sublane) quandolhsououtestiverem combinados emgmm_v2(e quandolhsourhsestiverem combinados emtgmm_v2).- Quando
outé fundido,out_size_n(esize_kparatgmm_v2) precisam ser alinhados anum_lanes(128) / tamanho do bloco, e apenas epílogos de saída única são compatíveis. partial_sumnão é compatível com a fusão.- O
rhscombinado emgmm_v2não é compatível comfuse_actou pesos compactados de sub-byte.
Como criar um kernel e uma operação compatíveis com o Fusion
Visão geral da arquitetura
A distribuição de fusão é dividida entre a fachada pública, o adaptador interno, a classe Op e o módulo de fusão complementar do kernel:
tokamax/ops/op_fusion.pyreexportafusecomo o ponto de entrada público.tokamax._src.ops.fuser_adapterdefine uma flag de contexto do usuário do JAX (in_op_fusion_context()) em torno dejax.experimental.pallas.fuser.fuse.- Quando
Op.__call__é executado nesse contexto, ele verifica se a subclasse substitui_fusible_fwd(gerandoNotImplementedError, se não) e delega parafuser_adapter.call_fusible_op. call_fusible_opsuspende o contexto de fusão ao resolverbound_args.default_config, vincula uma primitivafuser.fusiblesobre as folhas da matriz, materializa qualquer argumento não listado emOp.fusible_argnamese invocaOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)dentro debound_args._tokamax_metadata(config).
Etapa 1: declarar fusible_argnames e substituir _fusible_fwd no Op
Na subclasse Op do back-end (consulte
PallasMosaicTpuV2RaggedDot
para uma referência completa):
- Defina
fusible_argnamescomo os nomes de parâmetros cujas folhas de matriz precisam permanecer como fechamentosfuser.Fusion. Todos os outros argumentos de matriz (como metadados, índices ougroup_sizes) são materializados automaticamente emjax.Arrays regulares pelocall_fusible_opantes da execução de_fusible_fwd. - Substitua
_fusible_fwd. Ao contrário de_fwd(que retorna(out, residuals)),_fusible_fwdretorna a saídaTdiretamente e recebeout_fusionse oconfigresolvido. - Para operandos PyTree compostos cujas folhas não devem ser combinadas (por exemplo,
pesos
QArray(qvalue, scale)pré-quantizados), materialize-os explicitamente comfuser_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
)
Etapa 2: manter a integração do Fuser em um módulo complementar do *_fuser.py
Siga a separação do Tokamax entre o kernel principal (gmm_v2.py, tgmm_v2.py)
e a integração do fuser (gmm_fuser.py):
- Mantenha as importações de
jax.experimental.pallas.fuserfora do arquivo de kernel principal para que o kernel não fundido permaneça independente e fácil de ler. Desembrulhe os fechamentos triviais de
fuser.Fusionde equação zero antes de criar sua especificação de fusão: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 folha da matriz de entrada em umFusion, mesmo quando esse operando não tem operações de produtor. O desencapsulamento de fechamentos triviais mantém os operandos intocados no caminhoBlockSpecnão modificado e não fundido, com zero sobrecarga de ambiente de execução.Se o kernel de base estiver decorado com
@jax.jit, chameinspect.unwrap(base_kernel)no caminho fusível.@jax.jitrejeita argumentosfuser.Fusion.Se os autores de chamadas de kernel simples também puderem invocar o ponto de entrada combinável diretamente em
@fuser.fuse, detecte chamadasjax.Arraysimples e vinculefuser.fusibleautomaticamente (comogmm_fuser.gmm_v2_fusiblefaz).
Etapa 3: descompactar as fusões e transformar BlockSpecs com fuser_adapter
Use os auxiliares compartilhados em
tokamax._src.ops.fuser_adapter
em vez de chamar as APIs fuser de baixo nível diretamente:
Descompactar um prólogo de entrada:
lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)Retorna
(fn, values, values_type), em quevaluesé a tupla de matrizes de HBM fechadas pelo prólogo evalues_typecontém osShapeDtypeStructs delas.Descompactar um epílogo de saída única:
out_fn, out_values, out_values_type, out_init = ( fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type) )Desembrulha a convenção de saída de tupla de 1 elemento do Pallas Fuser em um único
ShapeDtypeStruct(out_init) e geraNotImplementedErrorem epílogos de várias saídas.Puxar uma entrada
BlockSpecpara trás por um 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, )Enviar e extrair uma saída
BlockSpecpor um 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_specprocessa reduções que preservam a forma com transmissões de tamanho 1 (como epílogosRMSNormque acionamfuser.push_block_specbruto), verifica se a especificação extraída corresponde aoout_specescrito do kernel, desfaz o valor de retorno da tupla de 1 elemento e mantém a compatibilidade entre as versões compatíveis do JAX.
Etapa 4: conectar as especificações e os callbacks extraídos ao kernel do Pallas
- Transmita as entradas de HBM capturadas com os
BlockSpecs extraídos:- O prólogo de entrada
valuesé executado no lugar do operando combinado (pareado comlhs_val_specs). - As entradas laterais do epílogo de saída (
out_values, como um viés de epílogo ou residual) são transmitidas como entradas de kernel de HBM somente leitura pareadas comout_fusion_input_specspara quepltpu.emit_pipelinebusque previamente os blocos na VMEM. Quando não estiverem combinadas, transmita uma tupla vazia()para refs e especificações (0 folhas PyTree).
- O prólogo de entrada
- Use tipos de PyTree distintos por modo de fusão:
pltpu.emit_pipelinemapeiajax.tree.map(..., in_specs, in_refs), então cada contêiner de referência de entrada e o contêinerin_specprecisam compartilhar o mesmo tipo de PyTree@jax.tree_util.register_dataclass(por exemplo,LhsRef[T]paralhsnão fundido em comparação comFusedLhsRef[T]paralhsfundido em prólogo).
Avalie os callbacks extraídos em blocos de VMEM dentro do corpo do kernel:
- Cada função extraída tem a assinatura
fn(program_ids, scalar_prefetch, *args). - Dentro de
pltpu.emit_pipeline(..., _explicit_indices=True), transmitapids = step.index(caso contrário,tuple(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)- Cada função extraída tem a assinatura
Erros comuns
pl.BoundedSliceereshape: a regra de extração de reformulação do Pallas Fuser rejeitapl.BoundedSlice. Se o kernel não fundido remodelar as entradas de HBM 2D em referências de subfaixas 3D antes deemit_pipeline, converta a especificação em umaBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)2D antes de extrair ou enviar por meio de operandos fundidos (consulte_to_2d_bounded_specemgmm_fuser.py).- Ordenação de epílogo com mascaramento de linha: se o kernel mascarar linhas fora do grupo ou
de preenchimento como zero e combinar blocos de subfaixas parciais em várias etapas, execute
out_fnantes de aplicar a máscara zero para que os epílogos não zero (como+ bias) não corrompam as linhas mascaradas. pl.kernelcomSequenceout_type:pl.kerneldescompacta umtupleoulistout_typeem vários argumentos posicionaisout_ref. O uso defuser_adapter.unpack_output_fusionmantém oout_initde saída única como umShapeDtypeStructsimples.- Preenchimento do lado do host x formas combinadas: como o Pallas Fuser não tem uma
regra
lax.padou regras de push/pulllax.slicenão alinhadas, valide os requisitos de alinhamento no início do métodoprepare()da especificação de combinação e gereNotImplementedErrorpara formas não compatíveis em vez de preencher objetosFusion. Ops auxiliares dentro de_fusible_fwd:call_fusible_opsuspendein_op_fusion_context()durante a resolução dedefault_confige dentro de_fusible_fwd. Portanto, chamar umOpauxiliar não mesclado dentro de_fusible_fwdexecuta o caminho normal de_fwdsem acionar erros de mesclagem aninhados.
Lista de verificação de teste
Ao adicionar suporte à fusão a um operador, inclua:
- Fusão de prólogo (redução pontual e de eixo completo, como
RMSNorm), fusão de epílogo (com e sem entradas laterais externas, como viés ou residual) e prólogo + epílogo combinados. - Paridade sem fusão: verifique se a chamada do ponto de entrada fusível sem
operações ao redor (simples,
@op_fusion.fusee@fuser.fuse) produz uma saída idêntica em termos de bits (chex.assert_trees_all_equal) ao kernel não fundido. - Gradientes
@jax.custom_vjpexplícitos: verifique se os valores diretos e os gradientes correspondem à referência não combinada. - Combinações sem suporte: verifique se há mensagens claras de
NotImplementedErrorpara formas não alinhadas ou opções de kernel incompatíveis.
Implementação de referência
- Fachada pública:
tokamax/ops/op_fusion.py Opde envio e auxiliares compartilhados:tokamax/_src/ops/fuser_adapter.py- Integração do fusor de kernel (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py - Integração do
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - Testes de fusão de kernel e
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyetokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py