GPT-SoVITS WebUI 部署、微调与推理实战指南

本篇以仓库中的土耳其语官方文档 docs/tr/README.md 为主体，系统梳理 GPT-SoVITS 从环境搭建、预训练模型部署到数据集制作、模型微调与推理的完整工作流。读完本文，你将能够独立完成各平台（Windows/Linux/macOS/Docker）的安装部署，掌握 install.sh 参数与 Docker 服务配置，理解数据集 .list 格式与 WebUI 各功能页的底层实现，并熟悉 V2/V3/V4/V2Pro 各版本的差异与切换方式。

项目概述与核心特性

GPT-SoVITS-WebUI 是一个面向“少样本声音克隆”的 Web 界面项目，其核心卖点是：1 分钟的语音数据即可训练出可用的 TTS 模型。根据官方文档，项目提供四类核心能力：

1. 零样本 TTS（Zero-shot TTS）：输入约 5 秒的人声参考样本，即可直接进行文本转语音，无需任何训练；
2. 少样本 TTS（Few-shot TTS）：用约 1 分钟的训练数据对模型做微调，可显著提升音色相似度与真实感；
3. 跨语言推理：支持用与训练集不同语言的文本做推理，目前覆盖英语、日语、中文、粤语、韩语；
4. WebUI 集成工具链：内置人声分离（UVR5）、数据集自动切分、中文 ASR 转写与文本标注工具，帮助零基础用户完成训练集与 GPT/SoVITS 模型的制作。

从源码结构看，项目的主入口 webui.py 通过 Popen 子进程统一管理“人声分离、语音切分、降噪、ASR、标注、文本分词与特征提取、自监督特征提取、语义 Token 提取、GPT 训练、SoVITS 训练、TTS 推理”等模块，每个模块对应 GPT_SoVITS/ 与 tools/ 下的独立脚本，这与文档描述的“工具链集成”一一对应。

测试环境与快速安装

已测试环境矩阵

官方文档给出的 Python / PyTorch / 设备组合如下，部署前可先对照自己的硬件选择路径：

Python Version	PyTorch Version	Device
Python 3.10	PyTorch 2.5.1	CUDA 12.4
Python 3.11	PyTorch 2.5.1	CUDA 12.4
Python 3.11	PyTorch 2.7.0	CUDA 12.8
Python 3.9	PyTorch 2.8.0dev	CUDA 12.8
Python 3.9	PyTorch 2.2.2	Apple silicon
Python 3.11	PyTorch 2.7.0	Apple silicon
Python 3.9	PyTorch 2.2.2	CPU

三种操作系统的一键安装

Windows 用户（win>=10 已测试）可以直接下载官方整合包，双击 go-webui.bat 启动 WebUI；Linux 与 macOS 用户则通过 conda + 安装脚本完成：

# Windows (PowerShell)
conda create -n GPTSoVits python=3.10
conda activate GPTSoVits
pwsh -F install.ps1 --Device <CU126|CU128|CPU> --Source <HF|HF-Mirror|ModelScope> [--DownloadUVR5]

# Linux
conda create -n GPTSoVits python=3.10
conda activate GPTSoVits
bash install.sh --device <CU126|CU128|ROCM|CPU> --source <HF|HF-Mirror|ModelScope> [--download-uvr5]

# macOS（注意：文档提示 Mac 上用 GPU 训练的模型结果质量明显更低，故暂时建议使用 CPU 路径）
conda create -n GPTSoVits python=3.10
conda activate GPTSoVits
bash install.sh --device <MPS|CPU> --source <HF|HF-Mirror|ModelScope> [--download-uvr5]

结合 install.sh 源码，各参数的实际行为可以进一步确认：

• --device 是必填项，可选 CU126 / CU128 / ROCM / MPS / CPU。脚本会按该值从 PyTorch 官方 wheel 源安装对应 CUDA 12.6 / 12.8、ROCm 6.2 或 CPU 版本的 torch；若检测不到 Nvidia 驱动或 /opt/rocm，会自动回退到 CPU；
• --source 是必填项，可选 HF / HF-Mirror / ModelScope，决定预训练模型、G2PW 模型、UVR5 权重、NLTK 数据与 Open JTalk 日语词典的下载源；
• --download-uvr5 为可选项，决定是否额外下载 UVR5 声伴分离权重到 tools/uvr5/uvr5_weights；
• 脚本在装依赖之前会先补齐构建环境：Linux 下若 GCC 低于 11 会从 conda-forge 安装 gcc/gxx 与对应 sysroot，macOS 下自动触发 Xcode Command Line Tools 安装，并统一安装 FFmpeg、CMake、unzip。

