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/dlhs gmm_v2 و هم drhs tgmm_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 out is fused, out_size_n (and size_k for tgmm_v2) must be aligned to num_lanes (128) / tile size, and only single-output epilogues are supported.
    • ‫partial_sum با ادغام پشتیبانی نمی‌شود.
    • ‫rhs ادغام‌شده در gmm_v2 همراه با fuse_act یا وزن‌های بسته‌بندی‌شده زیربایت پشتیبانی نمی‌شود.

نوشتن هسته و عملگر سازگار با Fusion

نمای کلی معماری

ارسال Fusion بین نمای عمومی، آداپتور داخلی، کلاس Op، و ماژول فیوزر همراه هسته تقسیم می‌شود:

  1. tokamax/ops/op_fusion.py fuse را به‌عنوان نقطه ورودی عمومی مجدداً صادر می‌کند.
  2. tokamax._src.ops.fuser_adapter پرچم بافت کاربر JAX (in_op_fusion_context()) را در اطراف jax.experimental.pallas.fuser.fuse تنظیم می‌کند.
  3. وقتی Op.__call__ در آن زمینه اجرا می‌شود، بررسی می‌کند که آیا زیرکلاس _fusible_fwd را لغو می‌کند (اگر نه، NotImplementedError را افزایش می‌دهد) و به fuser_adapter.call_fusible_op واگذار می‌کند.
  4. 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 را ببینید):

  1. fusible_argnames را روی نام‌های پارامتری تنظیم کنید که برگ‌های آرایه آن‌ها باید بستارهای fuser.Fusion باقی بمانند. همه آرگومان‌های آرایه دیگر (مانند فراداده، شاخص‌ها، یا group_sizes) به‌طور خودکار به jax.Arrayهای معمولی توسط call_fusible_op قبل‌از اجرای _fusible_fwd تبدیل می‌شوند.
  2. ملغی کردن _fusible_fwd. برخلاف _fwd (که (out, residuals) را برمی‌گرداند)، _fusible_fwd خروجی T را مستقیماً برمی‌گرداند و out_fusions و config حل‌شده را دریافت می‌کند.
  3. برای عملوندهای 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 x
    

    fuser.fusible هر برگ آرایه ورودی را در Fusion می‌پیچد، حتی زمانی که آن عملوند هیچ عملگر تولیدکننده‌ای نداشته باشد. Unwrapping trivial closures keeps untouched operands on the unmodified unfused BlockSpec path 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_type ShapeDtypeStructهای آن‌ها را نگه می‌دارد.

  • باز کردن یک مؤخره تک‌خروجی:

    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 raises NotImplementedError on 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

  1. ورودی‌های HBM ضبط‌شده را به‌همراه BlockSpecهای استخراج‌شده آن‌ها ارسال کنید:
    • Input prologue values ride in place of the fused operand (paired with lhs_val_specs).
    • ورودی‌های جانبی مؤخره خروجی (out_values، مانند سوگیری مؤخره یا باقیمانده) به‌عنوان ورودی‌های هسته HBM فقط خواندنی جفت‌شده با out_fusion_input_specs ارسال می‌شوند تا pltpu.emit_pipeline کاشی‌های آن‌ها را در VMEM پیش‌واکشی کند. وقتی غیرادغامی است، چندتایی خالی () را برای هر دو مرجع و مشخصات (۰ برگ PyTree) ارسال کنید.
  2. استفاده از انواع PyTree متمایز برای هر حالت ادغام:
    • pltpu.emit_pipeline jax.tree.map(..., in_specs, in_refs) را نگاشت می‌کند، بنابراین هر محفظه مرجع ورودی و محفظه in_spec آن باید دقیقاً همان نوع PyTree @jax.tree_util.register_dataclass را داشته باشند (برای مثال، LhsRef[T] برای lhs ادغام‌نشده درمقابل FusedLhsRef[T] برای lhs ادغام‌شده با مقدمه).
  3. ارزیابی فراخوانی‌های برگشتی کشیده‌شده روی کاشی‌های 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 Fuser pl.BoundedSlice را رد می‌کند. If your unfused kernel reshapes 2D HBM inputs to 3D sublane-tiled refs before emit_pipeline, convert the spec to a 2D BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) before pulling or pushing through fused operands (see _to_2d_bounded_spec in gmm_fuser.py).
  • ترتیب‌بندی مؤخره با پوشاندن ردیف: اگر هسته شما ردیف‌های خارج از گروه یا فاصله‌گذاری را به صفر می‌پوشاند و کاشی‌های زیرمسیر جزئی را در مراحل مختلف ترکیب می‌کند، out_fn را قبل‌از اعمال ماسک صفر اجرا کنید تا مؤخره‌های غیرصفر (مانند + bias) ردیف‌های پوشانده‌شده را خراب نکنند.
  • ‫pl.kernel با Sequence out_type: pl.kernel یک tuple یا list out_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.pad rule or unaligned lax.slice push/pull rules, validate alignment requirements early in your fusion spec's prepare() method and raise NotImplementedError for unsupported shapes rather than padding Fusion objects.
  • Helper Ops inside _fusible_fwd: call_fusible_op suspends in_op_fusion_context() during default_config resolution and inside _fusible_fwd, so calling an unfused helper Op inside _fusible_fwd runs its normal _fwd path without triggering nested fusion errors.

بازبینه آزمایش

هنگام افزودن پشتیبانی از هم‌جوشی به اپراتور، موارد زیر را پوشش دهید:

  1. ادغام پیش‌گفتار (کاهش نقطه‌ای و تمام‌محور مانند RMSNorm)، ادغام پس‌گفتار (با و بدون ورودی‌های جانبی خارجی مانند سوگیری یا باقیمانده)، و پیش‌گفتار + پس‌گفتار ترکیبی.
  2. 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.
  3. گرادیان‌های @jax.custom_vjp صریح: تأیید کنید که مقادیر پیش‌رو و گرادیان‌ها با مرجع ادغام‌نشده مطابقت داشته باشند.
  4. ترکیب‌های پشتیبانی‌نشده: پیام‌های واضح NotImplementedError را برای شکل‌های نامرتب یا گزینه‌های هسته ناسازگار درستی‌سنجی کنید.

پیاده‌سازی مرجع