Hợp nhất toán tử
tokamax.ops.op_fusion cho phép bạn kết hợp trực tiếp các thao tác JAX xung quanh (mở đầu và kết thúc) vào một hạt nhân TPU Tokamax Pallas có thể kết hợp thông qua JAX Pallas Fuser.
Thay vì hiện thực hoá các hoạt động kích hoạt trung gian cho HBM giữa một hoạt động chuẩn hoá hoặc kích hoạt và một hạt nhân tuỳ chỉnh, các hoạt động kết hợp sẽ chạy trong VMEM trên mỗi ô bên trong vòng lặp hạt nhân.
Sử dụng @op_fusion.fuse
Cách sử dụng cơ bản (Mở đầu và Kết thúc)
Nhập op_fusion từ tokamax.ops và gói hàm chứa toán tử Tokamax có thể kết hợp bằng @op_fusion.fuse (thường là bên trong @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)
Bạn có thể gọi API chức năng cấp cao bằng cách triển khai hợp nhất rõ ràng (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) hoặc gọi trực tiếp một thực thể tokamax.Op cụ thể (chẳng hạn như PallasMosaicTpuV2RaggedDot). Nếu một toán tử bên trong @op_fusion.fuse không hỗ trợ hợp nhất, Tokamax sẽ báo lỗi NotImplementedError.
Tuỳ chọn trang trí
op_fusion.fuse chuyển tiếp các đối số từ khoá của nó đến
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: Đánh dấu các đối số Python không phải mảng (ví dụ: giá trị cấu hình vô hướng hoặc cờ boolean) là tĩnh khi gọi một hàm kết hợp.debug=True: In jaxpr hợp nhất được theo dõi để giúp chẩn đoán lý do một toán tử không hợp nhất hoặc không truyền được thông số kỹ thuật khối.strict_mode: Kiểm soát các quy trình kiểm tra nghiêm ngặt về tính tương đương của thông số kỹ thuật khối của Pallas Fuser.
Đầu vào được lượng tử hoá và kích hoạt hạt nhân tích hợp
Phần mở đầu kết hợp kết hợp với tính năng lượng tử hoá kích hoạt nhanh (AsQArray),
trọng số được lượng tử hoá trước (qwix.QArray) và các hoạt động kích hoạt cổng/lên kết hợp tích hợp sẵn trên
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,
)
Một toán tử có thể kết hợp cho mỗi khối @op_fusion.fuse
JAX Pallas Fuser hỗ trợ một hạt nhân có thể kết hợp cho mỗi phạm vi @op_fusion.fuse.
Khi liên kết nhiều hạt nhân (ví dụ: gate_up theo sau là down trong một khối MoE), hãy gói từng giai đoạn có thể kết hợp trong hàm @op_fusion.fuse riêng bên trong một @jax.jit bên ngoài:
@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,
)
Tự động phân biệt bằng @jax.custom_vjp tường minh
@op_fusion.fuse kết hợp khối tính toán chuyển tiếp và không tự động tổng hợp các lượt truyền ngược kết hợp thông qua jax.grad. Khi phân biệt một khối hợp nhất, hãy gói các lệnh gọi chuyển tiếp và lùi trong một @jax.custom_vjp rõ ràng để bạn có thể hợp nhất các phần mở đầu/phần kết vào các hạt nhân chuyển tiếp và lùi (drhs / dlhs) một cách độc lập:
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)
Sử dụng Bare Fusible Kernel
Ưu tiên @op_fusion.fuse có trình bao bọc toán tử Tokamax (tokamax.ragged_dot hoặc PallasMosaicTpuV2RaggedDot) hơn là các hạt nhân có thể kết hợp và @jax.experimental.pallas.fuser.fuse để duy trì khả năng tương thích ngược và giữ lại quy trình chuẩn hoá đầu vào, tự động điều chỉnh và chuyển đổi tuần tự siêu dữ liệu. Nếu bạn gọi trực tiếp các hạt nhân gmm_v2/tgmm_v2 cấp thấp, hãy sử dụng gmm_fuser.gmm_v2_fusible hoặc gmm_fuser.tgmm_v2_fusible bên trong @op_fusion.fuse hoặc @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)
Khi không có hoạt động mở đầu hoặc kết thúc nào xung quanh gmm_v2_fusible/tgmm_v2_fusible,
các phép kết hợp 0 phương trình đơn giản sẽ được huỷ gói để nhân được biên dịch đi theo đúng
đường dẫn không kết hợp.
Các thao tác và quy tắc ràng buộc được hỗ trợ
- Các toán tử Tokamax hiện được hỗ trợ:
PallasMosaicTpuV2RaggedDot(implementation="mosaic_tpu_v2", bao gồm cảgmm_v2chuyển tiếp/dlhs vàtgmm_v2drhs). - Các dữ liệu gốc JAX mở đầu/kết thúc được hỗ trợ: Do JAX Pallas Fuser quản lý.
Các toán tử thường được hỗ trợ bao gồm toán học đơn phân/nhị phân theo điểm,
select/clamp, truyền kiểu dữ liệu,broadcast_in_dim,transpose,concatenate/stack/splitvàreduce_sumtrên toàn bộ trục khối (chẳng hạn nhưRMSNorm). Không thể hợp nhất các toán tử không có quy tắc đặc tả khối của trình hợp nhất, chẳng hạn nhưlax.pad, luồng điều khiển (scan/while/cond) vàreduce_max/reduce_min. PallasMosaicTpuV2RaggedDotcác quy tắc ràng buộc về hợp nhất:size_mphải được căn chỉnh theo cách xếp kề làn phụ của TPU (size_lhs_sublane) khilhshoặcoutđược hợp nhất tronggmm_v2(và khilhshoặcrhsđược hợp nhất trongtgmm_v2).- Khi
outđược hợp nhất,out_size_n(vàsize_kchotgmm_v2) phải được căn chỉnh theonum_lanes(128) / kích thước ô và chỉ hỗ trợ phần kết có một đầu ra. partial_sumkhông được hỗ trợ khi hợp nhất.- Không hỗ trợ
rhshợp nhất tronggmm_v2cùng vớifuse_acthoặc trọng số được đóng gói dưới dạng byte phụ.
Tạo hạt nhân và toán tử tương thích với Fusion
Tổng quan về Cấu trúc (Architecture)
Quá trình điều phối hợp nhất được phân chia giữa giao diện công khai, bộ chuyển đổi nội bộ, lớp Op và mô-đun hợp nhất đồng hành của nhân:
tokamax/ops/op_fusion.pyxuất lạifusedưới dạng điểm truy cập công khai.tokamax._src.ops.fuser_adapterđặt cờ ngữ cảnh người dùng JAX (in_op_fusion_context()) xung quanhjax.experimental.pallas.fuser.fuse.- Khi
Op.__call__chạy trong bối cảnh đó, nó sẽ kiểm tra xem lớp con có ghi đè_fusible_fwdhay không (nếu không thì sẽ tăngNotImplementedError) và uỷ quyền chofuser_adapter.call_fusible_op. call_fusible_optạm ngưng bối cảnh kết hợp trong khi phân giảibound_args.default_config, liên kết một dữ liệu gốcfuser.fusiblequa các lá mảng, hiện thực hoá mọi đối số không có trongOp.fusible_argnamesvà gọiOp._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs)bên trongbound_args._tokamax_metadata(config).
Bước 1: Khai báo fusible_argnames và ghi đè _fusible_fwd trên Op
Trên lớp con Op phụ trợ (xem PallasMosaicTpuV2RaggedDot để biết tài liệu tham khảo đầy đủ):
- Đặt
fusible_argnamesthành tên tham số có lá mảng phải giữ nguyên các hàm đóngfuser.Fusion. Tất cả các đối số mảng khác (chẳng hạn như siêu dữ liệu, chỉ mục hoặcgroup_sizes) đều đượccall_fusible_optự động cụ thể hoá thànhjax.Arraythông thường trước khi_fusible_fwdchạy. - Ghi đè
_fusible_fwd. Không giống như_fwd(trả về(out, residuals)),_fusible_fwdtrả về trực tiếp kết quảTvà nhậnout_fusionscùngconfigđã phân giải. - Đối với các toán hạng PyTree tổng hợp có lá không nên được hợp nhất (ví dụ:
trọng số
QArray(qvalue, scale)được lượng tử hoá trước), hãy hiện thực hoá chúng một cách rõ ràng bằngfuser_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
)
Bước 2: Giữ tính năng tích hợp Fuser trong mô-đun *_fuser.py đồng hành
Làm theo cách phân tách của Tokamax giữa nhân cốt lõi (gmm_v2.py, tgmm_v2.py)
và tích hợp fuser (gmm_fuser.py):
- Giữ các lệnh nhập
jax.experimental.pallas.fuserbên ngoài tệp nhân chính để nhân chưa hợp nhất vẫn độc lập và dễ đọc. Mở các hàm đóng
fuser.Fusionđơn giản có 0 phương trình trước khi tạo thông số kỹ thuật hợp nhất:def _unwrap_trivial_input_fusion(x): if isinstance(x, fuser.Fusion) and not jax.make_jaxpr(x)().jaxpr.eqns: return x() return xfuser.fusiblegói mọi lá mảng đầu vào trong mộtFusion, ngay cả khi toán hạng đó không có toán tử tạo. Việc huỷ gói các hàm đóng đơn giản sẽ giữ nguyên các toán hạng chưa được xử lý trên đường dẫnBlockSpecchưa được sửa đổi và chưa được hợp nhất mà không tốn thêm tài nguyên trong thời gian chạy.Nếu nhân cơ sở của bạn được trang trí bằng
@jax.jit, hãy gọiinspect.unwrap(base_kernel)trên đường dẫn có thể kết hợp –@jax.jittừ chối đối sốfuser.Fusion.Nếu phương thức gọi bare-kernel cũng có thể gọi trực tiếp điểm truy cập có thể kết hợp của bạn bên trong
@fuser.fuse, hãy phát hiện các lệnh gọijax.Arraybare và liên kếtfuser.fusibletự động (nhưgmm_fuser.gmm_v2_fusible).
Bước 3: Mở khoá Fusion và biến đổi BlockSpec bằng fuser_adapter
Sử dụng trình trợ giúp dùng chung trong tokamax._src.ops.fuser_adapter thay vì gọi trực tiếp các API fuser cấp thấp:
Giải nén phần mở đầu của dữ liệu đầu vào:
lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)Trả về
(fn, values, values_type), trong đóvalueslà bộ dữ liệu của các mảng HBM được đóng bằng phần mở đầu vàvalues_typechứaShapeDtypeStructcủa các mảng đó.Giải nén phần kết có một đầu ra:
out_fn, out_values, out_values_type, out_init = ( fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type) )Mở gói quy ước đầu ra 1 bộ dữ liệu của Pallas Fuser thành một
ShapeDtypeStruct(out_init) và tăngNotImplementedErrortrên phần kết thúc nhiều đầu ra.Kéo dữ liệu đầu vào
BlockSpecvề phía sau thông qua phần mở đầu: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, )Đẩy và kéo kết quả
BlockSpecthông qua phần kết: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_specxử lý các phép rút gọn giữ nguyên hình dạng bằng các phép truyền tin có kích thước 1 (chẳng hạn như phần kếtRMSNormkích hoạtfuser.push_block_specthô), xác minh rằng thông số kỹ thuật được lấy khớp vớiout_specđược viết của hạt nhân, huỷ gói giá trị trả về của bộ dữ liệu 1 và duy trì khả năng tương thích trên các bản phát hành JAX được hỗ trợ.
Bước 4: Kết nối thông số kỹ thuật và lệnh gọi lại được lấy vào nhân Pallas
- Truyền dữ liệu đầu vào HBM đã thu thập cùng với
BlockSpecđã lấy:- Đầu vào mở đầu
valuesđi thay cho toán hạng hợp nhất (được ghép nối vớilhs_val_specs). - Đầu vào phụ của phần kết đầu ra (
out_values, chẳng hạn như độ lệch phần kết hoặc phần dư) được truyền dưới dạng đầu vào hạt nhân HBM chỉ có thể đọc được ghép nối vớiout_fusion_input_specsđểpltpu.emit_pipelinetìm nạp trước các ô của chúng vào VMEM. Khi không hợp nhất, hãy truyền một bộ dữ liệu trống()cho cả tham chiếu và thông số kỹ thuật (0 lá PyTree).
- Đầu vào mở đầu
- Sử dụng các loại PyTree riêng biệt cho mỗi chế độ kết hợp:
pltpu.emit_pipelineliên kếtjax.tree.map(..., in_specs, in_refs), vì vậy, mỗi vùng chứa tham chiếu đầu vào và vùng chứain_speccủa vùng chứa đó phải có cùng loại PyTree@jax.tree_util.register_dataclass(ví dụ:LhsRef[T]cholhskhông hợp nhất so vớiFusedLhsRef[T]cholhshợp nhất phần mở đầu).
Đánh giá các lệnh gọi lại được lấy trên các ô VMEM bên trong phần thân hạt nhân:
- Mỗi hàm được lấy đều có chữ ký
fn(program_ids, scalar_prefetch, *args). - Bên trong
pltpu.emit_pipeline(..., _explicit_indices=True), hãy truyềnpids = step.index(nếu không thì truyềntuple(pl.program_id(i) for i in range(grid_len))) và()khinum_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)- Mỗi hàm được lấy đều có chữ ký
Các lỗi thường gặp
pl.BoundedSlicevàreshape: Quy tắc kéo định hình lại của Pallas Fuser từ chốipl.BoundedSlice. Nếu hạt nhân chưa hợp nhất của bạn định hình lại dữ liệu đầu vào HBM 2D thành tham chiếu dạng ô phụ 3D trướcemit_pipeline, hãy chuyển đổi thông số kỹ thuật thành 2DBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)trước khi kéo hoặc đẩy qua các toán hạng hợp nhất (xem_to_2d_bounded_spectronggmm_fuser.py).- Thứ tự phần kết có mặt nạ hàng: Nếu hạt nhân của bạn che các hàng ngoài nhóm hoặc hàng khoảng đệm thành 0 và kết hợp các ô phụ một phần trên các bước, hãy chạy
out_fntrước khi áp dụng mặt nạ 0 để các phần kết khác 0 (như+ bias) không làm hỏng các hàng được che. pl.kernelvớiSequenceout_type:pl.kernelgiải néntuplehoặclistout_typethành nhiều đối sốout_reftheo vị trí. Việc sử dụngfuser_adapter.unpack_output_fusionsẽ giữ choout_initcó một đầu ra duy nhất dưới dạngShapeDtypeStructthuần tuý.- Khoảng đệm phía máy chủ lưu trữ so với hình dạng hợp nhất: Vì Pallas Fuser không có quy tắc
lax.padhoặc quy tắc đẩy/kéolax.slicekhông được căn chỉnh, nên hãy xác thực các yêu cầu về căn chỉnh sớm trong phương thứcprepare()của thông số hợp nhất và tăngNotImplementedErrorcho các hình dạng không được hỗ trợ thay vì các đối tượng khoảng đệmFusion. - Trình trợ giúp
Opbên trong_fusible_fwd:call_fusible_optạm ngưngin_op_fusion_context()trong quá trình phân giảidefault_configvà bên trong_fusible_fwd, vì vậy, việc gọi trình trợ giúp không hợp nhấtOpbên trong_fusible_fwdsẽ chạy đường dẫn_fwdthông thường mà không gây ra lỗi hợp nhất lồng nhau.
Danh sách kiểm thử
Khi thêm tính năng hỗ trợ kết hợp cho một toán tử, hãy đề cập đến:
- Hợp nhất phần mở đầu (giảm theo điểm và toàn trục, chẳng hạn như
RMSNorm), hợp nhất phần kết (có và không có dữ liệu đầu vào bên ngoài như độ lệch hoặc phần dư) và kết hợp phần mở đầu + phần kết. - Tính tương đương không kết hợp: Xác minh việc gọi điểm truy cập có thể kết hợp mà không có toán tử xung quanh (thuần tuý,
@op_fusion.fusevà@fuser.fuse) sẽ tạo ra kết quả giống hệt theo bitwise (chex.assert_trees_all_equal) với hạt nhân không kết hợp. - Độ dốc
@jax.custom_vjprõ ràng: Xác minh các giá trị chuyển tiếp và độ dốc khớp với tệp đối chiếu chưa hợp nhất. - Tổ hợp không được hỗ trợ: Xác minh thông báo
NotImplementedErrorrõ ràng cho các hình dạng không khớp hoặc các tuỳ chọn hạt nhân không tương thích.
Triển khai tham chiếu
- Mặt tiền công khai:
tokamax/ops/op_fusion.py Opđiều phối và trình trợ giúp dùng chung:tokamax/_src/ops/fuser_adapter.py- Tích hợp trình kết hợp hạt nhân (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py - Tích hợp
Op._fusible_fwd:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py - Kiểm thử kết hợp kernel và
Op:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyvàtokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py