StableHLO è un set operativo di calcolo ML compatibile con le versioni precedenti ispirato a HLO/MHLO. Questo documento spiega il tipo e la portata della compatibilità che garantisce che StableHLO fornisca, in base al processo stabilito nella RFC di compatibilità.
Versions
La versione corrente di StableHLO è disponibile in Version.h.
Nella serie 0.x.x, la versione secondaria viene eseguita ogni volta che vengono apportate modifiche all'opset StableHLO o al formato di serializzazione StableHLO e la versione della patch viene interrotta ogni volta che integriamo StableHLO downstream, ovvero nel repository openxla/xla.
Garanzie
6 mesi di compatibilità con le versioni precedenti: gli artefatti portatili serializzati da una vecchia versione di libStablehlo hanno la stessa semantica* quando sono deserializzati da una nuova versione di libStablehlo se queste versioni sono create da commit openxla/stablehlo a meno di 6 mesi di distanza.
1 mese di compatibilità in avanti: gli artefatti portatili serializzati da una nuova versione di libStablehlo hanno la stessa semantica* quando sono deserializzati da una vecchia versione di libStablehlo se queste versioni sono create da commit openxla/stablehlo a meno di un mese di distanza, a meno che il programma non utilizzi nuove funzionalità introdotte dalla versione precedente.
* I programmi StableHLO vengono convertiti da/verso artefatti portabili tramite le API di compatibilità e la semantica di questi programmi è definita dalla specifica StableHLO. Consulta la sezione "Fuori ambito" per visualizzare esempi di ciò che non è coperto da questa definizione di compatibilità.
API
Gli artefatti portatili possono essere creati utilizzando lo strumento stablehlo-translate
o direttamente nelle API C++ o Python. La serializzazione richiede una versione di destinazione di StableHLO per scrivere un artefatto scritto in formato #.#.# (vedi Version.h per la versione corrente). La desserializzazione utilizza la versione corrente di StableHLO per leggere un artefatto.
stablehlo-translate
Si tratta del modo più semplice per creare e leggere un artefatto portatile.
# Write a StableHLO program to a portable artifact
$ stablehlo-translate --serialize file.mlir --target=0.9.0 > portable_artifact.mlir.bc
# Read StableHLO portable artifact
$ stablehlo-translate --deserialize portable_artifact.mlir.bc
C++
Per i flussi di lavoro programmatici, StableHLO fornisce le seguenti API di compatibilità:
// From: #include "stablehlo/api/PortableApi.h"
// Get the current StableHLO version.
//
// This value can be used as the `targetVersion` argument to
// `serializePortableArtifact`.
std::string getCurrentVersion();
// Get the minimum supported StableHLO version.
//
// This value can be used as the `targetVersion` argument to
// `serializePortableArtifact`.
std::string getMinimumVersion();
// From: #include "stablehlo/dialect/Serialization.h"
// Write a StableHLO program to a portable artifact
// Writes a stable payload for `module` to `os`. If compatibility with a
// previous version of StableHLO is required, provide the required version
// string `#.#.#` for `targetVersion`.
//
// Can fail if `module` cannot be expressed in the `targetVersion` version of
// StableHLO, e.g. if it's using new or removed features, or if it involves
// unsupported dialects.
LogicalResult serializePortableArtifact(ModuleOp module,
StringRef targetVersion,
raw_ostream& os);
// Read StableHLO portable artifact
//
// Can fail if `sourceStr` cannot be expressed in the current version of
// StableHLO, e.g. if it's using incompatible features. Returns nullptr if
// `sourceStr` is invalid or fails to deserialize.
OwningOpRef<ModuleOp> deserializePortableArtifact(StringRef sourceStr,
MLIRContext* context);
Consulta stablehlo/api/PortableApi.h
e stablehlo/dialect/Serialization.h
per le API complete.
Consulta la pagina StablehloTranslateMain.cpp per un esempio sull'utilizzo di queste API.
Python
StableHLO fornisce inoltre associazioni Python alle API di compatibilità C++:
def get_current_version() -> str: ...
def get_minimum_version() -> str: ...
def serialize_portable_artifact(module: ir.Module, target_version: str) -> bytes: ...
def serialize_portable_artifact(module: str, target_version: str) -> bytes: ...
def deserialize_portable_artifact(context: ir.Context, artifact: bytes) -> ir.Module: ...
def deserialize_portable_artifact(artifact: bytes) -> str: ...
Consulta StablehloModule.cpp
per le API Python complete.
Vedi stablehlo.py > test_serialization_apis per esempi di round trip sull'utilizzo delle API Python Serialization.
Test
Abbiamo una suite di compatibilità in stablehlo/test che comprende un compendio completo delle operazioni StableHLO serializzato per tutte le versioni StableHLO supportate. Per ogni richiesta di pull, stiamo testando la compatibilità sia con le versioni precedenti che con quelle precedenti, ovvero che la suite può essere deserializzata con il targeting HEAD (compatibilità con le versioni precedenti), che il compendio possa essere serializzato indirizzato a tutte le versioni di StableHLO supportate (compatibilità in avanti) e che i risultati siano sintatticamente identici ai programmi StableHLO originali.
Lavoro futuro
Crea una suite di compatibilità nell'upstream MLIR: utilizzando quanto appreso dalla creazione e manutenzione delle garanzie StableHLO, stiamo pianificando di contribuire a una suite di compatibilità all'upstream MLIR per fornire il rilevamento precoce di interruzioni accidentali della compatibilità nell'infrastruttura di bytecode MLIR (#1632).
Utilizza l'implementazione del riferimento: al momento, i test di compatibilità consistono nella deserializzazione della suite di compatibilità serializzata dalle versioni precedenti di libStablehlo e nel garantire che la deserializzazione produca programmi sintatticamente identici. Prevediamo di utilizzare anche un'implementazione di riferimento in questi test, allentando il requisito eccessivamente oneroso dell'identità sintattica e testando in modo esauriente l'implementazione del riferimento (#1245).
Fuori ambito
Elementi non portabili: le garanzie di compatibilità sono fornite solo per gli artefatti portatili creati in un modo molto specifico. Altri tipi di artefatti, ad esempio la rappresentazione a stampa del dialetto StableHLO o persino una rappresentazione in bytecode del dialetto StableHLO, non hanno garanzie di compatibilità.
Funzionalità non specificate: potremmo apportare modifiche incompatibili alle funzionalità storicamente supportate nei programmi StableHLO, ma che non fanno ancora parte della specifica StableHLO, ad esempio non forniamo garanzie di compatibilità per gli attributi non registrati.
Compatibilità con bug: possiamo apportare modifiche incompatibili se l'implementazione in libStablehlo contraddice la specifica StableHLO, ad esempio se una definizione nel dialetto VHLO è errata o se un verificatore nel dialetto StableHLO non corrisponde alla specifica.
Accuratezza numerica: StableHLO dispone di più operazioni con precisione definita dall'implementazione per tutti i consumer e persino all'interno dello stesso consumer in tutte le versioni. Di conseguenza, StableHLO non mira a garantire l'accuratezza numerica, anche se ciò potrebbe cambiare in futuro (#1156).
La compatibilità delle origini per le API C, C++ e Python in libStablehlo è un obiettivo aspirazionale. Al momento non offriamo garanzie di compatibilità delle fonti, ma facci sapere se si tratta di un caso d'uso importante per te e potremo discuterne a proposito del supporto (#1247).