MoYoYo.tts 使用手册
目录
简介
MoYoYo.tts 是一个综合性的声音克隆和文本转语音系统，结合了：
- 后端 API：基于 FastAPI 的 REST API，用于声音训练和推理
- 前端应用：Electron + Vue 桌面应用，具有直观的用户界面
该系统基于 GPT-SoVITS 技术构建，能够使用最少的训练数据（最短 5 秒音频）实现高质量的声音克隆。
目标用户：
- 想要创建自定义文本转语音声音的最终用户
- 将语音合成集成到应用程序中的开发人员
- 从事声音克隆技术研究的研究人员
主要功能：
- 快速模式：为初学者提供一键式声音克隆
- 高级模式：对训练管道进行精细控制
- 通过服务器发送事件（SSE）进行实时进度跟踪
- 多语言支持（中文、英文、日文）
- 支持 GPU 加速的 CUDA
快速开始
通过以下基本步骤，在 5 分钟内启动并运行：
1. 安装 uv（Python 包管理器）：
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
2. 设置 Python 环境：
cd GPT-SoVITS
uv sync # 创建 .venv 并安装所有依赖项
source .venv/bin/activate # macOS/Linux
# 或: .venv\Scripts\activate # Windows
3. 下载必需的模型（详见 3.3 节）：
# 下载并解压 NLTK 数据、预训练模型等
# 或使用前端应用自动下载
4. 启动后端 API：
cd api_server
python app/main.py
# API 运行在 http://localhost:8000
5. 启动前端应用（在新终端中）：
cd tts-voice-app
npm install
npm run dev
大功告成！Electron 应用将引导您完成模型设置和声音克隆。
有关详细的安装说明、平台特定注意事项和配置选项，请继续阅读以下内容。
系统要求
软件要求
| 组件 | 版本 | 说明 |
|---|---|---|
| Python | 3.10 - 3.12 | 推荐 Python 3.11 |
| Node.js | >= 18.x | 用于前端开发 |
| uv | 最新版 | Python 包管理器 |
| CUDA | 12.6 或 12.8 | 可选，用于 GPU 加速 |
硬件要求
| 组件 | 最低配置 | 推荐配置 |
|---|---|---|
| CPU | 双核 | 四核或更好 |
| RAM | 16 GB | 32 GB（用于训练） |
| GPU | 无（CPU 模式） | 配备 6GB+ 显存的 NVIDIA GPU |
| 存储 | 20 GB 可用空间 | 50 GB+（用于多个声音） |
GPU 说明：
- GPU 是可选的，但可显著加快训练速度（5-10 倍）
- 推荐使用支持 CUDA 12.6 或 12.8 的 NVIDIA GPU
- 目前不支持 AMD GPU 和 Apple Silicon 进行训练
安装指南
3.1 安装 uv 包管理器
uv 是一个快速的 Python 包安装器和解析器，可以替代 pip。
macOS / Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows（PowerShell）：
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
验证安装：
uv --version
3.2 Python 环境设置
该项目使用 uv 进行依赖管理，配置文件为 pyproject.toml。设置过程简化为一个命令。
步骤 1：进入项目目录
cd GPT-SoVITS
步骤 2：同步所有依赖项
# 这个命令将：
# - 创建虚拟环境（.venv）
# - 安装 Python 3.11（或您指定的版本）
# - 从 pyproject.toml 安装所有依赖项
# - 为您的平台安装正确的 PyTorch 版本
uv sync
步骤 3：激活环境
macOS / Linux：
source .venv/bin/activate
Windows：
.venv\Scripts\activate
您应该在终端提示符中看到 (.venv) 前缀。
平台特定的 PyTorch 安装工作原理：
pyproject.toml 会自动选择适当的 PyTorch 版本：
- macOS：安装仅 CPU 的 PyTorch（Apple Silicon 使用 CPU 模式）
- Linux：默认安装 CUDA 12.6 PyTorch
- Windows：需要手动选择 CUDA 版本（见下文）
Windows 用户 - 选择 CUDA 版本：
对于 Windows，您需要明确指定 PyTorch 索引：
CUDA 12.6（默认）：
uv sync
CUDA 12.8：
uv sync --index pytorch-cu128
仅 CPU（无 GPU）：
uv sync --index pytorch-cpu
验证安装：
# 检查 Python 版本
python --version # 应显示 Python 3.11.x
# 检查 PyTorch 安装
python -c "import torch; print(f'PyTorch: {torch.__version__}')"
# 检查 CUDA 可用性（如果您有 GPU）
python -c "import torch; print(f'CUDA 可用: {torch.cuda.is_available()}')"
3.3 下载必需的数据文件
以下数据文件是文本处理和声音训练所必需的。
NLTK 数据（文本处理必需）
NLTK（自然语言工具包）数据用于文本分词和处理。
# 从 ModelScope 下载
wget https://www.modelscope.cn/models/XXXXRT/GPT-SoVITS-Pretrained/resolve/master/nltk_data.zip
# 解压到 Python 环境
unzip -q -o nltk_data.zip -d .venv/
# 清理
rm nltk_data.zip
大小：约 10 MB 时间：< 1 分钟
Open JTalk 词典（日语必需）
Open JTalk 是日语文本转语音处理所必需的。
# 获取 pyopenjtalk 安装路径
PYOPENJTALK_PATH=$(python -c "import os, pyopenjtalk; print(os.path.dirname(pyopenjtalk.__file__))")
# 从 ModelScope 下载
wget https://www.modelscope.cn/models/XXXXRT/GPT-SoVITS-Pretrained/resolve/master/open_jtalk_dic_utf_8-1.11.tar.gz
# 解压到 pyopenjtalk 目录
tar -xzf open_jtalk_dic_utf_8-1.11.tar.gz -C "$PYOPENJTALK_PATH"
# 清理
rm open_jtalk_dic_utf_8-1.11.tar.gz
大小：约 50 MB 时间：< 2 分钟
3.4 前端设置
前端是使用 Vue.js 构建的 Electron 应用程序。
# 进入前端目录
cd tts-voice-app
# 安装 Node.js 依赖项
npm install
时间：2-5 分钟 说明：这会安装所有必需的 Node.js 包，包括 Electron、Vue 和 UI 组件。
配置
4.1 后端 API 配置
后端使用环境变量进行配置。在项目根目录创建 .env 文件以进行自定义设置。
创建 .env 文件（可选，默认值适用于本地开发）：
# 部署模式
# 选项：local, server
DEPLOYMENT_MODE=local
# API 服务器设置
API_HOST=0.0.0.0
API_PORT=8000
# 数据存储路径
DATA_DIR=~/.moyoyo-tts/data
SQLITE_PATH=~/.moyoyo-tts/data/tasks.db
# 训练设置
LOCAL_MAX_WORKERS=1 # 并发训练任务数
配置选项：
| 变量 | 默认值 | 说明 |
|---|---|---|
DEPLOYMENT_MODE |
local |
部署环境（local/server） |
API_HOST |
0.0.0.0 |
API 服务器绑定地址 |
API_PORT |
8000 |
API 服务器端口 |
DATA_DIR |
~/.moyoyo-tts/data |
数据存储目录 |
SQLITE_PATH |
~/.moyoyo-tts/data/tasks.db |
SQLite 数据库路径 |
LOCAL_MAX_WORKERS |
1 |
最大并发训练任务数 |
说明：
API_HOST=0.0.0.0允许来自任何网络接口的连接LOCAL_MAX_WORKERS=1防止内存有限的系统出现内存问题- 在高端系统上增加
LOCAL_MAX_WORKERS以同时训练多个声音
4.2 前端配置
前端在本地开发时只需要最少的配置。
默认设置：
- API 端点：
http://localhost:8000 - 声音存储：
~/.moyoyo-tts/voices/ - 模型存储：
GPT_SoVITS/pretrained_models/
自动配置： Electron 应用将：
- 自动检测并连接到本地 API 服务器
- 首次启动时创建所需的目录
- 通过模型设置页面下载缺失的模型
标准使用无需手动配置。
运行应用
5.1 启动后端 API 服务器
步骤 1：激活 Python 环境
# 进入项目目录
cd GPT-SoVITS
# 激活虚拟环境
source .venv/bin/activate # macOS/Linux
.venv\Scripts\activate # Windows
步骤 2：启动 API 服务器
方法 1 - 使用主脚本：
cd api_server
python app/main.py
方法 2 - 直接使用 uvicorn：
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
预期输出：
INFO: Started server process [12345]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
API 文档： 服务器运行后，访问交互式 API 文档：
- Swagger UI：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc
- OpenAPI JSON：http://localhost:8000/openapi.json
健康检查：
curl http://localhost:8000/health
# 预期输出：{"status": "healthy"}
5.2 启动前端 Electron 应用
步骤 1：打开新终端
保持后端服务器运行，打开一个新的终端窗口。
步骤 2：进入前端目录
cd tts-voice-app
步骤 3：启动开发模式
npm run dev
预期输出：
> tts-voice-app@1.0.0 dev
> electron-vite dev
VITE v4.x.x ready in xxx ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
Electron app starting...
Electron 应用将自动启动，开发模式下启用热重载。
开发模式功能：
- 热模块替换（HMR）实现即时 UI 更新
- Vue DevTools 集成
- 用于调试的控制台日志记录
- 主进程更改时自动重启
首次设置
首次启动 Electron 应用时，您需要下载必需的模型。
设置流程：
启动 Electron 应用
cd tts-voice-app npm run dev模型设置页面
- 应用自动检测缺失的模型
- 您将被重定向到模型设置页面
下载模型
- 点击"下载所有模型"按钮
- 要下载的模型：
- 预训练模型：4.56 GB
- G2PW 模型：588.86 MB
- FunASR：1.09 GB
- Faster Whisper：2.85 GB
- 总下载大小：约 9 GB
监控进度
- 实时进度条显示下载状态
- 预计时间：10-30 分钟（取决于连接速度）
- 下载可以暂停和恢复
设置完成
- 所有模型下载完成后，点击"继续"
- 您将被重定向到主 TTS 页面
- 应用现在可以使用了
故障排除：
- 如果下载失败，请检查您的互联网连接
- 确认您有约 10 GB 的可用磁盘空间
- 如需手动安装，请参见 3.3 节
功能概览
MoYoYo.tts 通过直观的界面提供强大的声音克隆和文本转语音功能：
快速模式为初学者提供简化的一键式工作流程。只需上传 5-30 秒的音频样本，选择您的质量预设（fast/standard/high），然后开始训练。系统自动处理所有管道阶段，包括音频处理、语音识别、特征提取和模型训练。在 10-40 分钟内，您将获得一个可用于文本转语音生成的自定义声音。
高级模式为经验丰富的用户提供对训练管道各个阶段的精细控制。您可以微调音频切片参数，在 ASR 模型之间选择（用于中文的 DamoASR，用于多语言的 Faster Whisper），调整训练轮数和批次大小，并监控每个阶段的详细进度。此模式非常适合优化质量或处理特定的音频特性。
文本转语音生成允许您立即使用任何训练好的声音将文本转换为自然发音的语音。调整说话速度（0.5x-2.0x），如果支持则选择情感语气，并在几秒钟内生成高质量的音频输出。系统支持多种语言，并提供实时音频播放和下载功能。
声音库管理将所有训练好的声音集中在一个地方。按语言或质量浏览、搜索和筛选声音。使用样本音频预览任何声音，导出模型进行备份或共享，并有效管理您的声音收藏。
有关详细的 API 文档和高级使用，请在后端服务器运行时访问交互式 Swagger UI：http://localhost:8000/docs。
故障排除
后端问题
端口已被占用
症状：启动服务器时出现 Address already in use 错误消息。
解决方案 1 - 在 .env 中更改端口：
echo "API_PORT=8001" >> .env
python app/main.py
解决方案 2 - 查找并终止使用端口的进程：
# macOS/Linux
lsof -ti:8000 | xargs kill -9
# Windows
netstat -ano | findstr :8000
taskkill /PID <pid> /F
数据库错误
症状：sqlite3.OperationalError 或数据库损坏消息。
解决方案 - 重置数据库：
# 备份现有数据库（可选）
cp ~/.moyoyo-tts/data/tasks.db ~/.moyoyo-tts/data/tasks.db.backup
# 删除损坏的数据库
rm ~/.moyoyo-tts/data/tasks.db
# 重启 API 服务器（数据库将被重新创建）
python app/main.py
Python 环境问题
症状：ModuleNotFoundError 或导入错误。
解决方案：
# 验证环境已激活
which python # 应显示 .venv 中的路径
# 重新安装所有依赖项
uv sync --reinstall
# 或从头强制重新安装
rm -rf .venv
uv sync
# 检查缺失的包
uv pip list
前端问题
无法连接到 API
症状：前端显示"无法连接到服务器"错误。
诊断：
# 检查后端是否正在运行
curl http://localhost:8000/health
# 检查网络连接
ping localhost
解决方案：
- 后端未运行：启动后端服务器（参见 5.1 节）
- 错误的端口：检查后端是否在端口 8000 上
- 防火墙：允许连接到 localhost:8000
- CORS 错误：检查后端
.env中的 CORS 设置
模型未下载
症状：模型下载失败或无限期挂起。
解决方案：
检查互联网连接：
curl -I https://www.modelscope.cn检查磁盘空间：
df -h # 需要约 10GB 可用空间手动下载：参见 3.3 节进行手动安装
代理问题：配置代理设置：
export http_proxy=http://proxy.example.com:8080 export https_proxy=http://proxy.example.com:8080
Electron 应用无法启动
症状：应用启动时崩溃或显示空白屏幕。
解决方案 1 - 清除缓存并重建：
# 进入前端目录
cd tts-voice-app
# 清除缓存
rm -rf node_modules package-lock.json dist .vite
# 重新安装依赖项
npm install
# 重建
npm run dev
解决方案 2 - 检查 Node.js 版本：
node --version # 应该是 >= 18.x
# 如需更新 Node.js
nvm install 18
nvm use 18
解决方案 3 - 检查 Electron 日志：
# macOS
~/Library/Logs/tts-voice-app/
# Linux
~/.config/tts-voice-app/logs/
# Windows
%APPDATA%\tts-voice-app\logs\
最后更新：2026-01-23 版本：1.0.0 维护者：MoYoYo.tts 开发团队