Projekt biblioteki
Tokamax ma na celu standaryzację i uproszczenie typowych procesów deweloperskich związanych z tworzeniem, optymalizacją, konserwacją i produkcyjnym wykorzystaniem jądra. Służą do tego klasy podstawowe i wspólna infrastruktura, które są dziedziczone przez wszystkie operatory w bibliotece i implementowane w dobrze ustrukturyzowanej platformie.
Warstwy operatora
Klasa bazowa Tokamax
tokamax.Op to podstawowa klasa Tokamax, która służy jako baza dla każdego operatora w bibliotece. Gdy wywoływany jest dowolny operator pochodny, ta warstwa automatycznie obsługuje te funkcje:
- Wiązanie argumentów: przed uruchomieniem jakichkolwiek obliczeń klasa bazowa normalizuje i weryfikuje argumenty elementu wywołującego w jedną reprezentację kanoniczną, dzięki czemu buforowanie, heurystyka i wykonywanie jądra mogą w jednolity sposób analizować obciążenie (za pomocą obiektu
BoundArguments), niezależnie od sposobu przekazywania danych wejściowych (patrzop.bind()). - Weryfikacja urządzenia: aby wcześnie wykryć niezgodności sprzętowe, operator przed uruchomieniem sprawdza obsługę urządzenia pod kątem docelowego akceleratora, jednocześnie umożliwiając pominięcie tej kontroli podczas kompilacji skrośnej z hosta procesora (patrz
op.supported_on(),bypass_device_check=Trueiconfig.cross_compile(True)). - Przechwytywanie grupowania: ponieważ najlepsza konfiguracja jądra (
Config) często zależy od pełnego rozmiaru problemu grupowania, a nie od pojedynczego wycinka, klasa podstawowa przechwytuje otaczające wymiary grupowania, gdy operator jest wektoryzowany (jax.vmap), dzięki czemu pamięci podręczne heurystyki i automatycznego dostrajania mogą optymalizować pod kątem rzeczywistego kształtu zbioru zadań (patrzop._capture_batched_args()). - Rozwiązanie konfiguracji: aby zapewnić wysoką wydajność od razu po uruchomieniu bez konieczności ręcznego dostrajania, klasa bazowa automatycznie rozwiązuje hiperparametry jądra, gdy obiekt wywołujący ich nie dostarcza. Wykorzystuje przy tym wcześniej dostrojone ustawienia w pamięci podręcznej dostrajania automatycznego na dysku (jeśli są dostępne) lub korzysta z wbudowanych heurystyk (patrz
BoundArguments.default_config). - Serializacja metadanych StableHLO: aby umożliwić introspekcję skompilowanych programów na potrzeby profilowania offline i automatycznego dostrajania, klasa bazowa umieszcza metadane operatora w obniżonym grafie, dzięki czemu narzędzia niższego poziomu mogą rekonstruować, które operatory zostały uruchomione i z jakimi danymi wejściowymi (kształty, typy itp.) bezpośrednio ze skompilowanego modułu lub profilu wydajności (patrz
_tokamax_metadata()). - Wykonywanie w przód i niestandardowy wektor-iloczyn Jakobianu: ponieważ wyspecjalizowane jądra sprzętowe często nie mogą być skutecznie różnicowane przez standardowe automatyczne różnicowanie, klasa bazowa koordynuje wykonywanie w przód i w tył jako parę, umożliwiając przekazywanie wartości pośrednich bezpośrednio do niestandardowego jądra wstecznego podczas obliczania gradientu (patrz
op._fwd()) i wywołańjax.custom_vjp.
Klasa bazowa dla konkretnej operacji
Każda rodzina operatorów definiuje własną klasę bazową, która dziedziczy po podstawowej klasie operatora i ustanawia umowę udostępnianą we wszystkich backendach (patrz np. RaggedDot):
- Implementacja referencyjna: każda klasa bazowa operatora zapewnia przenośną, czystą implementację referencyjną JAX pełnej specyfikacji matematycznej, w tym gradientów, jeśli ma to zastosowanie. Służy jako dane podstawowe do testów poprawności numerycznej i gwarantuje działanie zastępcze na dowolnym sprzęcie (patrz
RaggedDot._fwd()). - Wiązanie kanoniczne: ponieważ użytkownicy mogą wyrażać tę samą operację matematyczną na wiele sposobów – np. przekazując różne formy masek, ustawienia precyzji lub specyfikacje wymiarów – klasa bazowa operatora normalizuje dane wejściowe i sprawdza zgodność kształtu i typu, dzięki czemu poszczególne backendy sprzętowe muszą obsługiwać tylko jeden, przewidywalny format danych wejściowych (patrz
RaggedDot.bind()).
Klasy implementacji operacji
Te klasy zapewniają implementacje jądra specyficzne dla sprzętu i mogą być tworzone i wywoływane bezpośrednio przez użytkowników. Każda implementacja dziedziczy po klasie bazowej powiązanej z operatorem i zapewnia działanie powiązane z backendem (zobacz na przykład PallasMosaicTpuRaggedDot):
- Główna funkcjonalność: tutaj definiowane jest rzeczywiste wykonywanie jądra sprzętowego, zwykle przy użyciu języka jądra, takiego jak Pallas. Gdy operacja wymaga specjalnego przejścia wstecznego, jądro gradientu jest zwykle modelowane jako własna implementacja operatora pierwszej klasy, dzięki czemu można je konfigurować, dostrajać i testować niezależnie. Chociaż kod jądra najniższego poziomu jest często umieszczany w osobnym pliku pomocniczym, aby zapewnić modułowość, ta klasa służy jako główny interfejs do wywoływania tego jądra (patrz
PallasMosaicTpuRaggedDot._fwd()). - Konfiguracja: ponieważ jądra sprzętowe często udostępniają ustawienia wydajności, takie jak rozmiary kafelków, etapy potoku czy strategie buforowania pamięci, każdy backend definiuje dedykowaną strukturę konfiguracji, która pozwala użytkownikom lub zautomatyzowanym narzędziom kontrolować sposób partycjonowania, kompilowania i wykonywania jądra (patrz
Config). - Heurystyka: nie każde zadanie zostało wcześniej dostrojone automatycznie, więc każdy backend udostępnia wbudowaną heurystykę, która wybiera rozsądne domyślne parametry dostrajania na podstawie wymiarów problemu, typów danych i specyfikacji akceleratora (patrz
_get_heuristics_config()). - Przestrzeń wyszukiwania autotuningu: w przypadku zadań, w których liczy się maksymalna wydajność, każdy backend definiuje przestrzeń wyszukiwania autotuningu z prawidłowymi kombinacjami parametrów dla danego kształtu problemu, co pozwala autotunerowi na testowanie kandydatów i odkrywanie najszybszej konfiguracji (patrz
_get_autotuning_configs()). - Walidacja zależna od implementacji: jądra sprzętowe często mają bardziej rygorystyczne wymagania niż ogólne operacje matematyczne, takie jak reguły wyrównania wymiarów lub ograniczona obsługa typów danych. Każda implementacja sprawdza te ograniczenia i sygnalizuje, gdy zadanie nie może zostać obsłużone, co pozwala dyspozytorom wyższego poziomu na płynne przełączenie się na inny backend (patrz
PallasMosaicTpuRaggedDot._fwd()).
Interfejs API wysokiego poziomu
Większość operatorów ma wiele backendów – np.przenośną implementację referencyjną oraz co najmniej 1 jądro sprzętowe – i udostępnia jeden znany, wysokopoziomowy punkt wejścia (np. standardową funkcję jax.lax). Ta warstwa ma zapewniać użytkownikom prosty, gotowy interfejs, który automatycznie wybiera najlepszy obsługiwany backend dla ich sprzętu i kształtów wejściowych, a jednocześnie pozwala im w razie potrzeby poprosić o konkretną implementację (patrz tokamax.ragged_dot()).
ArgSpecs
Utrzymywanie wspólnego katalogu ważnych kształtów zbiorów zadań jest niezbędne do spójnego testowania i optymalizowania jądra w różnych backendach. Tokamax rejestruje te reprezentatywne kształty produkcyjne i porównawcze jako specyfikacje zadań, które są udostępniane we wszystkich implementacjach operatora. Dzięki temu testy trybu ciągłej integracji, testy porównawcze regresji i potoki automatycznego dostrajania mają jedno źródło wiarygodnych danych, które można filtrować według tagów dla różnych przepływów pracy (zobacz ArgSpecs dla ragged_dot).
Struktura repozytorium
Kod implementacji wewnętrznej znajduje się w prywatnym drzewie źródłowym (patrz tokamax/_src), a symbole publiczne operatorów, autotuningu, testów porównawczych i konfiguracji są ponownie eksportowane przez moduły najwyższego poziomu (patrz tokamax/__init__.py).
W każdym katalogu operatora (patrz tokamax/_src/ops) pliki są nazywane zgodnie ze spójną konwencją nazewnictwa, którą ilustruje ten przykład z użyciem kropki:
- Interfejs API wysokiego poziomu: definiuje publiczny funkcjonalny punkt wejścia i logikę wysyłania backendu (patrz
api.py). - Klasa bazowa dla konkretnej operacji: definiuje przenośną implementację referencyjną (patrz
base.py). - Implementacje backendu: definiują klasy operatorów, konfiguracje, heurystyki i przestrzenie autostrojenia (patrz
pallas_mosaic_tpu.py). - Jądra niskiego poziomu: oddziela samodzielne implementacje jądra i współdzielone funkcje pomocnicze niskiego poziomu od modułów towarzyszących (patrz
pallas_mosaic_tpu_kernel.py). - Specyfikacje zbioru zadań: kataloguje kanoniczne kształty wejściowe na potrzeby testowania, analizy porównawczej i automatycznego dostrajania (patrz
arg_specs.py). - Zestawy testów: definiuje współdzielone sparametryzowane kontrole poprawności wraz z zestawami testów dla poszczególnych backendów (patrz
test_base.py).
Operacje w katalogu experimental mają podobną strukturę, ale mogą nie być widoczne w publicznym interfejsie API. Te operacje są przeznaczone do szybkiej iteracji i eksploracji. Mogą się często i znacząco zmieniać, a oczekiwania dotyczące bieżącej konserwacji i wsparcia są ogólnie niższe.
Którą warstwę powinni wywoływać użytkownicy
Wybór punktu wejścia to zasadniczo kompromis między wygodą a kontrolą. Większość użytkowników powinna zacząć od wywoływania operatorów za pomocą funkcjonalnego interfejsu API wysokiego poziomu, który zapewnia znajomy interfejs i automatycznie wybiera odpowiednią implementację backendu. Gdy potrzebny jest deterministyczny wybór backendu, użytkownicy mogą przekazać do funkcji wysokiego poziomu jawny wybór implementacji, zachowując ten sam znak wywoławczy. Aby uzyskać maksymalną kontrolę, użytkownicy mogą bezpośrednio utworzyć instancję konkretnej klasy implementacji operatora, aby dostosować hiperparametry jądra, takie jak rozmiary kafelków, i przekazać argumenty specyficzne dla backendu.
Nie zalecamy bezpośredniego wywoływania funkcji jądra niskiego poziomu bez przechodzenia przez klasę implementacji operatora. Spowoduje to ominięcie kluczowej infrastruktury, w tym automatycznego dostrajania, sprawdzania poprawności i wyboru strony kanonicznej danych wejściowych oraz serializacji metadanych, bez żadnych znaczących oszczędności, ponieważ otoki operatorów są celowo lekkie. Na przykład w przypadku braku odpowiednich hiperparametrów dostrojonych automatycznie użytkownicy prawdopodobnie zauważą znacznie gorszą wydajność.
Zaawansowane tematy
Operator Fusion
Operatory Fusible Pallas TPU obsługują fuzję otaczających prologów i epilogów JAX bezpośrednio w jądrze za pomocą @tokamax.ops.op_fusion.fuse. Przykłady użycia oraz instrukcje tworzenia jądra i podklas Op zgodnych z fuzją znajdziesz w przewodniku po fuzji operatorów.
Publikacja w odcinkach
Jądra można serializować do StableHLO. Wywołania jądra to niestandardowe wywołania JAX, które są domyślnie zabronione w jax.export, co wymaga użycia tokamax.DISABLE_JAX_EXPORT_CHECKS, aby umożliwić eksportowanie wszystkich jąder Tokamax:
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),
)
Pamiętaj, że funkcje zserializowane za pomocą jądra Tokamax tracą niezależność od urządzenia, którą zapewnia standardowy StableHLO. Tokamax zapewnia 2 gwarancje serializacji:
- Zdeserializowana funkcja zserializowana na konkretnym urządzeniu będzie działać na urządzeniu, dla którego została zserializowana.
- Tokamax zapewnia takie same gwarancje zgodności jak JAX: zgodność wsteczna przez 6 miesięcy.
Kompilacja skrośna i eksportowanie procesora
Jądra Tokamax można eksportować lub kompilować skrośnie na hoście procesora:
- Jawny wybór implementacji (np.
implementation="mosaic_tpu_v2") automatycznie pomija weryfikację urządzenia hosta. - Możesz też włączyć kompilację skrośną globalnie, używając
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),
...,
)