TTS(Coqui)安装指南:pip 安装、源码构建与依赖体系详解
TTS(Coqui)安装指南:pip 安装、源码构建与依赖体系详解
本文基于 Coqui TTS 仓库的 安装文档 展开,系统讲解在 Linux 系统上通过 pip 与源码两种方式安装 🐸TTS 的完整流程,并结合 Makefile、setup.py 与 requirements.txt 说明各安装目标(target)、Python 版本约束、可选依赖组(extras)以及 Cython 扩展对构建环境的要求,帮助读者一次性搭建可用的推理/训练环境。
环境要求与适用前提
安装文档给出的原始环境基线是:
- Python 版本:
>=3.7 <3.11.0; - 已在 Ubuntu 18.10、19.10、20.10 上完成测试。
需要注意,以当前仓库的实际代码为准:setup.py 中的版本守卫已将约束收紧为:
if Version(python_version) < Version("3.9") or Version(python_version) >= Version("3.12"):
raise RuntimeError("TTS requires python >= 3.9 and < 3.12 ...")
且 python_requires 声明为 >=3.9.0, <3.12(见 setup.py)。也就是说,当前源码安装时 Python 版本的实际可接受区间是 3.9 ~ 3.11,早于 3.9 的环境在安装阶段就会直接抛出 RuntimeError。文档中的 ">=3.7" 表述属于历史遗留,实操时应以 setup.py 的硬校验为准。
此外,requirements.txt 对 numpy 做了按 Python 版本的分支锁定:
numpy==1.22.0;python_version<="3.10"
numpy>=1.24.3;python_version>"3.10"
这意味着 Python 3.11 环境会拉到较新的 numpy,若使用预编译环境需留意与 numba、torch 的 ABI 兼容性。
方式一:使用 pip 安装(推荐用于纯推理场景)
安装文档明确指出:如果只想用 🐸TTS 做推理(inference),推荐走 pip 渠道,无需关心仓库构建细节。
从 PyPI 安装发布版本:
pip install TTS # from PyPI
从 Git 仓库直接安装(适合跟踪最新提交):
pip install git+https://gitcode.com/GitHub_Trending/tt/TTS
从源码结构看,setup.py 注册了两个 console entry points,安装完成后可以直接在命令行验证:
entry_points={"console_scripts": ["tts=TTS.bin.synthesize:main", "tts-server = TTS.server.server:main"]}
即安装成功后,终端中应能看到 tts(文本合成 CLI)与 tts-server(Web 演示服务器,模板与静态资源打包在 TTS/server,由 setup.py 的 package_data 一并带入)两个命令。这是判断安装是否完整的最快方式。
方式二:从源码安装(推荐用于开发与二次控制)
安装文档给出的源码流程为:
git clone https://gitcode.com/GitHub_Trending/tt/TTS/
cd TTS
make system-deps # only on Linux systems.
make install
结合 Makefile 可以看到这两步背后实际执行的内容:
| Make 目标 | 实际命令 | 作用 |
|---|---|---|
system-deps |
sudo apt-get install -y libsndfile1-dev |
安装 Linux 系统级依赖 libsndfile 开发库,供 soundfile 读写音频使用(仅限 Linux,见 Makefile) |
install |
pip install -e .[all] |
以可编辑(editable)模式安装 TTS,并带上 all 依赖组(见 Makefile) |
几个值得展开的要点:
-
-e可编辑安装:源码修改后无需重新pip install,直接生效,适合训练调参、改模型结构; -
[all]依赖组:对应 setup.py 中的extras_require:extras_require={ "all": requirements_all, # dev + notebooks + ja 三份依赖的合集 "dev": requirements_dev, "notebooks": requirements_notebooks, "ja": requirements_ja, }若只需要开发依赖,可改为
make dev-deps(对应 Makefile,安装 requirements.dev.txt:black、coverage、isort、nose2、pylint)。 -
Windows 环境:安装文档的 Windows 小节单独指向了一份由 @GuyPaddock 撰写的 StackOverflow 安装指引(文档中给出外链地址)。从源码结构看,Windows 上的主要难点是 Cython 扩展编译与音频系统库,建议优先在 Linux 或容器内完成开发安装。
构建依赖:Cython 扩展与 pyproject.toml
从源码安装并非“纯 Python”流程。setup.py 声明了一个 Cython 扩展:
exts = [
Extension(
name="TTS.tts.utils.monotonic_align.core",
sources=["TTS/tts/utils/monotonic_align/core.pyx"],
)
]
该扩展对应 TTS/tts/utils/monotonic_align/core.pyx,是 Tacotron 系列强制对齐(monotonic alignment)的 C 加速核心。因此构建时需要:
- C 编译器(gcc/clang 工具链):负责编译
.pyx生成的 C 代码; - Cython:pyproject.toml 的
[build-system]固定了cython~=0.29.30与numpy>=1.22.0,即在隔离构建环境里也会自动装入匹配版本的 Cython 与 numpy; - numpy 头文件:setup.py 通过
include_dirs=numpy.get_include()将其引入扩展编译。
如果你只打算推理且不想经历本地编译,直接 pip install TTS 走 PyPI 预编译轮子是最省事的路线,这正是文档推荐 pip 的原因。
核心依赖结构(requirements 文件拆解)
requirements.txt 是整个安装的基础,setup.py 将其整体作为 install_requires(见 setup.py、setup.py)。按文件内注释分组:
| 分组(文件内注释) | 关键包 | 说明 |
|---|---|---|
| core deps | torch>=2.1、torchaudio、soundfile>=0.12.0、librosa>=0.10.0、scipy、scikit-learn、numba、inflect、tqdm、anyascii、pyyaml、fsspec、aiohttp、mutagen==1.47.0 |
模型训练/推理与音频处理基础栈;fsspec 注释标明 <= 2023.9.1 会导致 aux 测试失败,属于有意的版本下限 |
| deps for examples | flask>=2.0.1 |
演示服务器(TTS/server)依赖 |
| deps for inference | pysbd>=0.3.4 |
长文本语义分句 |
| deps for notebooks | umap-learn、pandas>=1.4,<2.0 |
数据集分析 Notebook(见 notebooks/dataset_analysis) |
| deps for training | matplotlib>=3.7.0 |
训练可视化(mel 图等) |
| coqui stack | trainer>=0.0.36、coqpit>=0.0.16 |
训练器框架与配置管理 |
| 多语言 g2p 依赖 | jieba、pypinyin(中文);jamo、nltk、g2pkk>=0.1.1、hangul_romanize(韩语);gruut[de,es,fr]==2.2.3(德/西/法);bangla、bnnumerizer、bnunicodenormalizer(孟加拉语) |
对应 TTS/tts/utils/text 下各语言 phonemizer 前端的运行依赖 |
| 特定模型依赖 | einops、transformers>=4.33.0(Tortoise);encodec>=0.1.1(Bark);unidecode、num2words、spacy[ja]>=3(XTTS) |
从源码结构看,这些服务于 TTS/tts/layers/tortoise、TTS/tts/layers/bark 与 TTS/tts/layers/xtts 三个模型栈 |
可选依赖组(extras)与文件的对应关系:
dev→ requirements.dev.txt(black、coverage、isort、nose2、pylint==2.10.2,支撑 Makefile 的style/lint/test目标);notebooks→ requirements.notebooks.txt(bokeh==1.4.0);ja→ requirements.ja.txt(mecab-python3==1.0.6、unidic-lite==1.0.8、cutlet)。文件内注释特别提示:这些日文 g2p 依赖“在部分系统上会引发兼容性问题且并非严格必需”,日语前端可用时按需启用即可。
安装后的验证与后续动作
安装完成后,建议按 Makefile 提供的测试目标进行健康检查(需要 dev 依赖组):
make deps # 等价于 pip install -r requirements.txt(见 Makefile#L71-L72)
make test # nose2 全量测试 + 覆盖率
make inference_tests # 仅跑 tests.inference_tests,验证 TTS() 推理链路
测试集入口见 tests 目录,如 tests/inference_tests(合成链路)、tests/aux_tests(音频处理器、说话人嵌入等)。其中 tests/aux_tests/test_readme.py 甚至会对 README 中的示例代码做执行校验,说明仓库自身对“文档中命令可运行”有持续保障。
此外,仓库提供了 dockerfiles/Dockerfile.dev 与 Dockerfile,对于不想手动处理系统依赖(如 libsndfile、Cython 编译链)的场景,直接在容器内完成开发安装是文档方案之外的稳妥替代路线。
小结
- 纯推理场景:
pip install TTS,验证tts/tts-server命令即可; - 开发场景:
git clone+make system-deps(仅 Linux)+make install,实质是libsndfile1-dev+ 可编辑安装带all依赖组; - 版本红线:Python 3.9~3.11(以 setup.py 硬校验为准,而非文档中的 >=3.7 表述),numpy 按 Python 版本自动分支;
- 从源码构建需 C 工具链 + Cython,用于编译
TTS.tts.utils.monotonic_align.core扩展; - 日语 g2p 依赖(
jaextras)按需安装,存在平台兼容性提示。