運算子融合
tokamax.ops.op_fusion 可讓您透過 JAX Pallas Fuser,將周圍的 JAX 作業 (前置和後置作業) 直接融合至可融合的 Tokamax Pallas TPU 核心。融合運算會在核心迴圈內每個圖塊的 VMEM 中執行,而不是在正規化或活化與自訂核心之間,將中繼活化具體化至 HBM。
使用@op_fusion.fuse
基本用法 (序言和結語)
從 tokamax.ops 匯入 op_fusion,並使用 @op_fusion.fuse 包裝含有可融合 Tokamax 運算子的函式 (通常在 @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。
裝飾器選項
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 範圍一個可融合核心。鏈結多個核心時 (例如在 MoE 區塊中,gate_up 後面接著 down),請將每個可融合階段包裝在外部 @jax.jit 內的專屬 @op_fusion.fuse 函式中:
@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 核心,請在 @op_fusion.fuse 或 @jax.experimental.pallas.fuser.fuse 中使用 gmm_fuser.gmm_v2_fusible 或 gmm_fuser.tgmm_v2_fusible:
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)。沒有融合器區塊規格規則的運算 (例如lax.pad、控制流程 (scan/while/cond) 和reduce_max/reduce_min) 無法融合。 PallasMosaicTpuV2RaggedDot融合限制:- 當
lhs或out在gmm_v2中融合時 (以及lhs或rhs在tgmm_v2中融合時),size_m必須與 TPU 子通道圖塊 (size_lhs_sublane) 對齊。 - 融合
out時,out_size_n(和tgmm_v2的size_k) 必須與num_lanes(128) / 圖塊大小對齊,且僅支援單一輸出結尾。 - 融合功能不支援
partial_sum。 gmm_v2中的融合rhs不支援fuse_act或子位元組封裝權重。
- 當
編寫與融合相容的核心和運算
架構總覽
Fusion 調度作業分為公開外觀、內部轉接器、Op 類別,以及核心的隨附融合器模組:
tokamax/ops/op_fusion.py會重新匯出fuse做為公開進入點。tokamax._src.ops.fuser_adapter會在jax.experimental.pallas.fuser.fuse周圍設定 JAX 使用者情境旗標 (in_op_fusion_context())。- 當
Op.__call__在該情境中執行時,會檢查子類別是否覆寫_fusible_fwd(如果沒有,則會引發NotImplementedError),並委派給fuser_adapter.call_fusible_op。 call_fusible_op會在解析bound_args.default_config時暫停融合情境、在陣列葉上繫結fuser.fusible原始物件、具體化未列在Op.fusible_argnames中的任何引數,並在bound_args._tokamax_metadata(config)內叫用Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)。
步驟 1:在 Op 上宣告 fusible_argnames 並覆寫 _fusible_fwd
在後端 Op 子類別中 (如需完整參考資料,請參閱 PallasMosaicTpuV2RaggedDot):
- 將
fusible_argnames設為參數名稱,其陣列分葉應維持fuser.Fusion閉包。所有其他陣列引數 (例如中繼資料、索引或group_sizes) 都會由call_fusible_op自動具體化為一般jax.Array,然後_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匯入核心核心檔案,讓未融合的核心保持獨立且易於閱讀。 在建構融合規格前,請先展開 0 方程式一般
fuser.Fusion閉包:def _unwrap_trivial_input_fusion(x): if isinstance(x, fuser.Fusion) and not jax.make_jaxpr(x)().jaxpr.eqns: return x() return xfuser.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:使用fuser_adapter拆開融合和變形BlockSpec
使用 tokamax._src.ops.fuser_adapter 中的共用輔助程式,而非直接呼叫低階 fuser API:
解壓縮輸入前言:
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) )將 Pallas Fuser 的 1 元組輸出慣例解包為單一
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 的廣播 (例如觸發原始fuser.push_block_spec的RMSNorm結尾),驗證提取的規格是否與核心寫入的out_spec相符,解開 1 元組傳回值,並在支援的 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容器必須共用完全相同的@jax.tree_util.register_dataclassPyTree 類型 (例如,未融合lhs的LhsRef[T]與前置融合lhs的FusedLhsRef[T])。
評估核心主體內 VMEM 圖塊上提取的回呼:
- 每個提取的函式都有簽章
fn(program_ids, scalar_prefetch, *args)。 - 在
pltpu.emit_pipeline(..., _explicit_indices=True)中,當num_scalar_prefetch=0時,傳遞pids = step.index(否則為tuple(pl.program_id(i) for i in range(grid_len))) 和():
# 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 的 reshape 提取規則會拒絕pl.BoundedSlice。如果未融合核心在emit_pipeline之前將 2D HBM 輸入內容重塑為 3D 子通道並排參照,請先將規格轉換為 2DBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...),再透過融合運算元提取或推送 (請參閱gmm_fuser.py中的_to_2d_bounded_spec)。- 使用資料列遮罩的結尾排序:如果核心將群組外或填充資料列遮罩為零,並跨步驟合併部分子通道圖塊,請在套用零遮罩「之前」執行
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物件。 _fusible_fwd內的輔助Op:call_fusible_op會在default_config解析期間和_fusible_fwd內暫停in_op_fusion_context(),因此在_fusible_fwd內呼叫未融合的輔助Op會執行其正常_fwd路徑,而不會觸發巢狀融合錯誤。
測試檢查清單
為運算子新增融合支援時,請涵蓋以下內容:
- Prologue 融合 (逐點和全軸縮減,例如
RMSNorm)、Epilogue 融合 (有和沒有外部側輸入,例如偏差或殘差),以及結合 Prologue + Epilogue。 - 無融合等效性:確認呼叫可融合進入點時,不含周圍運算 (一般、
@op_fusion.fuse和@fuser.fuse),會產生與未融合核心相同的位元輸出 (chex.assert_trees_all_equal)。 - 明確
@jax.custom_vjp梯度:確認正向值和梯度與未融合的參考值相符。 - 不支援的組合:確認是否有形狀不一致或核心選項不相容的明確
NotImplementedError訊息。
參考實作
- 公開外觀:
tokamax/ops/op_fusion.py Op調度及共用輔助程式:tokamax/_src/ops/fuser_adapter.py- 核心融合器整合 (
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