Progettazione di librerie
Tokamax è progettato per standardizzare e semplificare i percorsi tipici degli sviluppatori relativi alla creazione, all'ottimizzazione, alla manutenzione e all'utilizzo in produzione dei kernel. A questo scopo, utilizza classi di base e un'infrastruttura condivisa da cui tutti gli operatori della libreria ereditano e che implementano all'interno di un framework ben strutturato.
Livelli operatore
Classe base Tokamax
tokamax.Op
è la classe di base di Tokamax, che funge da base per ogni operatore della libreria. Quando viene richiamato un operatore derivato, questo livello gestisce automaticamente le seguenti funzionalità:
- Associazione degli argomenti: prima dell'esecuzione di qualsiasi calcolo, la classe base normalizza e convalida gli argomenti del chiamante in un'unica rappresentazione canonica in modo che la memorizzazione nella cache, l'euristica e l'esecuzione del kernel possano ragionare sul workload in modo uniforme (tramite un oggetto
BoundArguments), indipendentemente da come sono stati passati gli input (vediop.bind()). - Convalida del dispositivo: per rilevare tempestivamente le mancate corrispondenze hardware, l'operatore verifica il supporto del dispositivo rispetto all'acceleratore di destinazione prima dell'esecuzione, consentendo comunque di bypassare questo controllo durante la cross-compilazione da un host CPU (vedi
op.supported_on(),bypass_device_check=Trueeconfig.cross_compile(True)). - Acquisizione del raggruppamento in batch: poiché la migliore configurazione del kernel (
Config) spesso dipende dalle dimensioni del problema raggruppato in batch completo anziché da una singola sezione, la classe base acquisisce le dimensioni del raggruppamento in batch circostante quando un operatore viene vettorizzato (jax.vmap) in modo che le euristiche e le cache di ottimizzazione automatica possano ottimizzare la forma del workload reale (vediop._capture_batched_args()). - Risoluzione della configurazione: per fornire prestazioni elevate fin da subito senza richiedere l'ottimizzazione manuale, la classe base risolve automaticamente gli iperparametri del kernel ogni volta che il chiamante non li fornisce, riutilizzando le impostazioni ottimizzate automaticamente in precedenza in una cache di ottimizzazione automatica basata su disco, se disponibile, o ricorrendo alle euristiche integrate (vedi
BoundArguments.default_config). - Serializzazione dei metadati StableHLO: per rendere i programmi compilati
introspezionabili per la profilazione offline e l'ottimizzazione automatica, la classe base
incorpora i metadati degli operatori nel grafico ridotto in modo che gli strumenti downstream possano
ricostruire quali operatori sono stati eseguiti e con quali input (forme, tipi e così via)
direttamente da un modulo compilato o da un profilo delle prestazioni (vedi
_tokamax_metadata()). - Esecuzione in avanti e VJP personalizzato: poiché i kernel hardware specializzati spesso non possono essere differenziati in modo efficiente dalla differenziazione automatica standard, la classe base coordina l'esecuzione in avanti e all'indietro come coppia, consentendo al passaggio in avanti di passare i valori intermedi direttamente a un kernel all'indietro personalizzato durante il calcolo del gradiente (vedi
op._fwd()) e le chiamate ajax.custom_vjp.
Classe base specifica per l'operazione
Ogni famiglia di operatori definisce la propria classe base che eredita dalla classe di operatori di base e stabilisce il contratto condiviso tra tutti i backend (ad esempio, vedi RaggedDot):
- Implementazione di riferimento: ogni classe base dell'operatore fornisce un'implementazione di riferimento portabile e pure-JAX della specifica matematica completa, inclusi i gradienti, se applicabili. Questo funge da dato di fatto per i test di correttezza numerica e garantisce un fallback funzionante su qualsiasi hardware (vedi
RaggedDot._fwd()). - Binding canonico: poiché gli utenti possono esprimere la stessa operazione matematica in più modi, ad esempio passando diverse forme di maschere, impostazioni di precisione o specifiche di dimensione, la classe base dell'operatore normalizza gli input e controlla in anticipo la compatibilità di forma e tipo, in modo che i singoli backend hardware debbano gestire solo un singolo formato di input prevedibile (vedi
RaggedDot.bind()).
Classi di implementazione delle operazioni
Queste classi forniscono le implementazioni del kernel specifiche per l'hardware e possono essere istanziate e richiamate direttamente dagli utenti. Ogni implementazione eredita dalla classe base specifica dell'operatore e fornisce il comportamento specifico del backend (ad esempio, vedi PallasMosaicTpuRaggedDot):
- Funzionalità di base: qui viene definita l'esecuzione effettiva del kernel hardware, in genere utilizzando un linguaggio kernel come Pallas. Quando un'operazione richiede un backward pass specializzato, il kernel del gradiente viene solitamente modellato come un'implementazione dell'operatore di prima classe, in modo che possa essere configurato, ottimizzato e testato in modo indipendente. Sebbene il codice del kernel di livello più basso sia spesso inserito in un file helper separato per la modularità, questa classe funge da interfaccia principale per richiamare il kernel (vedi
PallasMosaicTpuRaggedDot._fwd()). - Configurazione: poiché i kernel hardware spesso espongono controlli delle prestazioni, come dimensioni dei tile, fasi della pipeline o strategie di buffering della memoria, ogni backend definisce una struttura di configurazione dedicata che consente agli utenti o agli strumenti automatici di controllare il modo in cui il kernel viene partizionato, compilato ed eseguito (vedi
Config). - Euristica: non tutti i workload sono stati ottimizzati automaticamente in anticipo, quindi ogni backend fornisce un'euristica integrata che sceglie parametri di ottimizzazione predefiniti ragionevoli in base alle dimensioni del problema, ai tipi di dati e alle specifiche dell'acceleratore (vedi
_get_heuristics_config()). - Spazio di ricerca dell'ottimizzazione automatica: per i workload in cui le prestazioni di picco sono importanti, ogni backend definisce uno spazio di ricerca dell'ottimizzazione automatica di combinazioni di parametri valide per una determinata forma del problema, consentendo all'ottimizzatore automatico di eseguire il benchmark dei candidati e scoprire la configurazione più veloce (vedi
_get_autotuning_configs()). - Convalida specifica per l'implementazione: i kernel hardware spesso hanno requisiti più rigidi rispetto all'operazione matematica generale, ad esempio regole di allineamento delle dimensioni o supporto limitato dei tipi di dati. Ogni implementazione convalida questi vincoli e segnala quando un workload non può essere gestito, consentendo ai dispatcher di livello superiore di eseguire il fallback in modo controllato su un altro backend (vedi
PallasMosaicTpuRaggedDot._fwd()).
API di alto livello
La maggior parte degli operatori ha più backend, ad esempio un'implementazione di riferimento portatile insieme a uno o più kernel specifici per l'hardware, ed espone un singolo entry point familiare di alto livello (ad esempio una funzione jax.lax standard). Questo livello è progettato per offrire agli utenti un'interfaccia semplice e immediata che seleziona automaticamente il backend supportato migliore per l'hardware e le forme di input, consentendo comunque di richiedere un'implementazione specifica quando necessario (vedi tokamax.ragged_dot()).
ArgSpecs
Mantenere un catalogo condiviso di forme di workload importanti è essenziale per testare e ottimizzare i kernel in modo coerente tra i backend. Tokamax acquisisce queste forme rappresentative di produzione e benchmark come specifiche dei workload che vengono condivise tra tutte le implementazioni di un operatore. In questo modo, i test di integrazione continua, i benchmark di regressione e le pipeline di ottimizzazione automatica hanno un'unica fonte di attendibilità che può essere filtrata in base ai tag per i diversi workflow (consulta gli ArgSpec per ragged_dot).
Struttura del repository
Il codice di implementazione interno si trova nell'albero di origine privato (vedi
tokamax/_src),
mentre i simboli pubblici per gli operatori, l'ottimizzazione automatica, il benchmarking e la configurazione
vengono riesportati tramite moduli di primo livello (vedi
tokamax/__init__.py).
All'interno di ogni directory dell'operatore (vedi
tokamax/_src/ops),
i file seguono una convenzione di denominazione coerente, illustrata qui utilizzando il punto irregolare:
- API di alto livello: definisce il punto di accesso funzionale pubblico e la logica di invio del backend (vedi
api.py). - Classe base specifica per l'operazione: definisce l'implementazione di riferimento portatile (vedi
base.py). - Implementazioni di backend: definisce classi di operatori, configurazioni, euristiche e spazi di ottimizzazione automatica specifici per l'hardware (vedi
pallas_mosaic_tpu.py). - Kernel di basso livello: separa le implementazioni di kernel autonome e gli helper di basso livello condivisi in moduli complementari (vedi
pallas_mosaic_tpu_kernel.py). - Specifiche del workload: cataloga le forme di input canoniche per i test, il benchmarking e l'ottimizzazione automatica (vedi
arg_specs.py). - Suite di test: definisce i controlli di correttezza parametrizzati condivisi insieme alle suite di test per backend (vedi
test_base.py).
Le operazioni all'interno della directory experimental seguono una struttura simile, ma potrebbero non essere esposte nell'API pubblica. Queste operazioni sono destinate a un'iterazione e un'esplorazione rapide e possono cambiare di frequente e in modo significativo, con aspettative generalmente inferiori in termini di manutenzione e assistenza continua.
Quale livello devono chiamare gli utenti
La scelta di un punto di ingresso è fondamentalmente un compromesso tra praticità e controllo. La maggior parte degli utenti dovrebbe iniziare chiamando gli operatori tramite l'API funzionale di alto livello, che fornisce un'interfaccia di stile familiare e seleziona automaticamente un'implementazione di backend adatta. Quando è necessaria la selezione deterministica del backend, gli utenti possono passare una scelta di implementazione esplicita alla funzione di alto livello, mantenendo la stessa firma di chiamata. Per il massimo controllo, gli utenti possono creare un'istanza di una classe di implementazione dell'operatore specifica direttamente per personalizzare gli iperparametri del kernel, come le dimensioni dei tile, e passare argomenti specifici del backend.
Non è consigliabile chiamare direttamente le funzioni kernel di basso livello senza passare attraverso una classe di implementazione dell'operatore. In questo modo, viene bypassata l'infrastruttura essenziale, tra cui l'ottimizzazione automatica, la convalida e la canonicalizzazione degli input e la serializzazione dei metadati, senza offrire risparmi significativi in termini di overhead, poiché i wrapper degli operatori sono intenzionalmente leggeri. Ad esempio, in assenza di iperparametri con ottimizzazione automatica appropriati, è probabile che gli utenti riscontrino prestazioni significativamente inferiori.
Argomenti avanzati
Fusione degli operatori
Gli operatori TPU Pallas fusibili supportano la fusione dei prologhi e degli epiloghi JAX circostanti direttamente nel kernel tramite @tokamax.ops.op_fusion.fuse. Consulta la guida alla fusione degli operatori per esempi di utilizzo e istruzioni sulla creazione di kernel e sottoclassi Op compatibili con la fusione.
Serializzazione
I kernel possono essere serializzati in StableHLO. Le chiamate kernel sono chiamate personalizzate JAX, che per impostazione predefinita sono vietate in jax.export, richiedendo l'utilizzo di tokamax.DISABLE_JAX_EXPORT_CHECKS per consentire l'esportazione di tutti i kernel 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),
)
Tieni presente che le funzioni serializzate con i kernel Tokamax perdono l'indipendenza dal dispositivo di StableHLO standard. Tokamax offre due garanzie di serializzazione:
- Una funzione deserializzata serializzata su un dispositivo specifico verrà eseguita esattamente sul dispositivo per cui è stata serializzata.
- Tokamax offre le stesse garanzie di compatibilità di JAX: compatibilità con le versioni precedenti di 6 mesi.
Cross-compilazione ed esportazione della CPU
I kernel Tokamax possono essere esportati o cross-compilati su un host CPU:
- La selezione esplicita dell'implementazione (ad es.
implementation="mosaic_tpu_v2") ignora automaticamente la convalida del dispositivo host. - In alternativa, abilita la cross-compilazione a livello globale utilizzando
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),
...,
)