Qwen3-TTS 0.6B CustomVoice 的 pnnx/ncnn 移植与 macOS/Linux 严格一致性验证

[SuLea-IT]

Qwen3-TTS 0.6B CustomVoice 的 pnnx/ncnn 移植与 macOS/Linux 严格一致性验证

对应任务：Tencent/ncnn#6791
公开仓库：https://github.com/SuLea-IT/Qwen3-TTS-ncnn
验证实现提交：a323153c991d517fbd919640d700eef453b1066b

1. 完成范围

本项目将官方 Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice 转换为 ncnn
模型，并在 C++ 中完成以下离线路径：

UTF-8 text
  -> Qwen byte-level BPE / CustomVoice prompt
  -> Talker prefill + incremental KV decode
  -> official logits processors + greedy + EOS
  -> 15-stage Code Predictor
  -> 16-code frame sequence at 12 Hz
  -> RVQ / speech decoder
  -> float waveform / PCM16 WAV at 24 kHz

最终运行程序不依赖 Python、PyTorch、Transformers、pnnx、ONNX Runtime
或 libtorch。验收范围固定为 0.6B CustomVoice、batch 1、offline、greedy、
CPU FP32；采样、流式、1.7B、Base/VoiceDesign、量化与 Vulkan 属于后续矩阵。

2. 固定版本

组件	固定版本
Qwen3-TTS 源码	022e286b98fbec7e1e916cb940cdf532cd9f488e
官方模型	85e237c12c027371202489a0ec509ded67b5e4b5
ncnn	13b6d5318c73be53bb386fa51e8067615d0eb7c1
pnnx	package 20260526，实际 executable SHA-256 40eba51b11f29a12b847d1cfa6abceb0fec60f1b7afeef37d8481a0ace865030
Python oracle	Python 3.12.13 / torch 2.11.0 / transformers 4.57.3
构建工具	CMake 4.0.3 / Ninja 1.12.1

官方 checkpoint 的 9 个文件由 checkpoint.json 逐项验证；最终 CPU
转换包由 conversion-assets-cpu.json 锁定 80 个文件，manifest SHA-256 为
cbbb3959a7bb79735ea7f546d03e502ae8bd1e16824d020ace0bdbf3b58eedfd。

3. 关键问题与修复

3.1 不能用 full recompute 代替官方 KV 路径

早期 25 帧参考每帧重算完整 prefix，并在第 6 帧出现 greedy 分支变化。
这不能证明增量 KV cache 的正确性。本项目直接调用固定官方 wrapper 的
DynamicCache 生成路径，并 hook Talker 与 Code Predictor 的 logits、K/V、
RoPE、mask、hidden 和 codes。

官方生成 N 个完整 codec frame 实际需要 N+1 次 Talker token 选择：

• step 0 只选择首个主码；
• step k>0 消费上一主码并完成一行 16-code frame；
• boundary step N 完成最后一帧，同时从 logits 选择 lookahead/EOS。

因此自然 EOS 运行的 54 帧对应 Talker step 0..54，而不是 54 次 forward。
本项目把这个映射写成机器断言，避免 off-by-one 或把 EOS 错当成一行 codes。

3.2 C++ 对齐官方 logits processor

主码本不再直接裸 argmax，而是依次实现并测试：

• repetition penalty 1.05，正/负 logits 与 Transformers 算法一致；
• suppress token 2048..3071，但恢复 EOS 2150；
• min_new_tokens=2 前禁止 EOS；
• NaN fail-closed 与 torch.argmax 的最低 index tie 行为；
• EOS 与 max-frame 边界分别记录。

3.3 干净 pnnx 转换必须形成闭包

转换器从空 output/work 目录开始，验证 checkpoint，记录 pnnx wrapper 与
实际 executable hash、完整 argv、Python/平台和所有转换脚本 hash；每次图
重写要求精确命中计数，零命中、少命中、重复 patch 都失败；输出不得含
残余 pnnx.*/Tensor.* 层或 symlink。

