Kitaplık Tasarımı

Tokamax; çekirdek yazma, optimizasyon, bakım ve üretim kullanımıyla ilgili tipik geliştirici yolculuklarını standartlaştırmak ve basitleştirmek için tasarlanmıştır. Bunu, kitaplıktaki tüm operatörlerin devraldığı ve iyi yapılandırılmış bir çerçeve içinde uyguladığı temel sınıflar ve paylaşılan altyapı aracılığıyla yapar.

Operatör Katmanları

Tokamax Base Class

tokamax.Op, Tokamax'ın temel sınıfıdır ve kitaplıktaki her operatör için temel görevi görür. Türetilmiş bir operatör çağrıldığında bu katman, aşağıdaki işlevleri otomatik olarak gerçekleştirir:

  • Bağımsız Değişken Bağlama: Herhangi bir hesaplama çalıştırılmadan önce temel sınıf, arayanın bağımsız değişkenlerini tek bir standart temsile normalleştirir ve doğrular. Böylece önbelleğe alma, sezgisel yöntemler ve çekirdek yürütme, girişlerin nasıl iletildiğine bakılmaksızın iş yükü hakkında tek tip bir şekilde (BoundArguments nesnesi aracılığıyla) akıl yürütebilir (op.bind() bölümüne bakın).
  • Cihaz Doğrulama: Donanım uyuşmazlıklarını erkenden yakalamak için operatör, çalıştırmadan önce cihaz desteğini hedef hızlandırıcıya göre doğrular. Bununla birlikte, bir CPU ana makinesinden çapraz derleme yaparken bu kontrolün atlanmasına izin verir (op.supported_on(), bypass_device_check=True ve config.cross_compile(True) bölümlerine bakın).
  • Batching Capture: En iyi çekirdek yapılandırması (Config) genellikle tek bir dilim yerine tam toplu problem boyutuna bağlı olduğundan, temel sınıf, bir operatör vektörleştirildiğinde (jax.vmap) çevreleyen toplu boyutları yakalar. Böylece buluşsal yöntemler ve otomatik ayarlama önbellekleri gerçek iş yükü şekli için optimize edilebilir (op._capture_batched_args() bölümüne bakın).
  • Yapılandırma Çözünürlüğü: Manuel ayarlama gerektirmeden kullanıma hazır güçlü performans sağlamak için temel sınıf, arayan tarafından sağlanmadığında çekirdek hiperparametrelerini otomatik olarak çözer. Bu işlem, varsa disk tabanlı bir otomatik ayarlama önbelleğinde önceden otomatik olarak ayarlanmış ayarları yeniden kullanarak veya yerleşik sezgisel yöntemlere geri dönerek yapılır (BoundArguments.default_config bölümüne bakın).
  • StableHLO Metadata Serialization: To make compiled programs introspectable for offline profiling and automated tuning, the base class embeds operator metadata into the lowered graph so downstream tools can reconstruct which operators ran and with what inputs (shapes, types, etc.) directly from a compiled module or performance profile (see _tokamax_metadata()).
  • İleri Yönlü Yürütme ve Özel VJP: Özel donanım çekirdekleri genellikle standart otomatik türev alma ile verimli bir şekilde türevlenemediğinden temel sınıf, ileri ve geri yönlü yürütmeyi bir çift olarak koordine eder. Bu sayede ileri yönlü geçiş, gradyan hesaplama sırasında ara değerleri doğrudan özel bir geri yönlü çekirdeğe iletebilir (op._fwd() ve jax.custom_vjp çağrılarına bakın).

İşleme Özgü Temel Sınıf

Her operatör ailesi, temel operatör sınıfından devralınan kendi temel sınıfını tanımlar ve tüm arka uçlarda paylaşılan sözleşmeyi oluşturur (örneğin, RaggedDot adresine bakın):

  • Referans Uygulama: Her operatör temel sınıfı, geçerli olduğunda gradyanlar da dahil olmak üzere tam matematiksel spesifikasyonun taşınabilir, saf JAX referans uygulamasını sağlar. Bu, sayısal doğruluk testleri için gerçek doğru görevi görür ve her donanımda çalışan bir yedek garanti eder (RaggedDot._fwd() bölümüne bakın).
  • Standart Bağlama: Kullanıcılar aynı matematiksel işlemi birden fazla şekilde ifade edebildiğinden (ör. farklı maske biçimleri, hassasiyet ayarları veya boyut spesifikasyonları iletme) operatör temel sınıfı, girişleri normalleştirir ve şekil ile tür uyumluluğunu önceden kontrol eder. Böylece, her bir donanım arka ucunun yalnızca tek bir öngörülebilir giriş biçimini işlemesi gerekir (bkz. RaggedDot.bind()).

İşlem Uygulama Sınıfları