也就是说，install.sh 成功运行后，文档“预训练模型”章节的 1、2、3 步（模型下载与解压）已自动完成。

手动安装（依赖与 FFmpeg）

如果不走脚本，手动安装分两步。

第一步，安装 Python 依赖：

conda create -n GPTSoVits python=3.10
conda activate GPTSoVits

pip install -r extra-req.txt --no-deps
pip install -r requirements.txt

第二步，按平台安装 FFmpeg（GPT-SoVITS 的音频读写大量依赖它）：

• Conda 用户：conda activate GPTSoVits && conda install ffmpeg
• Ubuntu/Debian：sudo apt install ffmpeg && sudo apt install libsox-dev
• Windows：下载 ffmpeg.exe 与 ffprobe.exe 放到 GPT-SoVITS 根目录，并安装 Visual Studio 2017 运行库
• macOS：brew install ffmpeg

Docker 部署

文档同时提供了基于 Docker 的部署方式。由于代码演进快于镜像发布，建议先查看镜像仓库中的最新 tag 再选择合适标签。关键约定如下：

• Lite 后缀表示镜像内不包含 ASR 模型与 UVR5 模型；UVR5 模型可手动下载，ASR 模型则会在需要时由程序自动下载。从 docker-compose.yaml 可见，Lite 服务额外挂载了 tools/asr/models 与 tools/uvr5/uvr5_weights 两个卷，与“Lite 镜像 + 宿主机模型目录”的配合方式吻合；
• Docker Compose 会绑定当前目录的全部文件，因此运行前务必切到项目根目录并拉取最新代码；
• 可选：使用仓库自带的 Dockerfile 自行构建镜像，获取最新变更。

环境变量：is_half 控制是否使用 fp16 半精度，GPU 支持时可设为 true 以节省显存（compose 文件中各服务的默认值即为 is_half=true）。

共享内存：Windows 上 Docker Desktop 的默认共享内存偏小，容易引发异常，文档建议按物理内存把 compose 中的 shm_size 调大（如 16g，当前文件默认即为 16g）。

服务选择：docker-compose.yaml 定义了四类服务，均映射了 9871–9874 与 9880 端口：

服务名	说明
GPT-SoVITS-CU126 / GPT-SoVITS-CU128	含完整功能的全量版（内置 ASR、UVR5 模型）
GPT-SoVITS-CU126-Lite / GPT-SoVITS-CU128-Lite	依赖更少、功能受限的轻量版

启动指定服务：

docker compose run --service-ports <GPT-SoVITS-CU126-Lite|GPT-SoVITS-CU128-Lite|GPT-SoVITS-CU126|GPT-SoVITS-CU128>

本地构建镜像与进入运行中的容器：

# 自行构建镜像
bash docker_build.sh --cuda <12.6|12.8> [--lite]

# 进入容器 Bash
docker exec -it <GPT-SoVITS-CU126-Lite|GPT-SoVITS-CU128-Lite|GPT-SoVITS-CU126|GPT-SoVITS-CU128> bash

预训练模型部署清单

install.sh 成功运行可跳过前 3 步，其余步骤按需手动完成。文档给出的完整清单为：

1. 下载 GPT-SoVITS 预训练模型，放入 GPT_SoVITS/pretrained_models；
2. 下载 G2PWModel 压缩包，解压并重命名为 G2PWModel 后放入 GPT_SoVITS/text（仅中文 TTS 需要）；
3. 下载 UVR5 权重（人声/伴奏分离、去混响），放入 tools/uvr5/uvr5_weights：
   • 若使用 bs_roformer 或 mel_band_roformer 模型，需把模型与对应配置文件一起放入该目录，两文件名除扩展名外必须一致，且名称中需包含 roformer 字样以被识别为 roformer 类模型。例如 bs_roformer_ep_368_sdr_12.9628.ckpt 与 bs_roformer_ep_368_sdr_12.9628.yaml 是一对，kim_mel_band_roformer.ckpt 与 kim_mel_band_roformer.yaml 是另一对；
   • 建议在文件名中直接体现模型类型（如 mel_mand_roformer、bs_roformer），否则程序会通过配置文件特征推断类型；
4. 中文 ASR：下载 Damo 的 ASR、VAD、标点恢复三个模型，放入 tools/asr/models；
5. 英语/日语 ASR：下载 Faster-Whisper Large V3 模型放入同一目录，也可选用同系列更小、更省磁盘的模型。

install.sh 中对应的自动逻辑可以佐证该清单：它检查 GPT_SoVITS/pretrained_models/sv 是否存在来跳过预训练包下载、检查 GPT_SoVITS/text/G2PWModel 来跳过 G2PW 下载，并在 --download-uvr5 开启时把 UVR5 权重解压到 tools/uvr5。

