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/dlhsgmm_v2و drhstgmm_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 المصاحبة للنواة:
tokamax/ops/op_fusion.pyيعيد تصديرfuseكنقطة دخول عامة.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).
الخطوة 1: الإعلان عن 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
)
الخطوة 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
- تمرير بيانات HBM التي تم تسجيلها مع
BlockSpecالتي تم سحبها:- يتم إدخال المقدّمة
valuesبدلاً من المعامل المدمج (المقترن بـlhs_val_specs). - يتم تمرير المدخلات الجانبية لخاتمة المخرجات (
out_values، مثل انحياز الخاتمة أو المتبقي) كمدخلات نواة HBM للقراءة فقط مقترنة بـout_fusion_input_specsبحيث يقومpltpu.emit_pipelineبجلب مربعاتها مسبقًا إلى VMEM. عند إلغاء الدمج، يتم تمرير صف فارغ()لكل من المراجع والمواصفات (0 ورقة PyTree).
- يتم إدخال المقدّمة
- استخدام أنواع 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المدمج في المقدمة).
تقييم عمليات الاستدعاء التي تم سحبها على مربّعات 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. إذا كانت النواة غير المدمجة تعيد تشكيل مدخلات HBM ثنائية الأبعاد إلى مراجع ثلاثية الأبعاد مقسّمة إلى مسارات فرعية قبلemit_pipeline، يجب تحويل المواصفات إلىBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)ثنائية الأبعاد قبل السحب أو الدفع من خلال المعاملات المدمجة (يُرجى الاطّلاع على_to_2d_bounded_specفيgmm_fuser.py). - ترتيب الخاتمة مع حجب الصفوف: إذا كانت النواة تحجب الصفوف خارج المجموعة أو
صفوف المساحة المتروكة إلى الصفر وتجمع بين مربعات المسارات الفرعية الجزئية عبر الخطوات، شغِّل
out_fnقبل تطبيق قناع الصفر حتى لا تفسد الخاتمات غير الصفرية (مثل+ bias) الصفوف المحجوبة. -
pl.kernelمعSequenceout_type: يفكّكpl.kerneltupleأوlistout_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العادي بدون ظهور أخطاء الدمج المتداخلة.
قائمة التحقّق من الاختبار
عند إضافة ميزة الدمج إلى مشغّل شبكة الجوّال، يجب تغطية ما يلي:
- دمج المقدّمة (تقليل النقاط والمحور الكامل مثل
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. - Explicit
@jax.custom_vjpgradients: Verify forward values and gradients match the unfused reference. - التركيبات غير المتوافقة: تحقَّق من رسائل
NotImplementedErrorالواضحة بشأن الأشكال غير المتوافقة أو خيارات النواة غير المتوافقة.
التنفيذ المرجعي
- الواجهة العامة:
tokamax/ops/op_fusion.py Opdispatch and shared helpers:tokamax/_src/ops/fuser_adapter.py- دمج Kernel fuser (
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