Bu sınıflar, donanıma özgü çekirdek uygulamalarını sağlar ve kullanıcılar tarafından doğrudan örneklendirilebilir ve çağrılabilir. Her uygulama, operatöre özel temel sınıfından devralınır ve arka uca özel davranışı sağlar (örneğin, PallasMosaicTpuRaggedDot bölümüne bakın):

  • Temel işlevsellik: Donanım çekirdeğinin gerçek yürütme işleminin tanımlandığı yerdir. Genellikle Pallas gibi bir çekirdek dili kullanılır. Bir işlem özel bir geriye doğru geçiş gerektirdiğinde, gradyan çekirdeği genellikle kendi birinci sınıf operatör uygulaması olarak modellenir, böylece bağımsız olarak yapılandırılabilir, ayarlanabilir ve test edilebilir. En düşük düzeydeki çekirdek kodu, modülerlik için genellikle ayrı bir yardımcı dosyaya ayrılsa da bu sınıf, söz konusu çekirdeği çağırmak için birincil arayüz görevi görür (PallasMosaicTpuRaggedDot._fwd() bölümüne bakın).
  • Yapılandırma: Donanım çekirdekleri genellikle performans düğmelerini (ör. karo boyutları, ardışık düzen aşamaları veya bellek arabelleğe alma stratejileri) gösterdiğinden her arka uç, kullanıcıların veya otomatik araçların çekirdeğin nasıl bölümlendirildiğini, derlendiğini ve yürütüldüğünü kontrol etmesine olanak tanıyan özel bir yapılandırma yapısı tanımlar (Config bölümüne bakın).
  • Sezgisel yöntemler: Her iş yükü önceden otomatik olarak ayarlanmadığından her arka uç, problem boyutlarına, veri türlerine ve hızlandırıcı özelliklerine göre makul varsayılan ayar parametrelerini seçen yerleşik sezgisel yöntemler sağlar (bkz. _get_heuristics_config()).
  • Otomatik Ayarlama Arama Alanı: En yüksek performansın önemli olduğu iş yükleri için her arka uç, belirli bir sorun şekli için geçerli parametre kombinasyonlarından oluşan bir otomatik ayarlama arama alanı tanımlar. Bu sayede otomatik ayarlayıcı, adayları karşılaştırabilir ve en hızlı yapılandırmayı keşfedebilir (bkz. _get_autotuning_configs()).
  • Uygulamaya Özel Doğrulama: Donanım çekirdekleri genellikle genel matematiksel işlemden daha katı koşullara (ör. boyut hizalama kuralları veya sınırlı veri türü desteği) sahiptir. Her uygulama bu kısıtlamaları doğrular ve bir iş yükü işlenemediğinde sinyal göndererek daha üst düzey dağıtıcıların başka bir arka uca sorunsuz bir şekilde geri dönmesine olanak tanır (bkz. PallasMosaicTpuRaggedDot._fwd()).

Üst Düzey API

Çoğu operatörün birden fazla arka ucu vardır (ör.bir veya daha fazla donanıma özel çekirdeğin yanı sıra taşınabilir bir referans uygulaması) ve tek bir tanıdık, üst düzey giriş noktası (ör. standart bir jax.lax işlevi) sunar. Bu katman, kullanıcılara donanımları ve giriş şekilleri için desteklenen en iyi arka ucu otomatik olarak seçen basit, kullanıma hazır bir arayüz sunmak üzere tasarlanmıştır. Bununla birlikte, kullanıcılar istedikleri zaman belirli bir uygulamayı talep edebilir (tokamax.ragged_dot() bölümüne bakın).

ArgSpecs

