Bibliotheksdesign

Tokamax wurde entwickelt, um typische Entwicklerprozesse im Zusammenhang mit der Erstellung, Optimierung, Wartung und Produktion von Kerneln zu standardisieren und zu vereinfachen. Dies geschieht über grundlegende Klassen und eine gemeinsame Infrastruktur, von der alle Operatoren in der Bibliothek erben und die sie in einem gut strukturierten Framework implementieren.

Operator-Ebenen

Tokamax-Basisklasse

tokamax.Op ist die grundlegende Klasse von Tokamax, die als Basis für jeden Operator in der Bibliothek dient. Wenn ein abgeleiteter Operator aufgerufen wird, übernimmt diese Ebene automatisch die folgenden Funktionen:

  • Argumentbindung: Bevor eine Berechnung ausgeführt wird, normalisiert und validiert die Basisklasse die Argumente des Aufrufers in eine einzige kanonische Darstellung. So können Caching, Heuristiken und Kernel-Ausführung die Arbeitslast einheitlich (über ein BoundArguments-Objekt) verarbeiten, unabhängig davon, wie die Eingaben übergeben wurden (siehe op.bind()).
  • Gerätevalidierung: Um Hardwarekonflikte frühzeitig zu erkennen, prüft der Operator vor der Ausführung, ob das Gerät den Zielbeschleuniger unterstützt. Diese Prüfung kann jedoch beim Cross-Kompilieren von einem CPU-Host umgangen werden (siehe op.supported_on(), bypass_device_check=True und config.cross_compile(True)).
  • Batching-Erfassung: Da die beste Kernel-Konfiguration (Config) oft von der Gesamtgröße des Batches und nicht von einem einzelnen Slice abhängt, erfasst die Basisklasse die umgebenden Batch-Dimensionen, wenn ein Operator vektorisiert wird (jax.vmap). So können Heuristiken und Autotuning-Caches für die tatsächliche Form der Arbeitslast optimiert werden (siehe op._capture_batched_args()).
  • Konfigurationsauflösung: Um eine hohe Leistung ohne manuelle Abstimmung zu bieten, löst die Basisklasse Kernel-Hyperparameter automatisch auf, wenn der Aufrufer sie nicht bereitstellt. Dabei werden zuvor automatisch abgestimmte Einstellungen in einem festplattenbasierten Cache für die automatische Abstimmung wiederverwendet, falls verfügbar, oder es wird auf integrierte Heuristiken zurückgegriffen (siehe BoundArguments.default_config).
  • StableHLO-Metadatenserialisierung: Damit kompilierte Programme für Offline-Profiling und automatisches Tuning introspektiv sind, bettet die Basisklasse Operatormetadaten in den herabgestuften Graphen ein. So können nachgelagerte Tools direkt aus einem kompilierten Modul oder Leistungsprofil rekonstruieren, welche Operatoren mit welchen Eingaben (Formen, Typen usw.) ausgeführt wurden (siehe _tokamax_metadata()).
  • Vorwärtsausführung und benutzerdefiniertes VJP: Da spezialisierte Hardware-Kernel oft nicht effizient durch standardmäßige automatische Differenzierung differenziert werden können, koordiniert die Basisklasse die Vorwärts- und Rückwärtsausführung als Paar. Dadurch kann der Vorwärtsdurchlauf Zwischenwerte während der Gradientenberechnung direkt an einen benutzerdefinierten Rückwärts-Kernel übergeben (siehe op._fwd()) und jax.custom_vjp aufrufen.

Vorgangsspezifische Basisklasse

Jede Operatorfamilie definiert eine eigene Basisklasse, die von der grundlegenden Operatorklasse erbt und den Vertrag festlegt, der für alle Back-Ends gilt (siehe z. B. RaggedDot):

  • Referenzimplementierung: Jede Operator-Basisklasse bietet eine portable, reine JAX-Referenzimplementierung der vollständigen mathematischen Spezifikation, einschließlich Gradienten, falls zutreffend. Dies dient als Grundwahrheit für Tests der numerischen Korrektheit und garantiert ein funktionierendes Fallback auf jeder Hardware (siehe RaggedDot._fwd()).
  • Kanonische Bindung: Da Nutzer dieselbe mathematische Operation auf verschiedene Weise ausdrücken können, z. B. durch Übergabe verschiedener Formen von Masken, Präzisionseinstellungen oder Dimensionsspezifikationen, normalisiert die Operator-Basisklasse die Eingaben und prüft die Kompatibilität von Form und Typ im Voraus. So müssen einzelne Hardware-Backends nur ein einziges, vorhersehbares Eingabeformat verarbeiten (siehe RaggedDot.bind()).

Op-Implementierungsklassen

