StableHLO ist ein abwärtskompatibles ML-Computing-opset, das von HLO/MHLO inspiriert ist. In diesem Dokument werden die Art und der Umfang der Kompatibilitätsgarantien von StableHLO basierend auf dem im Kompatibilitäts-RFC festgelegten Prozess erläutert.
Versionen
Die aktuelle Version von StableHLO finden Sie unter Version.h.
Die Nebenversion wird jedes Mal aktualisiert, wenn Änderungen am StableHLO-Opset oder am StableHLO-Serialisierungsformat vorgenommen werden, und die Patch-Version wird jedes Mal aktualisiert, wenn wir StableHLO im Downstream integrieren, d.h. in das Openxla-/xla-Repository.
Garantien
Gemäß dem StableHLO v1.0 Compatibility RFC umfasst das Kompatibilitätsfenster Folgendes:
5 Jahre Abwärtskompatibilität:Portable Artefakte, die von einer alten Version von libStablehlo serialisiert wurden, haben die gleiche Semantik*, wenn sie mit einer neuen Version von libStablehlo deserialisiert werden, sofern diese Versionen aus openxla/stablehlo-Commits erstellt werden, die weniger als fünf Jahre auseinanderliegen.
2 Jahre Aufwärtskompatibilität:Portable Artefakte, die von einer neuen Version von libStablehlo serialisiert wurden, haben die gleiche Semantik*, wenn sie mit einer alten Version von libStablehlo deserialisiert werden, wenn diese Versionen aus openxla/stablehlo-Commits erstellt wurden, die weniger als zwei Jahre auseinanderliegen, es sei denn, das Programm verwendet neue Funktionen, die seit der alten Version eingeführt wurden.
* StableHLO-Programme werden über Kompatibilitäts-APIs zu/aus portablen Artefakten konvertiert. Die Semantik dieser Programme ist in der StableHLO-Spezifikation definiert. Im Abschnitt „Nicht vorgesehen“ finden Sie Beispiele dafür, was von dieser Definition der Kompatibilität nicht abgedeckt wird.
APIs
Portable Artefakte können entweder mit dem stablehlo-translate-Tool oder direkt in der C++ oder Python API erstellt werden. Die Serialisierung benötigt eine Zielversion von StableHLO, um ein Artefakt zu schreiben, das im #.#.#-Format geschrieben wurde. Die aktuelle Version finden Sie unter Version.h. Da Patchversionen keine Auswirkungen auf die Kompatibilität haben, wird jedes Ziel mit einer Patchversion ungleich null während der Serialisierung standardmäßig auf null gesetzt.
Bei der Deserialisierung wird die aktuelle Version von StableHLO zum Lesen eines Artefakts verwendet.
stablehlo-translate
Dies ist die einfachste Möglichkeit, ein portables Artefakt zu erstellen und zu lesen.
# 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++
Für programmatische Workflows bietet StableHLO die folgenden Kompatibilitäts-APIs:
// 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);
Vollständige APIs finden Sie unter stablehlo/api/PortableApi.h und stablehlo/dialect/Serialization.h.
Informationen zur Verwendung dieser APIs finden Sie unter StablehloTranslateMain.cpp.
Python
StableHLO stellt auch Python-Bindungen an die C++-Kompatibilitäts-APIs bereit:
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: ...
Die vollständigen Python APIs finden Sie unter StablehloModule.cpp.
Unter stablehlo.py > test_serialization_apis finden Sie Beispiele für die Verwendung der Python-Serialisierungs-APIs.
Tests
In stablehlo/tests/vhlo haben wir eine Kompatibilitätssuite, die ein umfassendes Compendium der StableHLO-Vorgänge enthält, das für alle unterstützten StableHLO-Versionen versioniert wurde. Für jede Pull-Anfrage testen wir sowohl die Abwärts- als auch die Vorwärtskompatibilität. Das heißt, dass die Suite deserialisiert werden kann und auf HEAD (Abwärtskompatibilität) ausgerichtet ist, dass das Compendium auf alle unterstützten StableHLO-Versionen ausgerichtet werden kann (Aufwärtskompatibilität) und dass die Ergebnisse syntaktisch identisch mit den ursprünglichen StableHLO-Programmen sind.
Zukünftige Arbeiten
Eine Kompatibilitätssuite für MLIR-Upstream erstellen: Anhand der Erkenntnisse aus der Einrichtung und Pflege von StableHLO-Garantien möchten wir eine Kompatibilitätssuite für MLIR-Upstream bereitstellen, um eine Früherkennung für versehentliche Kompatibilitätsbrüche in der MLIR-Bytecode-Infrastruktur (Nr. 1632) bereitzustellen.
Referenzimplementierung verwenden: Momentan besteht bei Kompatibilitätstests die Deserialisierung der Kompatibilitätssuite, die von älteren Versionen von libStablehlo seriell ist, und dafür sorgen, dass durch die Deserialisierung syntaktisch identische Programme generiert werden. Wir planen auch den Einsatz einer Referenzimplementierung in diesen Tests, um die übermäßig lästige Anforderung einer syntaktischen Identität zu lockern und die Referenzimplementierung umfassend zu testen (#1245).
Ausgeschlossen
Nicht portierbare Artefakte:Kompatibilitätsgarantien werden nur für portable Artefakte gegeben, die auf eine ganz bestimmte Weise erstellt werden. Für andere Arten von Artefakten, z.B. eine optimierten Darstellung des StableHLO-Dialekts oder sogar eine Bytecode-Darstellung des StableHLO-Dialekts, gibt es keine Kompatibilitätsgarantien.
Nicht spezifizierte Funktionen:Wir nehmen möglicherweise inkompatible Änderungen an Funktionen vor, die bisher in StableHLO-Programmen unterstützt wurden, aber noch nicht Teil der StableHLO-Spezifikation sind. Beispielsweise geben wir keine Kompatibilitätsgarantien für nicht registrierte Attribute.
Fehlerkompatibilität:Wir können inkompatible Änderungen vornehmen, wenn die Implementierung in libStablehlo der StableHLO-Spezifikation widerspricht, z.B. wenn eine Definition im VHLO-Dialekt falsch ist oder ein Prüfer im StableHLO-Dialekt nicht der Spezifikation entspricht.
Numerische Genauigkeit: StableHLO hat mehrere Vorgänge mit implementierungsdefinierter Genauigkeit für alle Nutzer und sogar innerhalb desselben Nutzers über mehrere Versionen hinweg. Daher bietet StableHLO keine Garantien für die numerische Genauigkeit, auch wenn sich dies in Zukunft ändern kann (#1156).
Quellkompatibilität für C-, C++- und Python-APIs in libStablehlo ist ein ambitioniertes Ziel. Zum jetzigen Zeitpunkt können wir keine Garantien zur Quellenkompatibilität geben. Teilen Sie uns jedoch bitte mit, ob dies ein wichtiger Anwendungsfall für Sie ist, und wir können mit Ihnen über eine mögliche Unterstützung sprechen (#1247).