归档说明（2026-07-12）： 在根目录清理中从 .planning/ 移到了这里。 下方内部 .planning/ / specs/ 路径均为历史遗留 — 这些目录树已被移除；请参阅 git 历史。

SPIKE-01：采用 Serveurperso/OmniVoice-GGUF 作为自适应硬件的默认克隆引擎¶

许可证更正（2026-10-03）： 原先关于商业兼容性的结论已被撤回。请参阅源代码审查以了解代码、权重和下游条款的独立说明。本工程决策并未批准该模型用于 Pro。

状态： 提议中 — Wave 1 构建/冒烟测试仅用于确立技术可行性。验收还需要满足引擎验收中的权利门禁，包括所有者批准以及对受限免费应用引擎的首次使用披露。 日期： 2026-05-18（2026-05-20 更新，加入固定 SHA） 决策者： [维护者] 相关： ROADMAP 第四阶段；REQUIREMENTS GGUF-01..06；.planning/phases/04-adaptive-specialty-engines-spike-first/04-RESEARCH.md

背景¶

VoiceStudio v0.2.7 通过 backend/services/tts_backend.py:VoiceStudioBackend 将 k2-fsa/OmniVoice（代码/权重条款相互独立；0.6B Qwen3 主干，Higgs Audio v2 编解码器，24 kHz 单声道）作为默认语音克隆引擎。Python 进程内路径需要 PyTorch + CUDA / MPS / CPU，在 4 GB VRAM GPU 上会回退到 CPU 推理。

Serveurperso/OmniVoice-GGUF（HuggingFace，每月 10,960 次下载，2026-05-20 验证）发布了同一上游模型的 4 种量化版本 — Q4_K_M（约 659 MB VRAM）、Q8_0（约 945 MB，推荐平衡点）、BF16（约 1.6 GB）、F32（约 3.2 GB）— 可通过 MIT 许可的 omnivoice.cpp 运行时（github.com/ServeurpersoCom/omnivoice.cpp，固定 SHA 下 42 星、59 次提交、6 个未关闭问题）使用。这些量化使用自定义的 omnivoice-lm 架构（已通过 HF API gguf.architecture 确认），并且无法在原生 llama.cpp 中加载。

本决策是关于是否将 GGUF 引擎集成为硬件自适应默认引擎，并保留可覆盖的、回退到现有进程内 VoiceStudioBackend 的选项。

决策¶

仅技术性 GO — 按 GGUF-01..06 集成。在上述权利门禁通过之前，不得将引擎标记为 Accepted（已验收）。

集成形态为 VoiceStudioGGUFBackend(TTSBackend)，它包装了第二阶段的 SubprocessBackend，后者会从固定的 omnivoice.cpp 提交 SHA 构建出随平台捆绑的 omnivoice-tts 二进制并启动它。量化选择由 backend/services/gpu_sandbox.py 的 detect_capabilities() 扩展驱动，该扩展通过可随产品发布的 quant_map.json 将 (compute_class) → 量化文件名 进行映射。在探测与加载均成功的硬件上，GGUF 成为默认克隆引擎；任何失败情况下，现有进程内 VoiceStudioBackend 作为回退。

Spike 验证（2026-05-20）¶

固定 SHA（Wave 1 的任务 1 中填写）¶

• Serveurperso/OmniVoice-GGUF HuggingFace 仓库修订 SHA：361609388ae572a820d085185bbbe2a2aac4b30e（2026-05-20 通过 curl https://huggingface.co/api/models/Serveurperso/OmniVoice-GGUF 解析；lastModified 2026-04-30T13:39:10.000Z）
• ServeurpersoCom/omnivoice.cpp master HEAD SHA：886fc079838ca7400cb2b42b36e2a65aa1daabe8（2026-05-20 通过 curl https://api.github.com/repos/ServeurpersoCom/omnivoice.cpp/commits/master 解析；提交 2026-05-17T12:41:06Z — “cmake：将 /utf-8 限定到 C 和 C++，使 nvcc 不会将其视为输入文件”）

两个 SHA 都被镜像到 backend/engines/omnivoice_gguf/quant_map.json 的 _meta 块中，以确保引擎代码与 ADR 不会彼此漂移。

后果¶

正面影响： - 4 GB VRAM GPU（目前在进程内路径上会回退到 CPU）可通过 Q4_K_M 获得 GPU 加速的克隆。 - 更小的 VRAM 占用 = 当用户在同一会话中运行多个引擎时，不会挤占其他引擎的空间。 - 运行时集成并不确立商业模型权利；请参阅上面的更正。 - 与已发布版本使用相同的底层模型 — 最坏情况下，在特定硬件类别上与进程内路径不相上下，我们保留该路径作为回退。

负面影响 / 风险： - 向依赖图中添加了一个由他人维护的 C++ 运行时（omnivoice.cpp，决策时 42 星）。 - 向安装程序添加约 12-16 MB 的平台二进制（必须根据 Pitfall 6 对照第三阶段镜像时机基线进行验证）。 - macOS 代码签名范围扩大 4 个二进制（通过 REL-05 跟踪；与 #54 相同的 xattr -cr 变通方案适用于 v0.3.x）。 - omnivoice.cpp README 未发布独立的 buildmetal.sh 脚本；Apple Silicon Metal 直接通过 cmake -DGGML_METAL=ON 构建（#2105）。

缓解措施： - 按提交 SHA（886fc079838ca7400cb2b42b36e2a65aa1daabe8）固定 omnivoice.cpp；在 CI 中针对全部 4 个目标平台从固定的 SHA 重新构建。 - 在 quant_map.json 中按提交 SHA（361609388ae572a820d085185bbbe2a2aac4b30e）固定每个量化文件；JSON 可随应用发布，因此该表无需发布新应用即可更新。 - 如果任何 GGUF 步骤（探测、下载、加载、生成）失败，进程内 VoiceStudioBackend 仍作为回退方案保留。 - macOS Apple Silicon Metal 构建已通过 cmake -DGGML_METAL=ON（#2105）验证；进程内 VoiceStudioBackend 仍作为通用回退方案可用。 - 对打包的二进制文件计算 SHA-256 校验和（依据 GATE-05）；在首次启动及每次加载量化文件时进行验证。 - 子进程参数组合使用以应用目录为根目录的 Path 类型对象；量化覆盖 UI 仅为基于 quant_map.json 条目的下拉选择（不允许自由输入路径——供应链控制方式与 INST-09 类似）。

来源¶

• .planning/phases/04-adaptive-specialty-engines-spike-first/04-RESEARCH.md（本里程碑的研究）
• https://huggingface.co/Serveurperso/OmniVoice-GGUF（验证于 2026-05-18 / 重新验证于 2026-05-20）
• https://huggingface.co/api/models/Serveurperso/OmniVoice-GGUF（SHA 361609388ae572a820d085185bbbe2a2aac4b30e，2026-05-20）
• https://github.com/ServeurpersoCom/omnivoice.cpp（验证于 2026-05-18 / 重新验证于 2026-05-20）
• https://api.github.com/repos/ServeurpersoCom/omnivoice.cpp/commits/master（SHA 886fc079838ca7400cb2b42b36e2a65aa1daabe8，2026-05-20）
• https://huggingface.co/k2-fsa/OmniVoice（上游项目；另有一套代码/权重许可条款）
• backend/services/tts_backend.py（现有的 VoiceStudioBackend 参考实现）