数据集格式（.list 文件）

TTS 训练集的标注文件为 .list 文本，每行四段、以竖线分隔：

vocal_path|speaker_name|language|text

语言标签字典：

• zh：中文
• ja：日语
• en：英语
• ko：韩语
• yue：粤语

示例行：

D:\GPT-SoVITS\xxx/xxx.wav|xxx|en|I like playing Genshin.

启动 WebUI：微调工作流与推理

打开训练 WebUI

• 整合包用户：双击 go-webui.bat（或执行 go-webui.ps1）即可启动；当前仓库根目录提供 go-webui.bat 与 go-webui.ps1。
• 其他用户：

python webui.py <语言(可选)>

文档同时给出了 V1 底模的启动方式（go-webui-v1.bat / python webui.py v1 <语言>，或在 WebUI 内手动切换版本）。需要说明的是，从当前源码结构看，webui.py 入口第一行将 os.environ["version"] 固定为 "v2Pro"，且命令行参数仅解析末尾的语言参数（webui.py 中 sys.argv[-1] 与 scan_language_list() 比对），语言取值为 tools/i18n/locale 下的 JSON 语言码（如 zh_CN、en_US、tr_TR），未识别时回退为系统语言；因此“在命令行直接切 v1”这一用法应以你实际使用的发行版本为准。

启动后，主 WebUI 按“数据集处理 → 训练 → 推理”的页签组织流程。文档推荐的路径自动填充工作流为：

1. 填写语音路径；
2. 语音切分（切成短片段）；
3. 语音降噪（可选）；
4. ASR 转写；
5. 校对 ASR 转写文本；
6. 切换到下一页签执行微调。

从源码看，这一条流水线正是 webui.py 中各 open_* 函数串起来的子进程：open_slice 调用 tools/slice_audio.py、open_denoise 调用 tools/cmd-denoise.py、open_asr 按所选模型调用 tools/asr 下的 funasr_asr.py 或 fasterwhisper_asr.py（ASR 结果会写出为 输出目录/输入目录名.list）、标注页启动 tools/subfix_webui.py。完成数据集准备后，特征提取三步分别对应 GPT_SoVITS/prepare_datasets/ 下的 1-get-text.py（文本分词，产出 2-name2text.txt）、2-get-hubert-wav32k.py（Hubert 自监督特征 + wav32k）、3-get-semantic.py（SoVITS 语义 Token，产出 6-name2semantic.tsv）；v2Pro 版本还会额外执行 2-get-sv.py 提取说话人向量。训练阶段则依据版本选择脚本：v1/v2/v2Pro 走 GPT_SoVITS/s2_train.py 与 GPT_SoVITS/s1_train.py，v3/v4 走 GPT_SoVITS/s2_train_v3_lora.py，配置文件分别取自 GPT_SoVITS/configs 下的 s2.json / s2v2Pro.json 与 s1longer.yaml / s1longer-v2.yaml。

打开推理 WebUI

• 整合包用户：go-webui-v2.bat / go-webui-v2.ps1，随后访问 1-GPT-SoVITS-TTS/1C-inference 页签；
• 其他用户：

python GPT_SoVITS/inference_webui.py <语言(可选)>
# 或
python webui.py

再在 1-GPT-SoVITS-TTS/1C-inference 中打开推理页。从 webui.py 的 change_tts_inference 可以看到，推理页支持勾选“批量推理加速”，开启时会改用 GPT_SoVITS/inference_webui_fast.py，并通过环境变量 gpt_path、sovits_path、cnhubert_base_path、bert_path、_CUDA_VISIBLE_DEVICES、is_half 把选中的 GPT/SoVITS 权重与设备传给子进程。训练产出的权重默认按版本分别落在 GPT_weights_v*、SoVITS_weights_v* 目录（见 config.py 中的目录映射），启动时由 get_weights_names() 扫描进下拉列表。

版本说明：V2 / V3 / V4 / V2Pro

官方文档对四个版本的关键变化有明确记载：

V2：新增韩语与粤语支持；优化文本前端；预训练数据从 2k 小时扩展到 5k 小时；对低质量参考音频提升了合成质量。从 V1 环境升级需要更新 requirements.txt、拉取最新代码，并下载 v2 预训练模型放入 GPT_SoVITS/pretrained_models/gsv-v2final-pretrained（中文还需 G2PW 模型）。

V3：音色相似度显著提高，逼近目标说话人所需训练数据更少（底模本身、不微调时相似度也已改善）；GPT 模型更稳定，重复与跳字现象减少，更容易产出丰富的情绪表达。从 V2 升级到 V3 需要下载 s1v3.ckpt、s2Gv3.pth 及 BigVGAN 的 models--nvidia--bigvgan_v2_24khz_100band_256x 目录并放入 GPT_SoVITS/pretrained_models；另有关于音频超分模型（24k 升 48k）下载的说明见 tools/AP_BWE_main/24kto48k。

