Operatör birleştirme

tokamax.ops.op_fusion, JAX Pallas Fuser aracılığıyla çevreleyen JAX işlemlerini (prologlar ve epiloglar) doğrudan birleştirilebilir bir Tokamax Pallas TPU çekirdeğinde birleştirmenize olanak tanır. Normalleştirme veya etkinleştirme ile özel çekirdek arasındaki ara etkinleştirmeleri HBM'ye dönüştürmek yerine, birleştirilmiş işlemler çekirdek döngüsünün içindeki her bir parçada VMEM'de çalıştırılır.

@op_fusion.fuse kullanılıyor

Temel Kullanım (Giriş ve Sonuç)

tokamax.ops kaynağından op_fusion öğesini içe aktarın ve birleştirilebilir Tokamax operatörü içeren işlevi @op_fusion.fuse ile sarmalayın (genellikle @jax.jit içinde):

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)

Açık bir birleştirilebilir uygulama (tokamax.ragged_dot(..., implementation="mosaic_tpu_v2")) ile üst düzey işlevsel API'yi veya doğrudan belirli bir tokamax.Op örneğini (ör. PallasMosaicTpuV2RaggedDot) çağırabilirsiniz. @op_fusion.fuse içindeki bir operatör birleştirmeyi desteklemiyorsa Tokamax, NotImplementedError hatası verir.

Dekoratör Seçenekleri

op_fusion.fuse, anahtar kelime bağımsız değişkenlerini jax.experimental.pallas.fuser.fuse öğesine yönlendirir:

@op_fusion.fuse(
    resolve_fusion_dtypes=True,
    debug=False,
    strict_mode=True,
    static_argnums=None,
    static_argnames=None,
)
  • static_argnums / static_argnames: Birleştirilmiş bir işlevi çağırırken dizi olmayan Python bağımsız değişkenlerini (ör. skaler yapılandırma değerleri veya boole işaretleri) statik olarak işaretleyin.
  • debug=True: Bir işlemin neden birleştirilmediğini veya blok spesifikasyonu yayılımının neden başarısız olduğunu teşhis etmeye yardımcı olmak için izlenen birleştirme jaxpr'lerini yazdırır.
  • strict_mode: Pallas Fuser'ın katı blok spesifikasyonu eşdeğerlik kontrollerini yönetir.

Kuantize Girişler ve Yerleşik Çekirdek Etkinleştirmeleri

Birleştirilmiş prologlar, anında etkinleştirme nicelemesi (AsQArray), önceden nicelenmiş ağırlıklar (qwix.QArray) ve PallasMosaicTpuV2RaggedDot üzerinde yerleşik birleştirilmiş kapı/yukarı etkinleştirmelerle oluşturulur:

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 blok başına bir birleştirilebilir işlem

JAX Pallas Fuser, @op_fusion.fuse kapsamı başına tek bir birleştirilebilir çekirdeği destekler. Birden fazla çekirdeği zincirlerken (ör. bir MoE bloğunda gate_up ve ardından down) her bir birleştirilebilir aşamayı harici bir @jax.jit içinde kendi @op_fusion.fuse işlevine sarmalayın:

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

Açık @jax.custom_vjp ile Otomatik Farklılaştırma

@op_fusion.fuse, ileri hesaplama bloğunu birleştirir ve birleştirilmiş geri geçişleri jax.grad aracılığıyla otomatik olarak sentezlemez. Birleştirilmiş bir bloğu ayırt ederken ileri ve geri çağrıları açık bir @jax.custom_vjp ile sarmalayın. Böylece girişleri/çıkışları ileri ve geri (drhs / dlhs) çekirdeklerle bağımsız olarak birleştirebilirsiniz:

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'ı kullanma

Geriye dönük uyumluluğu korumak ve giriş standartlaştırma, otomatik ayarlama ve meta veri serileştirmeyi sürdürmek için yalın birleştirilebilir çekirdekler ve @jax.experimental.pallas.fuser.fuse yerine Tokamax operatör sarmalayıcıları (tokamax.ragged_dot veya PallasMosaicTpuV2RaggedDot) ile @op_fusion.fuse kullanın. Düşük seviyeli gmm_v2 / tgmm_v2 çekirdeklerini doğrudan çağırıyorsanız @op_fusion.fuse veya @jax.experimental.pallas.fuser.fuse içinde gmm_fuser.gmm_v2_fusible ya da gmm_fuser.tgmm_v2_fusible kullanın:

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 etrafında giriş veya çıkış işlemleri olmadığında, önemsiz 0 denklemli birleştirmeler açılır ve derlenen çekirdek, birleştirilmemiş yolu tam olarak alır.

