Conception de la bibliothèque

Tokamax est conçu pour standardiser et simplifier les parcours de développement types liés à la création, à l'optimisation, à la maintenance et à l'utilisation en production des kernels. Pour ce faire, il utilise des classes de base et une infrastructure partagée dont tous les opérateurs de la bibliothèque héritent et qu'ils implémentent dans un framework bien structuré.

Couches d'opérateurs

Classe de base Tokamax

tokamax.Op est la classe de base de Tokamax, qui sert de base à chaque opérateur de la bibliothèque. Lorsqu'un opérateur dérivé est appelé, cette couche gère automatiquement les fonctionnalités suivantes :

  • Liaison d'arguments : avant l'exécution de tout calcul, la classe de base normalise et valide les arguments de l'appelant dans une seule représentation canonique afin que la mise en cache, les heuristiques et l'exécution du noyau puissent toutes raisonner sur la charge de travail de manière uniforme (via un objet BoundArguments), quelle que soit la manière dont les entrées ont été transmises (voir op.bind()).
  • Validation de l'appareil : pour détecter rapidement les incompatibilités matérielles, l'opérateur vérifie la compatibilité de l'appareil avec l'accélérateur cible avant l'exécution, tout en permettant de contourner cette vérification lors de la compilation croisée à partir d'un hôte de processeur (voir op.supported_on(), bypass_device_check=True et config.cross_compile(True)).
  • Capture par lot : étant donné que la meilleure configuration de kernel (Config) dépend souvent de la taille complète du problème par lot plutôt que d'une seule tranche, la classe de base capture les dimensions de lot environnantes lorsqu'un opérateur est vectorisé (jax.vmap) afin que les caches d'heuristique et d'ajustement automatique puissent optimiser la forme réelle de la charge de travail (voir op._capture_batched_args()).
  • Résolution de la configuration : pour fournir des performances optimales sans nécessiter de réglage manuel, la classe de base résout automatiquement les hyperparamètres du noyau chaque fois que l'appelant ne les fournit pas, en réutilisant les paramètres précédemment réglés automatiquement dans un cache de réglage automatique sur disque, si disponible, ou en se rabattant sur des heuristiques intégrées (voir BoundArguments.default_config).
  • Sérialisation des métadonnées StableHLO : pour rendre les programmes compilés introspectables pour le profilage hors connexion et le réglage automatisé, la classe de base intègre les métadonnées de l'opérateur dans le graphique réduit afin que les outils en aval puissent reconstruire les opérateurs exécutés et avec quelles entrées (formes, types, etc.) directement à partir d'un module compilé ou d'un profil de performances (voir _tokamax_metadata()).
  • Exécution directe et VJP personnalisé : étant donné que les noyaux matériels spécialisés ne peuvent souvent pas être différenciés efficacement par la différenciation automatique standard, la classe de base coordonne l'exécution directe et l'exécution inverse en tant que paire, ce qui permet à la passe directe de transmettre des valeurs intermédiaires directement à un noyau inverse personnalisé lors du calcul du gradient (voir op._fwd()) et des appels à jax.custom_vjp.

Classe de base spécifique à l'opération

Chaque famille d'opérateurs définit sa propre classe de base qui hérite de la classe d'opérateur de base et établit le contrat partagé entre tous les backends (par exemple, consultez RaggedDot) :

  • Implémentation de référence : chaque classe de base d'opérateur fournit une implémentation de référence portable et purement JAX de la spécification mathématique complète, y compris les gradients, le cas échéant. Il sert de vérité terrain pour les tests d'exactitude numérique et garantit un remplacement fonctionnel sur n'importe quel matériel (voir RaggedDot._fwd()).
  • Liaison canonique : étant donné que les utilisateurs peuvent exprimer la même opération mathématique de plusieurs manières (par exemple, en transmettant différentes formes de masques, de paramètres de précision ou de spécifications de dimension), la classe de base de l'opérateur normalise les entrées et vérifie la compatibilité des formes et des types en amont. Ainsi, les backends matériels individuels n'ont à gérer qu'un seul format d'entrée prévisible (voir RaggedDot.bind()).

Classes d'implémentation des opérations