Diese Klassen stellen die hardwarespezifischen Kernel-Implementierungen bereit und können von Nutzern direkt instanziiert und aufgerufen werden. Jede Implementierung übernimmt die Eigenschaften der operatorspezifischen Basisklasse und stellt das Back-End-spezifische Verhalten bereit (siehe z. B. PallasMosaicTpuRaggedDot):

  • Hauptfunktion: Hier wird die eigentliche Ausführung des Hardware-Kernels definiert, in der Regel mit einer Kernel-Sprache wie Pallas. Wenn für einen Vorgang ein spezieller Rückwärtsdurchlauf erforderlich ist, wird der Gradientenkernel normalerweise als eigene erstklassige Operatorimplementierung modelliert, damit er unabhängig konfiguriert, optimiert und getestet werden kann. Obwohl der Kernel-Code der niedrigsten Ebene aus Gründen der Modularität häufig in eine separate Hilfsdatei ausgelagert wird, dient diese Klasse als primäre Schnittstelle zum Aufrufen dieses Kernels (siehe PallasMosaicTpuRaggedDot._fwd()).
  • Konfiguration: Da Hardware-Kernel oft Leistungseinstellungen wie Tile-Größen, Pipeline-Stufen oder Speicherpufferstrategien verfügbar machen, definiert jedes Backend eine dedizierte Konfigurationsstruktur, mit der Nutzer oder automatisierte Tools steuern können, wie der Kernel partitioniert, kompiliert und ausgeführt wird (siehe Config).
  • Heuristiken: Nicht jede Arbeitslast wurde im Voraus automatisch optimiert. Daher bietet jedes Backend integrierte Heuristiken, die basierend auf den Problemabmessungen, Datentypen und Beschleunigerspezifikationen angemessene Standardoptimierungsparameter auswählen (siehe _get_heuristics_config()).
  • Suchbereich für die automatische Abstimmung: Für Arbeitslasten, bei denen die Spitzenleistung wichtig ist, definiert jedes Backend einen Suchbereich für die automatische Abstimmung mit gültigen Parameterkombinationen für eine bestimmte Problemform. So kann der Autotuner Kandidaten vergleichen und die schnellste Konfiguration ermitteln (siehe _get_autotuning_configs()).
  • Implementierungsspezifische Validierung: Hardware-Kernel haben häufig strengere Anforderungen als die allgemeine mathematische Operation, z. B. Regeln für die Dimensionsausrichtung oder eingeschränkte Unterstützung von Datentypen. Jede Implementierung validiert diese Einschränkungen und signalisiert, wenn eine Arbeitslast nicht verarbeitet werden kann. So können übergeordnete Dispatcher ordnungsgemäß auf ein anderes Backend zurückgreifen (siehe PallasMosaicTpuRaggedDot._fwd()).

High-Level API

Die meisten Operatoren haben mehrere Back-Ends, z. B. eine portable Referenzimplementierung zusammen mit einem oder mehreren hardwarespezifischen Kernels, und stellen einen einzigen vertrauten, übergeordneten Einstiegspunkt bereit (z. B. eine standardmäßige jax.lax-Funktion). Diese Ebene bietet Nutzern eine einfache, sofort einsatzbereite Schnittstelle, die automatisch das am besten unterstützte Backend für ihre Hardware und Eingabeformen auswählt. Gleichzeitig können sie bei Bedarf eine bestimmte Implementierung anfordern (siehe tokamax.ragged_dot()).

ArgSpecs

Ein gemeinsamer Katalog wichtiger Arbeitslastformen ist für das konsistente Testen und Optimieren von Kernels über Back-Ends hinweg unerlässlich. Tokamax erfasst diese repräsentativen Produktions- und Benchmark-Formen als Arbeitslastspezifikationen, die von allen Implementierungen eines Operators gemeinsam genutzt werden. So erhalten Continuous-Integration-Tests, Regressions-Benchmarks und Autotuning-Pipelines eine zentrale Datenquelle, die nach Tags für verschiedene Workflows gefiltert werden kann (siehe ArgSpecs für ragged_dot).

Repository-Struktur

Der interne Implementierungscode befindet sich im privaten Quellbaum (siehe tokamax/_src), während öffentliche Symbole für Operatoren, Autotuning, Benchmarking und Konfiguration über Module auf oberster Ebene neu exportiert werden (siehe tokamax/__init__.py).

