Operator Fusion

tokamax.ops.op_fusion umożliwia scalanie otaczających operacji JAX (prologów i epilogów) bezpośrednio z jądrem TPU Tokamax Pallas za pomocą JAX Pallas Fuser. Zamiast materializować aktywacje pośrednie w HBM między normalizacją lub aktywacją a niestandardowym jądrem, połączone operacje są uruchamiane w VMEM na każdym kafelku wewnątrz pętli jądra.

Jak korzystać z aplikacji @op_fusion.fuse

Podstawowe użycie (prolog i epilog)

Zaimportuj op_fusion z tokamax.ops i opakuj funkcję zawierającą operator fuzji Tokamax za pomocą @op_fusion.fuse (zwykle wewnątrz @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)

Możesz wywołać funkcjonalny interfejs API wysokiego poziomu z wyraźną implementacją fuzji (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) lub bezpośrednio konkretną instancję tokamax.Op (np. PallasMosaicTpuV2RaggedDot). Jeśli operator wewnątrz @op_fusion.fuse nie obsługuje fuzji, Tokamax zgłasza błąd NotImplementedError.

Opcje dekoratora

op_fusion.fuse przekazuje argumenty słów kluczowych do 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: oznacz argumenty Pythona, które nie są tablicami (np. skalarne wartości konfiguracji lub flagi logiczne), jako statyczne podczas wywoływania funkcji scalonej.
  • debug=True: drukuje śledzone jaxprs fuzji, aby pomóc w diagnozowaniu, dlaczego operacja nie została połączona lub nie powiodła się propagacja specyfikacji bloku.
  • strict_mode: kontroluje rygorystyczne sprawdzanie równoważności specyfikacji bloków przez Pallas Fuser.

Skwantyzowane dane wejściowe i wbudowane aktywacje jądra

Połączone prologi są tworzone z kwantyzacją aktywacji na bieżąco (AsQArray), wstępnie skwantyzowanymi wagami (qwix.QArray) i wbudowanymi połączonymi aktywacjami bramki/góry na 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,
  )

Jedna operacja Fusible na blok @op_fusion.fuse

JAX Pallas Fuser obsługuje 1 jądro, które można połączyć, na zakres @op_fusion.fuse. W przypadku łączenia wielu jąder (np. gate_up, a następnie down w bloku MoE) umieść każdy etap fuzji we własnej funkcji @op_fusion.fuse wewnątrz zewnętrznej funkcji @jax.jit:

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

Automatyczne różniczkowanie z użyciem Explicit @jax.custom_vjp

@op_fusion.fuse łączy blok obliczeń w przód i nie syntetyzuje automatycznie połączonych przebiegów wstecznych przez jax.grad. Podczas różnicowania połączonego bloku opakuj wywołania do przodu i do tyłu w wyraźny @jax.custom_vjp, aby można było niezależnie łączyć prologi i epilogi w jądra do przodu i do tyłu (drhs / dlhs):

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)

Korzystanie z Bare Fusible Kernels

Zamiast czystych jąder fuzji i @jax.experimental.pallas.fuser.fuse używaj @op_fusion.fuse z opakowaniami operatorów Tokamax (tokamax.ragged_dot lub PallasMosaicTpuV2RaggedDot), aby zachować zgodność wsteczną oraz kanonikalizację danych wejściowych, automatyczne dostrajanie i serializację metadanych. Jeśli bezpośrednio wywołujesz jądra niskiego poziomu gmm_v2 / tgmm_v2, użyj gmm_fuser.gmm_v2_fusible lub gmm_fuser.tgmm_v2_fusible w @op_fusion.fuse lub @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)

Gdy operacje gmm_v2_fusible / tgmm_v2_fusible nie są otoczone operacjami prologu ani epilogu, trywialne fuzje z 0 równaniami są rozpakowywane, dzięki czemu skompilowane jądro przyjmuje dokładną ścieżkę bez fuzji.

Obsługiwane operacje i ograniczenia

  • Obecnie obsługiwane operacje Tokamax: PallasMosaicTpuV2RaggedDot (implementation="mosaic_tpu_v2", obejmujące zarówno forward/dlhs gmm_v2, jak i drhs tgmm_v2).
  • Obsługiwane elementy podstawowe JAX w prologu i epilogu: zarządzane przez JAX Pallas Fuser. Powszechnie obsługiwane operacje obejmują punktowe jednoargumentowe/dwuargumentowe operacje matematyczne, select/clamp, rzutowanie typu danych, broadcast_in_dim, transpose, concatenate/stack/split i reduce_sum na całej osi bloku (np. RMSNorm). Operacje bez reguł specyfikacji bloków fuzera, takie jak lax.pad, przepływ sterowania (scan/while/cond) i reduce_max/reduce_min, nie mogą być scalane.
  • Ograniczenia fuzji PallasMosaicTpuV2RaggedDot:
    • Wartość size_m musi być wyrównana do kafelkowania podrzędnego TPU (size_lhs_sublane), gdy lhs lub out jest scalone w gmm_v2 (oraz gdy lhs lub rhs jest scalone w tgmm_v2).
    • Gdy out jest scalony, out_size_n (i size_k dla tgmm_v2) musi być wyrównany do num_lanes (128) / rozmiaru kafelka. Obsługiwane są tylko epilogi z jednym wyjściem.
    • partial_sum nie jest obsługiwany w przypadku fuzji.
    • Połączone rhs w gmm_v2 nie są obsługiwane razem z fuse_act ani wagami spakowanymi w podbajty.

