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

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

• generate
• serve

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

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

1. 先把 CLI 跑起来

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

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

这样做的好处是：

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

2. generate 的常见用法

2.1 最小用法

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

它做的事情很简单：

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

2.2 指定 GPU

如果你想走 CUDA：

python -m moss_tts_nano generate ^
  --device cuda ^
  --dtype float16 ^
  --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 -m moss_tts_nano serve

如果你要显式走 GPU：

python -m moss_tts_nano serve --device cuda --dtype float16

启动后默认访问：

• 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+cpu
cuda_available= False
torch_cuda= None

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

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

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

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

最常见的现象包括：

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

解决方式很朴素：

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

看当前到底是哪个 Python。

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

conda run -n moss-tts-nano python -m moss_tts_nano serve --device cuda --dtype float16 --port 18084

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 好用，但实时流式更像"工程平衡题"，不是单个参数越大越好。