연산자 융합
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", 정방향/dlhsgmm_v2및 drhstgmm_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 클래스, 커널의 컴패니언 퓨저 모듈로 분할됩니다.
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)는_fusible_fwd가 실행되기 전에call_fusible_op에 의해 일반jax.Array로 자동 구체화됩니다._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.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 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 변환하기
하위 수준 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 커널에 연결
- 캡처된 HBM 입력과 가져온
BlockSpec를 함께 전달:- 융합된 피연산자 대신 입력 프롤로그
values를 사용합니다(lhs_val_specs와 페어링됨). - 출력 에필로그 부가 입력(
out_values, 예를 들어 에필로그 편향 또는 잔차)은out_fusion_input_specs와 페어링된 읽기 전용 HBM 커널 입력으로 전달되므로pltpu.emit_pipeline가 타일을 VMEM으로 프리패치합니다. 융합되지 않은 경우 참조와 사양 모두에 빈 튜플()를 전달합니다(PyTree 리프 0개).
- 융합된 피연산자 대신 입력 프롤로그
- 퓨전 모드별로 고유한 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의 형태 변경 가져오기 규칙이pl.BoundedSlice를 거부합니다. 융합되지 않은 커널이emit_pipeline전에 2D HBM 입력을 3D 하위 레인 타일 참조로 재구성하는 경우 융합된 피연산자를 통해 가져오거나 내보내기 전에 사양을 2DBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)로 변환합니다(gmm_fuser.py의_to_2d_bounded_spec참조).- 행 마스킹을 사용한 에필로그 순서 지정: 커널이 그룹 외부 또는 패딩 행을 0으로 마스킹하고 단계 전반에 걸쳐 부분 하위 레인 타일을 결합하는 경우 0이 아닌 에필로그(예:
+ bias)가 마스킹된 행을 손상시키지 않도록 0 마스크를 적용하기 전에out_fn를 실행합니다. pl.kernelwithSequenceout_type:pl.kernel는tuple또는listout_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경로를 실행합니다.
테스트 체크리스트
연산자에 융합 지원을 추가할 때는 다음을 포함합니다.
- 프롤로그 퓨전(
RMSNorm와 같은 점별 및 전체 축 축소), 에필로그 퓨전(바이어스 또는 잔차와 같은 외부 측면 입력이 있거나 없음), 프롤로그 + 에필로그 결합 - No-fusion 패리티: 주변 작업(일반,
@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