TTS(Coqui)安装指南:pip 安装、源码构建与依赖体系详解

原创2026-09-05 15:11:371,682 阅读
文章标签:语音音频人工智能深度学习预训练AI 应用

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)

几个值得展开的要点:

  1. -e 可编辑安装:源码修改后无需重新 pip install,直接生效,适合训练调参、改模型结构;

  2. [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)。

  3. 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 依赖(ja extras)按需安装,存在平台兼容性提示。
登录后查看全文
TTS