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/dlhsgmm_v2, jak i drhstgmm_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/splitireduce_sumna całej osi bloku (np.RMSNorm). Operacje bez reguł specyfikacji bloków fuzera, takie jaklax.pad, przepływ sterowania (scan/while/cond) ireduce_max/reduce_min, nie mogą być scalane. - Ograniczenia fuzji
PallasMosaicTpuV2RaggedDot:- Wartość
size_mmusi być wyrównana do kafelkowania podrzędnego TPU (size_lhs_sublane), gdylhsluboutjest scalone wgmm_v2(oraz gdylhslubrhsjest scalone wtgmm_v2). - Gdy
outjest scalony,out_size_n(isize_kdlatgmm_v2) musi być wyrównany donum_lanes(128) / rozmiaru kafelka. Obsługiwane są tylko epilogi z jednym wyjściem. partial_sumnie jest obsługiwany w przypadku fuzji.- Połączone
rhswgmm_v2nie są obsługiwane razem zfuse_actani wagami spakowanymi w podbajty.
- Wartość
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:
tokamax/ops/op_fusion.pyponownie eksportujefusejako publiczny punkt wejścia.tokamax._src.ops.fuser_adapterustawia flagę kontekstu użytkownika JAX (in_op_fusion_context()) wokółjax.experimental.pallas.fuser.fuse.- Gdy
Op.__call__działa w tym kontekście, sprawdza, czy podklasa zastępuje_fusible_fwd(jeśli nie, zgłaszaNotImplementedError) i przekazuje dofuser_adapter.call_fusible_op. call_fusible_opzawiesza kontekst fuzji podczas rozwiązywaniabound_args.default_config, wiąże element podstawowyfuser.fusiblez liśćmi tablicy, materializuje każdy argument, który nie jest wymieniony wOp.fusible_argnames, i wywołujeOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)wewnątrzbound_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):
- Ustaw
fusible_argnamesna nazwy parametrów, których liście tablicy powinny pozostać zamknięciamifuser.Fusion. Wszystkie pozostałe argumenty tablicy (takie jak metadane, indeksy lubgroup_sizes) są automatycznie przekształcane w zwykłe obiektyjax.Arrayprzezcall_fusible_op, zanim_fusible_fwdzostanie uruchomiony. - Zastąp
_fusible_fwd. W przeciwieństwie do_fwd(która zwraca(out, residuals))_fusible_fwdzwraca bezpośrednio dane wyjścioweTi otrzymujeout_fusionsoraz rozwiązaneconfig. - 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.fuserpowinny 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.Fusionz 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 xfuser.fusibleopakowuje każdy liść tablicy wejściowej wFusion, nawet jeśli ten operand nie ma operacji producenta. Wyodrębnianie trywialnych zamknięć zachowuje nietknięte operandy na niezmodyfikowanej, niescalonej ścieżceBlockSpecbez narzutu w czasie działania.Jeśli jądro podstawowe jest oznaczone dekoratorem
@jax.jit, wywołajinspect.unwrap(base_kernel)na ścieżce fuzji –@jax.jitodrzuca argumentyfuser.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łaniajax.Arrayi automatycznie wiążfuser.fusible(tak jak robi togmm_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), gdzievaluesto krotka tablic HBM zamkniętych przez prolog, avalues_typezawiera ichShapeDtypeStruct.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łądNotImplementedErrorw przypadku epilogów z wieloma wyjściami.Przeciąganie danych wejściowych
BlockSpecwstecz 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
BlockSpecza 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_specobsługuje redukcje zachowujące kształt z transmisjami o rozmiarze 1 (takimi jak epilogiRMSNorm, które wywołują nieprzetworzonefuser.push_block_spec), sprawdza, czy pobrana specyfikacja jest zgodna z zapisanąout_specją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
- Przekaż przechwycone dane wejściowe HBM wraz z pobranymi wartościami
BlockSpec:- Wejściowy prolog
valuesw miejscu połączonego operandu (sparowanego zlhs_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 zout_fusion_input_specs, dzięki czemupltpu.emit_pipelinepobiera 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).
- Wejściowy prolog
- Używanie różnych typów PyTree w poszczególnych trybach fuzji:
pltpu.emit_pipelinemapujejax.tree.map(..., in_specs, in_refs), więc każdy kontener wejściowy i jego kontenerin_specmuszą mieć dokładnie ten sam typ PyTree@jax.tree_util.register_dataclass(na przykładLhsRef[T]w przypadku niescalonegolhsiFusedLhsRef[T]w przypadku scalonego prologulhs).
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 razietuple(pl.program_id(i) for i in range(grid_len))) i(), gdynum_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)- Każda pobrana funkcja ma sygnaturę
Typowe problemy
pl.BoundedSliceireshape: reguła ściągania zmiany kształtu fuzera Pallas odrzucapl.BoundedSlice. Jeśli niescalone jądro zmienia kształt dwuwymiarowych danych wejściowych HBM na trójwymiarowe odwołania z podziałem na podlinie przedemit_pipeline, przekonwertuj specyfikację na dwuwymiarowąBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)przed pobraniem lub przesłaniem przez scalone operandy (patrz_to_2d_bounded_specwgmm_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_fnprzed zastosowaniem maski zerowej, aby niezerowe epilogi (takie jak+ bias) nie uszkodziły zamaskowanych wierszy. pl.kernelzSequenceout_type:pl.kernelrozpakowujetuplelublistout_typedo wielu pozycyjnych argumentówout_ref.fuser_adapter.unpack_output_fusionzachowuje pojedyncze dane wyjścioweout_initjako zwykłyShapeDtypeStruct.- Dopełnienie po stronie hosta a połączone kształty: ponieważ Pallas Fuser nie ma reguły
lax.padani reguł push/pulllax.slice, wymagania dotyczące wyrównania należy zweryfikować na wczesnym etapie w metodzieprepare()specyfikacji fuzji i zgłosićNotImplementedErrorw przypadku nieobsługiwanych kształtów, zamiast dopełniać obiektyFusion. - Pomocnik
Opw_fusible_fwd:call_fusible_opzawieszain_op_fusion_context()podczas rozwiązywaniadefault_configi wewnątrz_fusible_fwd, więc wywołanie niescalonego pomocnikaOpw_fusible_fwduruchamia jego normalną ścieżkę_fwdbez wywoływania błędów zagnieżdżonego scalania.
Lista kontrolna testowania
Dodając obsługę fuzji do operatora, uwzględnij:
- 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. - No-fusion parity: sprawdź, czy wywołanie punktu wejścia z możliwością fuzji bez otaczających operacji (plain,
@op_fusion.fusei@fuser.fuse) daje bitowo identyczne dane wyjściowe (chex.assert_trees_all_equal) jak jądro bez fuzji. - Jawne gradienty
@jax.custom_vjp: sprawdź, czy wartości i gradienty w przód są zgodne z niepołączonym odniesieniem. - Nieobsługiwane kombinacje: sprawdź komunikaty
NotImplementedErrordotyczące niewyrównanych kształtów lub niezgodnych opcji jądra.
Implementacja referencyjna
- Fasada publiczna:
tokamax/ops/op_fusion.py Op– wysyłanie i udostępnianie pomocników:tokamax/_src/ops/fuser_adapter.py- Integracja fuzera jądra (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py - Integracja z
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - Testy fuzji jądra i
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyitokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py