# MOSS-TTS-Nano 教程 02：CLI 与 Web Demo 实战

这篇教程聚焦两个最常用入口：

• generate
• serve

同时也会整理一套更实用的排坑经验，尤其是：

• GPU 没生效怎么办
• Web Demo 实时流式为什么会断断续续
• 哪些参数值得调，哪些参数收益很低

1. 先把 CLI 跑起来

如果你已经在仓库根目录，最稳的方式不是直接赌moss-tts-nano命令在不在 PATH 里，而是用模块方式启动。

python-mmoss_tts_nano generate ^ --prompt-speech assets/audio/zh_1.wav ^--text"你好，这是一次测试。"

这样做的好处是：

• 不依赖系统 PATH
• 更容易确认当前到底用的是哪个 Python 环境

2.generate的常见用法

2.1 最小用法

python-mmoss_tts_nano generate ^ --prompt-speech assets/audio/zh_1.wav ^--text"你好，这是一次测试。"

它做的事情很简单：

• 使用参考音频做语音克隆
• 把文本合成为语音
• 输出到默认 wav 文件

2.2 指定 GPU

如果你想走 CUDA：

python-mmoss_tts_nano generate ^--devicecuda ^--dtypefloat16 ^ --prompt-speech assets/audio/zh_1.wav ^--text"你好，这是一次 GPU 推理测试。"

这一步非常适合验证：

• 你的 GPU 环境是不是通的
• 当前torch是不是 CUDA 版

2.3 长文本相关参数

常见参数：

• --voice-clone-max-text-tokens
• --max-new-frames

其中：

• voice-clone-max-text-tokens越小，越容易分块
• voice-clone-max-text-tokens越大，单次处理文本越长

如果是长文本，建议理解成：

这是控制语音克隆场景下文本分块强度的参数

3.serve的本质

serve不是新的模型能力，而是把已有推理能力包装成：

• 本地网页
• HTTP 接口

典型命令：

python-mmoss_tts_nano serve

如果你要显式走 GPU：

python-mmoss_tts_nano serve--devicecuda--dtypefloat16

启动后默认访问：

• http://localhost:18083

4. Web Demo 里几个最关键的参数

4.1 Execution Device

这个参数决定请求走哪个执行设备：

• auto
• cpu
• cuda

如果你已经确认 GPU 环境没问题，建议优先用：

• cuda

4.2 Realtime Streaming Decode

这个选项决定你是不是要边生成边播。

关闭时：

• 更像“先生成完整音频，再播放”
• 听感通常更稳定

开启时：

• 更像“实时生成、实时播放”
• 延迟更低
• 但也更容易出现轻微不连续

4.3 Initial Playback Delay

这个参数非常关键。

它本质上是在告诉浏览器：

“先攒一点音频再播，还是尽快开始播。”

如果太小：

• 首音更快
• 但更容易断粮

如果太大：

• 更稳定
• 但首音更慢

在一台RTX 2060 Max-Q 6GB、Ryzen 7 4800H、32GB RAM的笔记本上，实际调试结果是：

• 0.08太激进
• 0.30明显比0.08稳
• 0.50比0.30更好
• 再往上到0.70 / 0.80收益不明显

所以一个更稳的经验值是：

• Initial Playback Delay = 0.50

4.4 Max TTS Batch Size / Max Codec Batch Size

这两个参数影响的是实时流式中每次处理音频块的粒度。

调试中一组更优的参数是：

• Max TTS Batch Size = 8
• Max Codec Batch Size = 4

它比默认值更有助于提升连续性，但也不能彻底解决实时流式里那一点点不连续。

5. GPU 没生效时怎么判断

先不要看显存占用，先看事实。

执行：

python-c"import torch; print('torch=', torch.__version__); print('cuda_available=', torch.cuda.is_available()); print('torch_cuda=', torch.version.cuda)"

如果输出类似：

torch=2.7.0+cpucuda_available=Falsetorch_cuda=None

说明你当前装的是 CPU 版 PyTorch，不可能真正走 GPU。

6. 一个非常典型的坑：环境串了

这类项目很容易出现这样的问题：

• 你以为自己在 conda 环境里
• 实际运行时却调到了系统 Python
• 然后出现各种奇怪报错

最常见的现象包括：

• typing_extensions缺失
• tn模块缺失
• 明明安装过包却提示找不到

解决方式很朴素：

python-c"import sys; print(sys.executable)"

看当前到底是哪个 Python。

如果你想彻底避免串环境，可以直接：

conda run-nmoss-tts-nano python-mmoss_tts_nano serve--devicecuda--dtypefloat16--port18084

7.No module named 'tn'是怎么来的

如果你在 Web Demo 里看到：

RuntimeError: No module named 'tn'

这通常不是模型本身的问题，而是文本归一化依赖没有装完整。

它经常发生在：

• 错误的 Python 环境
• WeTextProcessing没装完整
• tn相关依赖不在当前环境里

短期绕开方法：

• 在页面里关闭Enable WeTextProcessing

长期正确做法：

• 使用干净环境
• 正确安装pynini
• 正确安装WeTextProcessing

8. 实时流式为什么很难完全丝滑

这是这次调试里最重要的认识之一。

实时模式不是单纯“模型生成快不快”的问题，它至少包含这些环节：

1. 文本归一化
2. 文本分块
3. 模型流式推理
4. codec 流式解码
5. 服务端传输
6. 浏览器播放调度

只要其中任意一环有轻微抖动，最终就会表现成：

• 偶尔一小下不连续

这也是为什么：

• 调大显存占用不一定能解决
• 单纯增大Initial Playback Delay到某个点后收益就很有限

9. 实测后更稳的一组参数

基于这次真实调试，一个更稳的参考组合是：

Execution Device = cuda Realtime Streaming Decode = 开 Initial Playback Delay = 0.50 Voice Clone Max Text Tokens = 120 Max TTS Batch Size = 8 Max Codec Batch Size = 4

注意，这组参数的含义是：

• 在当前机器上更平衡
• 并不是说一定绝对最优
• 也不代表实时流式会完全没有轻微断续

10. 实用建议

如果你的目标是：

做演示

可以用实时模式，强调“边生成边播”的体验。

真正听结果

优先关闭实时流式，听最终一次性生成结果，通常更稳定。

继续调优

不要一直盯着显存数字，而要看：

• 首音速度
• 听感连续性
• 是否新增副作用

小结

serve好用，但实时流式更像“工程平衡题”，不是单个参数越大越好。