QwenLM/Qwen3-TTS ncnn 移植

[crafcat7]

Qwen/Qwen3-TTS-12Hz-0.6B-Base 在 ncnn 的适配：子图拆分、C++ runtime、PNNX 导出、音频一致性验证

作者: Lune
日期: 2026 年 7 月 3 日
版本: v0.1
适配范围: Qwen3-TTS-12Hz-0.6B-Base + Qwen3-TTS-Tokenizer-12Hz
作品链接：https://github.com/crafcat7/Qwen3-TTS-ncnn

---

摘要

本报告记录了将 Qwen/Qwen3-TTS 的 12Hz 0.6B Base voice clone 推理链路适配到 ncnn 的实现过程。当前完成的是一个可复现的第一阶段闭环：使用 PNNX 将 PyTorch 模型拆分导出为多组 ncnn param/bin，使用 C++ runtime 负责 tokenizer、参考音频前处理、profile 选择、Mimi split-RVQ 量化、greedy 生成调度和 wav 输出，并在相同输入、fp32、greedy、确定性配置下验证 ncnn 最终音频与 PyTorch 原版一致。

当前稳定验证用例为 96000-sample reference audio、max_new_tokens=59、top_k=1、top_p=1、temperature=1。该用例中 ncnn 自动选择 speaker_encoder_375 bucket，生成 code token 与 PyTorch 完全一致，最终 wav 可听且 waveform diff 通过阈值检查：

speaker_encoder_node = speaker_encoder_375
speaker_mel_frame_count = 375
generated code parity = 928 / 928
reference code parity = 800 / 800
wav length = 111360 / 111360
waveform max_abs ~= 1.69e-6
compare_pass = true
audio_sanity = pass for both PyTorch and ncnn

这次适配的方案是按静态窗口拆成可验证子图，把 Python 控制流、prompt 拼装、RVQ 最近邻搜索、profile/bucket 选择和音频 IO 下沉到 C++ runtime。这样既保留 ncnn 作为主要张量计算后端，也能在 PNNX 尚不完全覆盖动态控制流和复杂容器语义时得到可验证的端到端结果。

---

1. 项目背景

1.1 模型与任务

本次实现目标模型是：

• Qwen3-TTS-12Hz-0.6B-Base
• Qwen3-TTS-Tokenizer-12Hz

目标任务是 deterministic voice clone：

text + ref_audio.wav + ref_text
    -> Qwen3-TTS generation
    -> 24 kHz mono wav

1.2 设计目标

本次设计目标如下：

目标	当前状态
PyTorch 到 ncnn 导出	已完成 0.6B Base 所需 split graph 导出
C++ ncnn runtime	已完成 voice clone raw input runtime
参考音频输入	已完成 wav 读取、log-mel、speaker bucket 选择、tokenizer latent
最终 wav 输出	已完成 24 kHz mono wav 写出
PyTorch parity	已完成 stable 96k audible E2E parity

---

2. 总体架构

2.1 子图拆分策略

Qwen3-TTS 的 PyTorch 链路包含大量 Python 控制流、容器结构、动态 mask、RoPE/mRoPE 处理、codec 量化与自回归调度。为降低 PNNX trace 难度并让每个子模块可独立验证，本工程采用 split graph：

模块	形式	说明
speaker encoder	ncnn graph, 多 bucket	从参考音频 log-mel 提取 speaker embedding
tokenizer encoder latent	ncnn graph	Mimi encoder 前半段，输出 latent
tokenizer encoder RVQ	C++ native sidecar	使用导出的 codebook 进行 split-RVQ 最近邻量化
talker decoder layer 00..27	ncnn graph	固定窗口 transformer layer
talker final norm / text projection / codec head	ncnn graph	主 codebook greedy 生成
code predictor layer 00..04	ncnn graph	预测剩余 15 个 codebook
code predictor heads	ncnn graph	每个 subtalker codebook 一个 head
tokenizer decoder codebook lookup	C++ native sidecar	避开不稳定 Embed 前端
tokenizer decoder split chain	ncnn graph	preconv, input_proj, 8 decoder layers, final_norm, output_proj, vocoder_tail
wav IO / prompt / sampling	C++ native runtime	输入解析、确定性 greedy、输出 wav

flowchart TD
  A["Qwen3-TTS request"] --> B["qwen3_tts_ncnn runtime"]
  B --> C["Load model.json + profile"]
  C --> D["Load tokenizer vocab/merges"]
  B --> E["Read ref_audio.wav"]
  E --> F["Compute log-mel + speaker_encoder selector"]
  F --> G["speaker_embedding"]
  B --> H["Read text/ref_text"]
  H --> I["BPE encode + prompt assemble"]
  B --> J["tokenizer_encoder_latent.ncnn"]
  J --> K["C++ split-RVQ"]
  K --> L["ref_code"]
  I --> M["Load talker/text/code embeddings"]
  M --> N["Auto-regressive generation loop"]
  G --> N
  L --> N
  N --> O["talker_decoder_layer_00..27"]
  O --> P["talker_codec_head"]
  P --> Q["code_predictor_layer_00..04"]
  Q --> R["code_predictor_head_00..14"]
  R --> S["codebook lookup sidecar"]
  S --> T["tokenizer_decoder split chain"]
  T --> U["Wav output writer"]
  U --> V["qwen3_tts report + wav"]
  V --> W["compare / benchmark"]