Desteklenen İşlemler ve Kısıtlamalar

  • Şu anda desteklenen Tokamax işlemleri: PallasMosaicTpuV2RaggedDot (implementation="mosaic_tpu_v2", hem ileri/dlhs gmm_v2 hem de drhs tgmm_v2'yi kapsar).
  • Desteklenen giriş/çıkış JAX temel öğeleri: JAX Pallas Fuser tarafından yönetilir. Yaygın olarak desteklenen işlemler arasında noktasal tekli/ikili matematik, select/clamp, dtype yayınları, broadcast_in_dim, transpose, concatenate/stack/split ve tam bir blok ekseni boyunca reduce_sum (ör. RMSNorm) yer alır. Fuser blok spesifikasyon kuralları olmayan işlemler (ör. lax.pad, kontrol akışı (scan/while/cond) ve reduce_max/reduce_min) birleştirilemez.
  • PallasMosaicTpuV2RaggedDot birleştirme kısıtlamaları:
    • lhs veya out, gmm_v2 içinde birleştirildiğinde (ve lhs veya rhs, tgmm_v2 içinde birleştirildiğinde) size_m, TPU alt şerit döşemesiyle (size_lhs_sublane) hizalanmalıdır.
    • out birleştirildiğinde out_size_n (ve tgmm_v2 için size_k), num_lanes (128) / karo boyutuna hizalanmalıdır ve yalnızca tek çıkışlı epiloglar desteklenir.
    • partial_sum, birleştirme ile desteklenmez.
    • gmm_v2 içindeki birleştirilmiş rhs, fuse_act veya alt bayt paketlenmiş ağırlıklarla birlikte desteklenmez.

Birleştirme ile Uyumlu Çekirdek ve İşlem Yazma

Mimariye Genel Bakış

Fusion dağıtımı; herkese açık görünüm, dahili adaptör, Op sınıfı ve çekirdeğin tamamlayıcı fuser modülü arasında bölünür:

  1. tokamax/ops/op_fusion.py, fuse öğesini herkese açık giriş noktası olarak yeniden dışa aktarır.
  2. tokamax._src.ops.fuser_adapter, jax.experimental.pallas.fuser.fuse etrafında bir JAX kullanıcı bağlamı işareti (in_op_fusion_context()) ayarlar.
  3. Op.__call__ bu bağlamda çalıştırıldığında, alt sınıfın _fusible_fwd yöntemini geçersiz kılıp kılmadığını kontrol eder (kılmıyorsa NotImplementedError hatası verir) ve fuser_adapter.call_fusible_op yöntemine yetki verir.
  4. call_fusible_op, bound_args.default_config ifadesini çözümlerken birleştirme bağlamını askıya alır, dizi yaprakları üzerinde bir fuser.fusible temel öğesini bağlar, Op.fusible_argnames içinde listelenmeyen tüm bağımsız değişkenleri somutlaştırır ve bound_args._tokamax_metadata(config) içinde Op._fusible_fwd(*args, out_fusions=out_fusions, config=config, **kwargs) işlevini çağırır.

1. Adım: Op için fusible_argnames bildirme ve _fusible_fwd geçersiz kılma

Arka uç Op alt sınıfınızda (tam referans için PallasMosaicTpuV2RaggedDot sayfasına bakın):

  1. fusible_argnames parametresini, dizi yaprakları fuser.Fusion kapanışları olarak kalması gereken parametre adlarına ayarlayın. Diğer tüm dizi bağımsız değişkenleri (meta veriler, dizinler veya group_sizes gibi), _fusible_fwd çalıştırılmadan önce call_fusible_op tarafından otomatik olarak normal jax.Array'lere dönüştürülür.
  2. _fusible_fwd ayarını geçersiz kılın. _fwd ((out, residuals) döndürür) işlevinin aksine, _fusible_fwd doğrudan T çıkışını döndürür ve out_fusions ile çözümlenen config değerini alır.
  3. Yaprakları birleştirilmemesi gereken bileşik PyTree işlenenleri (ör. önceden kuantize edilmiş QArray(qvalue, scale) ağırlıkları) için bunları fuser_adapter.materialize(...) ile açıkça somutlaştırın.
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. adım: Fuser entegrasyonunu tamamlayıcı *_fuser.py modülünde tutun

Tokamax'ın çekirdek (gmm_v2.py, tgmm_v2.py) ve fuser entegrasyonu (gmm_fuser.py) arasındaki ayrımını takip edin:

  • Birleştirilmemiş çekirdeğin bağımsız ve kolay okunabilir kalması için jax.experimental.pallas.fuser içe aktarmalarını ana çekirdek dosyasının dışında tutun.
  • Birleştirme spesifikasyonunuzu oluşturmadan önce 0 denklemli önemsiz fuser.Fusion kapanışlarını açın:

    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, işlenenin üretici işlemleri olmasa bile her giriş dizisi yaprağını bir Fusion ile sarmalar. Önemsiz kapanışların sarmalamasını açmak, dokunulmamış işlenenleri değiştirilmemiş, birleştirilmemiş BlockSpec yolunda sıfır çalışma zamanı ek yüküyle tutar.

  • Temel çekirdeğiniz @jax.jit ile dekore edilmişse birleştirilebilir yolda inspect.unwrap(base_kernel) işlevini çağırın. @jax.jit, fuser.Fusion bağımsız değişkenlerini reddeder.

  • Yalnızca çekirdek kullanan arayanların da birleştirilebilir giriş noktanızı doğrudan @fuser.fuse içinde çağırabilmesi gerekiyorsa yalnızca jax.Array kullanan çağrıları algılayın ve fuser.fusible'yi otomatik olarak bağlayın (gmm_fuser.gmm_v2_fusible'nin yaptığı gibi).

