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/dlhsgmm_v2hem de drhstgmm_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/splitve tam bir blok ekseni boyuncareduce_sum(ör.RMSNorm) yer alır. Fuser blok spesifikasyon kuralları olmayan işlemler (ör.lax.pad, kontrol akışı (scan/while/cond) vereduce_max/reduce_min) birleştirilemez. PallasMosaicTpuV2RaggedDotbirleştirme kısıtlamaları:lhsveyaout,gmm_v2içinde birleştirildiğinde (velhsveyarhs,tgmm_v2içinde birleştirildiğinde)size_m, TPU alt şerit döşemesiyle (size_lhs_sublane) hizalanmalıdır.outbirleştirildiğindeout_size_n(vetgmm_v2içinsize_k),num_lanes(128) / karo boyutuna hizalanmalıdır ve yalnızca tek çıkışlı epiloglar desteklenir.partial_sum, birleştirme ile desteklenmez.gmm_v2içindeki birleştirilmişrhs,fuse_actveya 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:
tokamax/ops/op_fusion.py,fuseöğesini herkese açık giriş noktası olarak yeniden dışa aktarır.tokamax._src.ops.fuser_adapter,jax.experimental.pallas.fuser.fuseetrafında bir JAX kullanıcı bağlamı işareti (in_op_fusion_context()) ayarlar.Op.__call__bu bağlamda çalıştırıldığında, alt sınıfın_fusible_fwdyöntemini geçersiz kılıp kılmadığını kontrol eder (kılmıyorsaNotImplementedErrorhatası verir) vefuser_adapter.call_fusible_opyöntemine yetki verir.call_fusible_op,bound_args.default_configifadesini çözümlerken birleştirme bağlamını askıya alır, dizi yaprakları üzerinde birfuser.fusibletemel öğesini bağlar,Op.fusible_argnamesiçinde listelenmeyen tüm bağımsız değişkenleri somutlaştırır vebound_args._tokamax_metadata(config)içindeOp._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):
fusible_argnamesparametresini, dizi yapraklarıfuser.Fusionkapanışları olarak kalması gereken parametre adlarına ayarlayın. Diğer tüm dizi bağımsız değişkenleri (meta veriler, dizinler veyagroup_sizesgibi),_fusible_fwdçalıştırılmadan öncecall_fusible_optarafından otomatik olarak normaljax.Array'lere dönüştürülür._fusible_fwdayarını geçersiz kılın._fwd((out, residuals)döndürür) işlevinin aksine,_fusible_fwddoğrudanTçıkışını döndürür veout_fusionsile çözümlenenconfigdeğerini alır.- 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.fuseriçe aktarmalarını ana çekirdek dosyasının dışında tutun. Birleştirme spesifikasyonunuzu oluşturmadan önce 0 denklemli önemsiz
fuser.Fusionkapanış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 xfuser.fusible, işlenenin üretici işlemleri olmasa bile her giriş dizisi yaprağını birFusionile sarmalar. Önemsiz kapanışların sarmalamasını açmak, dokunulmamış işlenenleri değiştirilmemiş, birleştirilmemişBlockSpecyolunda sıfır çalışma zamanı ek yüküyle tutar.Temel çekirdeğiniz
@jax.jitile dekore edilmişse birleştirilebilir yoldainspect.unwrap(base_kernel)işlevini çağırın.@jax.jit,fuser.Fusionbağımsız değişkenlerini reddeder.Yalnızca çekirdek kullanan arayanların da birleştirilebilir giriş noktanızı doğrudan
@fuser.fuseiçinde çağırabilmesi gerekiyorsa yalnızcajax.Arraykullanan çağrıları algılayın vefuser.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. Buradavalues, giriş bölümü tarafından kapatılan HBM dizilerinin demetidir vevalues_type, bunlarınShapeDtypeStruct'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ı epiloglardaNotImplementedErrorhatası verir.Bir girişi
BlockSpecbir 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ışı
BlockSpecgö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. hamfuser.push_block_spec'yi tetikleyenRMSNormepilogları) işler, alınan spesifikasyonun çekirdeğin yazılıout_specdeğ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
- Yakalanan HBM girişlerini, alınan
BlockSpecs ile birlikte iletin:- Birleştirilmiş işlenen (
lhs_val_specsile eşlenmiş) yerine giriş prologuvalueskullanın. - Çıkış epilog yan girişleri (
out_values, örneğin epilog sapması veya kalıntısı),out_fusion_input_specsile eşlenmiş salt okunur HBM çekirdek girişleri olarak iletilir. Böylecepltpu.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.
- Birleştirilmiş işlenen (
- 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ı vein_speckapsayıcısı, tam olarak aynı@jax.tree_util.register_dataclassPyTree türünü paylaşmalıdır (örneğin, birleştirilmemişlhsiçinLhsRef[T]ve prolog birleştirilmişlhsiçinFusedLhsRef[T]).
Ç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=0olduğundapids = step.index(aksi takdirdetuple(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)- Çekilen her işlevin imzası
Sık Karşılaşılan Sorunlar
pl.BoundedSlicevereshape: Pallas Fuser'ın yeniden şekillendirme çekme kuralıpl.BoundedSlicedeğerini reddediyor. Birleştirilmemiş çekirdeğiniz,emit_pipelineiş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 2DBlockSpec((pl.BoundedSlice(tile_m), col_dim), ...)biçimine dönüştürün (gmm_fuser.pyiçindeki_to_2d_bounded_specbö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.kernelileSequenceout_type:pl.kernel, birtupleveyalistout_typeöğesini birden fazla konumsalout_refbağımsız değişkene açar.fuser_adapter.unpack_output_fusionkullanıldığında tek çıkışlıout_init, yalın birShapeDtypeStructolarak kalır.- Ana makine tarafındaki dolgu ve birleştirilmiş şekiller: Pallas Fuser'da
lax.padkuralı veya hizalanmamışlax.slicepush/pull kuralları olmadığından, birleştirme spesifikasyonunuzunprepare()yönteminde hizalama koşullarını erken doğrulayın veFusionnesnelerini doldurmak yerine desteklenmeyen şekiller içinNotImplementedErrorhatası verin. _fusible_fwdiçinde yardımcıOp'ler:call_fusible_op,default_configçözünürlüğü sırasında ve_fusible_fwdiçindein_op_fusion_context()'yi askıya alır. Bu nedenle,_fusible_fwdiçinde birleştirilmemiş bir yardımcıOp'i çağırmak, iç içe yerleştirilmiş birleştirme hatalarını tetiklemeden normal_fwdyolunu çalıştırır.
Test Kontrol Listesi
Bir operatöre birleştirme desteği eklerken şunları ele alın:
- Prologue füzyonu (
RMSNormgibi 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. - Birleştirme olmadan eşdeğerlik: Birleştirilebilir giriş noktasını çevreleyen işlemler (düz,
@op_fusion.fuseve@fuser.fuse) olmadan çağırmanın, birleştirilmemiş çekirdekle bit düzeyinde aynı çıkışı (chex.assert_trees_all_equal) ürettiğini doğrulayın. - Açık
@jax.custom_vjpgradyanlar: İleri değerlerin ve gradyanların birleştirilmemiş referansla eşleştiğini doğrulayın. - Desteklenmeyen kombinasyonlar: Hizalanmamış şekiller veya uyumsuz çekirdek seçenekleri için net
NotImplementedErrormesajlarını doğrulayın.
Referans Uygulama
- Herkese açık cephe:
tokamax/ops/op_fusion.py Opsevk ve paylaşılan yardımcılar:tokamax/_src/ops/fuser_adapter.py- Çekirdek fuser entegrasyonu (
GmmFusionSpec/TgmmFusionSpec):tokamax/_src/ops/gmm_v2/gmm_fuser.py Op._fusible_fwdentegrasyonu:tokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2.py- Çekirdek ve
Opbirleştirme testleri:tokamax/_src/ops/gmm_v2/gmm_fuser_test.pyvetokamax/_src/ops/ragged_dot/pallas_mosaic_tpu_v2_test.py