安装与配置 #

系统要求 #

硬件要求 #

text

┌─────────────────────────────────────────────────────────────┐
│                    硬件要求参考                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  最低配置（CPU 推理）：                                       │
│  ├── CPU：4 核以上                                          │
│  ├── 内存：8 GB                                             │
│  ├── 存储：10 GB 可用空间                                    │
│  └── 适用：测试、开发                                        │
│                                                             │
│  推荐配置（GPU 推理）：                                       │
│  ├── GPU：NVIDIA RTX 3060 或更高                            │
│  ├── 显存：8 GB 以上                                        │
│  ├── 内存：16 GB                                            │
│  ├── 存储：50 GB SSD                                        │
│  └── 适用：生产环境、训练                                    │
│                                                             │
│  训练配置：                                                  │
│  ├── GPU：NVIDIA RTX 3090/4090 或 A100                      │
│  ├── 显存：24 GB 以上                                       │
│  ├── 内存：32 GB 以上                                       │
│  ├── 存储：500 GB SSD                                       │
│  └── 适用：模型训练、微调                                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

软件要求 #

text

操作系统：
├── Linux（Ubuntu 20.04+ 推荐）
├── macOS 10.15+
└── Windows 10/11

Python 版本：
├── Python 3.9 - 3.11（推荐 3.10）
└── pip 21.0+

GPU 支持（可选）：
├── NVIDIA 驱动 450.80+
├── CUDA 11.8 或 12.x
└── cuDNN 8.x

安装方式 #

方式一：pip 安装（推荐） #

bash

# 创建虚拟环境
python -m venv tts-env
source tts-env/bin/activate  # Linux/macOS
# tts-env\Scripts\activate   # Windows

# 安装 Coqui TTS
pip install TTS

# 验证安装
tts --help

方式二：从源码安装 #

bash

# 克隆仓库
git clone https://github.com/coqui-ai/TTS.git
cd TTS

# 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 安装依赖
pip install -e .

方式三：Docker 安装 #

bash

# 拉取镜像
docker pull ghcr.io/coqui-ai/tts-cpu:latest

# 运行容器
docker run -it --rm \
  -p 5002:5002 \
  ghcr.io/coqui-ai/tts-cpu:latest

GPU 支持配置 #

安装 PyTorch GPU 版本 #

bash

# CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

验证 GPU 支持 #

python

import torch

# 检查 CUDA 是否可用
print(f"CUDA 可用: {torch.cuda.is_available()}")

if torch.cuda.is_available():
    print(f"CUDA 版本: {torch.version.cuda}")
    print(f"GPU 数量: {torch.cuda.device_count()}")
    print(f"GPU 名称: {torch.cuda.get_device_name(0)}")
    print(f"显存总量: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.2f} GB")

GPU 内存优化 #

python

import torch

# 清空缓存
torch.cuda.empty_cache()

# 设置内存增长
import os
os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'expandable_segments:True'

# 使用半精度
model = model.half()

平台特定配置 #

Linux 配置 #

bash

# 安装系统依赖
sudo apt-get update
sudo apt-get install -y \
    python3-dev \
    python3-pip \
    python3-venv \
    build-essential \
    espeak-ng \
    espeak

# 安装音频支持
sudo apt-get install -y \
    libsndfile1 \
    ffmpeg

# 配置环境变量
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

macOS 配置 #

bash

# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install python@3.10
brew install espeak-ng
brew install ffmpeg

# 配置环境
echo 'export PATH="/usr/local/opt/python@3.10/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows 配置 #

powershell

# 安装 Visual C++ Build Tools
# 下载地址: https://visualstudio.microsoft.com/visual-cpp-build-tools/

# 安装 espeak-ng
# 下载地址: https://github.com/espeak-ng/espeak-ng/releases

# 安装 ffmpeg
winget install ffmpeg

# 配置环境变量
$env:PATH += ";C:\Program Files\eSpeak NG"

依赖管理 #

核心依赖 #

text

TTS 核心依赖：
├── torch >= 1.7
├── torchaudio
├── numpy
├── scipy
├── librosa
├── soundfile
├── tqdm
├── matplotlib
└── trainer

可选依赖 #

bash

# 开发依赖
pip install TTS[dev]

# 测试依赖
pip install TTS[test]

# 文档依赖
pip install TTS[docs]

# 完整安装
pip install TTS[all]

requirements.txt 示例 #

text

TTS>=0.20.0
torch>=2.0.0
torchaudio>=2.0.0
numpy>=1.21.0
scipy>=1.7.0
librosa>=0.10.0
soundfile>=0.11.0
gradio>=3.0.0

配置文件 #

全局配置 #

python

# ~/.config/tts/config.json
{
    "model_path": "~/.local/share/tts",
    "cache_dir": "~/.cache/tts",
    "default_speaker": null,
    "default_language": "en",
    "audio": {
        "sample_rate": 22050,
        "output_path": "./output"
    }
}

