ONNX 语音包协议#

本文定义桌宠当前接受的独立 ONNX 语音包、安装流程和发布边界。权威实现位于 lib/script/gsvmove/package_manager.py、onnx_runtime.py 与 service.py。

1. 包格式#

语音包根目录固定为 ONNX_aimisiV2/，manifest.json 必须包含：

{
  "format": "aemeath-gpt-sovits-onnx",
  "format_version": 2,
  "runtime_revision": 3,
  "precision_profile": "fp16",
  "name": "aimisiV2",
  "sample_rate": 32000,
  "languages": ["zh", "en"],
  "reference_audio": "reference.wav",
  "reference_text": "reference.txt",
  "character_dir": "character",
  "common_dir": "common"
}

当前运行时要求同时具备中文和英文前端。角色模型放在 character/，可复用公共模型和中英文 G2P 资源放在 common/。参考音频与对应文案分别为 reference.wav 和 reference.txt；当前素材来自 zh_vo_MAIN_YHX_2_7.wav/.lab。

当前包内置中文 RoBERTa ONNX 与 tokenizer。中文文本必须生成真实 BERT 特征；RoBERTa 不能加载时推理必须失败，不能静默退回零特征。英文继续使用英文 G2P 前端。

必要文件由 package_manager._REQUIRED_PACKAGE_FILES 与按 precision_profile 分类的文件表共同定义，至少包括推理入口、参考素材、依赖清单、角色模型、CN-HuBERT、说话人编码器、中文 RoBERTa 和中英文 G2P 资源。format_version 描述稳定的公开包结构；runtime_revision 描述同一结构内必须更新的模型或推理修订。当前最低运行时修订为 3，缺失该字段或小于 3 的旧包必须提示“安装最新语音包”。新增格式版本时不得静默改变版本 1 的含义。

2. 完整性与安全#

SHA256SUMS.txt 使用每行 64位十六进制哈希 + 空白 + 相对路径 的格式。所有必要文件都必须进入校验清单；仅 validation/ 下的离线冒烟输出允许在归档中省略。路径不得为绝对路径、盘符路径或包含 ..，RAR 不得加密。

桌宠使用 rarfile 读取 RAR5 多卷目录并检查路径，实际解压固定调用随程序发布的官方 lib/script/gsvmove/bin/UnRAR.exe。该文件必须同时满足固定大小和 SHA-256 校验：

大小：560848 字节
SHA-256：0D3715001790F0FD18D3E850F947B540530B2D2DEB9A2E6A9E84F2ED7B234235
许可：lib/script/gsvmove/bin/LICENSE-UnRAR.txt

安装流程不得从网络下载或替换解压器。普通版和绿色版都必须携带上述二进制与许可证。

3. 发布源与档位#

每档是一个 RAR5 solid 单文件，使用 64 MiB 字典，不再分卷。客户端优先从 ModelScope 下载，失败后完整切换到 Hugging Face，不能混合不同镜像的内容。两个仓库必须上传文件名、README、SHA256SUMS.txt 与 release-manifest.json 完全相同的发布物：

档位	文件	压缩包	解压后	实际精度
完全包	`Aemeath_ONNX_GSV_Complete_FP32.rar`	1,158,190,671 B	1,438,886,877 B	非 INT8 高质量链路；上游 RoBERTa 源权重为 FP16
中等包	`Aemeath_ONNX_GSV_Medium_FP16.rar`	1,096,305,481 B	1,211,004,205 B	FP16 外置权重，运行时恢复 FP32
节约包（强烈推荐）	`Aemeath_ONNX_GSV_Saver_INT8.rar`	677,423,752 B	853,957,055 B	RoBERTa QInt8、CN-HuBERT/T2S INT4、VITS/Speaker FP16

安装前预留所选 archive、解压目录和额外 512 MiB 暂存空间。下拉档位和进度条必须使用以上真实大小；不得继续展示 600 MB 或旧的分卷数量。内置 UnRAR 校验与单文件下载同时启动。

4. 安装与迁移#

控制面板在检测到旧 start_gsvmove.bat、语音包缺失或语音包损坏时，将“安装最新语音包”置于顶部。用户选择固定磁盘后，目标路径为：

<磁盘根>\AemeathDeskPet\voice\ONNX_aimisiV2

下载和安装使用独立进度条。RAR 解压期间第二条进度条使用动态状态，不递归扫描正在增长的模型目录，以免与解压器争用磁盘 I/O 并导致界面失去响应；解压完成后，第二条进度按完整 SHA-256 校验、轻量依赖检查、激活与旧运行时清理组成单调递增的总进度。校验阶段按实际读取字节推进，只有激活和清理完成后才到达 100%。安装器先在同一磁盘的临时目录下载单个 archive、审计归档路径、解压并执行完整 SHA-256 校验；必要的轻量 Python 组件安装完成后，才释放当前引擎并原子替换活动包。失败时保留原活动包并清理临时目录。

