מיזוג אופרטורים
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)
אתם יכולים לקרוא ל-API הפונקציונלי ברמה הגבוהה עם הטמעה מפורשת של היתוך (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) או למכונה ספציפית של tokamax.Op ישירות (כמו PallasMosaicTpuV2RaggedDot). אם אופרטור בתוך @op_fusion.fuse לא תומך בהיתוך, Tokamax מעלה את השגיאה NotImplementedError.
אפשרויות של Decorator
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,
)
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,
מיזוגים טריוויאליים של 0 משוואות נפרמים, כך שהקרנל המקומפל עובר בדיוק בנתיב הלא ממוזג.
פעולות נתמכות ומגבלות
- פעולות 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 block-spec, כמוlax.pad, תהליך בקרה (scan/while/cond) ו-reduce_max/reduce_min. - אילוצי מיזוג של
PallasMosaicTpuV2RaggedDot:- צריך להתאים את
size_mל-TPU sublane tiling (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 בין ליבת ה-kernel (gmm_v2.py, tgmm_v2.py) לבין השילוב של fuser (gmm_fuser.py):
- חשוב להשאיר את הייבוא של
jax.experimental.pallas.fuserמחוץ לקובץ הליבה (kernel) הראשי, כדי שהליבה הלא ממוזגת תישאר עצמאית וקלה לקריאה. לפני שיוצרים את מפרט המיזוג, צריך לפתוח את הסגורים (closures) הטריוויאליים של
fuser.Fusionעם 0 משוואות: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שלא עבר שינוי או מיזוג, ללא תקורה בזמן ריצה.אם ה-kernel הבסיסי מעוטר ב-
@jax.jit, צריך להפעיל אתinspect.unwrap(base_kernel)בנתיב הניתן למיזוג –@jax.jitדוחה ארגומנטים שלfuser.Fusion.אם גם קריאות ל-bare-kernel צריכות להיות מסוגלות להפעיל את נקודת הכניסה הניתנת למיזוג ישירות בתוך
@fuser.fuse, צריך לזהות קריאות ל-jax.Arrayולקשר אתfuser.fusibleבאופן אוטומטי (כמו ש-gmm_fuser.gmm_v2_fusibleעושה).
שלב 3: פותחים את חבילות ה-Fusions ומשדרגים את BlockSpec עם fuser_adapter
משתמשים בפונקציות העזר המשותפות ב-tokamax._src.ops.fuser_adapter במקום לשלוח קריאות ישירות לממשקי API של fuser ברמה נמוכה:
פריקת פרולוג קלט:
lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)הפונקציה מחזירה את
(fn, values, values_type), כאשרvaluesהוא ה-tuple של מערכי HBM שנסגרו על ידי הפרולוג, ו-values_typeמכיל את ה-ShapeDtypeStructשלהם.פריקה של אפילוג עם פלט יחיד:
out_fn, out_values, out_values_type, out_init = ( fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type) )מבטל את העטיפה של מוסכמת הפלט של 1-tuple של 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הכתוב של הליבה, פותח את ערך ההחזרה של ה-tuple באורך 1 ושומר על תאימות בין גרסאות JAX נתמכות.
שלב 4: מחברים את המפרטים והקריאות החוזרות (callbacks) שנשלפו לליבה של 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ממוזג עם פרולוג).
הערכת הקריאות החוזרות (callbacks) שנשלפו באריחי 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עםSequenceout_type: הפונקציהpl.kernelפורקתtupleאו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), מיזוג אפילוג (עם ובלי קלט צדדי חיצוני כמו הטיה או שאריות) ושילוב של פרולוג ואפילוג. - זוגיות ללא מיזוג: מוודאים שקריאה לנקודת הכניסה הניתנת למיזוג ללא פעולות מסביב (פשוט,
@op_fusion.fuseו-@fuser.fuse) מפיקה פלט זהה ברמת הביט (chex.assert_trees_all_equal) לקרנל הלא ממוזג. - גרדיאנטים מפורשים של
@jax.custom_vjp: מוודאים שהערכים והגרדיאנטים של ההעברה קדימה תואמים לקובץ העזר הלא ממוזג. - שילובים לא נתמכים: בודקים אם יש הודעות
NotImplementedErrorברורות לגבי צורות לא מיושרות או אפשרויות ליבה לא תואמות.
הטמעה של קובץ עזר
- חזית ציבורית:
tokamax/ops/op_fusion.py -
Opdispatch and shared helpers:tokamax/_src/ops/fuser_adapter.py - שילוב של 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