【2026腾讯犀牛鸟】Qwen3-TTS的ncnn移植

[AI1379]

Qwen3-TTS 到 ncnn 的完整移植：从模型拆分到 C++ 端到端语音生成

摘要

本项目将 Qwen/Qwen3-TTS-12Hz-0.6B-Base 从 PyTorch 迁移到 ncnn，并用
C++ 实现完整的文本到语音推理路径。最终运行时覆盖 Qwen Tokenizer、Talker、
Code Predictor、Speaker Encoder、Speech Tokenizer Codec Encoder、Codec
Decoder、采样、KV cache、参考音频处理和 WAV 输出，不依赖运行时 Python 或
PyTorch。

项目的主要难点并不是把某一个 Transformer 转成 ncnn，而是正确复现三个神经
网络之间的动态生成协议：

1. Talker 根据文本、说话人条件和历史 codec token 预测每帧第一个码本；
2. Code Predictor 接收 Talker hidden state，自回归预测其余15个码本；
3. Codec Decoder 将16路离散 token 还原为24 kHz波形。

最终实现已在 Windows/MSVC 和 Linux/GCC 的 CPU 路径编译运行。短文本和148帧
长文本的 C++ codec ID 与官方 PyTorch 逐位一致；最终波形误差保持在
1e-4 量级。

模型结构拆解

Qwen3-TTS不是单一网络，而是三个子系统和一套生成协议。

1. Talker

Talker是28层Qwen3主干，hidden size为1024，16个query head、8个KV head，
head dim为128，SwiGLU中间维度为3072。它接收文本hidden、控制token、
speaker embedding和历史codec embedding，输出3072维第一个codec码本的
logits。

2. Code Predictor

Code Predictor是5层小型Transformer。每个音频帧中，Talker只决定第一个
码本，Code Predictor随后执行15次自回归步骤，生成剩余15个码本。完成一帧
后，16个token的embedding相加，成为Talker下一帧的codec输入。

3. Speech Tokenizer

Speech Tokenizer包含：

• 参考音频使用的Codec Encoder；
• 16路有效量化器；
• Transformer与卷积上采样组成的Codec Decoder。

24 kHz音频每个codec帧对应1920个采样点，因此帧率为12.5 Hz。

Codec Decoder的切分

最初尝试直接导出“整数codes到wav”的完整图，但ncnn在16路
unbind/embedding和整数输入路径上执行失败。最终在量化器后切分：

1. C++读取16组codebook和两组projection权重；
2. 对每帧执行codebook lookup；
3. 将第一路语义码本和其余15路声学码本分别投影并求和；
4. 把 [1, 512, T] 浮点hidden送入ncnn Codec body。

NumPy量化器复现与PyTorch的最大误差低于1e-4，从而把问题缩小为纯浮点
Transformer和卷积图。

单token SDPA问题与host attention

Talker和Code Predictor的decode阶段query length为1。独立测试发现ncnn SDPA
在该输入形状下与PyTorch不一致，无法通过简单参数调整恢复。

每层因此被拆成：

PreRoPE(ncnn)
  → RoPE + KV append + GQA attention(C++)
  → PostAttn(ncnn)

其中：

• PreRoPE输出Q/K/V和残差分支；
• C++执行half-rotate RoPE、按层维护KV cache，并完成GQA attention；
• PostAttn执行output projection、MLP和残差连接。

这种方式绕开了有问题的算子，同时仍由ncnn承担绝大多数矩阵计算。

mRoPE结论

配置中存在mrope_section=[24,20,20]和interleaved=true，初看需要实现视觉
模型式mRoPE。但检查官方get_rope_index后发现，TTS路径中三个位置维度始终
满足t == h == w。

因此mRoPE在当前模型中退化为标准一维half-rotate RoPE。直接使用
head_dim=128、rope_theta=1e6的一维实现与官方结果一致，避免了不必要的
复杂度。

文本前端与生成循环

C++ Tokenizer从Qwen Byte-Level BPE适配而来，支持：

• UTF-8和Unicode NFC；
• added tokens；
• 中英文、空白、emoji和Hangul；
• assistant prompt包装。

生成循环维护：

• 28层Talker KV cache；
• 每帧Talker第一个码本历史；
• Code Predictor每帧独立的15步生成状态；
• trailing_text_hidden到tts_pad的切换；
• 前两帧EOS屏蔽；
• min_frames、max_frames和codec EOS；
• repetition penalty、top-k、top-p、temperature和显式随机种子。

