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 (lihatop.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, danconfig.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 (lihatop._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 kejax.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:
- Fungsi yang dideserialisasi dan diserialisasi pada perangkat tertentu akan dijamin berjalan pada perangkat yang sama dengan perangkat yang digunakan untuk serialisasi.
- 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),
...,
)