Moonshine 仅加载 ORT 格式模型：迁移指南与底层实现解析

Moonshine 仅加载 ORT 格式模型迁移指南与底层实现解析【免费下载链接】moonshineVery low latency speech to text, intent recognition, and text to speech, for building voice agents and interfaces项目地址: https://gitcode.com/GitHub_Trending/moonshine3/moonshineMoonshine面向语音 Agent 的低延迟语音转写、意图识别与语音合成引擎已全面停止加载 ONNX.onnx格式模型改为在所有平台、所有绑定上只接受 ONNX Runtime 的 flatbuffer 编码格式.ort。本文以 docs/ort-only-models.md 为骨架结合仓库中的转换脚本与 C 源码说明这一破坏性变更的原因、受影响的自定义模型入口、具体的迁移步骤以及底层是如何以“一眼识别 明确报错”的方式把.onnx挡在门外的。读完你可以在自己的项目中完成旧模型的一次性迁移并理解为什么在浏览器、iOS、Android 与桌面端会出现完全一致的行为。为什么 Moonshine 只加载.ortMoonshine 之所以统一到 ORT 格式根源在 WebAssembly、iOS 与 Android 构建。这三个平台链接的是一个minimal最小化ONNX Runtime它按模型实际用到的算子裁剪编译算子白名单见 core/third-party/onnxruntime/moonshine-required-operators.config可以把 ONNX Runtime 约三分之二的代码从最终产物中裁掉。代价是最小化构建里根本没有编译进 ONNX 解析器因此在浏览器/移动端无论调用方代码怎么写.onnx都永远不可能被读取。具体收益与代价在 language-bindings/wasm/README.md 的 The minimal build, and what it costs you 一节有详细说明。由此产生了此前最糟糕的一种格局桌面端支持两种格式移动端只支持一种。开发者在 Mac 上能跑通的代码一到浏览器或手机就失败而且失败表现为一个晦涩的 ONNX Runtime 解析错误离真正的根因很远。统一在所有平台拒绝.onnx之后行为处处一致问题在你自己的办公桌上就能暴露出来。从源码结构看这一决策被固化在 TTS 会话选项里core/moonshine-tts/src/ort-session-options.cpp 中对所有 TTS 会话统一写入opts.AddConfigEntry(session.load_model_format, ORT);注释明确写道“STT 与拼写模型一直是 ORT-only在完整 ORT 构建上正是这一配置让误入的.onnx在此失败而不是在桌面端加载成功、到浏览器才失败”。也就是说即使桌面端用的是完整版 ONNX Runtime具备解析.onnx的能力也通过会话配置强制按 ORT 格式加载从而保证与 wasm/iOS/Android 的最小化构建行为一致。变更了什么受影响的模型入口官方发布的模型早已完成转换对你没有任何要求。变化只针对你自行提供的模型文件具体包括四类入口受影响入口说明piper_onnx/piper_model_onnx选项以及内存键piper/onnx自定义 Piper 语音模型oov_onnx_override选项与内存键自定义英文 OOV词表外单词模型在.ort迁移之前下载的 Embedding 模型目录目录内是model_variant.onnx加.onnx_data附属文件按名称解析模型时模型文件旁的任意.onnx以前在没有.ort时会退而取用.onnx关键点选项名与内存键名保持旧拼写已有调用代码可以原样编译、原样运行只是它们接受的文件格式收窄了。这一点在源码注释中多次强调——例如 core/moonshine-tts/src/moonshine-tts-options.h 对kTtsPiperOnnxKey piper/onnx的注释键名早于 ORT 迁移保留是为了让老调用方继续工作但它携带的字节或路径必须是.ort。各入口在代码中的落点Piper 自定义语音piper_onnx/piper_model_onnx/piper_model均映射到内存键piper/onnx见 core/moonshine-tts/src/moonshine-tts-options.cpp内存加载路径在 core/moonshine-tts/src/piper-tts.cpp 中对键piper/onnx的字节调用require_ort_model_bytes校验后再创建会话。英文 OOV 覆盖oov_onnx_override映射到oov_onnx_override键见 core/moonshine-tts/src/moonshine-g2p-options.cpp配套的oov_onnx_config用于从内存加载时提供合并后的 JSON 配置文本。Embedding 模型目录见下文“Embedding 目录如何处置”。ONNX 外部数据支持随之一并移除与.onnx同时消失的是ONNX external data外部数据支持即model.onnx.data/model.onnx_data这类附属文件。.ort是自包含的所以一个依赖附属文件的模型必须先被转换成单个文件才能继续使用。仓库证据显示这一变化已经固化Embedding 模型的清单测试断言新清单只包含model_q4.ort且不再出现.onnx_data见 core/moonshine-c-api-test.cppEmbedding 模型的加载实现也专门处理旧目录——发现只有model_variant.onnx而没有.ort时打印“Moonshine loads ORT-format models only. Re-download this model directory to get …”并返回错误而不是报“文件缺失”这种误导性信息见 core/gemma-embedding-model.cpp。迁移一次性转换模型并指向结果对每个模型只需转换一次然后把配置指向转换结果。官方转换命令python scripts/convert-models-to-ort.py path/to/model.onnx对于Embedding 模型目录请直接重新下载而不是手工转换——公开目录早已提供.ort版本手工转换反而容易遗漏tokenizer.bin等配套文件加载实现同时要求目录内有tokenizer.bin见 core/gemma-embedding-model.cpp。转换脚本的行为与参数源码级scripts/convert-models-to-ort.py 不是简单的“换格式”它会根据模型特点在三种结果间决策converted完整转换、split拆分为.model.ort.weights.ort双文件、too-large超出体积预算保留为.onnx。其核心逻辑如下完整优化转换用ORT_ENABLE_ALL图优化级别生成.ort_convert_at_level见 convert-models-to-ort.py。ORT 格式的图优化在转换时烘焙进文件加载时不会重新应用因此优化级别是文件的永久属性。两类模型的体积分化浮点权重模型如英文 OOV 模型完整优化后体积与.onnx相当且由于省去 protobuf 解析加载更快是纯赚int8 权重、推理时转 float 的模型Kokoro、所有 Piper 语音、中文与阿拉伯语 G2P 模型优化会把权重折叠成 float32.ort体积约4 倍于.onnx。若放弃优化来保体积推理会慢 3~5 倍因为折叠正是它们快的原因。超预算时走拆分模型在--max-growth预算内装不下时尝试调用 scripts/split-model-weights.py 拆成双文件既保留算子融合又恢复原体积。但拆分只在没有预打包pre-packing需求的模型上划算ORT 在加载时会把一个常量MatMul操作数重排成块布局而图输入做不到这会令 Transformer 类 G2P 模型推理慢约 2.2 倍Conv没有此步骤所以 Piper 语音可以“免费”拆分。脚本通过统计哪些算子消费反量化权重来决策PREPACKING_OPS {MatMul, FusedMatMul, Gemm, Attention}阈值PREPACK_SHARE_LIMIT 0.10见 convert-models-to-ort.py可能亏的模型一律保持.onnx不转换。--force-split的适用场景按字节数衡量的预打包测试在 Kokoro 上会误判——它的参数大多在 PL-BERT 编码器与时长预测器里测试读出 215% 的亏损但运行时主要耗在 iSTFTNet 解码器的卷积上实测拆分反而在 Pi 4 上快 1.00~1.07 倍且加载仅 2.1 秒对比完整优化 7.9 秒。--force-split正是为这类已实测验证的模型准备的见脚本模块 docstring。完整优化与 CoreML/NNAPI 的冲突完整优化会把整片区域融合成com.microsoft算子编译型执行提供程序无法识别因此也排除了 CoreML 与 NNAPI——这是实测后接受的取舍详见 docs/execution-providers.md。常用参数一览来自 convert-models-to-ort.py 的参数解析参数默认值作用roots必填要扫描的文件或目录目录递归查找*.onnx--max-growth8.0允许相对.onnx的最大体积增幅百分比最小 Piper 语音的图携带固定量的浮点权重拆分开销占比最大8% 正是它们所需--no-split关闭超预算模型直接跳过而非生成拆分双文件--force-split关闭即使预打包测试说不划算也强制拆分适用于 Kokoro 这类实测更快的模型--force关闭即使已存在.ort也重新转换--jobsCPU 核数的一半多进程并行转换数--dry-run关闭只列出将要转换的模型不实际执行转换前可先--dry-run预览例如python scripts/convert-models-to-ort.py --dry-run core/moonshine-tts/data启动时的失败表现现在传入.onnx会得到一个明确指出文件名和修复命令的报错而不是解析错误。如果你在启动日志里看到它就是这个原因。报错文案由 core/moonshine-tts/src/ort-model-format.h 生成形如what: Moonshine loads ORT-format models only. Convert it with scripts/convert-models-to-ort.py.源码层如何“一眼”识别 ORT 模型拒绝.onnx并给出可读报错靠的是一个极轻量的魔法数检查。 core/moonshine-tts/src/ort-model-format.h 中的require_ort_model_bytes只做一件事检查缓冲区偏移 4 处是否为ORTM四个字节。ORT flatbuffer 在该位置携带ORTM标识而序列化的 ONNX 模型是 protobuf不会命中——因此无需解析任何格式即可区分两者。该头文件 header-only 且不依赖 ONNX Runtime选项解析代码可以在不链接运行时的情况下使用它。配套的路径级校验在 core/moonshine-tts/src/g2p-path.his_onnx_model_name判断文件名是否以.onnx结尾而ort_model_path在按名称解析模型时若传入的是voice.onnx这种语音标识名会自动把后缀换成.ort去磁盘上找文件——这正是下文“voice 名照旧可用”的实现基础。require_ort_model_path则直接对以.onnx结尾的路径抛错。这些校验被分散在各模型加载路径中统一调用Piper 内存加载core/moonshine-tts/src/piper-tts.cpp、ZipVoice 内存加载core/moonshine-tts/src/zipvoice-tts.cpp、Kokoro 单文件与拆分双文件加载core/moonshine-tts/src/moonshine-tts.cpp、moonshine-tts.cpp。测试侧同样覆盖选项解析测试传入oov_onnx_override custom/oov.ort验证键被正确接收core/moonshine-tts/tests/moonshine-g2p-options-test.cppC API 测试验证piper_onnx选项会生成piper/onnx内存键core/moonshine-c-api-test.cpp。哪些没有变迁移并非推倒重来以下三件事保持不变Piper 配置附属文件命名不变Piper 的 config sidecar 沿用上游voice.onnx.json命名无论模型本体是什么格式。它是 JSON 而非模型不受影响。这一定义见 core/moonshine-tts/src/moonshine-tts-options.hPiper 上游就这样命名我们保持该名称与模型本身格式无关。Bundle 目录名不变目录名如zh_hans/roberta_chinese_base_upos_onnx/只是目录名照旧使用。语音标识名解析不变你仍然可以按上游voice.onnx名称请求语音——那是一个语音标识符而非文件名最终会解析到磁盘上的.ort文件ort_model_path的后缀替换逻辑见 core/moonshine-tts/src/g2p-path.h。小结对 Moonshine 的现有用户本变更只影响自备模型的场景piper_onnx/piper_model_onnx、piper/onnx内存键、oov_onnx_override、旧版 Embedding 目录以及名称旁路里的.onnx。迁移动作只有两个——用python scripts/convert-models-to-ort.py path转换自备模型Embedding 目录直接重新下载并留意体积预算相关的--max-growth、--no-split、--force-split参数决策。底层由session.load_model_formatORT会话配置、ORTM魔法数校验与明确的报错文案共同保证任何平台、任何入口.onnx都在第一时间以可读的方式被拒绝而不是把晦涩的解析错误留到浏览器或手机上去撞。【免费下载链接】moonshineVery low latency speech to text, intent recognition, and text to speech, for building voice agents and interfaces项目地址: https://gitcode.com/GitHub_Trending/moonshine3/moonshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考