安装前只执行所选磁盘的容量检查和安装目录创建，不能为查找旧 GSVmove 而递归扫描桌面、下载目录或用户目录。下载应在容量检查通过后立即开始；新包成功激活后，只按已有路径记录解析和清理旧运行时，记录缺失或无效时保留旧目录。

磁盘下拉弹层必须使用桌宠粉青配色并注册到安装浮窗之上的窗口层级。开始安装后，内置 RAR 校验与下载连接分别报告状态；下载首批数据到达前使用动态进度，不能让网络等待持续显示为“准备 RAR 后端”。进行中的安装窗口提供“后台安装”：点击后立即隐藏窗口但不取消下载、解压或激活任务；从控制面板再次打开安装入口可恢复查看原进度。后台模式仅通过桌宠气泡提示转入后台、下载完成并进入解压校验、激活、完成以及失败或取消等关键节点，禁止按进度回调刷屏。应用退出时仍按正常清理流程取消活动安装。

成功状态写入 <用户根>/user/state/voice_package.json，同时将 gsv_auto_start 持久化为开启并立即预热新包。只有新包激活成功后才允许删除路径记录明确指向且通过安全校验的旧外部 GSVmove 目录、start_gsvmove.bat 和旧路径记录；仓库内 lib/script/gsvmove/ 是公开兼容门面，不属于清理目标。

控制面板对有效包和已检测到的损坏包显示“删除语音包”入口。用户确认后，服务必须在同一推理锁内释放当前 ONNX 引擎并完成后台删除，随后清理匹配的安装状态并立即切回安装提示。删除 API 只接受固定磁盘下 <磁盘根>\AemeathDeskPet\voice\ONNX_aimisiV2 的普通目录，拒绝任意状态路径和符号链接；不会删除语音缓存或仓库内兼容门面。删除中断形成的不完整目录仍应被识别为损坏包，允许再次删除或直接重新安装。

5. 推理契约#

GsvmoveService 保留既有事件和公开函数，但不再启动端口 9880 或请求 HTTP /tts。单个常驻 AimisiOnnx 引擎在原语音工作线程中处理请求，自动识别中文或英文，并输出 PCM 16-bit WAV 到用户缓存。

格式版本 2 采用 GPT-SoVITS API v2 的参数命名。参考音频固定为包内 reference.wav，不开放 ref_audio_path 和 aux_ref_audio_paths；prompt_text、prompt_lang 可以为固定参考音频提供动态文案与语言。

实际参与当前 v2Pro 推理的参数为：

text、text_lang：合成文本与 zh、en、auto 语言选择。桌宠聊天会保留中英文原文，并按内容携带对应语言提示；混合文本使用 auto。
prompt_text、prompt_lang：固定参考音频的提示文案与语言；省略时使用包内 reference.txt 和中文。
top_k、top_p、temperature、repetition_penalty、seed：直接进入 ONNX T2S 采样图。
speed_factor：范围 0.5 至 2.0，默认 1.0；在 VITS 内部调整语义时间轴，不对最终波形重采样，因此不会随语速整体升降调。动态长度严格复刻原生 speed == 1 分支和 floor(length / speed) + 1 规则，固定种子噪声在图内裁到同一长度。
text_split_method、fragment_interval：按 cut0 至 cut5 切分长文本并控制片段间停顿。
max_steps：ONNX 语义解码保护上限，范围 64 至 1200。

控制面板开放上述实际生效的 temperature、top_k、top_p、repetition_penalty、speed_factor、text_split_method、fragment_interval、seed 和 max_steps。面板值作为每次桌宠语音请求的默认值，事件请求显式提供同名参数时仍以请求值优先。

参考 HuBERT 提示语义复刻 9872/API 当前链路：在 16 kHz 参考音频尾部追加 32000 * 0.3 个零样本，再提取提示 token；说话人编码和 VITS 参考频谱仍使用未追加静音的参考音频。Genie 中文 G2P 对当前参考文案及回归句生成的标准化文本、音素 ID 与 word2ph 已与 9872 原生 chinese2 链路逐项核对一致。

请求层还接受 batch_size、batch_threshold、split_bucket、parallel_infer、streaming_mode、overlap_length、min_chunk_length、sample_steps、super_sampling 和 media_type。当前图固定 batch 1，桌宠需要完整 WAV 后再播放，所以批处理、并行和流式参数不改变执行策略；sample_steps 与 super_sampling 是 v3/v4 参数，对 v2Pro 不适用。新增调用方应区分“兼容接收”和“当前模型实际消费”，不得把不适用字段描述为已生效。

6. 发布验收#

更新语音包时至少验证：

py -3 -m unittest tests.test_voice_package_manager tests.test_onnx_voice_runtime tests.test_voice_package_installer_ui
py -3 scripts/package_release.py --dry-run --version VERIFY
py -3 scripts/package_green_release.py --dry-run --version VERIFY

普通版和绿色版都必须包含 UnRAR.exe 和 LICENSE-UnRAR.txt。发布仓库不得包含旧七分卷；上传后应分别从 ModelScope 与 Hugging Face 的公开 resolve 链接抽样下载，校验 archive SHA-256、执行完整包校验和一次中英文 CPU 推理。