StableHLO：版本兼容性

可视化演示

三步展示版本兼容性：算子集版本演进（新版本仅新增算子不改旧语义）、旧模型在新版本编译器中的解析·匹配·编译·执行流程、以及StableHLO独立算子版本与ONNX固定opset的对比。

兼容性理念：给旧房子的一纸承诺

在旧城改造中，最让人安心的不是新楼有多漂亮，而是一句“老房不拆”。如果你家的老房子属于历史保护区，那么无论新增多少商场和地铁，它都可以继续住人、继续办证、继续通电。StableHLO 的兼容性理念，就是为 AI 模型这种“老房子”画出一片保护区。

AI 模型训练完成后，并不会直接变成能在所有硬件上运行的二进制程序，而是会先翻译成一种叫作“中间表示”的语言。StableHLO 是 MLIR 生态里的一种高层中间表示，位于框架和底层编译器之间。它有点像“施工图纸”：框架负责画出图纸，编译器负责按图纸盖房子。为什么需要版本兼容？因为模型的生命周期常常以年计，而编译器每几个月就发布新版本。若没有保护承诺，每次升级编译器都等于对线上模型“强制拆迁”。

StableHLO 把“兼容”当成首要目标。它提供版本化规范，让不同编译器知道某个程序由哪个版本产生，并按规范解读；它坚持向前兼容，允许旧版本生成的程序被新版本编译器加载；它对算子集演进设限，保证历史算子不会因为新增算子而失去意义。这个三角结构，构成了 StableHLO 兼容性的地基。

就像历史保护条例不是一句口号，而要落到门牌、图纸和审批流程上，StableHLO 的承诺也落到版本号、规范文档和算子演进规则里。下面我们一层层拆开看。

版本化规范：兼容性的“施工手册”

老城区改造不能靠口头承诺，必须有一本随时更新的“施工手册”。哪类房子可以改，哪类必须保留，梁柱能加多粗，外墙能刷什么颜色，都要白纸黑字写清楚。StableHLO 的版本化规范，就是这本施工手册。

在编译链路中，模型从 PyTorch、JAX 等框架导出时，往往要经过多层中间表示。MLIR 这类多级中间表示系统，把模型拆成一层层 IR；StableHLO 是其中一层，靠近框架，负责把模型的高层语义稳定地表达出来。为了让不同版本的编译器能正确协作，一个 StableHLO 程序在导出时，会把自己的“规范版本”记录在序列化文件中。新版编译器读到版本号后，就能知道该用哪一版“施工手册”来解读这些算子。

版本化规范具体记录什么？它不只写“有哪些算子”，更会写每个算子的输入输出要求、数据类型约束和语义定义。比如 stablehlo.add 两个张量是不是必须形状一致、能不能做广播、结果的数据类型如何推断，这些都要有明确条文。规范每一次补充和修订，都要留下演进记录，否则旧程序出了问题也没法追溯。

所以，版本化规范不是一堆文档，而是编译器、模型与开发者三方共同遵守的“城市契约”。有了这本手册，兼容性才不是一句空话。

向前兼容：老住户搬进新城市

城市修了新路、建了新门禁系统，老住户手里的老房本，能不能照样办新门禁卡？StableHLO 说：能。版本兼容性中最重要的“向前兼容”，指的就是旧版 StableHLO 程序，可以被新版编译器加载。

“向前”的方向是时间方向：程序从旧版本走向新版本。反过来，“新程序被旧编译器加载”并不在向前兼容的保证范围内。因为新编译器可能认识新算子，旧编译器却不认识。如果某个 StableHLO 程序用了比编译器更新的特性，编译器完全可以拒绝加载。

更形式化地说，向前兼容可以写成这样一个不变量：

向前兼容保证了“老住户入住新城市”的基本权利。至于新城市的商场、地铁和新材料，那是另一套玩法，旧城市不必提前理解。

算子集演进：建筑材料可以加，老料不能废

城市建设中，新材料会不断出现：新型混凝土、防震钢材、环保涂料。它们可以加入建筑规范，但已有材料不会被一夜之间禁掉，否则老房子的安全认证就会全部失效。StableHLO 的算子集演进，遵循同样的逻辑。

在 StableHLO 里，算子就像建筑规范里的“材料目录”：add 是把两块砖叠起来，dot_general 是搭一座桁架，while 是一套循环施工流程。为了让模型不断拥抱新能力，StableHLO 允许新增算子，新算子可以解决新的计算需求。但新增并不等于随意，它必须纳入规范：写明语义、定义输入输出约束、记录引入版本，让所有编译器都能按统一规则理解。

更难的是修改已有算子。StableHLO 要求已有算子的语义保持稳定；如果只是做“兼容扩展”，比如增加一个带默认值的新属性，这通常可以接受。但如果是改变核心语义、删除合法输入组合，就会让旧模型结果发生变化，属于破坏兼容的行为。即使某个算子不再被推荐使用，它可以进入“弃用”状态，但不能立刻从规范里彻底删除，因为旧版本的模型文件可能还在线上运行。

一句话总结：算子目录可以越变越厚，但绝不能把前几页从规范里撕掉。

增量升级：翻新而不是推到重来

老城区改造最稳妥的做法，不是一次性把整座城推倒，而是一段一段翻新：今天换水管，明天修路灯，后天通地铁。每次改动都尽量不打扰正在生活的居民。StableHLO 的版本演进，也讲究“增量升级”。