greedy模式用于严格数值对齐；sampling模式验证同seed复现和不同seed分叉。

参考音频前端

x-vector路径在C++中完成：

1. 读取PCM16/24/32或float32 RIFF/WAVE；
2. 多声道混合为单声道；
3. 使用soxr HQ重采样到24 kHz；
4. 计算128-bin log-mel；
5. 运行ncnn ECAPA-TDNN得到1024维speaker embedding；
6. 构造官方9-token streaming prefill。

完整ICL路径还会通过Speech Tokenizer Codec Encoder得到101×16参考codes，
并与参考文本一起构造官方prompt。

当前Speaker Encoder图固定使用8秒输入，Codec Encoder使用8.08秒输入；不足
时补零，超出时裁剪。这是参考前端的已知限制，不影响目标语音的任意长度输出。

从101帧到任意长度Codec

早期Codec图根据golden固定为101帧，即约8.08秒。101只是当时参考音频的
长度，不是模型架构限制。

官方chunked_decode每次处理300帧新内容，并在后续块携带25帧左上下文。
如果继续使用101帧图，每块只能容纳76帧新内容。实测这种高频分块在边界处
最大误差达到0.2586，不可接受。

最终将pnnx图固定为：

300帧主体 + 25帧左上下文 = 325帧

C++对任意输入长度执行相同的300+25调度。最后一个不足325帧的窗口重复尾部
token进行padding；由于网络是因果结构，只保留有效前缀。377帧跨块测试相对
PyTorch的最大误差为2.26e-4。

代价是短音频也要运行325帧图，CPU计算量较大。未来可以增加多个固定shape
图做长度分流，但单图325帧首先保证了官方分块语义和任意输出长度。

一致性验证方法

项目没有只比较“听起来像不像”，而是建立逐级golden：

• Tokenizer token ID；
• text embedding与prefill hidden；
• 每层Q/K/V、hidden和KV cache；
• Talker logits与第一个码本；
• Code Predictor 15路token；
• 完整帧序列；
• quantizer hidden；
• Codec输出浮点波形；
• 最终WAV长度、RMS和最大绝对误差。

关键结果：

测试	结果
32帧持续生成	512/512 codec ID一致
短x-vector	16帧，256/256 codec ID一致
短x-vector最终WAV	30720采样点，最大误差9.299e-5
长x-vector	148帧自然EOS，2368/2368 codec ID一致
长x-vector最终WAV	284160采样点，最大误差1.423e-4
101帧Codec	最大误差2.294e-4
377帧Codec	最大误差2.265e-4
完整ICL	参考codes与目标codes逐位一致，端到端测试通过

Windows本地具备全部golden时注册34项CTest，覆盖单元、CLI错误处理、子模型
数值、持续生成、greedy/sampling、x-vector、ICL和长序列Codec。

跨平台与依赖

运行时构建采用CMake和C++17，依赖：

• ncnn；
• vendored soxr；
• C/C++标准库。

Python、PyTorch、transformers、qwen-tts、ModelScope和pnnx只参与模型转换和
golden生成，不参与最终运行。

已验证：

• Windows 11、MSVC、ncnn预编译CPU包；
• WSL2 Arch Linux、GCC 15、ncnn静态CPU构建；
• GitHub Actions上的Windows/Ubuntu快速编译与CLI smoke测试。

已知限制

• 只验证0.6B Base、batch=1、Auto、streaming；
• 参考音频前端仍是固定8/8.08秒；
• Vulkan尚未验证；
• 325帧单图对短音频存在额外计算；
• 当前只直接读取WAV，MP3/FLAC等容器需外部解码；
• 生成后的ncnn运行时资源约4.01 GiB，不存放在Git仓库；
• 还未针对实时率、峰值内存和不同CPU做系统benchmark。

这些限制不改变本轮核心结论：Qwen3-TTS的文本、音色条件、双Transformer生成
和Codec解码已经能够在纯C++/ncnn CPU运行时中完成，并在已覆盖的短文本、
长文本和ICL样例上与官方PyTorch保持严格一致。

复现入口

• 构建与运行：README_CN.md
• 原始模型下载：model-download.md
• 完整模型转换：model-conversion.md
• Linux构建：linux-build.md
• 长序列Codec：long-sequence-codec.md
• 隔离部署测试：deployment-test.md
• 开发过程与风险记录：PLAN.md
• 仓库地址：AI1379/Qwen3-TTS-ncnn