StableHLO uses the MLIR Bytecode Format for serialization.
The MLIR Bytecode Format is a serialization format used to encode MLIR programs. From the MLIR RFC, it was built for "the benefits that a binary format brings to the table; namely serialization speed and size, mmap capabilities, more easily enabled versioning, etc." Performance, serialization size, and memory tests were run using large test from various dialects to validate the format.
MLIR bytecode was not specifically built to make MLIR stable, but the MLIR RFC notes that it would be possible to provide compatibility guarantees on top of this format, which we successfully did for StableHLO (see compatibility.md).
Portable artifacts can be created using either the stablehlo-translate
tool,
or directly in C++ or Python APIs. Serialization needs a target version of
StableHLO to write an artifact written in #.#.#
format (See Version.h
for current version). Deserialization uses the current version of StableHLO to
read an artifact.
This is the easiest way to create and read a portable artifact.
# 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
For programmatic workflows, StableHLO provides the following APIs to create portable artifacts:
// From: #include "stablehlo/dialect/Serialization.h"
// Write a StableHLO program to a portable artifact
LogicalResult serializePortableArtifact(ModuleOp module,
StringRef targetVersion,
raw_ostream& os);
// Read StableHLO portable artifact
OwningOpRef<ModuleOp> deserializePortableArtifact(StringRef sourceStr,
MLIRContext* context);
In the near future, we are also planning to add Python APIs for serialization and deserialization (#1301).