ChatTTS · 面向日常对话的生成式语音合成模型 · 本地环境搭建与推理使用全指南

项目仓库： https://github.com/2noise/ChatTTS

代码协议：GNU AGPLv3+ · 模型协议：CC BY-NC 4.0（仅限教育与研究用途，禁止商用与违法用途） · 运行语言：Python + PyTorch · 支持语种：中文、英语 · WebUI 端口：8080（Gradio，源码参数可调） · 模型权重：HuggingFace 2Noise/ChatTTS · 仓库分支：main（命令、参数与版本以官方仓库最新说明为准）

1 项目简介

ChatTTS 是一款专门为对话场景（例如 LLM 助手、语音对话机器人）设计的文本转语音（Text-to-Speech）生成式模型。它针对对话式任务做了优化，合成语音自然且富有表现力，支持多个说话人参与互动；模型能够预测并控制笑声、停顿、语气词等细粒度韵律特征，在韵律表现上优于多数开源 TTS 模型。

本仓库包含算法框架与若干简单示例；由社区维护的扩展型终端用户产品，可参考官方 README 指向的索引仓库 Awesome-ChatTTS。开源版本模型在 HuggingFace 上发布，训练数据为 4 万小时规模、未做 SFT 的预训练模型；主模型以 10 万小时以上中英文音频数据训练，相关口径以官方说明为准。

非官方声明与用途声明：ChatTTS 模型权重以 CC BY-NC 4.0 协议发布，仅限教育与研究用途，不得用于任何商业或违法用途；作者不保证信息的准确性、完整性与可靠性。项目训练时在 4 万小时模型中加入了少量高频噪声，并以 MP3 格式尽量压缩音频质量，以降低被恶意滥用的风险；团队内部已训练检测模型并计划后续开源。合成语音可能被用于伪造他人声音，使用前必须取得声音对应方的明确授权。

1.1 核心信息一览

1.2 适用场景

• 为自研 LLM 助手、语音对话机器人准备口语化的中文 / 英文语音输出，需要自然停顿、笑声与语气词等接近真人对话的韵律表现。
• 学术研究对话式 TTS 模型的韵律控制、说话人嵌入与自回归采样策略。
• 在本地研究环境中离线合成少量测试音频，用于语音链路测试与方案对比。
• 开发者基于开源算法框架二次开发面向特定场景的 TTS 应用（需同时遵守代码与模型协议）。

1.3 能力边界（官方口径）

• 当前已支持中英双语；其他语种尚未发布。
• 当前发布模型中，词级可控单元仅为 [laugh]、[uv_break]、[lbreak]；除笑声外的其他情绪控制能力尚未开源，多情绪控制在路线图中待发布。
• 多说话人稳定性、音频质量属于自回归模型的共性问题，可能出现说话人漂移或音质波动；官方建议多次采样挑选满意结果。
• 开源模型为 4 万小时预训练模型（无 SFT），不等同于完整主模型能力；本仓库只提供算法基础设施与简单示例，不附带生产级用户产品。

2 功能特性

以下条目来自官方 README 与中文文档，具体参数效果以本地实测为准。

2.1 对话式合成

• 面向对话任务优化，支持多个说话人，便于生成互动式对话语音。
• 提供说话人随机采样（sample_random_speaker），采样结果可保存用于后续音色复现。

2.2 细粒度韵律控制

• 句子级别：oral_(0-9)、laugh_(0-2)、break_(0-7) 等特殊 token，在文本精修阶段控制口语化程度、笑声与停顿。
• 词级别：[uv_break]、[laugh]、[lbreak] 直接嵌入原文，控制词间停顿、笑声与句间停顿。
• 推理参数：temperature、top_P、top_K 控制采样分布，调节随机性与稳定性。

2.3 模型与推理能力

• 已开源 4 万小时基础模型与 spk_stats 文件；已开源 DVAE 编码器与零样本推理代码。
• 支持流式音频生成（Streaming audio generation）。
• 附带命令行推理脚本、Gradio WebUI 与 Python 基础 / 高级用法示例。

2.4 路线图（官方记录）

• 已完成：4 万小时基础模型与说话人统计文件开源、流式音频生成、DVAE 编码器与零样本推理代码开源。
• 待完成：多情绪控制；ChatTTS.cpp 推理后端（欢迎社区新建仓库）。

3 官方界面预览

官方 README 未提供可静态引用的界面截图；可通过以下官方入口查看演示效果：