Tworzenie jądra i operacji zgodnych z fuzją

Omówienie architektury

Wysyłanie fuzji jest podzielone między fasadę publiczną, adapter wewnętrzny, klasę Op i moduł fuzji towarzyszący jądru:

  1. tokamax/ops/op_fusion.py ponownie eksportuje fuse jako publiczny punkt wejścia.
  2. tokamax._src.ops.fuser_adapter ustawia flagę kontekstu użytkownika JAX (in_op_fusion_context()) wokół jax.experimental.pallas.fuser.fuse.
  3. Gdy Op.__call__ działa w tym kontekście, sprawdza, czy podklasa zastępuje _fusible_fwd (jeśli nie, zgłasza NotImplementedError) i przekazuje do fuser_adapter.call_fusible_op.
  4. call_fusible_op zawiesza kontekst fuzji podczas rozwiązywania bound_args.default_config, wiąże element podstawowy fuser.fusible z liśćmi tablicy, materializuje każdy argument, który nie jest wymieniony w Op.fusible_argnames, i wywołuje Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) wewnątrz bound_args._tokamax_metadata(config).

Krok 1. Zadeklaruj fusible_argnames i zastąp _fusible_fwd w Op

W podklasie backendu Op (pełne informacje znajdziesz w PallasMosaicTpuV2RaggedDot):

  1. Ustaw fusible_argnames na nazwy parametrów, których liście tablicy powinny pozostać zamknięciami fuser.Fusion. Wszystkie pozostałe argumenty tablicy (takie jak metadane, indeksy lub group_sizes) są automatycznie przekształcane w zwykłe obiekty jax.Array przez call_fusible_op, zanim _fusible_fwd zostanie uruchomiony.
  2. Zastąp _fusible_fwd. W przeciwieństwie do _fwd (która zwraca (out, residuals)) _fusible_fwd zwraca bezpośrednio dane wyjściowe T i otrzymuje out_fusions oraz rozwiązane config.
  3. W przypadku złożonych operandów PyTree, których liście nie powinny być scalane (np. wstępnie skwantyzowane wagi QArray(qvalue, scale)), zmaterializuj je bezpośrednio za pomocą 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
    )

Krok 2. Zachowaj integrację z Fuser w module towarzyszącym *_fuser.py

Postępuj zgodnie z podziałem Tokamax na jądro podstawowe (gmm_v2.py, tgmm_v2.py) i integrację z fuserem (gmm_fuser.py):

  • Importy jax.experimental.pallas.fuser powinny znajdować się poza głównym plikiem jądra, aby niescalone jądro było samodzielne i łatwe do odczytania.
  • Przed utworzeniem specyfikacji fuzji rozpakuj trywialne zamknięcia fuser.Fusion z 0 równaniami:

    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 opakowuje każdy liść tablicy wejściowej w Fusion, nawet jeśli ten operand nie ma operacji producenta. Wyodrębnianie trywialnych zamknięć zachowuje nietknięte operandy na niezmodyfikowanej, niescalonej ścieżce BlockSpec bez narzutu w czasie działania.

  • Jeśli jądro podstawowe jest oznaczone dekoratorem @jax.jit, wywołaj inspect.unwrap(base_kernel) na ścieżce fuzji – @jax.jit odrzuca argumenty fuser.Fusion.

  • Jeśli wywołujący bez jądra powinni mieć możliwość wywoływania punktu wejścia bezpośrednio w @fuser.fuse, wykrywaj wywołania jax.Array i automatycznie wiąż fuser.fusible (tak jak robi to gmm_fuser.gmm_v2_fusible).

Krok 3. Rozpakuj fuzje i przekształć BlockSpec za pomocą fuser_adapter

Używaj udostępnionych funkcji pomocniczych w tokamax._src.ops.fuser_adapter, zamiast bezpośrednio wywoływać interfejsy API fuser niskiego poziomu:

  • Rozpakuj prolog wejściowy:

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

    Zwraca (fn, values, values_type), gdzie values to krotka tablic HBM zamkniętych przez prolog, a values_type zawiera ich ShapeDtypeStruct.

  • Rozpakowywanie epilogu z jednymi danymi wyjściowymi:

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

    Rozpakowuje konwencję wyjściową 1-krotki Pallas Fuser do pojedynczego obiektu ShapeDtypeStruct (out_init) i zgłasza błąd NotImplementedError w przypadku epilogów z wieloma wyjściami.

  • Przeciąganie danych wejściowych BlockSpec wstecz przez prolog:

    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,
    )
    
  • Przesyłanie i pobieranie danych wyjściowych BlockSpec za pomocą epilogu:

    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 obsługuje redukcje zachowujące kształt z transmisjami o rozmiarze 1 (takimi jak epilogi RMSNorm, które wywołują nieprzetworzone fuser.push_block_spec), sprawdza, czy pobrana specyfikacja jest zgodna z zapisaną out_spec jądra, wyodrębnia wartość zwracaną w postaci krotki jednoelementowej i utrzymuje zgodność między obsługiwanymi wersjami JAX.