两个独立空目录的 CPU 转换 A/B 最终 80/80 文件逐字节一致。随后使用 clean-B
而不是继承下载包重新跑 25 帧与自然 EOS 54 帧 parity，关闭了“manifest 与
运行模型不是同一产物”的证据断点。

3.4 float 到 PCM16 的最后一 LSB

官方 soundfile/libsndfile 的 float→PCM16 行为不是简单四舍五入。本项目改为
clip 到 [-1,1]、乘 32768、向负无穷取整，NaN 输出静音，并增加边界单测。
在修正且使用官方 soundfile fixture 后，两帧 3,840 个 PCM 样本可逐字节一致。

3.5 低内存 Linux 的模型生命周期

FP32 模型很大。运行时采用固定 ncnn revision 已有的
Option::use_mapped_model_loading，prompt 构建后释放 frontend，生成完整
整数 codes 后释放 Talker/Code Predictor 和 cache，再进入固定 325 帧 speech
decoder，避免所有大网络同时常驻。

在只有约 3.6 GiB RAM、原 1.9 GiB swap 已满的 Ubuntu 主机上，最终验证使用：

• detached nohup + setsid，不依赖 SSH 会话；
• CTest -j1、模型与 BLAS 单线程；
• 临时 8 GiB、priority 100 swap；
• EXIT/INT/TERM trap 强制 swapoff 与删除；
• GNU time -v 记录资源。

最终 12 项 CTest 用时 641.83 秒，真实模型项 618.04 秒，最大 RSS 记录
7,433,148 KiB；结束状态为 exit_code=0、swap_cleanup_ok=true，未修改
fstab，也未停止服务器其他服务。

3.6 fail-closed 稳健性

新增门禁包括：

• frames/threads 使用完整十进制严格解析，拒绝 1x、0、负数和溢出；
• 显式空文本、畸形 JSON、非 object 根、缺少 frontend 时禁止静默回退；
• codec/hidden 乘法溢出、缓冲长度与每个 code ID 在访问 embedding 或
  memcpy 前验证；
• 资产缺失、截断、同大小 hash 损坏、symlink、重复 path、非法 hash 均失败；
• decoder 调度覆盖 context 25 下 current 299/300 可用、301 拒绝。

4. 严格一致性结果

固定输入：

text     Hello, welcome to Qwen text to speech.
language English
speaker  Ryan
mode     greedy, CPU FP32, one thread

验收项	clean CPU ncnn 结果
2 帧	32/32 codes exact；3,840 个 PCM 样本与官方 fixture 逐字节一致
25 帧	400/400 codes exact；float max abs 1.73e-6；SNR 114.9 dB；PCM max 1 LSB
max_frames=100	54 帧自然 EOS；864/864 codes exact；float max abs 1.71e-6；SNR 114.75 dB；PCM max 1 LSB
oracle 重复性	BPE、codes、hidden、float waveform、trace bitwise exact
前缀一致性	25 帧是 54 帧运行的 exact prefix，含 Talker boundary forward

自然终止证据还验证：Code Predictor 恰好 54*15 次；最后 processed
lookahead 为 EOS 2150；内部最大 token 数 101 尚未达到，因此不是长度截断。

5. 双平台 CMake 结果

平台	CTest	安装程序	动态依赖
macOS arm64	hardened 12/12；最新复跑 64.51 s	SHA-256 d633b2c55ae7493521e9748a20b20748cb4d1680d654aec63d4c555ee73b4397	仅系统 libc++ / libSystem，无 RPATH
Ubuntu 24.04 x86_64	hardened 12/12，641.83 s	SHA-256 c848cec24fc544c62476b9221c0822e9801b7d354bc793e0ee3dcc5567bce2b5	仅 libstdc++/libm/libgcc_s/libc 与系统 loader，无 RPATH/RUNPATH