• Colab 在线笔记本：examples/ipynb/colab.ipynb，在浏览器中加载模型并试听示例音频。
• Bilibili 讲解视频：官方 README 给出的演示视频 BV1zn4y1o7iV，用于了解模型详细能力。
• 本地启动 Gradio WebUI 后，浏览器访问 http://localhost:8080 即可看到官方示例界面；本文未截取第三方静态图片作为封面。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Python：官方 Conda 示例使用 Python 3.11；建议为项目单独创建 Conda 或虚拟环境隔离依赖。
• PyTorch 与 torchaudio：requirements.txt 要求 torch>=2.1.0、torchaudio；GPU 推理需与本机 CUDA 版本匹配的 PyTorch 安装方式，具体组合以 PyTorch 官方安装指南为准。
• 核心依赖（来自官方 requirements.txt）：numpy<3.0.0、numba、tqdm、vector_quantize_pytorch、transformers>=4.41.1、vocos、IPython、gradio、pybase16384、av、pydub、requests；pynini==2.1.5、WeTextProcessing、nemo_text_processing 仅在 Linux 平台安装。
• 系统工具：Linux 文本规范化相关依赖在 Windows / macOS 上的安装限制，以官方 Issues 与依赖包说明为准。
• 网络：首次加载模型需从 HuggingFace 拉取权重；离线环境请先在可联网机器完成缓存，再迁移到目标机器，缓存目录与离线加载方式以官方仓库最新说明为准。

5.2 硬件建议（官方 FAQ 口径）

上表显存与速度数据来自官方 README FAQ，针对 30 秒音频与 4090 显卡口径；长文本、并发批量与不同显卡上的表现需自行实测。

5.3 端口与输出路径

6 方式一：源码环境安装 + Gradio WebUI 启动（推荐本地体验）

官方未提供 Docker Compose 一键部署文件；本地体验以源码安装 + WebUI 为准。

6.1 克隆仓库

git clone https://github.com/2noise/ChatTTS
cd ChatTTS

6.2 方式 A：直接安装依赖

pip install --upgrade -r requirements.txt

6.3 方式 B：Conda 环境安装（官方示例）

conda create -n chattts python=3.11
conda activate chattts
pip install -r requirements.txt

6.4 可选：vLLM 支持（仅 Linux）

pip install safetensors vllm==0.2.7 torchaudio

官方 README 明确标注：TransformerEngine 当前适配尚未完成、不可正常运行，不要安装；FlashAttention-2 在当前版本会拖慢生成速度，同样不要安装；二者仅供开发研究目的参考。

6.5 启动 WebUI

确认当前目录为项目根目录后执行：

python examples/web/webui.py

可通过脚本参数调整监听地址与端口：

python examples/web/webui.py --server_name 0.0.0.0 --server_port 8080

启动后在浏览器打开 http://localhost:8080，输入文本、选择说话人与参数后试听并下载音频。

7 方式二：命令行与 Python API 运行（开发者 / 脚本集成）

7.1 命令行推理

脚本会把音频保存为 ./output_audio_n.mp3：

python examples/cmd/run.py "Your text 1." "Your text 2."

7.2 从 PyPI 安装为依赖库

# 稳定版本
pip install ChatTTS

# GitHub 最新版本
pip install git+https://github.com/2noise/ChatTTS

# 本地目录开发模式安装
pip install -e .

7.3 基础 Python 用法

import ChatTTS
import torch
import torchaudio

chat = ChatTTS.Chat()
chat.load(compile=False)  # 编译为 True 可获得更好性能

texts = ["PUT YOUR 1st TEXT HERE", "PUT YOUR 2nd TEXT HERE"]

wavs = chat.infer(texts)

for i in range(len(wavs)):
    # 不同版本 torchaudio 保存接口略有差异，依次尝试两种写法
    try:
        torchaudio.save(f"basic_output{i}.wav",
                        torch.from_numpy(wavs[i]).unsqueeze(0), 24000)
    except Exception:
        torchaudio.save(f"basic_output{i}.wav",
                        torch.from_numpy(wavs[i]), 24000)

7.4 高级用法：说话人与韵律控制

###################################
# 1. 从高斯分布随机采样一个说话人
rand_spk = chat.sample_random_speaker()
print(rand_spk)  # 保存该字符串，用于后续恢复同一音色

params_infer_code = ChatTTS.Chat.InferCodeParams(
    spk_emb=rand_spk,      # 接入采样到的说话人嵌入
    temperature=.3,        # 自定义温度
    top_P=0.7,            # Top-P 解码阈值
    top_K=20,             # Top-K 解码阈值
)

###################################
# 2. 句子级别人工控制
# 使用 oral_(0-9)、laugh_(0-2)、break_(0-7) 在文本中生成控制 token
params_refine_text = ChatTTS.Chat.RefineTextParams(
    prompt='[oral_2][laugh_0][break_6]',
)

wavs = chat.infer(
    texts,
    params_refine_text=params_refine_text,
    params_infer_code=params_infer_code,
)

###################################
# 3. 词级别人工控制
text = 'What is [uv_break]your favorite english food?[laugh][lbreak]'
wavs = chat.infer(
    text,
    skip_refine_text=True,
    params_refine_text=params_refine_text,
    params_infer_code=params_infer_code,
)

7.5 自检示例（自我介绍文本）

官方仓库附带的英文自我介绍示例使用 [uv_break]、[laugh] 等词级标记与 RefineTextParams 句子级参数组合；英文目前仍属于实验性支持，完整代码见仓库 README.md 的 self introduction 小节。

8 配置项说明

8.1 推理参数 InferCodeParams

8.2 文本精修参数 RefineTextParams