Loading

当前模型包入口为 model.json。它记录 profile、capabilities、各 ncnn 子图路径、tokenizer 文件、embedding/RVQ sidecar、窗口大小、采样率和 profile coverage。

2.2 运行时调用流

Qwen3TTS::generate(request, config)
    |
    |-- load model.json and select profile
    |-- load tokenizer vocab/merges
    |-- read ref_audio wav
    |
    |-- speaker path
    |     |-- wav -> log-mel
    |     |-- select speaker_encoder_<mel_frames> when available
    |     `-- ncnn speaker encoder -> speaker_embedding
    |
    |-- reference codec path
    |     |-- wav -> padded tokenizer encoder input
    |     |-- ncnn tokenizer_encoder_latent
    |     `-- C++ Mimi split-RVQ -> ref_code
    |
    |-- prompt path
    |     |-- BPE encode text/ref_text
    |     |-- load text/codec/code-predictor embeddings
    |     `-- assemble prompt hidden states
    |
    |-- generation loop
    |     |-- talker_decoder_layer_00..27
    |     |-- talker_codec_head -> main codebook
    |     |-- code_predictor_layer_00..04
    |     `-- code_predictor_head_00..14 -> remaining codebooks
    |
    |-- decode
    |     |-- C++ codebook lookup
    |     |-- tokenizer_decoder split ncnn chain
    |     `-- vocoder_tail -> waveform
    |
    `-- write 24 kHz mono wav and report json

---

3. 为什么不是单个完整 ncnn graph

3.1 PyTorch 全图 trace 的问题

直接导出完整 Qwen3-TTS 推理链路会遇到几个结构性问题：

1. Transformers causal mask 和部分动态路径会进入 functorch/vmap 或复杂 Python 容器语义，PNNX 难以稳定 lower。
2. talker 自回归生成包含跨 step 状态、prompt/trailing hidden 拼接、采样策略和停止条件，不适合作为静态单图。
3. tokenizer decoder/full tokenizer encoder 中存在 dict/list/control-flow 边界，完整路径难以一次性转换。
4. Mimi RVQ 最近邻量化依赖 cdist/argmin 类语义。虽然后续 PNNX/ncnn 已补充相关能力方向，当前 release runtime 仍保留经过验证的 C++ RVQ。

因此当前工程选择“PNNX + ncnn 子图 + C++ runtime”的工程化拆分。这个方案降低了每个 graph 的输入输出复杂度，也让 parity 可以逐层、逐子链路、最终音频逐级定位。

3.2 当前保留的 C++ native 部分

部分	原因
BPE tokenizer	与原版 prompt 构造强相关，C++ 可控且易验证
wav 读取/写出	runtime 基础能力
log-mel speaker 前处理	避免把音频 IO 和特征提取混进 PNNX 图
Mimi split-RVQ	当前已验证的最近邻量化路径
codebook lookup	避开 tokenizer decoder front Embed 不稳定路径
generation loop	自回归调度天然属于 runtime
profile/bucket selection	根据输入长度选择静态窗口 graph
audio sanity/parity report	测试和发布质量门禁

---

4. 关键难点与解决方案

4.1 难点 1：静态窗口与任意输入之间的边界

Qwen3-TTS 的自然输入长度是动态的，但 ncnn graph 更适合固定 shape。最初如果只导出单一窗口，短输入、长 reference、长输出都会混在一起失败，错误也不容易定位。

解决方案是引入 profile：

profile = v38_raw_general
tokenizer_encoder_sample_count = 193920
speaker_encoder_frames = 757 example metadata
talker_window = 117
code_predictor_window = 16
tokenizer_decoder_window = 128
sample_rate = 24000

runtime 根据 reference sample count、speaker mel frame count 和生成预算进行校验或选择。超出 profile coverage 的输入会被明确拒绝，而不是静默生成错误音频。

4.2 难点 2：Mimi tokenizer encoder 的完整 graph 与 RVQ

tokenizer encoder 的 latent 前半段可以稳定导出为 ncnn graph，但完整 encoder 包含 RVQ 最近邻量化和 codebook 选择。为了先完成 raw E2E parity，本工程把路径拆成：

tokenizer_encoder_latent.ncnn
    -> C++ split-RVQ with tokenizer_encoder_quantizer.bin/json
    -> ref_code

这样做的好处是：

• ncnn 仍负责重计算量的 latent 前向。
• RVQ 的距离计算、argmin 和 codebook residual update 在 C++ 中完全可控。
• 可以直接比较 ref_code，当前 stable 用例为 800 / 800 完全一致。