3. adım: Fusion'ları açın ve fuser_adapter ile BlockSpec'leri dönüştürün

Düşük düzeyli fuser API'leri doğrudan çağırmak yerine tokamax._src.ops.fuser_adapter içindeki paylaşılan yardımcıları kullanın:

  • Giriş prologunu açma:

    lhs_fn, lhs_values, lhs_values_type = fuser_adapter.unpack_input_fusion(lhs)
    

    (fn, values, values_type) döndürür. Burada values, giriş bölümü tarafından kapatılan HBM dizilerinin demetidir ve values_type, bunların ShapeDtypeStruct'lerini içerir.

  • Tek çıkışlı bir epilog açma:

    out_fn, out_values, out_values_type, out_init = (
        fuser_adapter.unpack_output_fusion(out_fusions, raw_out_type)
    )
    

    Pallas Fuser'ın 1-demet çıkış kuralını tek bir ShapeDtypeStruct (out_init) olarak açar ve çok çıkışlı epiloglarda NotImplementedError hatası verir.

  • Bir girişi BlockSpec bir giriş bölümü üzerinden geriye çekme:

    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,
    )
    
  • Sonsöz aracılığıyla çıkışı BlockSpec gönderme ve alma:

    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 boyutlu yayınlarla şekli koruyan azaltmaları (ör. ham fuser.push_block_spec'yi tetikleyen RMSNorm epilogları) işler, alınan spesifikasyonun çekirdeğin yazılı out_spec değeriyle eşleştiğini doğrular, 1 demetli dönüş değerini açar ve desteklenen JAX sürümleri arasında uyumluluğu korur.

4. adım: Özellikleri ve geri çağırmaları Pallas çekirdeğine bağlama

  1. Yakalanan HBM girişlerini, alınan BlockSpecs ile birlikte iletin:
    • Birleştirilmiş işlenen (lhs_val_specs ile eşlenmiş) yerine giriş prologu values kullanın.
    • Çıkış epilog yan girişleri (out_values, örneğin epilog sapması veya kalıntısı), out_fusion_input_specs ile eşlenmiş salt okunur HBM çekirdek girişleri olarak iletilir. Böylece pltpu.emit_pipeline, parçalarını VMEM'e önceden getirir. Birleştirilmediğinde hem referanslar hem de spesifikasyonlar (0 PyTree yaprağı) için boş bir tuple () iletin.
  2. Birleştirme modu başına farklı PyTree türleri kullanma:
    • pltpu.emit_pipeline, jax.tree.map(..., in_specs, in_refs)'i eşler. Bu nedenle, her giriş referans kapsayıcısı ve in_spec kapsayıcısı, tam olarak aynı @jax.tree_util.register_dataclass PyTree türünü paylaşmalıdır (örneğin, birleştirilmemiş lhs için LhsRef[T] ve prolog birleştirilmiş lhs için FusedLhsRef[T]).
  3. Çekirdek gövdesindeki VMEM parçalarında alınan geri çağırmaları değerlendirme:

    • Çekilen her işlevin imzası fn(program_ids, scalar_prefetch, *args).
    • pltpu.emit_pipeline(..., _explicit_indices=True) içinde, num_scalar_prefetch=0 olduğunda pids = step.index (aksi takdirde tuple(pl.program_id(i) for i in range(grid_len))) ve () değerlerini iletin:
    # 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)
    

Sık Karşılaşılan Sorunlar

  • pl.BoundedSlice ve reshape: Pallas Fuser'ın yeniden şekillendirme çekme kuralı pl.BoundedSlice değerini reddediyor. Birleştirilmemiş çekirdeğiniz, emit_pipeline işleminden önce 2D HBM girişlerini 3D alt şerit döşemeli referanslara dönüştürüyorsa birleştirilmiş işlenenleri çekmeden veya göndermeden önce spesifikasyonu 2D BlockSpec((pl.BoundedSlice(tile_m), col_dim), ...) biçimine dönüştürün (gmm_fuser.py içindeki _to_2d_bounded_spec bölümüne bakın).
  • Satır maskeleme ile epilog sıralaması: Çekirdeğiniz, grup dışı veya dolgu satırlarını sıfıra maskeliyor ve adımlar arasında kısmi alt şerit parçalarını birleştiriyorsa sıfır maskesini uygulamadan out_fn önce çalıştırın. Böylece sıfır olmayan epiloglar (ör. + bias) maskelenmiş satırları bozmaz.
  • pl.kernel ile Sequence out_type: pl.kernel, bir tuple veya list out_type öğesini birden fazla konumsal out_ref bağımsız değişkene açar. fuser_adapter.unpack_output_fusion kullanıldığında tek çıkışlı out_init, yalın bir ShapeDtypeStruct olarak kalır.
  • Ana makine tarafındaki dolgu ve birleştirilmiş şekiller: Pallas Fuser'da lax.pad kuralı veya hizalanmamış lax.slice push/pull kuralları olmadığından, birleştirme spesifikasyonunuzun prepare() yönteminde hizalama koşullarını erken doğrulayın ve Fusion nesnelerini doldurmak yerine desteklenmeyen şekiller için NotImplementedError hatası verin.
  • _fusible_fwd içinde yardımcı Op'ler: call_fusible_op, default_config çözünürlüğü sırasında ve _fusible_fwd içinde in_op_fusion_context()'yi askıya alır. Bu nedenle, _fusible_fwd içinde birleştirilmemiş bir yardımcı Op'i çağırmak, iç içe yerleştirilmiş birleştirme hatalarını tetiklemeden normal _fwd yolunu çalıştırır.

Test Kontrol Listesi

Bir operatöre birleştirme desteği eklerken şunları ele alın:

  1. Prologue füzyonu (RMSNorm gibi noktasal ve tam eksenli azaltma), epilogue füzyonu (sapma veya artık gibi harici yan girişler olan ve olmayan) ve birleşik prologue + epilogue.
  2. Birleştirme olmadan eşdeğerlik: Birleştirilebilir giriş noktasını çevreleyen işlemler (düz, @op_fusion.fuse ve @fuser.fuse) olmadan çağırmanın, birleştirilmemiş çekirdekle bit düzeyinde aynı çıkışı (chex.assert_trees_all_equal) ürettiğini doğrulayın.
  3. Açık @jax.custom_vjp gradyanlar: İleri değerlerin ve gradyanların birleştirilmemiş referansla eşleştiğini doğrulayın.
  4. Desteklenmeyen kombinasyonlar: Hizalanmamış şekiller veya uyumsuz çekirdek seçenekleri için net NotImplementedError mesajlarını doğrulayın.

Referans Uygulama