Operator Fusion
tokamax.ops.op_fusion به شما امکان میدهد عملیات JAX اطراف (پیشگفتارها و
پسگفتارها) را مستقیماً ازطریق JAX Pallas Fuser در یک هسته TPU قابلادغام Tokamax Pallas ادغام کنید.
بهجای تحقق فعالسازیهای میانی به HBM بین نرمالسازی یا فعالسازی و هسته سفارشی، عملیات ادغامشده در VMEM روی هر کاشی داخل حلقه هسته اجرا میشود.
درحال استفاده از @op_fusion.fuse
استفاده پایه (پیشگفتار و پسگفتار)
op_fusion را از tokamax.ops وارد کنید و تابع حاوی عملگر Tokamax قابلادغام را با @op_fusion.fuse (معمولاً داخل @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)
میتوانید میانای برنامهسازی کاربردی کاربردی سطح بالا را با پیادهسازی قابلادغام صریح (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) یا یک نمونه خاص tokamax.Op را مستقیماً (مانند PallasMosaicTpuV2RaggedDot) فراخوانی کنید. اگر یک اپراتور داخل @op_fusion.fuse از ادغام پشتیبانی نکند، Tokamax NotImplementedError را مطرح میکند.
گزینههای تزئینکننده
op_fusion.fuse متغیرهای مستقل کلیدواژه خود را به
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: آرگومانهای غیرآرایهای Python (برای مثال، مقادیر پیکربندی اسکالر یا پرچمهای بولی) را هنگام فراخوانی تابع ادغامشده بهعنوان ثابت علامتگذاری کنید. debug=True: jaxprs ادغام ردیابیشده را چاپ میکند تا به تشخیص اینکه چرا یک op ادغام نشده یا انتشار block-spec ناموفق بوده است کمک کند.strict_mode: بررسیهای دقیق معادلسازی مشخصات بلوک Pallas Fuser را کنترل میکند.
ورودیهای کوانتیده و فعالسازیهای هسته داخلی
Fused prologues compose with on-the-fly activation quantization (AsQArray),
pre-quantized weights (qwix.QArray), and built-in fused gate/up activations on
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,
)
یک عملیات قابلادغام در هر قطعه @op_fusion.fuse
JAX Pallas Fuser از یک هسته قابلادغام در هر محدوده @op_fusion.fuse پشتیبانی میکند.
When chaining multiple kernels (for example, gate_up followed by down in an
MoE block), wrap each fusible stage in its own @op_fusion.fuse function inside
an outer @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,
)
Automatic Differentiation with Explicit @jax.custom_vjp
@op_fusion.fuse بلوک محاسباتی پیشرو را ادغام میکند و بهطور خودکار
گذرگاههای ادغامشده پسرو را ازطریق jax.grad ترکیب نمیکند. هنگام متمایز کردن یک
بلوک ادغامشده، فراخوانیهای پیشرو و پسرو را در یک
@jax.custom_vjp صریح بپیچید تا بتوانید پیشگفتارها/پسگفتارها را بهطور مستقل در هستههای پیشرو و
پسرو (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)
استفاده از Bare Fusible Kernels
برای حفظ سازگاری با نسخههای قدیمی و حفظ متعارفسازی ورودی، تنظیم خودکار، و سریالسازی فراداده، @op_fusion.fuse را با پوشانندههای عملگر Tokamax (tokamax.ragged_dot یا PallasMosaicTpuV2RaggedDot) بر هستههای ذوبشدنی ساده و @jax.experimental.pallas.fuser.fuse ترجیح دهید. اگر
هستههای سطح پایین gmm_v2 / tgmm_v2 را مستقیماً فراخوانی میکنید، از
gmm_fuser.gmm_v2_fusible یا gmm_fuser.tgmm_v2_fusible در
@op_fusion.fuse یا @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)
وقتی هیچ عملیات پیشگفتار یا پسگفتاری gmm_v2_fusible / tgmm_v2_fusible را احاطه نکرده باشد،
ادغامهای بیاهمیت معادله صفر باز میشوند تا هسته کامپایلشده دقیقاً
مسیر ادغامنشده را طی کند.
عملیات و محدودیتهای پشتیبانیشده
- عملیات Tokamax که درحالحاضر پشتیبانی میشود:
PallasMosaicTpuV2RaggedDot(implementation="mosaic_tpu_v2"، که هم forward/dlhsgmm_v2و هم drhstgmm_v2را پوشش میدهد). - پیشگفتار / پسگفتار پشتیبانیشده JAX primitives: تحت نظارت
JAX Pallas Fuser.
عملیاتهای معمولاً پشتیبانیشده شامل ریاضیات نقطهای یکتایی/دوتایی،
select/clamp، تبدیلهای dtype،broadcast_in_dim،transpose،concatenate/stack/split، وreduce_sumدر سراسر یک محور بلوک کامل (مانندRMSNorm) است. عملیاتهای بدون قوانین مشخصات بلوک fuser—مانندlax.pad، جریان کنترل (scan/while/cond)، وreduce_max/reduce_min—نمیتوانند ادغام شوند. - محدودیتهای ادغام
PallasMosaicTpuV2RaggedDot:-
size_mباید با کاشیکاری زیرمسیر TPU (size_lhs_sublane) تراز شود وقتیlhsیاoutدرgmm_v2ادغام شده باشد (و وقتیlhsیاrhsدرtgmm_v2ادغام شده باشد). - When
outis fused,out_size_n(andsize_kfortgmm_v2) must be aligned tonum_lanes(128) / tile size, and only single-output epilogues are supported. -
partial_sumبا ادغام پشتیبانی نمیشود. -
rhsادغامشده درgmm_v2همراه باfuse_actیا وزنهای بستهبندیشده زیربایت پشتیبانی نمیشود.
-
نوشتن هسته و عملگر سازگار با Fusion
نمای کلی معماری
ارسال Fusion بین نمای عمومی، آداپتور داخلی، کلاس Op، و ماژول فیوزر همراه هسته تقسیم میشود:
tokamax/ops/op_fusion.pyfuseرا بهعنوان نقطه ورودی عمومی مجدداً صادر میکند.tokamax._src.ops.fuser_adapterپرچم بافت کاربر JAX (in_op_fusion_context()) را در اطرافjax.experimental.pallas.fuser.fuseتنظیم میکند.- وقتی
Op.__call__در آن زمینه اجرا میشود، بررسی میکند که آیا زیرکلاس_fusible_fwdرا لغو میکند (اگر نه،NotImplementedErrorرا افزایش میدهد) و بهfuser_adapter.call_fusible_opواگذار میکند. call_fusible_opبافت ادغام را هنگام حل کردنbound_args.default_configتعلیق میکند، یکfuser.fusibleاولیه را روی برگهای آرایه مقید میکند، هر آرگومانی را که درOp.fusible_argnamesفهرست نشده است محقق میکند، وOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)را درbound_args._tokamax_metadata(config)فراخوانی میکند.
مرحله ۱: اعلام fusible_argnames و لغو کردن _fusible_fwd در Op
در زیرکلاس Op باطن (برای مرجع کامل،
PallasMosaicTpuV2RaggedDot
را ببینید):
fusible_argnamesرا روی نامهای پارامتری تنظیم کنید که برگهای آرایه آنها باید بستارهایfuser.Fusionباقی بمانند. همه آرگومانهای آرایه دیگر (مانند فراداده، شاخصها، یاgroup_sizes) بهطور خودکار بهjax.Arrayهای معمولی توسطcall_fusible_opقبلاز اجرای_fusible_fwdتبدیل میشوند.- ملغی کردن
_fusible_fwd. برخلاف_fwd(که(out, residuals)را برمیگرداند)،_fusible_fwdخروجیTرا مستقیماً برمیگرداند وout_fusionsوconfigحلشده را دریافت میکند. - برای عملوندهای PyTree مرکب که برگهای آنها نباید ادغام شوند (برای مثال،
وزنهای
QArray(qvalue, scale)پیشکوانتیزهشده)، آنها را بهطور صریح با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
)
مرحله ۲: «ادغامکننده Fuser» را در «واحد همپا» *_fuser.py نگه دارید
جداسازی Tokamax بین هسته مرکزی (gmm_v2.py، tgmm_v2.py)
و ادغام فیوزر آن (gmm_fuser.py) را دنبال کنید:
- واردات
jax.experimental.pallas.fuserرا خارج از فایل هسته اصلی نگه دارید تا هسته غیرادغامشده مستقل و خوانا باقی بماند. قبلاز ساختن مشخصات ادغام، بستارهای
fuser.Fusionبدیهی با معادله صفر را باز کنید:def _unwrap_trivial_input_fusion(x): if isinstance(x, fuser.Fusion) and not jax.make_jaxpr(x)().jaxpr.eqns: return x() return xfuser.fusibleهر برگ آرایه ورودی را درFusionمیپیچد، حتی زمانی که آن عملوند هیچ عملگر تولیدکنندهای نداشته باشد. Unwrapping trivial closures keeps untouched operands on the unmodified unfusedBlockSpecpath with zero runtime overhead.اگر هسته پایه شما با
@jax.jitتزئین شده است،inspect.unwrap(base_kernel)را در مسیر ذوبشدنی فراخوانی کنید—@jax.jitآرگومانهایfuser.Fusionرا رد میکند.اگر فراخوانندگان هسته خام نیز باید بتوانند نقطه ورودی قابلادغام شما را مستقیماً در
@fuser.fuseفراخوانی کنند، فراخوانیهایjax.Arrayخام را شناسایی کنید وfuser.fusibleرا بهطور خودکار مقید کنید (همانطور کهgmm_fuser.gmm_v2_fusibleانجام میدهد).
مرحله ۳: باز کردن بستهبندی «ادغامها» و تبدیل کردن BlockSpec با fuser_adapter
بهجای فراخوانی مستقیم میاناهای برنامهسازی کاربردی fuser سطح پایین، از کمککنندههای مشترک در
tokamax._src.ops.fuser_adapter
استفاده کنید:
باز کردن پیشگفتار ورودی:
lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)
(fn, values, values_type)را برمیگرداند که در آنvaluesچندتایی آرایههای HBM است که توسط مقدمه بسته شدهاند وvalues_typeShapeDtypeStructهای آنها را نگه میدارد.باز کردن یک مؤخره تکخروجی:
out_fn, out_values, out_values_type, out_init = ( fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type) )Unwraps Pallas Fuser's 1-tuple output convention into a single
ShapeDtypeStruct(out_init) and raisesNotImplementedErroron multi-output epilogues.کشیدن ورودی
BlockSpecبه عقب ازطریق پیشگفتار: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, )ارسال و دریافت برونداد
BlockSpecازطریق مؤخره: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کاهشهای حفظ شکل را با همهفرستیهای اندازه ۱ (مثل مؤخرههایRMSNormکهfuser.push_block_specخام را فعال میکنند) مدیریت میکند، تأیید میکند که مشخصات استخراجشده باout_specنوشتهشده هسته مطابقت دارد، مقدار بازگشتی ۱-چندتایی را باز میکند، و سازگاری را در نسخههای پشتیبانیشده JAX حفظ میکند.
Step 4: Wire Pulled Specs and Callbacks Into the Pallas Kernel
- ورودیهای HBM ضبطشده را بههمراه
BlockSpecهای استخراجشده آنها ارسال کنید:- Input prologue
valuesride in place of the fused operand (paired withlhs_val_specs). - ورودیهای جانبی مؤخره خروجی (
out_values، مانند سوگیری مؤخره یا باقیمانده) بهعنوان ورودیهای هسته HBM فقط خواندنی جفتشده باout_fusion_input_specsارسال میشوند تاpltpu.emit_pipelineکاشیهای آنها را در VMEM پیشواکشی کند. وقتی غیرادغامی است، چندتایی خالی()را برای هر دو مرجع و مشخصات (۰ برگ PyTree) ارسال کنید.
- Input prologue
- استفاده از انواع PyTree متمایز برای هر حالت ادغام:
pltpu.emit_pipelinejax.tree.map(..., in_specs, in_refs)را نگاشت میکند، بنابراین هر محفظه مرجع ورودی و محفظهin_specآن باید دقیقاً همان نوع PyTree@jax.tree_util.register_dataclassرا داشته باشند (برای مثال،LhsRef[T]برایlhsادغامنشده درمقابلFusedLhsRef[T]برایlhsادغامشده با مقدمه).
ارزیابی فراخوانیهای برگشتی کشیدهشده روی کاشیهای VMEM در داخل بدنه هسته:
- هر تابع کشیدهشده دارای امضای
fn(program_ids, scalar_prefetch, *args)است. - درون
pltpu.emit_pipeline(..., _explicit_indices=True)،pids = step.index(درغیراینصورتtuple(pl.program_id(i) for i in range(grid_len))) و()را وقتی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)- هر تابع کشیدهشده دارای امضای
اشتباهات رایج
pl.BoundedSliceوreshape: قانون کشیدن تغییر شکل Pallas Fuserpl.BoundedSliceرا رد میکند. If your unfused kernel reshapes 2D HBM inputs to 3D sublane-tiled refs beforeemit_pipeline, convert the spec to a 2DBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)before pulling or pushing through fused operands (see_to_2d_bounded_specingmm_fuser.py).- ترتیببندی مؤخره با پوشاندن ردیف: اگر هسته شما ردیفهای خارج از گروه یا فاصلهگذاری را به صفر میپوشاند و کاشیهای زیرمسیر جزئی را در مراحل مختلف ترکیب میکند،
out_fnرا قبلاز اعمال ماسک صفر اجرا کنید تا مؤخرههای غیرصفر (مانند+ bias) ردیفهای پوشاندهشده را خراب نکنند. -
pl.kernelباSequenceout_type:pl.kernelیکtupleیاlistout_typeرا به چند متغیر مستقلout_refموقعیتی باز میکند. استفاده ازfuser_adapter.unpack_output_fusion،out_initتکخروجی را بهصورتShapeDtypeStructساده نگه میدارد. - Host-side padding vs. fused shapes: Because Pallas Fuser does not have a
lax.padrule or unalignedlax.slicepush/pull rules, validate alignment requirements early in your fusion spec'sprepare()method and raiseNotImplementedErrorfor unsupported shapes rather than paddingFusionobjects. - Helper
Ops inside_fusible_fwd:call_fusible_opsuspendsin_op_fusion_context()duringdefault_configresolution and inside_fusible_fwd, so calling an unfused helperOpinside_fusible_fwdruns its normal_fwdpath without triggering nested fusion errors.
بازبینه آزمایش
هنگام افزودن پشتیبانی از همجوشی به اپراتور، موارد زیر را پوشش دهید:
- ادغام پیشگفتار (کاهش نقطهای و تماممحور مانند
RMSNorm)، ادغام پسگفتار (با و بدون ورودیهای جانبی خارجی مانند سوگیری یا باقیمانده)، و پیشگفتار + پسگفتار ترکیبی. - No-fusion parity: Verify calling the fusible entrypoint with no
surrounding ops (plain,
@op_fusion.fuse, and@fuser.fuse) produces bitwise-identical output (chex.assert_trees_all_equal) to the unfused kernel. - گرادیانهای
@jax.custom_vjpصریح: تأیید کنید که مقادیر پیشرو و گرادیانها با مرجع ادغامنشده مطابقت داشته باشند. - ترکیبهای پشتیبانینشده: پیامهای واضح
NotImplementedErrorرا برای شکلهای نامرتب یا گزینههای هسته ناسازگار درستیسنجی کنید.
پیادهسازی مرجع
- نمای عمومی:
tokamax/ops/op_fusion.py Opارسال و کمککنندههای مشترک:tokamax/_src/ops/fuser_adapter.py- ادغام فیوزر هسته (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py - ادغام
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - آزمایشهای ادغام هسته و
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyوtokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py