如何用 MNN qwen3_tts_demo 运行 Qwen3-TTS 文本转语音？
【免费下载链接】MNNMNN: A blazing-fast, lightweight inference engine battle-tested by Alibaba, powering high-performance on-device LLMs and Edge AI.项目地址: https://gitcode.com/GitHub_Trending/mn/MNN
本文的任务是：用 MNN 自带的qwen3_tts_demo命令行工具，把一段文本合成为语音文件。qwen3_tts_demo是 MNN 针对 Qwen3-TTS 的端到端文本转语音（TTS）示例，基于 LLM 引擎的 Omni/Talker 路径实现（见 demo 源码）。跑通后你会得到一个 24 kHz 的 wav 文件，以及 prefill / decode / 音频处理耗时和 RTF 统计。
前置条件有两个：一是引擎编译时必须开启音频支持，二是需要准备 Qwen3-TTS 的 MNN 模型目录和一段参考音色音频。下面按顺序说明。
编译：开启 MNN_BUILD_LLM 和 MNN_BUILD_AUDIO
qwen3_tts_demo的可执行文件只在MNN_BUILD_AUDIO开启时才构建（engine/CMakeLists.txt 中qwen3_tts_demo的定义被if (MNN_BUILD_AUDIO)包住），而 TTS 路径又属于 LLM 功能，因此编译时两个选项都要打开：
mkdir build && cd build cmake .. -DMNN_BUILD_LLM=ON -DMNN_BUILD_AUDIO=ON make -j16-DMNN_BUILD_LLM=ON的说明见 docs/transformers/llm.md 的"第二步：引擎编译"；其中还提到需要图像/音频输入的 Omni 模型可再加-DMNN_BUILD_LLM_OMNI=ON，以及按平台追加-DMNN_AVX512=ON（x86）等选项。MNN_BUILD_AUDIO是根目录 CMakeLists 中的选项（默认 OFF），源码中对缺少LLM_SUPPORT_AUDIO宏的运行会直接报Qwen3-TTS ref_audio requires LLM_SUPPORT_AUDIO。
编译完成后，build目录下会生成qwen3_tts_demo。
准备模型目录与参考音频
模型侧需要准备 Qwen3-TTS 的 MNN 模型目录（下称model_dir）。demo 启动时会自动读取<model_dir>/config.json（源码中为Llm::createLLM(joinPath(modelDir, "config.json"))），所以该目录内必须包含导出的config.json及相应模型文件，导出流程可参考 docs/transformers/llm.md 中llmexport.py的用法。
音色侧必须提供一段参考音频 wav。--ref_audio <wav>是必填项：它提供 speaker-embedding-only 音色克隆所需的参考音色，加载时会用 soxr-like 高质量重采样器重采样到 24 kHz。文档明确说明不带--ref_audio的零 speaker embedding 路径不受支持，因为该路径不能产生可靠的语音。
文档给出的评测参考音频下载地址为：
https://modelscope.cn/datasets/huangzhengxiang/qwen3-tts-ref/resolve/master/qwen3_tts_ref.wav建议下载到仓库内的transformers/llm/resource/audio/qwen3_tts_ref.wav，运行 demo 时用该路径作为--ref_audio的值。
运行命令与参数
qwen3_tts_demo的参数格式为：
./qwen3_tts_demo model_dir --text <text> [max_frames] [dump_dir] [language] --ref_audio <wav> [--normalize [target_peak]]一个按此格式拼出的完整示例（model_dir换成你的 Qwen3-TTS MNN 模型目录）：
./qwen3_tts_demo /path/to/qwen3_tts_model --text "你好，我是 MNN。" 512 /tmp/tts_out chinese \ --ref_audio transformers/llm/resource/audio/qwen3_tts_ref.wav --normalize各参数含义（依据 transformers/README.md 与 docs/transformers/llm.md）：
model_dir：Qwen3-TTS MNN 模型目录，必须包含config.json；--text <text>：要合成的文本；max_frames：最多生成的 codec 帧数，默认 128，每帧约 80 ms。长文本要调大，否则会被截断；遇到 EOS 会提前停止，所以它只是一个上限；dump_dir：调试输出目录，指定后保存 wav 和 bin 文件（demo 会自动mkdir该目录，失败会报错退出）；language：语言，默认auto，支持auto/chinese/english/german/italian/portuguese/spanish/japanese/korean/french/russian；--ref_audio <wav>：必填，参考音色音频；--normalize [target_peak]：可选，只对保存的 wav 做峰值归一化，不填值时目标峰值为 1，取值必须在 (0, 1] 区间，否则报错normalize target_peak must be in (0, 1]。
三个位置参数max_frames、dump_dir、language按顺序出现在--text <text>之后，--ref_audio、--normalize等选项放在其后。出现拼写不符的选项会报unknown option并退出。
结果验证
运行成功时，demo 依次输出（以下格式来自 qwen3_tts_demo.cpp 中的实际打印语句，frames等数值随输入而变）：
- 波形摘要：
waveform shape=[1,<采样点数>] size=<采样点数>及前 16 个采样值； - 指定了
--normalize时额外输出waveform_normalized摘要，以及normalize target_peak=... original_peak=... scale=...； - 指定了
dump_dir时输出saved wav: <dump_dir>/qwen3_tts_text.wav； Qwen3-TTS text C++ chain finished. frames=<生成帧数>；- 耗时统计：
prefill time、decode time、audio process time、waveform duration和audio RTF。
dump_dir中会生成这些文件（见 demo 源码）：
| 文件 | 内容 |
|---|---|
qwen3_tts_text.wav | 最终语音，24000 Hz 保存（应用了--normalize时为归一化后的波形） |
mnn_text_waveform.bin | 原始 float 波形 |
mnn_text_waveform_normalized.bin | 仅在指定--normalize时保存 |
mnn_text_codes.bin | 生成的 codec token 序列（int 数组） |
失败的判断依据是 demo 会打印明确的错误信息并返回非零退出码：Qwen3-TTS load failed（模型加载失败，常见于model_dir下缺少config.json）、Qwen3-TTS generation failed、Qwen3-TTS generated empty waveform（加载成功但没有产生波形），以及--ref_audio is required for Qwen3-TTS speaker-embedding-only voice cloning（漏写必填的参考音频参数）。
限制与说明
- 参考音色必须提供，音色克隆只走 speaker-embedding 路径；参考音频会被重采样到 24 kHz，与输出采样率一致；
max_frames设得过小会截断语音，长句需要调大，但生成遇到 EOS 会自然提前结束；--normalize只影响落盘的 wav，不改变打印的波形摘要中waveform那一项（它始终打印原始波形）；- 引擎侧未定义
LLM_SUPPORT_AUDIO（即编译时未开MNN_BUILD_AUDIO）时，--ref_audio路径不可用，运行会报Qwen3-TTS ref_audio requires LLM_SUPPORT_AUDIO。
如果 wav 内容与预期不符，可结合dump_dir中的mnn_text_codes.bin（codec token）和mnn_text_waveform.bin（原始波形）做进一步比对。相关参数与命令的完整说明见 docs/transformers/llm.md 和 transformers/README.md。
【免费下载链接】MNNMNN: A blazing-fast, lightweight inference engine battle-tested by Alibaba, powering high-performance on-device LLMs and Edge AI.项目地址: https://gitcode.com/GitHub_Trending/mn/MNN
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
：中文医疗领域大模型本地部署与临床适配指南)