V4：修复 V3 因非整数倍上采样引入的“金属声”，并直接输出 48kHz 音频以防止音质发闷（V3 仅 24kHz）。作者认为 V4 可替代 V3，但仍建议自行测试验证。升级需下载 gsv-v4-pretrained/s2v4.ckpt 与 gsv-v4-pretrained/vocoder.pth 放入 GPT_SoVITS/pretrained_models。

V2Pro：相比 V2 显存占用略高，但综合表现优于 V4，同时保持相同的硬件成本与速度优势。文档同时指出：V1/V2 与 V2Pro 系列功能相近，V3/V4 功能相近；在平均质量偏低的训练集上 V1/V2/V2Pro 往往比 V3/V4 更稳；且 V3/V4 的音色更贴近参考音频而非整体训练集。升级需下载 v2Pro/s2Dv2Pro.pth、v2Pro/s2Gv2Pro.pth、v2Pro/s2Dv2ProPlus.pth、v2Pro/s2Gv2ProPlus.pth 与 sv/pretrained_eres2netv2w24s4ep4.ckpt 放入 GPT_SoVITS/pretrained_models。

这些版本与文件名的对应关系在 config.py 中有直接佐证：pretrained_sovits_name 与 pretrained_gpt_name 两个字典按 v1/v2/v3/v4/v2Pro/v2ProPlus 键维护各版本底模路径（例如 v3/v4/v2Pro 共用 GPT 底模 s1v3.ckpt，v2Pro 的 SoVITS 底模为 v2Pro/s2Gv2Pro.pth）。webui.py 的 set_default() 也体现了版本差异：非 v3/v4 版本默认 SoVITS 训练 8 epoch（每 4 epoch 存一次），v3/v4 则默认 2 epoch（每 1 epoch 存一次），并按显存自动估算 batch size。

（扩展）命令行方式执行各工具

文档最后附了一组不走 WebUI 的命令行用法，适合脚本化与批量处理。

启动 UVR5 声伴分离 WebUI：

python tools/uvr5/webui.py "<infer_device>" <is_half> <webui_port_uvr5>

数据集语音切分。文档示例写作 python audio_slicer.py，在当前仓库中对应的实现是 tools/slice_audio.py，其参数按位置传入，含义可参照 tools/slicer2.py 封装的 Slicer 类及 tools/slice_audio.py 中的注释：

python tools/slice_audio.py \
    "<原始音频文件或目录路径>" \
    "<切分片段保存目录>" \
    <声音阈值> \
    <每个片段的最短时长> \
    <相邻片段之间的最短间隔> \
    <音量曲线计算的步长>

参数语义（源码注释）：threshold——低于该值视为静音的候选切割点；min_length——单段最小时长，过短的开头会与后段合并直至达标；min_interval——两次切割的最短间隔；hop_size——音量曲线步长，越小越精细但计算量越高；切分按 32kHz 重采样进行，输出为 原文件名_起始帧_结束帧.wav。

中文 ASR 转写（FunASR 后端，仅中文）：

python tools/asr/funasr_asr.py -i <输入> -o <输出>

其他语言 ASR 转写（Faster-Whisper 后端）。注意该后端没有进度条，GPU 上可能出现耗时延迟：

python tools/asr/fasterwhisper_asr.py -i <输入> -o <输出> -l <语言>

两个脚本都支持 -s 指定模型尺寸（fasterwhisper_asr.py、funasr_asr.py 的 argparse 定义），WebUI 内部调用时（webui.py）还会额外传 -p 指定 fp16/fp32 精度；ASR 输出统一写入 <输出目录>/<输入目录名>.list，正好与上文数据集格式衔接。

小结与延伸阅读

本文完整继承了 docs/tr/README.md 的章节骨架——特性、测试环境、三平台安装、手动安装、Docker、预训练模型清单、数据集格式、微调/推理流程、V2–V4/V2Pro 版本说明与命令行工具——并逐条对照仓库源码（install.sh、webui.py、config.py、docker-compose.yaml、tools/slice_audio.py、tools/asr）补充了参数语义、子进程调用链与版本差异的实现依据。后续可继续阅读：

• docs/tr/Changelog_TR.md：仓库内土耳其语版更新日志，逐条记录各次提交的变更内容；
• Colab-WebUI.ipynb / Colab-Inference.ipynb：官方提供的 Colab 训练与推理脚本；
• GPT_SoVITS/configs：s1/s2 系列训练配置，是理解训练超参的原始出处。