Desain Library

Tokamax dirancang untuk menstandarkan dan menyederhanakan perjalanan developer pada umumnya terkait penulisan, pengoptimalan, pemeliharaan, dan penggunaan produksi kernel. Hal ini dilakukan melalui class dasar dan infrastruktur bersama yang diwarisi dan diterapkan oleh semua operator dalam library dalam framework yang terstruktur dengan baik.

Lapisan Operator

Kelas Dasar Tokamax

tokamax.Op adalah class dasar Tokamax, yang berfungsi sebagai dasar untuk setiap operator di library. Saat operator turunan dipanggil, lapisan ini akan otomatis menangani fungsi berikut:

  • Pengikatan Argumen: Sebelum komputasi apa pun berjalan, class dasar menormalisasi dan memvalidasi argumen pemanggil menjadi satu representasi kanonis sehingga caching, heuristik, dan eksekusi kernel dapat mempertimbangkan workload secara seragam (melalui objek BoundArguments), terlepas dari cara input diteruskan (lihat op.bind()).
  • Validasi Perangkat: Untuk mendeteksi ketidakcocokan hardware sejak awal, operator memverifikasi dukungan perangkat terhadap akselerator target sebelum dijalankan, sekaligus tetap mengizinkan pemeriksaan ini dilewati saat melakukan kompilasi silang dari host CPU (lihat op.supported_on(), bypass_device_check=True, dan config.cross_compile(True)).
  • Pengambilan Batching: Karena konfigurasi kernel terbaik (Config) sering kali bergantung pada ukuran masalah batch penuh, bukan satu slice, class dasar menangkap dimensi batch di sekitarnya saat operator divektorisasi (jax.vmap) sehingga heuristik dan cache penyesuaian otomatis dapat mengoptimalkan bentuk workload yang sebenarnya (lihat op._capture_batched_args()).
  • Resolusi Konfigurasi: Untuk memberikan performa yang kuat secara langsung tanpa memerlukan penyesuaian manual, class dasar akan menyelesaikan hyperparameter kernel secara otomatis setiap kali pemanggil tidak menyediakannya -- menggunakan kembali setelan yang telah disesuaikan secara otomatis sebelumnya dalam cache penyesuaian otomatis berbasis disk jika tersedia, atau kembali ke heuristik bawaan (lihat BoundArguments.default_config).
  • Serialisasi Metadata StableHLO: Untuk membuat program yang dikompilasi dapat diintrospeksi untuk pembuatan profil offline dan penyesuaian otomatis, class dasar menyematkan metadata operator ke dalam grafik yang diturunkan sehingga alat downstream dapat merekonstruksi operator mana yang dijalankan dan dengan input apa (bentuk, jenis, dll.) langsung dari modul yang dikompilasi atau profil performa (lihat _tokamax_metadata()).
  • Eksekusi Maju dan VJP Kustom: Karena kernel hardware khusus sering kali tidak dapat dibedakan secara efisien oleh diferensiasi otomatis standar, class dasar mengoordinasikan eksekusi maju dan mundur sebagai pasangan, sehingga penerusan maju dapat meneruskan nilai perantara secara langsung ke kernel mundur kustom selama komputasi gradien (lihat op._fwd()) dan panggilan ke jax.custom_vjp.

Class Dasar Khusus Operasi

Setiap kelompok operator menentukan class dasarnya sendiri yang diwarisi dari class operator dasar dan menetapkan kontrak yang dibagikan di semua backend (misalnya, lihat RaggedDot):

  • Implementasi Referensi: Setiap class dasar operator menyediakan implementasi referensi JAX murni yang portabel dari spesifikasi matematika lengkap, termasuk gradien jika berlaku. Hal ini berfungsi sebagai kebenaran nyata untuk pengujian kebenaran numerik dan menjamin penggantian yang berfungsi pada hardware apa pun (lihat RaggedDot._fwd()).
  • Binding Kanonis: Karena pengguna dapat mengekspresikan operasi matematika yang sama dengan berbagai cara—seperti meneruskan berbagai bentuk mask, setelan presisi, atau spesifikasi dimensi—class dasar operator menormalisasi input dan memeriksa kompatibilitas bentuk dan jenis di awal sehingga backend hardware individual hanya perlu menangani satu format input yang dapat diprediksi (lihat RaggedDot.bind()).

Class Implementasi Operasi