Önemli iş yükü şekillerinin paylaşılan bir kataloğunu tutmak, çekirdekleri arka uçlar arasında tutarlı bir şekilde test etmek ve optimize etmek için çok önemlidir. Tokamax, bu temsili üretim ve karşılaştırma şekillerini, bir operatörün tüm uygulamalarında paylaşılan iş yükü spesifikasyonları olarak yakalar. Bu sayede sürekli entegrasyon testleri, regresyon karşılaştırmaları ve otomatik ayarlama ardışık düzenleri, farklı iş akışları için etiketlere göre filtrelenebilen tek bir doğruluk kaynağına sahip olur (ragged_dot için ArgSpecs'e bakın).

Depo Yapısı

Dahili uygulama kodu, özel kaynak ağacında (bkz. tokamax/_src) bulunurken operatörler, otomatik ayarlama, karşılaştırma ve yapılandırma için herkese açık semboller, üst düzey modüller aracılığıyla yeniden dışa aktarılır (bkz. tokamax/__init__.py).

Her operatör dizininde (bkz. tokamax/_src/ops) dosyalar, burada düzensiz nokta kullanılarak gösterilen tutarlı bir adlandırma kuralına uyar:

  • Üst Düzey API: Herkese açık işlevsel giriş noktasını ve arka uç gönderim mantığını tanımlar (api.py bölümüne bakın).
  • İşleme Özel Temel Sınıf: Taşınabilir referans uygulamasını tanımlar (bkz. base.py).
  • Arka uç uygulamaları: Donanıma özgü operatör sınıflarını, yapılandırmaları, sezgisel yöntemleri ve otomatik ayarlama alanlarını tanımlar (pallas_mosaic_tpu.py bölümüne bakın).
  • Düşük Seviyeli Çekirdekler: Bağımsız çekirdek uygulamalarını ve paylaşılan düşük seviyeli yardımcıları yardımcı modüllere ayırır (bkz. pallas_mosaic_tpu_kernel.py).
  • İş Yükü Spesifikasyonları: Test, karşılaştırma ve otomatik ayarlama için standart giriş şekillerini kataloglar (arg_specs.py bölümüne bakın).
  • Test Paketleri: Arka uç başına test paketlerinin yanı sıra paylaşılan parametreleştirilmiş doğruluk kontrollerini tanımlar (bkz. test_base.py).

experimental dizinindeki işlemler benzer bir yapıya sahiptir ancak herkese açık API'de gösterilmeyebilir. Bu işlemler, hızlı iterasyon ve keşif için tasarlanmıştır. Sık sık ve önemli ölçüde değişebilir. Bu işlemler için sürekli bakım ve destek beklentileri genellikle daha düşüktür.

Kullanıcılar hangi katmanı çağırmalıdır?

Giriş noktası seçmek, temel olarak kolaylık ve kontrol arasında bir denge kurmaktır. Çoğu kullanıcı, tanıdık bir stil arayüzü sağlayan ve otomatik olarak uygun bir arka uç uygulaması seçen üst düzey işlevsel API aracılığıyla operatörleri çağırarak başlamalıdır. Belirleyici arka uç seçimi gerektiğinde kullanıcılar, aynı çağrı imzasını korurken üst düzey işleve açık bir uygulama seçimi iletebilir. Kullanıcılar, maksimum kontrol için belirli bir operatör uygulama sınıfını doğrudan örneklendirerek çekirdek hiperparametrelerini (ör. karo boyutları) özelleştirebilir ve arka uca özel bağımsız değişkenler iletebilir.

Bir operatör uygulama sınıfından geçmeden doğrudan alt düzey çekirdek işlevlerini çağırmanız önerilmez. Bunu yapmak, otomatik ayarlama, giriş doğrulama ve standartlaştırma ile meta veri serileştirme gibi temel altyapıyı atlar. Operatör sarmalayıcılar kasıtlı olarak hafif olduğundan, anlamlı bir ek yük tasarrufu sağlamaz. Örneğin, uygun otomatik ayarlanmış hiperparametreler olmadığında kullanıcılar muhtemelen önemli ölçüde yetersiz performans görür.

İleri Düzey Konular

Operatör birleştirme

Birleştirilebilir Pallas TPU operatörleri, @tokamax.ops.op_fusion.fuse aracılığıyla çevreleyen JAX prologlarını ve epiloglarını doğrudan çekirdeğe birleştirmeyi destekler. Kullanım örnekleri ve birleştirmeyle uyumlu çekirdekler ve Op alt sınıflar oluşturma talimatları için Operatör Birleştirme kılavuzuna bakın.

Serileştirme

Çekirdekler StableHLO olarak serileştirilebilir. Çekirdek çağrıları, JAX özel çağrılarıdır. Bunlar jax.export içinde varsayılan olarak yasaklanmıştır. Tüm Tokamax çekirdeklerinin dışa aktarılmasına izin vermek için tokamax.DISABLE_JAX_EXPORT_CHECKS kullanılması gerekir:

from jax import export

f_grad_exported = export.export(f_grad, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS)(
    jax.ShapeDtypeStruct(x.shape, x.dtype),
    jax.ShapeDtypeStruct(scale.shape, scale.dtype),
)

Tokamax çekirdekleriyle serileştirilen işlevlerin, standart StableHLO'nun cihazdan bağımsız olma özelliğini kaybettiğini unutmayın. Tokamax, iki serileştirme garantisi sunar:

  1. Belirli bir cihazda serileştirilen bir serileştirilmiş işlevin, serileştirildiği cihazda çalışacağı garanti edilir.
  2. Tokamax, JAX ile aynı uyumluluk garantilerini sunar: 6 ay geriye dönük uyumluluk.

Çapraz Derleme ve CPU Dışa Aktarma

Tokamax çekirdekleri, CPU ana makinesinde dışa aktarılabilir veya çapraz derlenebilir:

  • Açık uygulama seçimi (ör. implementation="mosaic_tpu_v2"), ana cihaz doğrulamasını otomatik olarak atlar.
  • Alternatif olarak, tokamax.config.cross_compile(True) kullanarak çapraz derlemeyi genel olarak etkinleştirebilirsiniz:
with tokamax.config.cross_compile(True):
  f_exported = export.export(
      f, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS
  )(
      jax.ShapeDtypeStruct(x.shape, x.dtype),
      ...,
  )