两边的安装程序与各自实际通过 CTest 的 build-tree 程序逐字节相同。Linux
安装程序还独立跑了一次真实两帧模型：10:20.98 退出 0，32/32 codes
和 3,840 个 PCM 样本全部与官方 fixture 逐字节一致；并在 /tmp 下运行
--help，排除了工作目录依赖。

发布前又从完整 Git bundle 克隆到全新目录，在无网络、固定 ncnn/json
源码下完成 296/296 编译步骤和 8/8 host CTest。该审计先暴露出
编译参数检查器将 ncnn 按单个源文件设置的 ARM dispatch ISA 参数误报为
全局污染；修复后豁免必须同时匹配规范化 ncnn 根目录、架构目录与专用文件名，
项目源、普通 ncnn 源、架构不匹配和伪造相似路径仍会失败。修复后 macOS
12/12、Ubuntu 相关 9/9 复跑全过。全新安装程序与 build-tree 程序字节相同，
SHA-256 为 cacc9e50d2e741da43bf8d7b4498ab481590035e4937c67a832c04c518e1ca94，
仅依赖系统 libc++/libSystem，无 LC_RPATH。

6. 复现入口

转换与完整命令见
models/qwen3-tts/README.md。最小构建形式：

export NCNN_SOURCE_DIR=/path/to/pinned-ncnn
export NLOHMANN_JSON_SOURCE_DIR=/path/to/json-3.12.0
export QWEN3_TTS_MODEL_DIR=/path/to/verified-qwen3-tts-ncnn

cmake --preset macos-arm64-parity       # 或 linux-x86_64-parity
cmake --build --preset <matching-preset>
ctest --preset <matching-preset> --output-on-failure --no-tests=error -j1
cmake --install build/<matching-preset> --prefix dist/<matching-preset>

Linux host-only ASan/UBSan 使用 linux-x86_64-sanitizers preset：Debug sanitizer
构建完成 222 步，8/8 host/negative CTest 全过，无 sanitizer 报告。低内存模型
测试使用 tools/run_linux_low_memory_ctest.sh。

7. 开源复用与边界

工程基线来自 March-77/ncnn_llm@f46ec001...，并保留 nihui、
LudovicoYIN 与 mingshi2333 相关实现的 Apache-2.0 署名。本轮直接使用的
上游运行时 API 是固定 ncnn 的 mapped model loading；相关 PR/Discussion 只
作为调研线索，不能替代本地可复查证据。完整来源和许可证见
THIRD_PARTY.md 与
OPEN_SOURCE_RESEARCH.md。

8. 已知边界

本次没有声称 sampling RNG、真正流式输出、1.7B、Base voice clone、
VoiceDesign、INT8/FP16/Vulkan parity。299/300/301 当前是调度与缓冲边界门禁；
固定 325 帧 decoder 已被真实两帧 smoke 运行，但尚未发布官方 300 帧 waveform
fixture。这些属于后续扩展，不影响 #6791 核心离线 CustomVoice 路径的验收。

[SuLea-IT]

最终发布补充（2026-07-17）

• 最终提交：198fe759dad0ddbe7a0ff30c89f7fc87e63fc16f
• 固定标签：v0.1.1-qwen3-tts-6791
• 最终 GitHub Actions：run 29575893427

该运行的 Ubuntu、macOS、Windows 三个 CMake job 均为 completed / success。首轮公开 CI 暴露的是严格编译参数审计器对 ncnn 构建目录中生成的 x86 dispatch 源文件产生误报；最终修复只允许规范化 ncnn 源码根或构建根下、文件名明确为 ISA 专用 dispatch 的源文件使用对应 per-source ISA 参数，项目源码、普通 ncnn 源码及一般生成源码仍保持 fail-closed。

本修复不改变 Qwen3-TTS 图、权重、C++ 推理路径或已报告的 parity 结果。最终机器门禁为 PASS，对应源码快照包含 145 个公开文件。