Class ini menyediakan implementasi kernel khusus hardware dan dapat diinstansiasi serta dipanggil langsung oleh pengguna. Setiap implementasi mewarisi dari class dasar khusus operator dan menyediakan perilaku khusus backend (misalnya, lihat PallasMosaicTpuRaggedDot):

  • Fungsi Inti: Di sinilah eksekusi kernel hardware yang sebenarnya ditentukan, biasanya menggunakan bahasa kernel seperti Pallas. Jika suatu operasi memerlukan backward pass khusus, kernel gradien biasanya dimodelkan sebagai implementasi operator kelas satu tersendiri sehingga dapat dikonfigurasi, disesuaikan, dan diuji secara independen. Meskipun kode kernel tingkat terendah sering kali difaktorkan ke dalam file bantuan terpisah untuk modularitas, class ini berfungsi sebagai antarmuka utama untuk memanggil kernel tersebut (lihat PallasMosaicTpuRaggedDot._fwd()).
  • Konfigurasi: Karena kernel hardware sering kali mengekspos tombol performa—seperti ukuran ubin, tahap pipeline, atau strategi buffering memori, setiap backend menentukan struktur konfigurasi khusus yang memungkinkan pengguna atau alat otomatis mengontrol cara kernel dipartisi, dikompilasi, dan dieksekusi (lihat Config).
  • Heuristik: Tidak semua workload telah disesuaikan secara otomatis sebelumnya, sehingga setiap backend menyediakan heuristik bawaan yang memilih parameter penyesuaian default yang wajar berdasarkan dimensi masalah, jenis data, dan spesifikasi akselerator (lihat _get_heuristics_config()).
  • Autotuning Search Space: Untuk workload yang mengutamakan performa puncak, setiap backend menentukan ruang penelusuran penyesuaian otomatis dari kombinasi parameter yang valid untuk bentuk masalah tertentu, sehingga autotuner dapat melakukan benchmark terhadap kandidat dan menemukan konfigurasi tercepat (lihat _get_autotuning_configs()).
  • Validasi Khusus Implementasi: Kernel hardware sering kali memiliki persyaratan yang lebih ketat daripada operasi matematika umum, seperti aturan penyelarasan dimensi atau dukungan jenis data yang terbatas. Setiap implementasi memvalidasi batasan dan sinyal ini saat workload tidak dapat ditangani, sehingga dispatcher tingkat yang lebih tinggi dapat beralih dengan lancar ke backend lain (lihat PallasMosaicTpuRaggedDot._fwd()).

API Tingkat Tinggi

Sebagian besar operator memiliki beberapa backend—seperti implementasi referensi portabel bersama satu atau beberapa kernel khusus hardware—dan mengekspos satu titik entri tingkat tinggi yang sudah dikenal (misalnya, fungsi jax.lax standar). Lapisan ini dirancang untuk memberi pengguna antarmuka drop-in sederhana yang otomatis memilih backend yang didukung terbaik untuk hardware dan bentuk input mereka, sekaligus memungkinkan mereka meminta implementasi tertentu jika diinginkan (lihat tokamax.ragged_dot()).

ArgSpecs

Mempertahankan katalog bersama bentuk workload yang penting sangat penting untuk menguji dan mengoptimalkan kernel secara konsisten di seluruh backend. Tokamax menangkap bentuk produksi dan benchmark yang representatif ini sebagai spesifikasi workload yang dibagikan di semua implementasi operator. Hal ini memberikan pengujian continuous integration, benchmark regresi, dan pipeline penyesuaian otomatis satu sumber tepercaya yang dapat difilter menurut tag untuk berbagai alur kerja (lihat ArgSpecs untuk ragged_dot).

Struktur Repositori

Kode implementasi internal berada di bawah hierarki sumber pribadi (lihat tokamax/_src), sementara simbol publik untuk operator, penyesuaian otomatis, tolok ukur, dan konfigurasi diekspor ulang melalui modul tingkat atas (lihat tokamax/__init__.py).

