StableHLO 是以 HLO/MHLO 為靈感來源，是具有回溯相容性的機器學習運算運算手。本文根據 相容性 RFC 中建立的程序，說明 StableHLO 提供的相容性保證的種類和範圍。
版本
您可以在 Version.h 中找到目前的 StableHLO 版本。
每次建構 StableHLO 運算集或 StableHLO 序列化格式時，都會改進次要版本，而每次我們將 StableHLO 下游整合 (即轉到 openxla/xla 存放區) 時，修補程式版本就會提高。
保證
根據 StableHLO v1.0 相容性 RFC，相容性視窗包含下列內容：
5 年回溯相容性：當舊版 libStablehlo 以新的 libStablehlo 版本還原序列化，且相隔不到 5 年，則由新版 libStablehlo 序列化的可攜式構件擁有相同的語意*。
提供 2 年前瞻相容性：除非程式使用舊版本推出不到 2 年，由新版 libStablehlo 序列化，由舊版 libStablehlo 序列化的可攜式構件具有相同的語意*。
* StableHLO 程式會透過相容性 API 轉換為或從可攜式構件，而這些程式的語意是根據 StableHLO 規格定義。請參閱「超出範圍」一節，瞭解這個相容性定義未涵蓋的內容範例。
API
您可以使用 stablehlo-translate 工具，或直接在 C++ 或 Python API 中建立可攜式構件。序列化需要 StableHLO 的目標版本，才能寫入以 #.#.# 格式編寫的成果 (如要瞭解目前版本，請參閱 Version.h 部分)。由於修補程式版本不會影響相容性，因此在序列化期間，任何含有非零修補程式版本的目標都會預設為零。反序列化程序會使用最新版 StableHLO 來讀取構件。
stablehlo-translate
這是建立及讀取可攜式構件最簡單的方法。
# 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++
針對程式輔助工作流程，StableHLO 提供下列相容性 API：
// 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);
如需完整 API，請參閱 stablehlo/api/PortableApi.h 和 stablehlo/dialect/Serialization.h。
如需這些 API 的使用範例，請參閱 StablehloTranslateMain.cpp。
Python
StableHLO 也提供 C++ 相容性 API 的 Python 繫結：
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: ...
如需完整的 Python API，請參閱 StablehloModule.cpp。
如需使用 Python 序列化 API 的往返範例，請參閱 stablehlo.py > test_serialization_apis。
測試命名空間
我們在 stablehlo/tests/vhlo 中提供了相容性套件，其中包含針對所有支援的 StableHLO 版本序列化的 StableHLO 運算完整的 StableHLO 運算專案。我們會針對每個提取要求，測試回溯和前向相容性，意即套件可以是反序列化目標 HEAD (回溯相容性)、所有支援的 StableHLO 版本 (前向相容性)，而且結果的語法都與原始 StableHLO 程式完全相同。
未來工作
在 MLIR 上游建立相容性套件：我們計劃為 MLIR 上游提供相容性套件，以及早偵測 MLIR 位元碼基礎架構中的意外相容性中斷情形 (#1632)。
使用參考實作：目前相容性測試包含將舊版 libStablehlo 序列化的相容性套件還原序列化，並確保去序列化作業會產生語法相同的程式。我們也打算在這些測試中使用參照實作，藉此放寬語法身分的嚴格要求，並全面測試參考實作 (#1245)。
範圍外
非可攜式的構件：相容性保證僅適用於以特定方式建立的可攜式構件。其他類型的成果 (例如 StableHLO 方形圖的美化表示法，甚至是 StableHLO 方言的位元碼表示法) 並沒有相容性保證。
未受保護的功能：我們可能會對過去在 StableHLO 計畫支援但尚未納入 StableHLO 規格的某些功能做出不相容的變更，例如不提供未註冊屬性的相容性保證。
錯誤相容性：如果 libStablehlo 實作項目與 StableHLO 規格牴觸 (例如 VHLO 方言中的定義有誤，或 StableHLO 方言中的驗證器不符規格)，我們可能會做出不相容的變更。
數值準確度：StableHLO 有多個運算，對所有消費者 (甚至是同一消費者中，不同版本) 的實作定義皆設有準確度。因此，StableHLO 不會試圖保證數值準確度，但日後可能會改變。(#1156)。
libStablehlo 中針對 C、C++ 和 Python API 提供原始碼相容性是理想目標。我們目前並未提供原始碼相容性保證，不過如果這對您來說是重要的用途，請告知我們，以便我們協助您提供支援 (#1247)。