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 (patrz op.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=True i config.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ń (patrz op._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:

  1. Zdeserializowana funkcja zserializowana na konkretnym urządzeniu będzie działać na urządzeniu, dla którego została zserializowana.
  2. 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),
      ...,
  )