Operator Fusion

يتيح لك tokamax.ops.op_fusion دمج عمليات JAX المحيطة (المقدمات والخاتمات) مباشرةً في نواة Tokamax Pallas TPU قابلة للدمج من خلال JAX Pallas Fuser. بدلاً من تخزين عمليات التنشيط الوسيطة في ذاكرة 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 لا يتيح الدمج، يظهر الخطأ NotImplementedError في Tokamax.

خيارات الديكور

تُعيد الدالة 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 المدمجة التي تم تتبُّعها للمساعدة في تشخيص سبب عدم دمج عملية أو تعذُّر نشر مواصفات الكتلة.
  • ‫strict_mode: تتحكّم في عمليات التحقّق الصارمة من تكافؤ مواصفات الحظر في Pallas Fuser.

المدخلات المكمّمة وعمليات تفعيل النواة المضمّنة

تتألف المقدمات المدمجة من تكميم التنشيط الفوري (AsQArray)، والأوزان المكمّمة مسبقًا (qwix.QArray)، وتنشيطات البوابة/الزيادة المدمجة على 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. عند ربط عدة نواة (على سبيل المثال، gate_up متبوعة بـ down في كتلة MoE)، يجب تضمين كل مرحلة قابلة للدمج في دالة @op_fusion.fuse الخاصة بها داخل @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,
  )

الاشتقاق الآلي باستخدام @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)

استخدام النواة القابلة للدمج بدون إضافات

يُفضَّل استخدام @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 في المقدّمة والخاتمة: تخضع لإدارة 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 مع تقسيم المسار الفرعي لوحدة معالجة الموتّرات (size_lhs_sublane) عند دمج السمة lhs أو out في السمة gmm_v2 (وعند دمج السمة lhs أو rhs في السمة tgmm_v2).
    • عند دمج out، يجب محاذاة out_size_n (وsize_k لـ tgmm_v2) مع num_lanes (128) / حجم المربّع، ولا تتوفّر سوى الخاتمات ذات الناتج الواحد.
    • ‫"partial_sum" غير متوافق مع ميزة الدمج.
    • لا يمكن استخدام rhs المدمج في gmm_v2 مع fuse_act أو الأوزان المجمّعة في وحدات أصغر من البايت.

إنشاء نواة وعملية متوافقتَين مع Fusion

نظرة عامة على البنية

يتم تقسيم إرسال Fusion بين الواجهة العامة والمحوّل الداخلي وفئة Op ووحدة fuser المصاحبة للنواة:

  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).

الخطوة 1: الإعلان عن 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
    )

الخطوة 2: الاحتفاظ بدمج Fuser في وحدة *_fuser.py مصاحبة

اتّبِع الفصل الذي يجريه Tokamax بين النواة الأساسية (gmm_v2.py وtgmm_v2.py) ودمجها مع fuser‏ (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، حتى عندما لا يحتوي هذا المعامل على عمليات إنتاج. يؤدي إلغاء التفاف عمليات الإغلاق البسيطة إلى إبقاء المعاملات التي لم يتم لمسها على مسار BlockSpec غير المعدّل وغير المدمج بدون أي وقت تشغيل إضافي.

  • إذا كانت النواة الأساسية مزيّنة بـ @jax.jit، يمكنك استدعاء inspect.unwrap(base_kernel) على المسار القابل للدمج، حيث يرفض @jax.jit الوسيطات fuser.Fusion.

  • إذا كان من المفترض أن يتمكّن المتصلون من النواة المجرّدة من استدعاء نقطة الدخول القابلة للدمج مباشرةً داخل @fuser.fuse، يمكنك رصد طلبات jax.Array المجرّدة وربط fuser.fusible تلقائيًا (كما يفعل gmm_fuser.gmm_v2_fusible).

الخطوة 3: فتح حِزم Fusions وتحويل "BlockSpec" باستخدام "fuser_adapter"

استخدِم المساعدين المشتركين في tokamax._src.ops.fuser_adapter بدلاً من طلب واجهات برمجة تطبيقات fuser منخفضة المستوى مباشرةً:

  • تفكيك مقدمة الإدخال:

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

    تعرض هذه الدالة (fn, values, values_type) حيث values هي صفيفات HBM التي تم إغلاقها بواسطة المقدّمة وvalues_type تحتوي على ShapeDtypeStructs.

  • Unpack a single-output epilogue:

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

    تفكّك هذه الدالة مخرجات Pallas Fuser التي تكون على شكل صف واحد إلى قيمة واحدة من النوع ShapeDtypeStruct (out_init) وتُظهر الخطأ NotImplementedError في حال وجود مخرجات متعددة في الخاتمة.

  • سحب الإدخال 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 عمليات الاختزال التي تحافظ على الشكل باستخدام عمليات بث بحجم 1 (مثل خاتمات RMSNorm التي تؤدي إلى تشغيل fuser.push_block_spec الخام)، وتتحقق من أن المواصفات المسحوبة تطابق out_spec المكتوبة في النواة، وتفك قيمة الإرجاع المكونة من صف واحد، وتحافظ على التوافق عبر إصدارات JAX المدعومة.

الخطوة 4: ربط المواصفات وعمليات الاستدعاء التي تم سحبها بنواة Pallas

  1. تمرير بيانات HBM التي تم تسجيلها مع BlockSpec التي تم سحبها:
    • يتم إدخال المقدّمة values بدلاً من المعامل المدمج (المقترن بـ lhs_val_specs).
    • يتم تمرير المدخلات الجانبية لخاتمة المخرجات (out_values، مثل انحياز الخاتمة أو المتبقي) كمدخلات نواة HBM للقراءة فقط مقترنة بـ out_fusion_input_specs بحيث يقوم pltpu.emit_pipeline بجلب مربعاتها مسبقًا إلى VMEM. عند إلغاء الدمج، يتم تمرير صف فارغ () لكل من المراجع والمواصفات (0 ورقة 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. إذا كانت النواة غير المدمجة تعيد تشكيل مدخلات HBM ثنائية الأبعاد إلى مراجع ثلاثية الأبعاد مقسّمة إلى مسارات فرعية قبل emit_pipeline، يجب تحويل المواصفات إلى BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) ثنائية الأبعاد قبل السحب أو الدفع من خلال المعاملات المدمجة (يُرجى الاطّلاع على _to_2d_bounded_spec في 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 مجردة.
  • الحشو على جهاز المضيف مقابل الأشكال المدمجة: بما أنّ Pallas Fuser لا يتضمّن قاعدة lax.pad أو قواعد دفع/سحب lax.slice غير متوافقة، يجب التحقّق من متطلبات التوافق في وقت مبكر من طريقة prepare() لمواصفات الدمج وإصدار NotImplementedError للأشكال غير المتوافقة بدلاً من حشو كائنات Fusion.
  • الدوال المساعدة Op داخل _fusible_fwd: call_fusible_op يعلّق in_op_fusion_context() أثناء حلّ default_config وداخل _fusible_fwd، لذا فإنّ استدعاء دالة مساعدة غير مدمجة Op داخل _fusible_fwd يشغّل مسار _fwd العادي بدون ظهور أخطاء الدمج المتداخلة.

قائمة التحقّق من الاختبار

عند إضافة ميزة الدمج إلى مشغّل شبكة الجوّال، يجب تغطية ما يلي:

  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. Explicit @jax.custom_vjp gradients: Verify forward values and gradients match the unfused reference.
  4. التركيبات غير المتوافقة: تحقَّق من رسائل NotImplementedError الواضحة بشأن الأشكال غير المتوافقة أو خيارات النواة غير المتوافقة.

التنفيذ المرجعي