연산자 융합

tokamax.ops.op_fusion를 사용하면 JAX Pallas Fuser를 통해 주변 JAX 작업(프롤로그 및 에필로그)을 융합 가능한 Tokamax Pallas TPU 커널에 직접 융합할 수 있습니다. 정규화 또는 활성화와 커스텀 커널 간에 중간 활성화를 HBM으로 구체화하는 대신 융합된 작업은 커널 루프 내의 각 타일에서 VMEM으로 실행됩니다.

@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)

명시적 융합 구현(tokamax.ragged_dot(..., implementation="mosaic_tpu_v2"))이 있는 상위 수준 함수형 API를 호출하거나 특정 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를 통해 융합된 역방향 패스를 자동으로 합성하지 않습니다. 융합된 블록을 미분할 때는 프롤로그/에필로그를 정방향 및 역방향(drhs/dlhs) 커널에 독립적으로 융합할 수 있도록 정방향 및 역방향 호출을 명시적 @jax.custom_vjp로 래핑합니다.

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 사용

이전 버전과의 호환성을 유지하고 입력 표준화, 자동 조정, 메타데이터 직렬화를 유지하려면 Tokamax 연산자 래퍼(tokamax.ragged_dot 또는 PallasMosaicTpuV2RaggedDot)가 있는 @op_fusion.fuse를 베어 퓨저블 커널 및 @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", 정방향/dlhs gmm_v2 및 drhs tgmm_v2 모두 포함)
  • 지원되는 프롤로그/에필로그 JAX 프리미티브: JAX Pallas Fuser에 의해 제어됩니다. 일반적으로 지원되는 작업에는 전체 블록 축(예: RMSNorm)에서 점별 단항/이항 수학, select/clamp, dtype 변환, broadcast_in_dim, transpose, concatenate/stack/split, reduce_sum가 포함됩니다. 퓨저 블록 사양 규칙이 없는 작업(예: 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 또는 하위 바이트 패킹 가중치와 함께 지원되지 않습니다.

퓨전 호환 커널 및 작업 작성

아키텍처 개요

퓨전 디스패치는 공개 외관, 내부 어댑터, Op 클래스, 커널의 컴패니언 퓨저 모듈로 분할됩니다.

  1. tokamax/ops/op_fusion.py는 fuse를 공개 진입점으로 다시 내보냅니다.
  2. tokamax._src.ops.fuser_adapter는 jax.experimental.pallas.fuser.fuse 주위에 JAX 사용자 컨텍스트 플래그(in_op_fusion_context())를 설정합니다.
  3. Op.__call__가 이 컨텍스트 내에서 실행되면 서브클래스가 _fusible_fwd를 재정의하는지 확인하고(그렇지 않으면 NotImplementedError 발생) fuser_adapter.call_fusible_op에 위임합니다.
  4. 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 참고):

  1. fusible_argnames를 배열 리프가 fuser.Fusion 클로저로 유지되어야 하는 매개변수 이름으로 설정합니다. 다른 모든 배열 인수(예: 메타데이터, 색인 또는 group_sizes)는 _fusible_fwd가 실행되기 전에 call_fusible_op에 의해 일반 jax.Array로 자동 구체화됩니다.
  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.py 모듈에 퓨저 통합 유지

핵심 커널(gmm_v2.py, tgmm_v2.py)과 퓨저 통합(gmm_fuser.py) 간의 Tokamax 분리를 따릅니다.

  • 융합되지 않은 커널이 자체 포함되고 읽기 쉽도록 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 x
    

    fuser.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 변환하기

하위 수준 fuser API를 직접 호출하는 대신 tokamax._src.ops.fuser_adapter의 공유 도우미를 사용합니다.

  • 입력 프롤로그 압축 풀기:

    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 커널에 연결

  1. 캡처된 HBM 입력과 가져온 BlockSpec를 함께 전달:
    • 융합된 피연산자 대신 입력 프롤로그 values를 사용합니다(lhs_val_specs와 페어링됨).
    • 출력 에필로그 부가 입력(out_values, 예를 들어 에필로그 편향 또는 잔차)은 out_fusion_input_specs와 페어링된 읽기 전용 HBM 커널 입력으로 전달되므로 pltpu.emit_pipeline가 타일을 VMEM으로 프리패치합니다. 융합되지 않은 경우 참조와 사양 모두에 빈 튜플 ()를 전달합니다(PyTree 리프 0개).
  2. 퓨전 모드별로 고유한 PyTree 유형 사용:
    • pltpu.emit_pipeline는 jax.tree.map(..., in_specs, in_refs)를 매핑하므로 각 입력 참조 컨테이너와 in_spec 컨테이너는 정확히 동일한 @jax.tree_util.register_dataclass PyTree 유형을 공유해야 합니다(예: 융합되지 않은 lhs의 경우 LhsRef[T], 프롤로그 융합 lhs의 경우 FusedLhsRef[T]).
  3. 커널 본문 내 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의 형태 변경 가져오기 규칙이 pl.BoundedSlice를 거부합니다. 융합되지 않은 커널이 emit_pipeline 전에 2D HBM 입력을 3D 하위 레인 타일 참조로 재구성하는 경우 융합된 피연산자를 통해 가져오거나 내보내기 전에 사양을 2D BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)로 변환합니다(gmm_fuser.py의 _to_2d_bounded_spec 참조).
  • 행 마스킹을 사용한 에필로그 순서 지정: 커널이 그룹 외부 또는 패딩 행을 0으로 마스킹하고 단계 전반에 걸쳐 부분 하위 레인 타일을 결합하는 경우 0이 아닌 에필로그(예: + bias)가 마스킹된 행을 손상시키지 않도록 0 마스크를 적용하기 전에 out_fn를 실행합니다.
  • pl.kernel with 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() 메서드에서 정렬 요구사항을 조기에 검증하고 Fusion 객체를 패딩하는 대신 지원되지 않는 도형에 대해 NotImplementedError를 발생시킵니다.
  • _fusible_fwd 내부의 도우미 Op: call_fusible_op는 default_config 확인 중 및 _fusible_fwd 내부에서 in_op_fusion_context()를 정지하므로 _fusible_fwd 내부에서 융합되지 않은 도우미 Op를 호출하면 중첩된 융합 오류를 트리거하지 않고 일반 _fwd 경로를 실행합니다.

테스트 체크리스트

연산자에 융합 지원을 추가할 때는 다음을 포함합니다.

  1. 프롤로그 퓨전(RMSNorm와 같은 점별 및 전체 축 축소), 에필로그 퓨전(바이어스 또는 잔차와 같은 외부 측면 입력이 있거나 없음), 프롤로그 + 에필로그 결합
  2. No-fusion 패리티: 주변 작업(일반, @op_fusion.fuse, @fuser.fuse) 없이 융합 가능한 진입점을 호출하면 융합되지 않은 커널과 비트 단위로 동일한 출력(chex.assert_trees_all_equal)이 생성되는지 확인합니다.
  3. 명시적 @jax.custom_vjp 경사: 정방향 값과 경사가 융합되지 않은 참조와 일치하는지 확인합니다.
  4. 지원되지 않는 조합: 정렬되지 않은 도형 또는 호환되지 않는 커널 옵션에 대한 명확한 NotImplementedError 메시지를 확인합니다.

참조 구현