Ces classes fournissent les implémentations de kernel spécifiques au matériel et peuvent être instanciées et appelées directement par les utilisateurs. Chaque implémentation hérite de sa classe de base spécifique à l'opérateur et fournit le comportement spécifique au backend (par exemple, consultez PallasMosaicTpuRaggedDot) :

  • Fonctionnalité de base : c'est là que l'exécution réelle du kernel matériel est définie, généralement à l'aide d'un langage de kernel tel que Pallas. Lorsqu'une opération nécessite une passe arrière spécialisée, le noyau de gradient est généralement modélisé comme sa propre implémentation d'opérateur de première classe afin de pouvoir être configuré, ajusté et testé indépendamment. Bien que le code de kernel de niveau le plus bas soit souvent factorisé dans un fichier d'assistance distinct pour la modularité, cette classe sert d'interface principale pour appeler ce kernel (voir PallasMosaicTpuRaggedDot._fwd()).
  • Configuration : étant donné que les noyaux matériels exposent souvent des boutons de performances (tels que les tailles de tuiles, les étapes de pipeline ou les stratégies de mise en mémoire tampon), chaque backend définit une structure de configuration dédiée qui permet aux utilisateurs ou aux outils automatisés de contrôler la façon dont le noyau est partitionné, compilé et exécuté (voir Config).
  • Heuristiques : toutes les charges de travail n'ont pas été réglées automatiquement à l'avance. Chaque backend fournit donc des heuristiques intégrées qui choisissent des paramètres de réglage par défaut raisonnables en fonction des dimensions du problème, des types de données et des spécifications de l'accélérateur (voir _get_heuristics_config()).
  • Espace de recherche de réglage automatique : pour les charges de travail où les performances de pointe sont importantes, chaque backend définit un espace de recherche de réglage automatique des combinaisons de paramètres valides pour une forme de problème donnée, ce qui permet au réglage automatique d'évaluer les candidats et de découvrir la configuration la plus rapide (voir _get_autotuning_configs()).
  • Validation spécifique à l'implémentation : les kernels matériels ont souvent des exigences plus strictes que l'opération mathématique générale, comme des règles d'alignement des dimensions ou une compatibilité limitée avec les types de données. Chaque implémentation valide ces contraintes et signale lorsqu'une charge de travail ne peut pas être gérée, ce qui permet aux répartiteurs de niveau supérieur de basculer correctement vers un autre backend (voir PallasMosaicTpuRaggedDot._fwd()).

API de haut niveau