后续如果 full tokenizer encoder graph 重新导出并通过 native-op scan 与 raw E2E parity，可以再把 C++ RVQ 替换掉。

4.3 难点 3：talker 与 code predictor 的生成调度

Qwen3-TTS 并不是只生成单 token。每一帧需要主 codebook token，并由 code predictor 生成剩余 15 个 codebook。为了让 ncnn 与 PyTorch 完全一致，runtime 必须复刻：

• prompt hidden state 组装
• speaker embedding 注入
• reference codec ids 注入
• talker greedy argmax
• code predictor 的 no-cache prefix 调度
• 16 个 quantizer 的 codebook 排列
• tokenizer decoder 输入布局

工程中为此加入了多级 replay 验证，包括 talker layer、talker stack、code predictor、prompt-level generation replay 和最终 wav compare。最终 stable 96k 用例达到 928 / 928 generated code token 完全一致。

5. 代码与产物结构

Qwen3-TTS-ncnn/
  CMakeLists.txt
  cmake/
    Dependencies.cmake
  src/
    qwen3_tts_runtime.cpp
    qwen3_tts_runtime.h
    audio_wav.cpp
    audio_wav.h
    utils/tokenizer/
  examples/
    qwen3_tts/
      qwen3_tts_main.cpp
      ref.wav
    llm_ncnn_run/
      tts_only_main.cpp
      qwen3_tts_runner.cpp
      options.cpp
  export/
    qwen3_tts_export.py
  tools/qwen3_tts/
    add_speaker_bucket.py
    validate_profile_package.py
    inspect_capabilities.py
    benchmark_ncnn_runtime.py
  tests/parity/
    qwen3_tts_generation_trace.py
    qwen3_tts_compare.py
    qwen3_tts_raw_parity_suite.py
    qwen3_tts_wav_sanity.py
  scripts/
    run_fresh_96k_parity.ps1
  docs/qwen3_tts/

---

6. 一键复现流程

在 Windows PowerShell 中：

cd C:\Users\Lune\code\AI\Qwen3-TTS-ncnn

$env:NCNN_DIR = "C:\Users\Lune\code\AI\ncnn"
$env:PYTHON   = "C:\Users\Lune\environment\miniconda3\envs\ai-llm\python.exe"
$env:PNNX     = "C:\Users\Lune\code\AI\ncnn\build-pnnx-rebuild-vs\src\Release\pnnx.exe"

.\scripts\run_fresh_96k_parity.ps1

脚本会执行：

1. CMake CPU-only 构建。
2. 导出基础 v38_raw_general 模型包。
3. 单独导出并合并 speaker_encoder_375。
4. 校验模型包 profile 和 native op。
5. 生成 96000-sample reference wav。
6. 运行 PyTorch deterministic baseline。
7. 运行 ncnn runtime 生成 wav。
8. 比较 token、waveform、audio sanity。

成功时应看到：

speaker_encoder_node = speaker_encoder_375
speaker_mel_frame_count = 375
code_tokens = 928 / 928
compare_pass = True

---

7. 验证结果

flowchart LR
  A["PyTorch baseline trace\n(seed fixed, greedy)"] --> B["qwen3_tts_generation_trace/*.npz"]
  B --> C["qwen3_tts_ncnn run (same input)"]
  C --> D["ncnn_report.json + ncnn.wav"]
  C --> E["model.json + profile metadata"]
  D --> F["qwen3_tts_compare.py"]
  B --> F
  E --> F
  D --> G["qwen3_tts_wav_sanity.py"]
  A --> G
  F --> H["token parity + waveform"]
  G --> I["audio sanity"]
  H --> J{"all gates pass"}
  I --> J
  J --> K["stable parity pass"]
  J --> L["expected-fail sentinels / capability block"]

Loading

7.1 最终 stable 96k raw E2E parity

项目	结果
模式	deterministic voice clone
reference length	96000 samples
speaker mel frames	375
active speaker graph	speaker_encoder_375
max new tokens	59
generated code parity	928 / 928
reference code parity	800 / 800
wav length	111360 / 111360
waveform max abs	~1.69e-6
waveform thresholds	max_abs/MAE/RMSE <= 5e-4
PyTorch audible sanity	pass
ncnn audible sanity	pass
final compare	pass

9. 结论

本次 Qwen3-TTS-ncnn 适配已经完成 0.6B Base deterministic voice clone 的核心闭环：PNNX split export、ncnn 子图加载、C++ raw input runtime、参考音频处理、生成调度、wav 输出和 PyTorch raw E2E parity。

当前方案不是“完整 PyTorch 全图一键转 ncnn”，而是更适合这个模型复杂度的工程化落地方式：把张量密集部分交给 ncnn，把动态控制流和音频/codec glue 放在 C++ runtime。

参考项目

• QwenLM/Qwen3-TTS
• futz12/ncnn_llm
• Tencent/ncnn