# E022 Qwen3-TTS 安装与使用命令

实测日期为2026年11月8日。Windows 11 x64、Python 3.12.10、RTX 3060 Laptop 6GB、驱动546.30。先安装64位Python 3.12，并用 py -3.12 --version 确认。以下组合已经在本机验证，其他电脑应先核对 PyTorch 官方安装选择器和驱动兼容性。

工作文件夹可以放在自己选择的位置。参考录音使用你自己或已获得本人同意的声音。

## 1. 建立干净环境

```powershell
mkdir E022_qwen3tts
cd E022_qwen3tts
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
```

后续直接调用虚拟环境内的程序，不需要修改PowerShell执行策略，也不依赖激活脚本。

## 2. 安装本机验证的CUDA组合，再装Qwen3-TTS

官方历史版本页仍提供此命令。实际首装未指定版本号，从官方cu118索引解析到的版本即以下组合；为复现将版本写明。

```powershell
.\.venv\Scripts\python.exe -m pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu118
.\.venv\Scripts\python.exe -m pip install -U qwen-tts
.\.venv\Scripts\python.exe -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
.\.venv\Scripts\python.exe -m pip check
```

本次解析：qwen-tts0.1.1、transformers4.57.3、accelerate1.12.0、Gradio6.17.3。CUDA检测输出 `True`，实际GPU矩阵运算与语音生成均通过。若为False，先核对是否NVIDIA显卡、驱动与安装包是否兼容，不能只凭False断定装成CPU版。

官方入口：
- https://pytorch.org/get-started/locally/
- https://pytorch.org/get-started/previous-versions/#v2-7-1
- https://github.com/QwenLM/Qwen3-TTS

## 3. 从ModelScope下载模型

```powershell
.\.venv\Scripts\python.exe -m pip install -U modelscope
.\.venv\Scripts\modelscope.exe download --model Qwen/Qwen3-TTS-12Hz-0.6B-Base --local_dir ./Qwen3-TTS-12Hz-0.6B-Base
```

本次ModelScope1.40.2。该Base快照14个文件合计2,516,106,826字节（约2.52GB/2.34GiB），已经包含 `speech_tokenizer` 子目录，无需另外下载独立Tokenizer仓库。不要漏掉这个子目录。安装环境和临时文件还需要额外磁盘空间；这是模型大小，不是安装总占用。

## 4. 启动本机网页

```powershell
.\.venv\Scripts\qwen-tts-demo.exe ./Qwen3-TTS-12Hz-0.6B-Base --ip 127.0.0.1 --port 8000 --no-flash-attn
```

浏览器打开 http://127.0.0.1:8000 。本机实测HTTP上传WAV并生成成功。这个地址供当前电脑使用；未开启公网分享，不需要HTTPS上传本地文件。不要照搬官方远程麦克风HTTPS场景的要求。

关键修正：本次CLI默认开启FlashAttention2，源稿不加选项的命令实际报 `ImportError: ... flash_attn ... not installed`。加上 `--no-flash-attn` 后通过，不为该教程在Windows编译FlashAttention。

本次未安装系统SoX可执行程序，导入会显示 `SoX could not be found`；pip的sox包已安装。这条提示在已测试的PCM WAV上传、克隆、合成及下载流程中没有阻断；不能推断所有格式或所有SoX功能都可用。本次Gradio6还显示theme/css参数位置变化警告，核心流程实测通过，没有修改第三方包。

## 5. 界面使用

1. 在“Clone & Generate / 克隆并合成”上传本人或已获本人同意的 `my_voice.wav`。
2. 在Reference Text填写参考录音原话；本教程不勾选效果受限的x-vector-only选项。
3. Target Text填写新文案，Language选Chinese，点击Generate。
4. 等Status明确显示Finished，试听右侧Output Audio，下载WAV；不要把左侧参考音频当成生成结果。
5. 短句分段生成。改一段就重做一段；数字、英文、专有名词逐项回听。字幕保留应显示的实际数值/名称，发音输入可以另行调整。

## 6. Python备用路线（本次GPU/CPU实测采用同一API）

把自己参考录音的原话填入 `ref_text`，脚本存为 `generate.py`，放在模型文件夹和 `my_voice.wav` 所在的工作目录。

```python
import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "./Qwen3-TTS-12Hz-0.6B-Base",
    device_map="cuda:0",
    dtype=torch.bfloat16,
    attn_implementation="sdpa",
    local_files_only=True,
)
wavs, sr = model.generate_voice_clone(
    text="这里写你想生成的视频旁白。",
    language="Chinese",
    ref_audio="my_voice.wav",
    ref_text="这里替换成你自己参考录音的逐字稿。",
)
sf.write("output.wav", wavs[0], sr)
```

```powershell
.\.venv\Scripts\python.exe .\generate.py
```

仅用CPU时，本机测试使用 `device_map="cpu"`、`dtype=torch.float32` 和 `torch.set_num_threads(8)`；15秒左右输出约需71秒，不承诺其他CPU速度。生成需先完成模型下载。