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_v2 chuyển tiếp/dlhs và tgmm_v2 drhs).
  • 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/split và reduce_sum trê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.
  • PallasMosaicTpuV2RaggedDot các quy tắc ràng buộc về hợp nhất:
    • size_m phải được căn chỉnh theo cách xếp kề làn phụ của TPU (size_lhs_sublane) khi lhs hoặc out được hợp nhất trong gmm_v2 (và khi lhs hoặc rhs được hợp nhất trong tgmm_v2).
    • Khi out được hợp nhất, out_size_n (và size_k cho tgmm_v2) phải được căn chỉnh theo num_lanes (128) / kích thước ô và chỉ hỗ trợ phần kết có một đầu ra.
    • partial_sum không được hỗ trợ khi hợp nhất.
    • Không hỗ trợ rhs hợp nhất trong gmm_v2 cùng với fuse_act hoặ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:

  1. tokamax/ops/op_fusion.py xuất lại fuse dưới dạng điểm truy cập công khai.
  2. tokamax._src.ops.fuser_adapter đặt cờ ngữ cảnh người dùng JAX (in_op_fusion_context()) xung quanh jax.experimental.pallas.fuser.fuse.
  3. Khi Op.__call__ chạy trong bối cảnh đó, nó sẽ kiểm tra xem lớp con có ghi đè _fusible_fwd hay không (nếu không thì sẽ tăng NotImplementedError) và uỷ quyền cho fuser_adapter.call_fusible_op.
  4. call_fusible_op tạm ngưng bối cảnh kết hợp trong khi phân giải bound_args.default_config, liên kết một dữ liệu gốc fuser.fusible qua các lá mảng, hiện thực hoá mọi đối số không có trong Op.fusible_argnames và gọi Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) bên trong bound_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 đủ):

  1. Đặt fusible_argnames thành tên tham số có lá mảng phải giữ nguyên các hàm đóng fuser.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ặc group_sizes) đều được call_fusible_op tự động cụ thể hoá thành jax.Array thông thường trước khi _fusible_fwd chạy.
  2. Ghi đè _fusible_fwd. Không giống như _fwd (trả về (out, residuals)), _fusible_fwd trả về trực tiếp kết quả T và nhận out_fusions cùng config đã phân giải.
  3. Đố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ằng 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
    )

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.fuser bê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 x
    

    fuser.fusible gói mọi lá mảng đầu vào trong một Fusion, 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ẫn BlockSpec chư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ọi inspect.unwrap(base_kernel) trên đường dẫn có thể kết hợp – @jax.jit từ 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ọi jax.Array bare và liên kết fuser.fusible tự độ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 đó values là bộ dữ liệu của các mảng HBM được đóng bằng phần mở đầu và values_type chứa ShapeDtypeStruct củ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ăng NotImplementedError trên phần kết thúc nhiều đầu ra.

  • Kéo dữ liệu đầu vào BlockSpec về 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ả BlockSpec thô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_spec xử 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ết RMSNorm kích hoạt fuser.push_block_spec thô), xác minh rằng thông số kỹ thuật được lấy khớp với out_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

  1. 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ới lhs_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ới out_fusion_input_specs để pltpu.emit_pipeline tì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).
  2. Sử dụng các loại PyTree riêng biệt cho mỗi chế độ kết hợp:
    • pltpu.emit_pipeline liên kết jax.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ứa in_spec của vùng chứa đó phải có cùng loại PyTree @jax.tree_util.register_dataclass (ví dụ: LhsRef[T] cho lhs không hợp nhất so với FusedLhsRef[T] cho lhs hợp nhất phần mở đầu).
  3. Đá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ền pids = step.index (nếu không thì truyền tuple(pl.program_id(i) for i in range(grid_len))) và () khi 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)
    

Các lỗi thường gặp

  • pl.BoundedSlice và reshape: Quy tắc kéo định hình lại của Pallas Fuser từ chối pl.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ước emit_pipeline, hãy chuyển đổi thông số kỹ thuật thành 2D BlockSpec((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_spec trong gmm_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_fn trướ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.kernel với Sequence out_type: pl.kernel giải nén tuple hoặc list out_type thành nhiều đối số out_ref theo vị trí. Việc sử dụng fuser_adapter.unpack_output_fusion sẽ giữ cho out_init có một đầu ra duy nhất dưới dạng ShapeDtypeStruct thuầ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.pad hoặc quy tắc đẩy/kéo lax.slice khô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ức prepare() của thông số hợp nhất và tăng NotImplementedError cho các hình dạng không được hỗ trợ thay vì các đối tượng khoảng đệm Fusion.
  • Trình trợ giúp Op bên trong _fusible_fwd: call_fusible_op tạm ngưng in_op_fusion_context() trong quá trình phân giải default_config và bên trong _fusible_fwd, vì vậy, việc gọi trình trợ giúp không hợp nhất Op bên trong _fusible_fwd sẽ chạy đường dẫn _fwd thô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:

  1. 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.
  2. 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.fuse và @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.
  3. Độ dốc @jax.custom_vjp rõ 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.
  4. Tổ hợp không được hỗ trợ: Xác minh thông báo NotImplementedError rõ 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