מיזוג אופרטורים

‫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/dlhs gmm_v2 ו-drhs tgmm_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 הנלווה של הליבה:

  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 בין ליבת ה-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

  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. הערכת הקריאות החוזרות (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 עם 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. זוגיות ללא מיזוג: מוודאים שקריאה לנקודת הכניסה הניתנת למיזוג ללא פעולות מסביב (פשוט, @op_fusion.fuse ו-@fuser.fuse) מפיקה פלט זהה ברמת הביט (chex.assert_trees_all_equal) לקרנל הלא ממוזג.
  3. גרדיאנטים מפורשים של @jax.custom_vjp: מוודאים שהערכים והגרדיאנטים של ההעברה קדימה תואמים לקובץ העזר הלא ממוזג.
  4. שילובים לא נתמכים: בודקים אם יש הודעות NotImplementedError ברורות לגבי צורות לא מיושרות או אפשרויות ליבה לא תואמות.

הטמעה של קובץ עזר