Krok 4. Połącz specyfikacje i wywołania zwrotne Wire Pulled z jądrem Pallas

  1. Przekaż przechwycone dane wejściowe HBM wraz z pobranymi wartościami BlockSpec:
    • Wejściowy prolog values w miejscu połączonego operandu (sparowanego z lhs_val_specs).
    • Wejścia dodatkowe epilogu wyjściowego (out_values, takie jak bias lub reszta epilogu) są przekazywane jako wejścia jądra HBM tylko do odczytu sparowane z out_fusion_input_specs, dzięki czemu pltpu.emit_pipeline pobiera ich kafelki do VMEM. Jeśli nie są połączone, przekaż pustą krotkę () zarówno dla odwołań, jak i specyfikacji (0 liści PyTree).
  2. Używanie różnych typów PyTree w poszczególnych trybach fuzji:
    • pltpu.emit_pipeline mapuje jax.tree.map(..., in_specs, in_refs), więc każdy kontener wejściowy i jego kontener in_spec muszą mieć dokładnie ten sam typ PyTree @jax.tree_util.register_dataclass (na przykład LhsRef[T] w przypadku niescalonego lhs i FusedLhsRef[T] w przypadku scalonego prologu lhs).
  3. Ocenianie wywołań zwrotnych pobranych na kafelkach VMEM wewnątrz jądra:

    • Każda pobrana funkcja ma sygnaturę fn(program_ids, scalar_prefetch, *args).
    • Wewnątrz pltpu.emit_pipeline(..., _explicit_indices=True) przekaż pids = step.index (w przeciwnym razie tuple(pl.program_id(i) for i in range(grid_len))) i (), gdy 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)
    

Typowe problemy

  • pl.BoundedSlice i reshape: reguła ściągania zmiany kształtu fuzera Pallas odrzuca pl.BoundedSlice. Jeśli niescalone jądro zmienia kształt dwuwymiarowych danych wejściowych HBM na trójwymiarowe odwołania z podziałem na podlinie przed emit_pipeline, przekonwertuj specyfikację na dwuwymiarową BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) przed pobraniem lub przesłaniem przez scalone operandy (patrz _to_2d_bounded_spec w gmm_fuser.py).
  • Kolejność epilogów z maskowaniem wierszy: jeśli jądro maskuje wiersze spoza grupy lub wiersze dopełnienia do zera i łączy częściowe kafelki podrzędne w różnych krokach, uruchom out_fn przed zastosowaniem maski zerowej, aby niezerowe epilogi (takie jak + bias) nie uszkodziły zamaskowanych wierszy.
  • pl.kernel z Sequence out_type: pl.kernel rozpakowuje tuple lub list out_type do wielu pozycyjnych argumentów out_ref. fuser_adapter.unpack_output_fusion zachowuje pojedyncze dane wyjściowe out_init jako zwykły ShapeDtypeStruct.
  • Dopełnienie po stronie hosta a połączone kształty: ponieważ Pallas Fuser nie ma reguły lax.pad ani reguł push/pull lax.slice, wymagania dotyczące wyrównania należy zweryfikować na wczesnym etapie w metodzie prepare() specyfikacji fuzji i zgłosić NotImplementedError w przypadku nieobsługiwanych kształtów, zamiast dopełniać obiekty Fusion.
  • Pomocnik Op w _fusible_fwd: call_fusible_op zawiesza in_op_fusion_context() podczas rozwiązywania default_config i wewnątrz _fusible_fwd, więc wywołanie niescalonego pomocnika Op w _fusible_fwd uruchamia jego normalną ścieżkę _fwd bez wywoływania błędów zagnieżdżonego scalania.

Lista kontrolna testowania

Dodając obsługę fuzji do operatora, uwzględnij:

  1. fuzja prologu (redukcja punktowa i pełnoosiowa, np. RMSNorm), fuzja epilogu (z zewnętrznymi danymi wejściowymi, takimi jak bias lub residual, i bez nich) oraz połączony prolog i epilog.
  2. No-fusion parity: sprawdź, czy wywołanie punktu wejścia z możliwością fuzji bez otaczających operacji (plain, @op_fusion.fuse i @fuser.fuse) daje bitowo identyczne dane wyjściowe (chex.assert_trees_all_equal) jak jądro bez fuzji.
  3. Jawne gradienty @jax.custom_vjp: sprawdź, czy wartości i gradienty w przód są zgodne z niepołączonym odniesieniem.
  4. Nieobsługiwane kombinacje: sprawdź komunikaty NotImplementedError dotyczące niewyrównanych kształtów lub niezgodnych opcji jądra.

Implementacja referencyjna