拆解 .oasr 格式：一个文件装下权重、分词器和元数据

一个 .oasr 文件就是一个完整的模型运行时包——权重、分词器、描述符全在里面，拷贝和校验都只需处理一个对象。

训练好的语音模型通常以目录形式交付：权重文件一到三个，分词器一个，config 一份，有时还有独立的 metadata JSON。这些文件必须配套存在、版本一致，搬运时稍有差池就会对不上。OpenASR 选择了另一条路——把模型打成单个文件。运行时包的扩展名是 .oasr，一个 .oasr 文件里同时承载权重、分词器和加载器需要的描述符。模型变成了一个可以缓存、复制、哈希校验的单一对象，而不是一个你只能祈祷没人改过顺序的文件夹。

底层就是标准 GGUF

这里没有自造的二进制容器。.oasr v1 的有效载荷就是标准 GGUF 字节流——OpenASR 在 v1 阶段没有定义任何自定义外层容器。四字节魔数 OASR 已经预留给未来的真正容器格式，当前遇到这个魔数会直接拒绝。所以”格式”在今天的含义就是：GGUF 加上一套关于内部内容和文件命名的契约。

两道边界：字节层与扩展名层

OpenASR 刻意把两种很容易混为一谈的检查分开了。底层的容器探测只看文件头四个魔数字节，完全不关心文件名：GGUF 放行，预留的 OASR 魔数当前拒绝，其他魔数一律失败关闭。这个读取器有意不感知扩展名，所以内部的 GGUF 测试夹具不管叫什么名字都能正常加载。

面向用户的契约则更严格，靠扩展名把关。OPENASR_RUNTIME_PACK_EXTENSION = "oasr" 是唯一的运行时包扩展名：CLI 的 --model-pack 入参和 import-*-local 转换器的输出都只接受和产出 .oasr，旧的 .gguf 扩展名在所有公开边界上已经不再被接受。内部走的仍然是 GGUF，但对外一律是 .oasr。

描述符住在文件里面

OpenASR 的描述符没有放在 sidecar 文件中，而是作为 GGUF 键值元数据直接嵌入同一个文件：openasr.package.version（必须为字符串 "1"）、openasr.model.family、openasr.model.architecture、openasr.runtime.min_version、openasr.audio.frontend、openasr.decode.policy。加载器和运行时选择层直接从包里读取这些键，文件自己就能描述该如何运行自己。

v1 的 .oasr 结构可以这样理解：它就是一个标准 GGUF 文件，头部是 GGUF 自己的头部（不是逐包签名），里面依次是权重张量、分词器数据和 OpenASR 描述符元数据——三者打包在同一个文件里。

因为载荷就是 GGUF，运行时用 zero-copy mmap 绑定权重，并复用计算图缓冲区来控制峰值 RSS。单文件的形态不仅方便管理，也是加载开销低廉的原因。

openasr transcribe --model-pack model.oasr clip.wav
# 一个文件进，转录结果出——没有需要同步的 sidecar

哈希固定加目录签名，而不是文件内签名

一个自描述的单文件很容易让人脱口而出”签名的”，但这么说并不准确。.oasr 打包了权重、分词器和元数据，但不携带任何文件内的发布者签名。信任是在拉取阶段通过两个独立机制建立的：拉取时对包做 sha256 加文件大小的固定校验，指向它的 catalog manifest 则由 Ed25519 签名。包是载荷，信任在它旁边，不在它身上。签名目录和 fail-closed 拉取链的完整流程可以参考另一篇文章 How the signed catalog and fail-closed pull chain work。

两个机制，不是一个签名

包本身是内容固定的（大小加 sha256 必须在安装前匹配）。另外，catalog manifest 由 OpenASR 内置的 Ed25519 catalog key 签名，且拒绝回滚。两者都不是嵌入在 .oasr 文件内部的签名。

“.oasr 是一个可移植的运行时包，不是一个签过名的文件：字节是 GGUF，信任来自哈希固定和旁边的签名目录。”

—— 出自 v1 package contract

这句话就是整个设计的浓缩。标准字节流让生态工具继续可用，单文件让模型成为一个可审计的对象，描述符内嵌让它能自行运转，信任放在该放的地方而不是烙在载荷上。