04 — 环境与安装

为什么需要多个虚拟环境

GPT-SoVITS 依赖一组较旧/固定版本的 ML 包（torch、transformers、librosa 等），与 faster-whisper、llama-cpp-python 所需的新栈存在冲突。强行合并到一个环境会很脆弱，因此项目使用两个必需 venv，并可选第三个给 Qwen3-TTS：

Venv	Python	用途	创建方式
`venvs/venv_main`	3.11	Vocal10n 主程序：UI、STT、LLM、pipeline	`setup_env.ps1`
`venvs/venv_tts`	3.11	GPT-SoVITS HTTP 服务（`api_v2.py`）	`setup_env.ps1`
`venvs/venv_qwen3tts`	3.11	Qwen3-TTS HTTP 服务	手动

启动脚本 start.ps1 会从 venv_tts 启 GPT-SoVITS、从 venv_main 启主应用。二者通过 127.0.0.1:9880（TTS）和 127.0.0.1:5124（OBS）通信。

一次性安装

前置条件：

Windows 10/11。
可通过 py -3.11 调用 Python 3.11。
NVIDIA 驱动 + CUDA 12.x 运行库。
Visual C++ Build Tools（llama-cpp-python 回退源码编译时需要）。

步骤：

git clone https://github.com/itsLittleKevin/Vocal10n.git
cd Vocal10n

# 创建 venv_main 和 venv_tts，并安装依赖
.\setup_env.ps1

# 放置模型：
#   models/llm/Qwen3-4B-Instruct-2507.Q4_K_M.gguf
#   vendor/GPT-SoVITS/GPT_SoVITS/pretrained_models/...
#   reference_audio/<your_clone_sample>.wav (+ 对应 .txt)

如果 llama-cpp-python 未安装到 CUDA 版本，可显式安装匹配 wheel：

venvs\venv_main\Scripts\pip install llama-cpp-python `
  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121

setup_env.ps1 支持参数：

-SkipMain / -SkipTTS：仅更新一个 venv。
-Force：删除并重建。

所需模型

文件	路径	说明
Whisper large-v3-turbo	首次使用下载到 `~/.cache/huggingface`	由 `stt.model_size` 控制
Qwen3-4B GGUF	`models/llm/Qwen3-4B-Instruct-2507.Q4_K_M.gguf`	路径在 `translation.model_path`
GPT-SoVITS 预训练权重	`vendor/GPT-SoVITS/GPT_SoVITS/pretrained_models/`	按上游 README 放置
参考 WAV + 文本	`reference_audio/` 与 `vendor/GPT-SoVITS/reference_audio/`	路径由 `tts.ref_audio_path` 指定

启动

.\start.ps1

脚本会：

检查 venv_main 是否存在。
如果 9880 空闲且存在 vendor/GPT-SoVITS/api_v2.py，后台隐藏启动 SoVITS 并记录 PID。
设置 PYTHONPATH（包含 vendor/GPT-SoVITS/ 与 vendor/GPT-SoVITS/GPT_SoVITS/）以保证 API 相对导入可解析。
在 venv_main 中运行 python -m vocal10n.app。
主程序退出后，如果 SoVITS 仍在运行则自动终止。

start.bat 是对该 PowerShell 脚本的薄封装。