Windows 11 上本地部署 Qwen3-TTS

    在 Windows 11 上本地部署 Qwen3-TTS，主要有一键整合包、Python 包安装、源码部署和 Docker/WSL2 四种方案。对于大多数用户，方案一（一键整合包） 是最简单快捷的选择；如果你需要更灵活的控制或集成到开发工作流中，方案二（通过 pip 安装） 则更为推荐。

前置条件

在开始之前，请确保系统已准备好以下基础环境：

方案一：使用一键整合包/便携版（最简单）

这是最快捷的方式，适合不想配置 Python 环境的用户。社区已有多个成熟的整合包：

选项 A：Qwen3-TTS 一键整合包

1. 下载整合包：访问社区分享的整合包链接下载（如 CSDN 或网盘资源）。

2. 解压并运行：解压到任意文件夹，运行 install.bat 安装依赖（仅需一次）。

3. 启动应用：根据需要选择对应的启动脚本（如 WebUI、声音克隆、语音设计等），双击运行即可。

选项 B：SelfVox（推荐）

SelfVox 是一个免环境配置的桌面 GUI 工具，支持声音克隆和 VOICEVOX 兼容 API。

1. 下载安装：从 SelfVox Releases 下载 SelfVox-Setup.exe 并运行。

2. 自动配置：首次启动时会自动完成 Python 环境搭建和模型下载（约 4.5GB），进度通过弹窗显示。

3. 启动使用：双击 SelfVox.exe，点击 Start Server 即可使用。

注意：SelfVox 使用端口 50021，与 VOICEVOX 冲突，使用前需先关闭 VOICEVOX。

选项 C：Qwen3-TTS Portable PRO

支持多语言、声音克隆、声音设计等功能的一键便携版。

1. 下载并解压压缩包。

2. 运行 portable/install.bat 安装依赖。

3. 运行 portable/run.bat 启动应用。

选项 D：Qwen-TTS Studio（桌面应用）

基于 Compose Multiplatform 构建的桌面应用，支持 Windows 和 Linux。

1. 从 GitHub Releases 下载 MSI 安装包或便携 ZIP。

2. 根据是否已安装 CUDA 运行时，选择 windows-cuda-system（较小）或 windows-cuda-bundled（包含 CUDA DLL）。

3. 直接运行，无需 Python 环境。

方案二：通过 pip 安装（推荐）

这种方式更灵活，适合希望将 Qwen3-TTS 集成到 Python 项目中的开发者。

步骤：

1. 安装 Python 3.12：从 Microsoft Store 或 Python 官网 安装，务必勾选 Add Python to PATH。

2. 创建虚拟环境：

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
.\venv\Scripts\activate

3. 安装 qwen-tts 包：

# 升级 pip
python -m pip install --upgrade pip

# 安装 qwen-tts（包含 PyTorch、transformers 等）
pip install -U qwen-tts

这将自动安装约 2-3GB 的依赖包。

4. 验证 GPU 支持：

python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
# 应输出: CUDA available: True

5. （可选）安装 Flash Attention 2：显著加速 NVIDIA GPU 推理，但编译可能需要 10-20 分钟：

pip install flash-attn --no-build-isolation

如果编译失败可跳过，服务仍可正常工作，只是速度稍慢。

6. 下载模型：模型在首次加载时会自动下载，也可手动下载到本地目录：

# 安装 ModelScope CLI（国内用户推荐）
pip install -U modelscope

# 下载 TTS 模型
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice

7. 基本使用：

from qwen_tts import QwenTTS

tts = QwenTTS(model_name="Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice")
audio = tts.generate("你好，这是 Qwen3-TTS 的语音合成测试。")

方案三：从源代码克隆安装（完整功能）

这种方式可以获得功能最完整的本地实现，包含 Gradio Web UI 和多种音色选择。

步骤：

1. 克隆仓库并创建虚拟环境：

git clone https://github.com/SUP3RMASS1VE/Qwen3-TTS.git
cd Qwen3-TTS

python -m venv venv
venv\Scripts\activate

2. 安装依赖：

# 安装 uv（快速包安装器）
pip install uv

# 安装项目依赖
uv pip install -r requirements.txt

# 安装 CUDA 12.8 版 PyTorch
uv pip install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 --index-url https://download.pytorch.org/whl/cu128

# 安装 Triton for Windows
uv pip install triton-windows==3.3.1.post19

3. （可选）安装 Flash Attention：

uv pip install https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.4.10/flash_attn-2.8.2+cu128torch2.7-cp310-cp310-win_amd64.whl

4. 启动应用：

python app.py

Gradio UI 将启动在 http://localhost:7860，支持声音设计、声音克隆和自定义语音生成。

5. 支持的模型：

硬件要求：0.6B 模型需 8GB+ 显存，1.7B 模型需 16GB+ 显存。

方案四：Docker / WSL2 部署（环境隔离）

如果希望完全隔离运行环境，可以使用 Docker 配合 WSL2 部署。

步骤：

1. 启用 WSL2（以管理员身份运行 PowerShell）：

wsl --install

重启后完成 Ubuntu 用户设置，验证：wsl -l -v 应显示 VERSION 为 2。

2. 安装 Docker Desktop：从官网下载，安装时勾选 Use the WSL 2 based engine，在 Settings → Resources → WSL Integration 中启用 Ubuntu。

3. 拉取并运行镜像：

# 拉取镜像
docker pull csdns/qwen3-tts-12hz-1.7b-voicedesign:latest

# 运行容器
docker run -d -p 7860:7860 --name qwen3-tts csdns/qwen3-tts-12hz-1.7b-voicedesign:latest

4. 访问界面：打开浏览器访问 http://localhost:7860。

方案五：GGUF + llama.cpp（极致性能）

如果追求极致的推理速度，可以使用 GGUF 量化模型配合 llama.cpp。

步骤：

1. 安装 llama.cpp：

winget install llama.cpp

2. 下载 GGUF 模型：

# 从 Hugging Face 下载
llama download -hf ggml-org/Qwen3-TTS-12Hz-1.7B-Base-GGUF:Q4_K_M

3. 启动推理服务：

llama serve -hf ggml-org/Qwen3-TTS-12Hz-1.7B-Base-GGUF:Q4_K_M

性能参考：在 RTX 5050 上，RTF（实时率）可达 0.35（1 秒音频仅需 0.35 秒生成）。1.7B 模型显存占用约 1.8GB。

常见问题排查

总结