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 o gmm_v2 de encaminhamento/dlhs quanto o tgmm_v2 de 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/split e reduce_sum em um eixo de bloco completo (como RMSNorm). Operações sem regras de especificação de bloco do fuser, como lax.pad, fluxo de controle (scan/while/cond) e reduce_max/reduce_min, não podem ser combinadas.
  • Restrições de fusão do PallasMosaicTpuV2RaggedDot:
    • size_m precisa estar alinhado ao bloco de subfaixa da TPU (size_lhs_sublane) quando lhs ou out estiverem combinados em gmm_v2 (e quando lhs ou rhs estiverem combinados em tgmm_v2).
    • Quando out é fundido, out_size_n (e size_k para tgmm_v2) precisam ser alinhados a num_lanes (128) / tamanho do bloco, e apenas epílogos de saída única são compatíveis.
    • partial_sum não é compatível com a fusão.
    • O rhs combinado em gmm_v2 não é compatível com fuse_act ou 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:

  1. tokamax/ops/op_fusion.py reexporta fuse como o ponto de entrada público.
  2. tokamax._src.ops.fuser_adapter define uma flag de contexto do usuário do JAX (in_op_fusion_context()) em torno de jax.experimental.pallas.fuser.fuse.
  3. Quando Op.__call__ é executado nesse contexto, ele verifica se a subclasse substitui _fusible_fwd (gerando NotImplementedError, se não) e delega para fuser_adapter.call_fusible_op.
  4. call_fusible_op suspende o contexto de fusão ao resolver bound_args.default_config, vincula uma primitiva fuser.fusible sobre as folhas da matriz, materializa qualquer argumento não listado em Op.fusible_argnames e invoca Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) dentro de bound_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):

  1. Defina fusible_argnames como os nomes de parâmetros cujas folhas de matriz precisam permanecer como fechamentos fuser.Fusion. Todos os outros argumentos de matriz (como metadados, índices ou group_sizes) são materializados automaticamente em jax.Arrays regulares pelo call_fusible_op antes da execução de _fusible_fwd.
  2. Substitua _fusible_fwd. Ao contrário de _fwd (que retorna (out, residuals)), _fusible_fwd retorna a saída T diretamente e recebe out_fusions e o config resolvido.
  3. Para operandos PyTree compostos cujas folhas não devem ser combinadas (por exemplo, pesos QArray(qvalue, scale) pré-quantizados), materialize-os explicitamente com 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
    )

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.fuser fora 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.Fusion de 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 x
    

    fuser.fusible une cada folha da matriz de entrada em um Fusion, mesmo quando esse operando não tem operações de produtor. O desencapsulamento de fechamentos triviais mantém os operandos intocados no caminho BlockSpec não modificado e não fundido, com zero sobrecarga de ambiente de execução.

  • Se o kernel de base estiver decorado com @jax.jit, chame inspect.unwrap(base_kernel) no caminho fusível. @jax.jit rejeita argumentos fuser.Fusion.

  • Se os autores de chamadas de kernel simples também puderem invocar o ponto de entrada combinável diretamente em @fuser.fuse, detecte chamadas jax.Array simples e vincule fuser.fusible automaticamente (como gmm_fuser.gmm_v2_fusible faz).

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 que values é a tupla de matrizes de HBM fechadas pelo prólogo e values_type contém os ShapeDtypeStructs 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 gera NotImplementedError em epílogos de várias saídas.

  • Puxar uma entrada BlockSpec para 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 BlockSpec por 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_spec processa reduções que preservam a forma com transmissões de tamanho 1 (como epílogos RMSNorm que acionam fuser.push_block_spec bruto), verifica se a especificação extraída corresponde ao out_spec escrito 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

  1. Transmita as entradas de HBM capturadas com os BlockSpecs extraídos:
    • O prólogo de entrada values é executado no lugar do operando combinado (pareado com lhs_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 com out_fusion_input_specs para que pltpu.emit_pipeline busque previamente os blocos na VMEM. Quando não estiverem combinadas, transmita uma tupla vazia () para refs e especificações (0 folhas PyTree).
  2. Use tipos de PyTree distintos por modo de fusão:
    • pltpu.emit_pipeline mapeia jax.tree.map(..., in_specs, in_refs), então cada contêiner de referência de entrada e o contêiner in_spec precisam compartilhar o mesmo tipo de PyTree @jax.tree_util.register_dataclass (por exemplo, LhsRef[T] para lhs não fundido em comparação com FusedLhsRef[T] para lhs fundido em prólogo).
  3. 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), transmita pids = step.index (caso contrário, tuple(pl.program_id(i) for i in range(grid_len))) e () quando 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)
    

Erros comuns

  • pl.BoundedSlice e reshape: a regra de extração de reformulação do Pallas Fuser rejeita pl.BoundedSlice. Se o kernel não fundido remodelar as entradas de HBM 2D em referências de subfaixas 3D antes de emit_pipeline, converta a especificação em uma BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) 2D antes de extrair ou enviar por meio de operandos fundidos (consulte _to_2d_bounded_spec em gmm_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_fn antes de aplicar a máscara zero para que os epílogos não zero (como + bias) não corrompam as linhas mascaradas.
  • pl.kernel com Sequence out_type: pl.kernel descompacta um tuple ou list out_type em vários argumentos posicionais out_ref. O uso de fuser_adapter.unpack_output_fusion mantém o out_init de saída única como um ShapeDtypeStruct simples.
  • Preenchimento do lado do host x formas combinadas: como o Pallas Fuser não tem uma regra lax.pad ou regras de push/pull lax.slice não alinhadas, valide os requisitos de alinhamento no início do método prepare() da especificação de combinação e gere NotImplementedError para formas não compatíveis em vez de preencher objetos Fusion.
  • Ops auxiliares dentro de _fusible_fwd: call_fusible_op suspende in_op_fusion_context() durante a resolução de default_config e dentro de _fusible_fwd. Portanto, chamar um Op auxiliar não mesclado dentro de _fusible_fwd executa o caminho normal de _fwd sem acionar erros de mesclagem aninhados.

Lista de verificação de teste

Ao adicionar suporte à fusão a um operador, inclua:

  1. 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.
  2. Paridade sem fusão: verifique se a chamada do ponto de entrada fusível sem operações ao redor (simples, @op_fusion.fuse e @fuser.fuse) produz uma saída idêntica em termos de bits (chex.assert_trees_all_equal) ao kernel não fundido.
  3. Gradientes @jax.custom_vjp explícitos: verifique se os valores diretos e os gradientes correspondem à referência não combinada.
  4. Combinações sem suporte: verifique se há mensagens claras de NotImplementedError para formas não alinhadas ou opções de kernel incompatíveis.

Implementação de referência