In jedem Operatorverzeichnis (siehe tokamax/_src/ops) folgen die Dateien einer einheitlichen Namenskonvention, die hier anhand von Ragged Dot veranschaulicht wird:

  • High-Level API: Definiert den öffentlichen funktionalen Einstiegspunkt und die Backend-Dispatch-Logik (siehe api.py).
  • Vorgangsspezifische Basisklasse: Definiert die portable Referenzimplementierung (siehe base.py).
  • Backend-Implementierungen: Definiert hardwarespezifische Operatorklassen, Konfigurationen, Heuristiken und Autotuning-Bereiche (siehe pallas_mosaic_tpu.py).
  • Low-Level-Kernel: Trennt eigenständige Kernel-Implementierungen und freigegebene Low-Level-Hilfsprogramme in Begleitmodule (siehe pallas_mosaic_tpu_kernel.py).
  • Arbeitslastspezifikationen: Katalogisiert kanonische Eingabeformen für Tests, Benchmarking und automatische Abstimmung (siehe arg_specs.py).
  • Test-Suites: Definiert freigegebene parametrisierte Korrektheitsprüfungen zusammen mit Test-Suites pro Backend (siehe test_base.py).

Vorgänge im Verzeichnis experimental folgen einer ähnlichen Struktur, werden aber möglicherweise nicht in der öffentlichen API bereitgestellt. Diese Vorgänge sind für schnelle Iterationen und Erkundungen gedacht und können sich häufig und erheblich ändern. Die Erwartungen an die laufende Wartung und den Support sind im Allgemeinen geringer.

Welche Ebene sollten Nutzer aufrufen?

Die Wahl eines Einstiegspunkts ist im Wesentlichen ein Kompromiss zwischen Komfort und Kontrolle. Die meisten Nutzer sollten Operatoren über die funktionale High-Level-API aufrufen, die eine vertraute Schnittstelle bietet und automatisch eine geeignete Backend-Implementierung auswählt. Wenn eine deterministische Backend-Auswahl erforderlich ist, können Nutzer eine explizite Implementierungsauswahl an die High-Level-Funktion übergeben, während die Aufrufsignatur beibehalten wird. Für maximale Kontrolle können Nutzer eine bestimmte Operator-Implementierungsklasse direkt instanziieren, um Kernel-Hyperparameter wie Kachelgrößen anzupassen und Backend-spezifische Argumente zu übergeben.

Es wird nicht empfohlen, Low-Level-Kernelfunktionen direkt aufzurufen, ohne eine Operator-Implementierungsklasse zu verwenden. Dadurch wird wichtige Infrastruktur umgangen, einschließlich Autotuning, Eingabevalidierung und -kanonisierung sowie Metadatenserialisierung, ohne dass nennenswerte Einsparungen beim Overhead erzielt werden, da die Operator-Wrapper absichtlich schlank sind. Ohne geeignete automatisch abgestimmte Hyperparameter ist die Leistung wahrscheinlich deutlich schlechter.

Erweiterte Themen

Operator Fusion

Fusible Pallas-TPU-Operatoren unterstützen das Zusammenführen von umgebenden JAX-Prologues und -Epilogues direkt in den Kernel über @tokamax.ops.op_fusion.fuse. Im Leitfaden zur Operatorfusion finden Sie Anwendungsbeispiele und Anleitungen zum Erstellen von fusionskompatiblen Kernels und Op-Unterklassen.

Serialisierung

Kernel können in StableHLO serialisiert werden. Kernel-Aufrufe sind benutzerdefinierte JAX-Aufrufe, die in jax.export standardmäßig gesperrt sind. Daher muss tokamax.DISABLE_JAX_EXPORT_CHECKS verwendet werden, damit alle Tokamax-Kernel exportiert werden können:

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

Beachten Sie, dass mit Tokamax-Kernels serialisierte Funktionen die Geräteunabhängigkeit von Standard-StableHLO verlieren. Tokamax bietet zwei Serialisierungsgarantien:

  1. Eine deserialisierte Funktion, die auf einem bestimmten Gerät serialisiert wurde, wird garantiert auf genau dem Gerät ausgeführt, für das sie serialisiert wurde.
  2. Tokamax bietet dieselben Kompatibilitätsgarantien wie JAX: 6 Monate Abwärtskompatibilität.

Cross-Kompilierung und CPU-Export

Tokamax-Kernel können auf einem CPU-Host exportiert oder cross-kompiliert werden:

  • Bei einer expliziten Implementierungsauswahl (z.B. implementation="mosaic_tpu_v2") wird die Hostgerätevalidierung automatisch umgangen.
  • Alternativ können Sie die Cross-Kompilierung global mit tokamax.config.cross_compile(True) aktivieren:
with tokamax.config.cross_compile(True):
  f_exported = export.export(
      f, disabled_checks=tokamax.DISABLE_JAX_EXPORT_CHECKS
  )(
      jax.ShapeDtypeStruct(x.shape, x.dtype),
      ...,
  )