La plupart des opérateurs ont plusieurs backends (par exemple, une implémentation de référence portable ainsi qu'un ou plusieurs kernels spécifiques au matériel) et exposent un seul point d'entrée de haut niveau familier (par exemple, une fonction jax.lax standard). Cette couche est conçue pour offrir aux utilisateurs une interface simple et prête à l'emploi qui sélectionne automatiquement le meilleur backend compatible pour leur matériel et leurs formes d'entrée, tout en leur permettant de demander une implémentation spécifique si nécessaire (voir tokamax.ragged_dot()).

ArgSpecs

Il est essentiel de maintenir un catalogue partagé de formes de charges de travail importantes pour tester et optimiser les kernels de manière cohérente sur l'ensemble des backends. Tokamax capture ces formes représentatives de production et de benchmark en tant que spécifications de charge de travail partagées entre toutes les implémentations d'un opérateur. Cela fournit aux tests d'intégration continue, aux benchmarks de régression et aux pipelines de réglage automatique une source unique de vérité qui peut être filtrée par tags pour différents workflows (voir les ArgSpecs pour ragged_dot).

Structure du dépôt

Le code d'implémentation interne se trouve dans l'arborescence source privée (voir tokamax/_src), tandis que les symboles publics pour les opérateurs, l'ajustement automatique, l'analyse comparative et la configuration sont réexportés via des modules de premier niveau (voir tokamax/__init__.py).

Dans chaque répertoire d'opérateur (voir tokamax/_src/ops), les fichiers suivent une convention d'attribution de noms cohérente, illustrée ici à l'aide de l'opérateur "ragged dot" :

  • API de haut niveau : définit le point d'entrée fonctionnel public et la logique de distribution du backend (voir api.py).
  • Classe de base spécifique à l'opération : définit l'implémentation de référence portable (voir base.py).
  • Implémentations de backend : définit les classes d'opérateurs, les configurations, les heuristiques et les espaces d'ajustement automatique spécifiques au matériel (voir pallas_mosaic_tpu.py).
  • Noyaux de bas niveau : sépare les implémentations de noyau autonomes et les assistants de bas niveau partagés en modules associés (voir pallas_mosaic_tpu_kernel.py).
  • Spécifications de la charge de travail : catalogue les formes d'entrée canoniques pour les tests, l'analyse comparative et l'ajustement automatique (voir arg_specs.py).
  • Suites de tests : définit des vérifications d'exactitude paramétrées partagées ainsi que des suites de tests par backend (voir test_base.py).

Les opérations du répertoire experimental suivent une structure similaire, mais peuvent ne pas être exposées dans l'API publique. Ces opérations sont destinées à l'itération et à l'exploration rapides, et peuvent changer fréquemment et de manière significative, avec des attentes généralement plus faibles en matière de maintenance et d'assistance continues.

Quelle couche les utilisateurs doivent-ils appeler ?

Le choix d'un point d'entrée est fondamentalement un compromis entre commodité et contrôle. La plupart des utilisateurs doivent commencer par appeler des opérateurs via l'API fonctionnelle de haut niveau, qui fournit une interface de style familier et sélectionne automatiquement une implémentation de backend appropriée. Lorsque la sélection déterministe du backend est nécessaire, les utilisateurs peuvent transmettre un choix d'implémentation explicite à la fonction de haut niveau tout en conservant la même signature d'appel. Pour un contrôle maximal, les utilisateurs peuvent instancier directement une classe d'implémentation d'opérateur spécifique afin de personnaliser les hyperparamètres du kernel (comme les tailles de tuiles) et de transmettre des arguments spécifiques au backend.

Il n'est pas recommandé d'appeler directement des fonctions de kernel de bas niveau sans passer par une classe d'implémentation d'opérateur. Cela contourne l'infrastructure essentielle (y compris l'ajustement automatique, la validation et la canonisation des entrées, et la sérialisation des métadonnées) sans offrir d'économies de frais généraux significatives, car les wrappers d'opérateurs sont intentionnellement légers. En l'absence d'hyperparamètres de réglage automatique appropriés, par exemple, les utilisateurs risquent de constater des performances nettement inférieures à la normale.

Rubriques avancées

Fusion d'opérateurs

Les opérateurs TPU Pallas fusibles permettent de fusionner les prologues et épilogues JAX environnants directement dans le noyau via @tokamax.ops.op_fusion.fuse. Consultez le guide Fusion d'opérateurs pour obtenir des exemples d'utilisation et des instructions sur la création de noyaux et de sous-classes Op compatibles avec la fusion.

Sérialisation

Les noyaux peuvent être sérialisés en StableHLO. Les appels de kernel sont des appels personnalisés JAX, qui sont interdits par défaut dans jax.export, ce qui nécessite l'utilisation de tokamax.DISABLE_JAX_EXPORT_CHECKS pour permettre l'exportation de tous les kernels 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),
)

Notez que les fonctions sérialisées avec des noyaux Tokamax perdent l'indépendance vis-à-vis de l'appareil de StableHLO standard. Tokamax offre deux garanties de sérialisation :

  1. Une fonction désérialisée qui a été sérialisée sur un appareil spécifique est garantie de s'exécuter sur l'appareil exact pour lequel elle a été sérialisée.
  2. Tokamax offre les mêmes garanties de compatibilité que JAX : rétrocompatibilité de six mois.

Compilation croisée et exportation du processeur

Les noyaux Tokamax peuvent être exportés ou compilés de manière croisée sur un hôte de processeur :

  • La sélection explicite de l'implémentation (par exemple, implementation="mosaic_tpu_v2") contourne automatiquement la validation de l'appareil hôte.
  • Vous pouvez également activer la compilation croisée de manière globale à l'aide de 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),
      ...,
  )