环境变量配置 #

bash

# ~/.bashrc 或 ~/.zshrc

# TTS 模型存储路径
export TTS_HOME=~/.local/share/tts

# 缓存目录
export TTS_CACHE=~/.cache/tts

# Hugging Face 缓存
export HF_HOME=~/.cache/huggingface

# CUDA 配置
export CUDA_VISIBLE_DEVICES=0

# 内存优化
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

模型管理 #

模型存储位置 #

text

默认模型存储路径：
├── Linux: ~/.local/share/tts/
├── macOS: ~/.local/share/tts/
└── Windows: C:\Users\<用户名>\.local\share\tts\

模型目录结构：
tts/
├── tts_models--en--ljspeech--vits/
│   ├── model_file.pth
│   ├── config.json
│   └── speakers.json
└── vocoder_models--en--ljspeech--hifigan_v2/
    ├── model_file.pth
    └── config.json

自定义模型路径 #

python

import os
from TTS.api import TTS

# 设置自定义路径
os.environ['TTS_HOME'] = '/custom/path/to/models'

# 加载模型
tts = TTS(model_name="tts_models/en/ljspeech/vits")

清理模型缓存 #

bash

# 查看缓存大小
du -sh ~/.local/share/tts/
du -sh ~/.cache/tts/

# 清理缓存
rm -rf ~/.cache/tts/*

验证安装 #

基础验证 #

bash

# 检查版本
tts --version

# 列出可用模型
tts --list_models

# 测试合成
tts --text "Hello, this is a test." --out_path test.wav

Python 验证 #

python

from TTS.api import TTS
import torch

# 检查设备
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"使用设备: {device}")

# 加载模型测试
tts = TTS("tts_models/en/ljspeech/vits").to(device)

# 合成测试
tts.tts_to_file(text="Hello world!", file_path="test.wav")
print("安装验证成功！")

完整验证脚本 #

python

import torch
from TTS.api import TTS

def verify_installation():
    print("=" * 50)
    print("Coqui TTS 安装验证")
    print("=" * 50)
    
    # 1. PyTorch 版本
    print(f"\n1. PyTorch 版本: {torch.__version__}")
    
    # 2. CUDA 支持
    cuda_available = torch.cuda.is_available()
    print(f"2. CUDA 可用: {cuda_available}")
    if cuda_available:
        print(f"   - GPU: {torch.cuda.get_device_name(0)}")
        print(f"   - CUDA 版本: {torch.version.cuda}")
    
    # 3. TTS 版本
    try:
        import TTS
        print(f"3. TTS 版本: {TTS.__version__}")
    except:
        print("3. TTS 版本: 未知")
    
    # 4. 模型加载测试
    device = "cuda" if cuda_available else "cpu"
    print(f"4. 使用设备: {device}")
    
    try:
        tts = TTS("tts_models/en/ljspeech/vits").to(device)
        print("   - 模型加载: 成功")
    except Exception as e:
        print(f"   - 模型加载: 失败 - {e}")
        return False
    
    # 5. 合成测试
    try:
        tts.tts_to_file(text="Test successful", file_path="verify_test.wav")
        print("   - 语音合成: 成功")
    except Exception as e:
        print(f"   - 语音合成: 失败 - {e}")
        return False
    
    print("\n" + "=" * 50)
    print("所有验证通过！")
    print("=" * 50)
    return True

if __name__ == "__main__":
    verify_installation()

常见问题 #

问题 1：安装失败 #

bash

# 错误：编译错误
# 解决：安装编译依赖

# Linux
sudo apt-get install build-essential python3-dev

# macOS
xcode-select --install

# Windows
# 安装 Visual C++ Build Tools

问题 2：CUDA 内存不足 #

python

# 解决方案 1：使用 CPU
device = "cpu"
tts = TTS(model_name).to(device)

# 解决方案 2：使用更小的模型
tts = TTS("tts_models/en/ljspeech/fast_speech")

# 解决方案 3：清理缓存
import torch
torch.cuda.empty_cache()

问题 3：音频库问题 #

bash

# 错误：libsndfile not found
# 解决：

# Linux
sudo apt-get install libsndfile1

# macOS
brew install libsndfile

# Windows
pip install pysoundfile

问题 4：espeak 问题 #

bash

# 错误：espeak-ng not found
# 解决：

# Linux
sudo apt-get install espeak-ng

# macOS
brew install espeak-ng

# Windows
# 下载安装 espeak-ng
# 添加到 PATH 环境变量

问题 5：模型下载失败 #

python

# 解决方案：手动下载模型
import os
from TTS.utils.manage import ModelManager

# 设置代理
os.environ['HTTP_PROXY'] = 'http://proxy:port'
os.environ['HTTPS_PROXY'] = 'http://proxy:port'

# 或使用镜像
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

下一步 #

安装完成后，继续学习快速开始，开始你的第一个语音合成项目！