Dalam setiap direktori operator (lihat tokamax/_src/ops), file mengikuti konvensi penamaan yang konsisten, yang diilustrasikan di sini menggunakan titik tidak rata:

  • API Tingkat Tinggi: Menentukan titik entri fungsional publik dan logika pengiriman backend (lihat api.py).
  • Class Dasar Khusus Operasi: Menentukan implementasi referensi portabel (lihat base.py).
  • Implementasi Backend: Menentukan class operator, konfigurasi, heuristik, dan ruang penyesuaian otomatis khusus hardware (lihat pallas_mosaic_tpu.py).
  • Kernel Tingkat Rendah: Memisahkan implementasi kernel mandiri dan helper tingkat rendah bersama ke dalam modul pendamping (lihat pallas_mosaic_tpu_kernel.py).
  • Spesifikasi Workload: Mengatalogkan bentuk input kanonis untuk pengujian, benchmarking, dan penyesuaian otomatis (lihat arg_specs.py).
  • Suite Pengujian: Menentukan pemeriksaan kebenaran berparameter bersama beserta suite pengujian per backend (lihat test_base.py).

Operasi dalam direktori experimental mengikuti struktur yang serupa, tetapi mungkin tidak diekspos di API publik. Operasi ini ditujukan untuk iterasi dan eksplorasi yang cepat, serta dapat sering berubah secara signifikan, dengan ekspektasi yang umumnya lebih rendah terkait pemeliharaan dan dukungan berkelanjutan.

Lapisan Mana yang Harus Dipanggil Pengguna

Memilih titik entri pada dasarnya adalah kompromi antara kenyamanan dan kontrol. Sebagian besar pengguna harus memulai dengan memanggil operator melalui API fungsional tingkat tinggi, yang menyediakan antarmuka gaya yang sudah dikenal dan secara otomatis memilih implementasi backend yang sesuai. Jika pemilihan backend deterministik diperlukan, pengguna dapat meneruskan pilihan implementasi eksplisit ke fungsi tingkat tinggi sambil mempertahankan tanda tangan panggilan yang sama. Untuk kontrol maksimum, pengguna dapat membuat instance class implementasi operator tertentu secara langsung untuk menyesuaikan hyperparameter kernel—seperti ukuran ubin—dan meneruskan argumen khusus backend.

Memanggil fungsi kernel tingkat rendah secara langsung tanpa melalui class implementasi operator tidak direkomendasikan. Tindakan ini akan mengabaikan infrastruktur penting—termasuk penyesuaian otomatis, validasi dan kanonikalisasi input, serta serialisasi metadata—tanpa menawarkan penghematan overhead yang berarti, karena wrapper operator sengaja dibuat ringan. Misalnya, tanpa hyperparameter yang disesuaikan secara otomatis dan sesuai, pengguna kemungkinan akan melihat performa yang jauh di bawah optimal.

Topik Lanjutan

Penggabungan Operator

Operator TPU Pallas yang dapat digabungkan mendukung penggabungan prolog dan epilog JAX di sekitarnya langsung ke kernel melalui @tokamax.ops.op_fusion.fuse. Lihat panduan Operator Fusion untuk mengetahui contoh penggunaan dan petunjuk tentang cara menulis kernel dan subclass Op yang kompatibel dengan fusion.

Serialisasi

Kernel dapat diserialisasi ke StableHLO. Panggilan kernel adalah panggilan kustom JAX, yang secara default dilarang di jax.export, sehingga memerlukan penggunaan tokamax.DISABLE_JAX_EXPORT_CHECKS agar semua kernel Tokamax dapat diekspor:

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

Perhatikan bahwa fungsi yang diserialisasi dengan kernel Tokamax akan kehilangan independensi perangkat dari StableHLO standar. Tokamax memberikan dua jaminan serialisasi:

  1. Fungsi yang dideserialisasi dan diserialisasi pada perangkat tertentu akan dijamin berjalan pada perangkat yang sama dengan perangkat yang digunakan untuk serialisasi.
  2. Tokamax memberikan jaminan kompatibilitas yang sama seperti JAX: kompatibilitas mundur 6 bulan.

Kompilasi Silang dan Ekspor CPU

Kernel Tokamax dapat diekspor atau dikompilasi silang di host CPU:

  • Pemilihan implementasi eksplisit (misalnya, implementation="mosaic_tpu_v2") akan otomatis mengabaikan validasi perangkat host.
  • Atau, aktifkan kompilasi silang secara global menggunakan tokamax.config.cross_compile(True):
with tokamax.config.cross_compile(True):
  f_exported = export.export(
      f, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS
  )(
      jax.ShapeDtypeStruct(x.shape, x.dtype),
      ...,
  )