8.3 词级控制标记

8.4 WebUI 启动参数

8.5 模型加载开关

• chat.load(compile=False)：compile 设为 True 可获得更好性能；是否开启编译与运行环境兼容性以实测为准。
• 模型权重默认从 HuggingFace 2Noise/ChatTTS 仓库拉取；离线镜像、权重挂载与自定义模型路径等高级配置，以官方仓库最新说明与 Issues 讨论为准。

9 常用运维命令

# 安装 / 升级依赖（克隆仓库后）
pip install --upgrade -r requirements.txt

# 启动 Gradio WebUI
python examples/web/webui.py

# 命令行合成并输出 mp3
python examples/cmd/run.py "第一段测试文本。" "第二段测试文本。"

# 安装为 Python 库（稳定版 / 最新版 / 本地开发模式）
pip install ChatTTS
pip install git+https://github.com/2noise/ChatTTS
pip install -e .

文件与缓存管理：

• 命令行输出音频位于项目根目录 output_audio_n.mp3；Python 示例输出 WAV 采样率 24000 Hz。
• 模型权重与 HuggingFace 缓存目录位置以当前版本实现为准；升级前确认缓存目录不被误删，避免重复下载。
• 清理测试音频与中间产物时，不要误删权重缓存目录。

10 常见故障排查

10.1 显存不足（OOM）

• 官方 FAQ 口径：约 30 秒音频至少需要 4 GB GPU 显存；显存不足时先缩短单次文本长度、降低并发与批量。
• 确认 PyTorch 已识别到 CUDA 设备；torch.cuda.is_available() 返回 True 后再执行 GPU 推理。
• 仍超限时改用更短文本分段合成，或在官方 Issues 中查找长文本分段方案。

10.2 依赖安装失败（Linux 文本规范化组件）

• pynini、WeTextProcessing、nemo_text_processing 仅在 Linux 平台安装；非 Linux 平台对照 requirements.txt 条件注释安装，或参考 Issues 中的替代方案。
• 安装过程较慢属于官方已知说明；网络受限时可先准备 PyPI 镜像索引再安装。

10.3 模型下载失败或卡住

• 检查能否访问 HuggingFace；必要时按官方推荐方式配置镜像或先在联网环境下载权重后离线迁移。
• 首次加载耗时取决于网络与权重大小；重复报错时核对缓存目录完整性，删除损坏缓存后重新拉取。

10.4 说话人漂移、声音不稳定或音质差

• 官方 FAQ 说明：这是 bark、valle 等自回归模型的共性问题，通常难以完全避免；可多次采样挑选满意结果。
• 适当降低 temperature、调整 top_P 与 top_K 提升稳定性；固定 spk_emb 复现目标音色。

10.5 情绪控制不生效

• 当前发布模型仅支持 [laugh]、[uv_break]、[lbreak] 三个词级控制单元；其他情绪控制尚未开源，不要在提示中使用未发布的情绪标记。
• 句子级 laugh_(0-2)、break_(0-7)、oral_(0-9) 通过 RefineTextParams.prompt 传入，需确认调用参数正确挂载。

10.6 生成音频带有噪声或音质被压缩

• 官方说明：4 万小时训练模型在训练阶段加入了少量高频噪声，并采用 MP3 格式压缩音质，属于为防止恶意滥用而主动采取的措施，并非安装故障。
• 输出 WAV 可保留更高采样质量；具体量化参数以官方仓库最新说明为准。

10.7 速度偏慢

• 官方口径 4090 上 RTF 约 0.3；其他显卡或 CPU 环境速度差异较大。
• 核对 torch、torchaudio 与 CUDA 版本匹配；不要安装官方标注“DO NOT INSTALL”的 TransformerEngine 与 FlashAttention-2，二者当前版本反而影响正常运行或拖慢速度。

11 风险与合规说明

• 代码与模型双重协议：代码以 AGPLv3+ 发布；模型权重以 CC BY-NC 4.0 发布，仅限教育与研究用途，不得用于任何商业或违法用途。基于本项目搭建对外服务前，必须同时核对两项协议义务。
• 声音授权与伦理：合成特定真人声音需取得本人明确授权；禁止用合成语音进行冒充、诈骗、造谣或其他违法活动。官方已主动在模型中加入噪声与压缩措施，内部训练了检测模型并计划开源，后续平台可能对 AI 合成语音进行溯源检测。
• 输出可靠性：模型韵律与断句可能出现错误，正式内容须人工校对；官方不保证输出信息的准确性、完整性与可靠性。
• 第三方依赖许可：PyTorch、transformers、vocos、gradio 等依赖各自适用独立许可证；部署到生产环境前逐一核对。
• 隐私与数据：本地运行可避免文本上传第三方，但模型缓存、日志与输出音频中可能包含输入文本，妥善管理本机文件与共享范围。
• 非官方立场：本文为依据官方 README、中文文档、依赖清单与 FAQ 整理的研究环境部署指南；如官方文档更新，以仓库与 HuggingFace 模型卡最新说明为准。