Ming-3.0-Audio-Tiny-GGUF 开发者指南：audiocpp_cli 参数全解、request-option 与高级用法

Ming-3.0-Audio-Tiny-GGUF 是「明（Ming）3.0 音频微型模型」的 GGUF 权重仓库，配合 audiocpp_cli 命令行即可在本地离线完成语音识别（ASR）、文字转语音（TTS）、声音克隆与语音对话。本文全解 audiocpp_cli 常用参数、request-option 选项与低显存高级用法，帮你快速上手。

一、Ming-3.0-Audio-Tiny-GGUF 是什么？🎙️

一个 GGUF 文件里装下了整套推理组件：音频编码器、KDA/MLA MoE Thinker、Talker、音频 VAE、CAMPPlus 说话人编码器、分词器与配置（详见 README.md）。它支持：

• 离线转写（ASR）与音频理解
• 命名音色 TTS（如 US_James）
• 声音克隆（提供一段参考音频即可）
• 语音对话（s2s：音频进、语音出）

语音输出为 单声道 44.1 kHz，无需联网、无需 Python 环境。

三种量化精度怎么选？

文件	精度	适用场景
ming-3.0-audio-tiny-bf16.gguf	原始 BF16（专家路由与 CAMPPlus 为 F32）	显存充足、追求最高保真
ming-3.0-audio-tiny-q8_0.gguf	Thinker 专家库 Q8_0，其余保持源精度	精度与体积折中
ming-3.0-audio-tiny-q4_k.gguf	Thinker 专家库 Q4_K + Q8_0 文本输出头	显存紧张、以转写为主

💡 小贴士：量化只压缩了 Thinker 专家库，音频编码器、Talker、VAE 与说话人编码器原样保留，所以纯 TTS 场景显存不会因量化而下降；以 ASR 为主的负载选 Q4_K 最划算。

二、获取模型权重

git clone https://gitcode.com/hf_mirrors/audio-cpp/Ming-3.0-Audio-Tiny-GGUF

克隆后按需取用上述三个 .gguf 文件之一即可，仓库采用 MIT 协议（见 LICENSE）。

三、audiocpp_cli 常用参数速查表

参数	作用
--family ming3_audio	指定模型家族（固定写法）
--task asr / tts / clon / s2s	选择任务：转写 / 合成 / 克隆 / 语音对话
--backend cuda	推理后端，GPU 用 cuda，也可用 CPU
--model <文件.gguf>	模型路径
--audio <wav>	输入音频（asr、s2s 使用）
--text "..."	待合成文本（tts、clon 使用）
--voice-ref <wav>	克隆用的参考音频
--request-option key=value	每次请求的选项，可多次出现
--session-option key=value	会话级选项（如磁盘专家模式）
--out <wav>	输出音频路径
--log	打印运行日志，排查问题必开

四、3 条示例命令：ASR、TTS、声音克隆

以下命令来自 README.md，可直接替换文件路径运行：

1️⃣ 语音转文字（ASR）

audiocpp_cli --family ming3_audio --task asr --backend cuda \
  --model ming-3.0-audio-tiny-bf16.gguf --audio recording.wav --log

2️⃣ 命名音色 TTS（无需参考音频）

audiocpp_cli --family ming3_audio --task tts --backend cuda \
  --model ming-3.0-audio-tiny-bf16.gguf \
  --text "The sun warms the earth, and a soft breeze moves through the garden." \
  --request-option voice_id=US_James --request-option language=en \
  --out speech.wav --log

3️⃣ 声音克隆（提供参考音频 + 文本）

audiocpp_cli --family ming3_audio --task clon --backend cuda \
  --model ming-3.0-audio-tiny-bf16.gguf --voice-ref reference.wav \
  --text "Please leave the lamp beside the window." \
  --request-option language=en --out clone.wav --log

参考音频决定说话人身份；目标语言一致的参考音频发音更稳，例如合成中文时优先用中文参考样本。

五、request-option 选项详解：voice_id、language 与 reference_text

--request-option 以 key=value 形式出现，可叠加多个，是控制合成行为的核心：

选项	说明
voice_id=US_James	指定内置命名音色（免参考音频的 TTS）
language=en（或 zh 等）	声明文本语言，影响发音规则
reference_text=<文本>	提供参考音频的转写文本，连同音频一起作为声学前缀，克隆相似度更高
text_chunk_size=100	长文本切块预算（字符数），默认 100，长语音输出按此分块生成

⚠️ 注意：原生前端不使用 Python 版的 FST 文本归一化器，数字建议直接拼写出来（例如把 100 写成 one hundred），以保证发音符合预期。

六、高级用法：低显存「磁盘专家」模式 🔥

显存不够装下全部专家权重时，加一个会话选项即可：

audiocpp_cli --family ming3_audio --task asr --backend cuda \
  --model ming-3.0-audio-tiny-q4_k.gguf --audio long.wav \
  --session-option ming3_audio.disk_experts=true --log

• 专家权重留在主机内存，按层按需换入有界的 GPU 缓存（默认每层 8 个专家槽位），神经计算仍全部在所选 GPU 上执行
• offload 模式下 Thinker 的 KV 存储随实际上下文用量增长，不再一次性预留整个生成分额；max_tokens 上限不变

📈 实测收益（RTX 5090，CUDA 常驻模式，见 README.md）：

指标	优化前	优化后
音乐示例（152.84 s）Q4_K RTF	0.050	0.024（约 2 倍提速）
峰值显存	14,600 MiB	11,596 MiB（降约 20%）

七、实用建议清单 ✅

1. 短文本 ASR 采用贪心解码、256 token 额度，结果与官方 Python 实现逐字一致；长会议转写/摘要两侧均使用 32,768 token 额度
2. TTS 可复现：在固定 seed（测试用 42）、guidance scale 2、sigma 0.25、temperature 0 下，多次生成的 WAV 逐字节一致
3. CPU 也能跑：CPU 推理可通过 ASR/TTS 功能验证，只是未列入 CUDA 性能对比
4. s2s 任务适合"语音问答"场景：输入音频由 Thinker 理解后，直接由 Talker 合成回答，省去中间文本

八、许可证

本仓库沿用上游 checkpoint 的 MIT 协议（LICENSE），可自由用于个人与商业项目。

把模型文件下载到本地，配好一条 audiocpp_cli 命令，你的离线语音流水线就搭好了——转写、合成、克隆，一个工具全包。