在 StableHLO 的兼容性框架里，变更会被分成两类。一类是兼容变更，比如给算子增加一个可选参数、扩展某种输入类型、补充更清晰的约束说明。这类变更不改变旧程序的计算结果，可以被稳定版本吸收。另一类是非兼容变更，比如改变算子的核心语义、删除某个合法用法。这类变更不能夹带在常规升级里，因为一旦上线，旧模型可能悄悄跑出错误结果。

所以，非兼容变更必须走更谨慎的路径。它可以先进入实验特性，让社区快速试用和反馈；成熟后再以新版本的方式正式引入。迁移路径要平滑，最好让用户明确知道：当前程序还能不能用、什么时候需要改、改起来风险有多大。这就是“风险控制”在编译器版本演进中的含义。

增量升级的本质，是让新旧版本之间的差距始终“看得见、控得住”。就像旧城改造不能一次性停水停电一个月，StableHLO 也不会让一次版本升级变成“所有旧模型集体重写”的灾难。

生产价值：从“搬家”变成“续租”

在真实生产环境里，模型不是训练完就结束，而是要长期迭代、持续服务。想象一个推荐系统模型已经线上运行两年，如果每次编译器升级都要把模型重新导出、重新验证，那就像是每半年搬一次家，成本极高。StableHLO 的兼容性，让“搬家”变成了“续租”。

有了向前兼容，模型导出后的 StableHLO 文件可以跨越多个编译器版本继续使用。编译管线升级时，旧模型文件依然能进入新管线，不需要重训、不需要重写、不需要逐层排查算子是否失效。这直接降低了模型长期维护成本，也让“升级编译器”从高风险操作变成可控操作。

兼容性还带来了回滚策略的灵活性。如果新版本的编译器后端出现了一个 bug，线上可以快速回滚到旧版本编译器，而模型文件本身不需要改动。因为在兼容性框架下，同一个旧程序既可以由新编译器加载，也可以继续由旧编译器加载，这给运维留出了充足的逃生通道。

生产系统的信任，是一点一点建立起来的。当模型文件、编译器和算子规范三者形成稳定的契约，团队才敢放心地升级基础设施，而不是每次升级都如履薄冰。

实验特性：新房型先试点，成熟后再入规范

城市不会一上来就批准一种全新材料进入历史保护区，而是会先建几栋实验房，让居民试住、让专家检验，确认安全后再写入建筑规范。StableHLO 为了平衡创新与稳定，也保留了这样一块“实验区”。

实验特性意味着快速迭代：新算子、新语法、新语义可以先在实验阶段出现，社区可以尽早试用并给出反馈。这个阶段的特性不承担完整的前向兼容义务，因为设计可能随时调整。一旦特性经过验证、被正式纳入 StableHLO 规范，它就开始享受稳定版本的保护，同时也要承担兼容性义务——从那一刻起，旧程序对它的依赖会成为新的历史资产。

这种机制避免了两个极端：如果所有新特性一上来就必须永久兼容，设计会变得保守，很难快速试错；如果所有特性都随意变化，又会破坏稳定版本的可信度。实验区就像一个“新房型示范区”，把不确定性隔离在保护区之外。

最终，StableHLO 的生态既有创新空间，也有稳定边界。老房子不拆迁，新房子又能不断盖起来，这才是编译器生态最健康的状态。

AI 应用场景

Python 演示

def parse_version(v):    return tuple(int(x) for x in v.split("."))  class OpSpec:    def __init__(self, name, introduced_version, removed_version=None):        self.name = name        self.introduced_version = introduced_version        self.removed_version = removed_version  class Program:    def __init__(self, version, ops):        self.version = version        self.ops = ops  class StableHLORegistry:    def __init__(self, current_version):        self.current_version = current_version        self.specs = []     def add_op(self, spec):        self.specs.append(spec)     def find_spec(self, name):        for spec in self.specs:            if spec.name == name:                return spec        return None     def can_load(self, program):        if parse_version(program.version) > parse_version(self.current_version):            return False        for op_name in program.ops:            spec = self.find_spec(op_name)            if spec is None:                return False            if parse_version(spec.introduced_version) > parse_version(program.version):                return False            if spec.removed_version is not None:                if parse_version(spec.removed_version) <= parse_version(program.version):                    return False        return True  if __name__ == "__main__":    registry = StableHLORegistry("0.21.0")    registry.add_op(OpSpec("stablehlo.add", "0.1.0"))    registry.add_op(OpSpec("stablehlo.dot_general", "0.18.0"))    registry.add_op(OpSpec("stablehlo.while", "0.5.0"))     old_program = Program("0.18.0", ["stablehlo.add", "stablehlo.dot_general"])    bad_program = Program("0.18.0", ["stablehlo.future_op"])    future_program = Program("0.22.0", ["stablehlo.add"])     print("old loadable:", registry.can_load(old_program))    print("unknown op loadable:", registry.can_load(bad_program))    print("future program loadable:", registry.can_load(future_program))

1. def parse_version(v): return tuple(int(x) for x in v.split("."))把 "0.18.0" 变成 (0, 18, 0)，避免字符串比较在版本位数不同时出错。
2. if parse_version(program.version) > parse_version(self.current_version): return False程序版本比编译器还新，不满足向前兼容，直接拒绝。
3. spec = self.find_spec(op_name)去算子“历史档案”里查找这个算子的引入版本与删除版本。
4. if parse_version(spec.introduced_version) > parse_version(program.version): return False如果算子在程序版本之后才出现，说明这个旧程序不可能合法使用它。
5. if spec.removed_version is not None and ... return False如果算子已被删除，而旧程序版本又落在删除之后，加载也会失败，这正是“禁止随意删除算子”的原因。

常见误区

面试题