Qwen TTS Deployment Guide | Qwen TTS 部署指南

This repository provides instructions for deploying and running Qwen3 Text-to-Speech (TTS) services.
本项目用于部署和运行 Qwen3 文本转语音（TTS） 服务，支持本地 Conda 环境与 Docker 两种部署方式。

---

Table of Contents | 目录

• Requirements | 环境要求
• Initial Setup | 初次创建环境
• Dependency Installation | 安装依赖
• SoX Installation (Windows) | 安装 SoX（Windows）
• Model Download | 模型下载
• Run & Stop | 启动与停止
• Docker Deployment | Docker 构建方式

---

Requirements | 环境要求

• OS：Windows（Docker 部署可跨平台）
• Python：3.12
• CUDA：12.4（GPU 推理需要）
• Conda（Anaconda / Miniconda）
• NVIDIA Driver correctly installed

---

Initial Setup | 初次创建环境

Create Python 3.12 Conda Environment

创建 Python 3.12 隔离环境

conda create -n qwen-tts python=3.12 -y

Activate Environment

激活环境

conda activate qwen-tts

---

Dependency Installation | 安装依赖

Install PyTorch (CUDA 12.4)

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

Install Qwen TTS Core Library

安装 Qwen TTS 官方核心库

pip install -U qwen-tts

Install Web Service & Audio Dependencies

安装 Web 服务与音频处理组件

pip install fastapi uvicorn jinja2 python-multipart soundfile

---

SoX Installation (Windows) | 安装 SoX（Windows）

SoX is required for audio processing during TTS inference.
SoX 是 TTS 推理所需的音频处理工具。

Download | 下载

Official website 官方地址：
https://sourceforge.net/projects/sox/files/sox/

Download win32.exe installer.
下载 win32.exe 安装包。

Install | 安装

Recommended installation path:
建议安装路径：

C:\sox

Environment Variable | 环境变量配置

1. Right-click This PC → Properties
2. Advanced system settings → Environment Variables
3. Add the following path to Path (System Variables)

C:\sox

Verify Installation | 验证安装

Restart terminal and run:

sox --version

If the version is displayed, installation is successful.
若显示版本号，则表示安装成功。

---

Model Download | 下载模型

Install ModelScope

pip install modelscope

Download Qwen TTS Models

下载 Qwen TTS 模型

modelscope download   --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice   --local_dir ./Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice

modelscope download   --model Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign   --local_dir ./Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign

modelscope download   --model Qwen/Qwen3-TTS-12Hz-1.7B-Base   --local_dir ./Qwen/Qwen3-TTS-12Hz-1.7B-Base

---

Run & Stop | 启动与停止

Start Service | 启动服务

conda activate qwen-tts
python main.py

Exit Conda Environment | 退出环境

conda deactivate

---

Docker Deployment | Docker 构建方式

If you prefer containerized deployment, use Docker Compose.
如果你希望使用容器化部署，可使用 Docker Compose。

Build & Run

docker-compose up -d --build

---

Notes | 说明

• This guide assumes basic knowledge of Conda and Docker.
  本文档默认你具备 Conda 与 Docker 的基础使用经验。
• For GPU Docker usage, ensure nvidia-container-toolkit is installed.
  使用 GPU Docker 请确保已安装 nvidia-container-toolkit。
• Model files are large; initial download may take time.
  模型体积较大，首次下载耗时较长，请耐心等待。

---