最新Qwen3-TTS 从零到运行全流程教程（Windows + GPU 支持）
2026-01-31
AI
type
Post
status
Published
date
Jan 31, 2026
slug
qwen3-tts
summary
本教程带你完整搭建 Qwen3-TTS 运行环境，从 Python 安装与虚拟环境配置，到 GPU 支持的 PyTorch 安装、flash-attn 优化，再到 模型下载与管理，最终实现本地模型快速启动与测试。教程内容清晰、按步骤操作，适合初学者快速上手 Qwen3-TTS 并进行语音生成实验。
tags
工具
AI
必看精选
category
AI
icon
password
前言：为了方便，我这里使用的是最基础的模型。你可以根据需要使用Qwen3-TTS官方提供的其它几个模型。
1️⃣ 安装 Python 环境
在开始后续操作之前，我们需要先准备好 Python 运行环境。
本教程将统一使用 Python 3.12.10，请务必按照说明安装对应版本，避免后续出现兼容性问题。
📥 下载 Python
- 打开 Python 官方下载页面：
- 在页面中找到并下载 Python 3.12.10 对应你系统的安装包
- Windows：
Windows installer (64-bit) - macOS：
macOS installer - Linux：使用系统自带包管理器或源码安装（后文会单独说明）
💡 建议：尽量从 Python 官网下载，避免使用第三方来源，以防版本不一致或被篡改。
🛠️ 安装 Python
- 双击 打开刚刚下载好的 Python 安装程序
- 在安装界面 务必勾选 下面这个选项：
- ✅ Add Python to PATH（添加到系统环境变量）
⚠️ 如果没有勾选该选项，后续在命令行中将无法直接使用 python，需要手动配置环境变量，操作会相对繁琐。
- 勾选完成后，点击 Install Now，等待安装完成即可
安装完成后，你的电脑中就已经具备了基础的 Python 运行环境。
2️⃣ 安装 Python 版本管理器（强烈推荐）
虽然已经成功安装了 Python，但在实际使用中，我们经常会遇到这些情况：
- 不同项目需要 不同版本的 Python
- 想快速查看当前默认 Python 版本
- 希望方便地 安装、卸载、管理多个 Python 版本
因此，这里强烈推荐再安装一个 Python 版本管理器，它可以帮助你：
- 📌 管理多个 Python 版本
- 🧹 更干净地安装与卸载 Python
- 🧠 避免版本混乱导致的环境问题
💡 使用版本管理器几乎是开发者的标配，后面所有教程也都会基于它来操作。
⚙️ 使用 Python 版本管理器
安装完成后，直接保持默认设置即可，无需额外修改任何选项。
安装完成后：
- 打开 命令行终端
- Windows：
Win + R→ 输入cmd - 或在开始菜单中搜索「命令提示符」
- 输入以下命令并回车：
该命令是 Python 版本管理器提供的命令，用于查看：
- 当前已经安装的 Python 版本
- 哪个版本是默认使用的
❗ 如果 py list 执行报错怎么办？
如果你在执行
py list 时提示命令不存在或报错，大概率原因如下：在前面「手动安装 Python」的过程中，系统自动安装了 旧版 Python Launcher，与当前使用的版本管理器产生了冲突。
✅ 解决方法
- 打开 系统设置 → 应用 / 已安装的应用
- 搜索：
Python Launcher
- 找到后将其 卸载
⚠️ 注意区分名称，不要卸载错了：
- ❌ Python Launcher（需要卸载）
- ✅ Python Install Manager（这是我们新安装的，不要卸载）
卸载完成后，重新打开终端，再次执行：
一般即可正常显示。
3️⃣ 设置默认 Python 版本（我常用的方法）
接下来讲一个我日常最常用、也最不容易出错的 Python 版本切换方式。
🧩 原理说明
通过系统环境变量，指定一个「默认 Python 版本」，让管理器在启动时自动使用它。
🛠️ 设置步骤
- 打开 系统环境变量设置
- Windows：
- 搜索「环境变量」
- 选择「编辑系统环境变量」
- 点击「环境变量」
- 新增一个 系统变量（或用户变量也可以）：
- 变量名：
- 变量值：
- 保存并关闭所有窗口
🔍 如何确认版本是否正确？
你可以再次执行：
你会看到类似这样的输出：
- 带有 标记的版本
👉 就是当前默认使用的 Python 版本
例如：
这里的
3.12，正好对应我们在环境变量中设置的值。💡 补充说明
- 如果 没有设置 这个环境变量：
- 默认会使用「最后安装的 Python 版本」
- 严格来说，是按照 环境变量中的顺序 决定的
- 当然，也还有其他方式可以切换版本：
- 修改配置文件
- 使用命令临时切换
- 但我个人更推荐这种方式：
- ✅ 不容易出错
- ✅ 不用记命令
- ✅ 一次设置，长期生效
到这里为止，我们的 Python 基础环境 已经全部安装并配置完成了。
如果前面的步骤都没有报错，那么说明你的系统已经可以正常运行 Python 项目了。
接下来，我们正式开始尝试运行 Qwen3-TTS。
4️⃣ 准备 Qwen3-TTS 运行目录
在开始之前，我们先为 Qwen3-TTS 创建一个独立的工作目录，用于存放代码、模型文件以及后续生成的相关内容。
📁 创建项目目录
请在你的电脑中创建以下目录Qwen3-TTS：
你可以通过以下任意方式完成：
- 在文件资源管理器中手动创建
- 或在命令行中执行创建命令
💡 说明：我这里的目录中已经运行过相关内容，可能包含其他文件夹。如果你是第一次创建这个目录，里面是空的属于正常情况，不用担心。
5️⃣ 创建并使用 Python 虚拟环境
接下来，我们需要在刚刚创建的 Qwen3-TTS 项目目录 中，创建一个独立的 Python 虚拟环境。
📂 进入项目目录
- 打开 命令行终端
- 使用
cd命令进入上一步创建的目录：
确认当前路径已经位于该目录下，再继续后续操作。
🧪 创建虚拟环境
在项目目录中，执行以下命令创建虚拟环境：
你也可以使用下面这个命令，明确指定 Python 版本 来创建虚拟环境：
🔍 两种写法的区别
py -m venv .venv- 使用当前终端正在使用的 Python 版本
- 通常就是系统默认版本
py -3.12 -m venv .venv- 明确指定使用 Python 3.12
- 更适合对版本有严格要求的项目
📌 命令参数说明（了解即可）
python：用于执行命令的 Python 解释器
m：以“模块”的方式运行
venv：标准库中的虚拟环境模块
ENV_DIR：虚拟环境目录名称（必填）
执行完成后，你会在当前目录下看到一个：
文件夹，这就是我们创建好的 虚拟环境。
🤔 为什么一定要使用虚拟环境？
当你在一台电脑上同时运行多个 Python 项目时：
- 不同项目依赖的库版本可能不同
- 很容易出现 依赖冲突、版本覆盖等问题
虚拟环境的作用就是：
隔离每个项目的依赖环境各项目互不影响，安全、干净、可控
这是 Python 项目的标准做法。
▶️ 激活虚拟环境
创建完成后，需要进入（激活）虚拟环境。
请根据你当前使用的终端类型，选择对应命令：
1️⃣ CMD（命令提示符）
2️⃣ PowerShell
这两个命令的含义是：
- 以当前目录为起点
- 执行
.venv\Scripts\目录中的激活脚本
- 将当前终端切换到该虚拟环境中
✅ 验证虚拟环境是否生效
激活成功后，命令行前面会出现类似：
此时可以执行：
示例输出：
说明当前虚拟环境正在使用 Python 3.12.10，一切正常。
6️⃣ 安装 Qwen3-TTS
确保你已经进入虚拟环境后，执行以下命令安装 Qwen3-TTS：
等待安装完成即可。
7️⃣ 尝试启动（此时运行失败是正常的）
安装完成后，可以先尝试执行下面的命令：
⚠️ 这里基本可以确定是运行不起来的，这是完全正常的。
原因是：
- Qwen3-TTS 还需要额外的运行环境配置
- 并且我不推荐在没有 GPU 的情况下运行
- 大模型相关任务，基本都离不开 GPU 支持
📖 启动命令含义说明
其中：
qwen-tts-demo
👉 Qwen3-TTS 提供的示例启动命令
<model_id>
👉 模型在 Hugging Face 上的唯一标识
示例中的模型：
🤖 什么是 Hugging Face？
Hugging Face 是一个：
- 开源模型托管平台
- 大模型社区与生态中心
- 提供模型下载、文档、示例代码
你可以在该平台上找到：
- 各类大语言模型
- 语音、图像、多模态模型
- 以及对应的使用说明
后续 Qwen3-TTS 的模型文件，也正是从这里获取的。
8️⃣ 安装 Qwen3-TTS 所需的系统环境
接下来我们开始安装 Qwen3-TTS 运行所必须的系统级依赖。
这些工具不是 Python 库，而是会被程序直接调用的外部工具。
🎵 安装 SoX（音频处理工具）
🔎 SoX 是什么？
SoX（Sound eXchange） 是一个常用的音频处理工具：
- 音频格式转换
- 重采样、裁剪、处理音频流
- 功能定位上类似 ffmpeg
👉 Qwen3-TTS 在运行过程中会依赖 SoX
如果系统中没有正确配置 SoX，程序将无法正常生成或处理音频。
📥 下载 SoX
请前往 SoX 官方下载页面：
下载完成后，得到一个 Windows 安装程序（
.exe 文件）。🛠️ 安装 SoX
- 双击下载好的 SoX 安装程序
- 直接默认安装即可
- 安装过程中可以自行修改安装目录（建议记住该路径）
⚙️ 添加 SoX 到系统环境变量
安装完成后，必须将 SoX 的安装目录添加到系统环境变量中，否则：
❌ Qwen3-TTS 将无法找到 sox 命令，运行时会直接报错
操作说明（Windows）
- 打开 系统环境变量设置，我这边是在用户变量。
- 找到
Path环境变量
- 新增一条路径，填入 SoX 的安装目录
- 保存并关闭所有窗口
✅ 验证 SoX 是否安装成功
⚠️ 必须重新打开一个新的终端窗口（非常重要）
在新终端中执行：
如果输出类似下面的内容，说明：
- SoX 已成功安装
- 环境变量配置正确
📌 常见注意事项
- ❗ 如果你是在 旧终端窗口中执行命令，很可能会提示找不到
sox
- 修改环境变量后，一定要 重新打开终端
- 只要能正常输出版本号，就代表这一步已经完成
9️⃣ 确认 PyTorch 是否为 CUDA 版本（是否支持 GPU）
在运行 Qwen3-TTS 之前，必须确认当前虚拟环境中的 PyTorch 是 CUDA 版。
如果是 CPU 版 PyTorch，即使你电脑有显卡，也无法使用 GPU 运行模型。
🔍 检查 PyTorch 与 CUDA 状态
请确保你已经 进入虚拟环境（
.venv），然后执行以下命令：✅ 正常情况（CUDA 版 PyTorch）
如果你的输出结果类似下面这样，说明 GPU 环境一切正常：
含义说明：
+cu126：表示 PyTorch 是 CUDA 12.6 版本
cuda: True：GPU 可用
torch cuda: 12.6：PyTorch 使用的 CUDA 版本
👉 这种情况可以直接继续后续步骤，无需处理。
❌ 异常情况（CPU 版 PyTorch）
如果你看到的是类似下面的输出：
这就意味着：
- 当前安装的是 CPU 版 PyTorch
- GPU 无法被使用
- Qwen3-TTS 基本无法正常运行（或性能极差）
🧹 卸载 CPU 版 PyTorch（如存在）
如果你遇到了上面的 CPU 情况，请先卸载已有的 PyTorch 相关包：
💡 一般情况下你可能还没安装过这些包，如果提示不存在，直接忽略即可。
📥 安装 CUDA 版 PyTorch（推荐做法）
接下来，我们需要从 PyTorch 官方 获取 CUDA 版本的安装方式。
🔹 官方示例命令（不推荐直接用）
这是 PyTorch 官网给出的默认 CUDA 安装命令（不包含 torchaudio）：
📌 为什么要额外安装 torchaudio？
- Qwen3-TTS 依赖
torchaudio
- 单独后装可能出现版本不一致问题
- 所以这里直接 一次性同源安装，最稳妥
✅ 推荐使用的完整命令（强烈推荐）
请在 虚拟环境中 执行下面这条命令：
这条命令会：
- 安装 CUDA 12.6 版 PyTorch
- 同时安装
torchvision与torchaudio
- 确保三者 版本一致、来源一致
🔁 安装完成后再次验证
安装完成后，请 重新执行最开始的检测命令：
只要看到：
cuda: True
- 且版本号包含
+cuXXX
就说明 GPU 环境已经配置完成 🎉
🔟 再次确认 PyTorch 已成功切换为 CUDA 版
在完成 PyTorch 重新安装后，我们需要再次验证当前虚拟环境中使用的是否是 CUDA 版 PyTorch。
请在 虚拟环境（
.venv）中 执行以下命令：如果你看到：
- 版本号包含
+cuXXX
cuda: True
说明 PyTorch 已成功切换为 GPU 版本。
✅ 运行前的完整环境检查（强烈推荐）
到这里为止，运行环境已经基本准备完成。
在真正启动 Qwen3-TTS 之前，建议做一次完整的环境校验，可以提前发现潜在问题。
⚠️ 以下所有验证 都必须在虚拟环境中执行，因为依赖都是安装在 .venv 里的。
1️⃣ 验证 torch / torchvision / torchaudio
首先确认三大核心库：
- 是否安装成功
- 是否能正常导入
- 版本是否一致（同为 CUDA 版）
执行：
示例输出：
👉 三者均为
+cu126，说明版本 来源一致、环境正确。2️⃣ 确认 CUDA 与显卡识别情况
接下来确认：
- CUDA 是否可用
- PyTorch 使用的 CUDA 版本
- 是否正确识别到你的显卡
执行：
示例输出：
👉 如果能正确显示你的显卡型号，说明 GPU 环境完全可用。
3️⃣ 确认 qwen-tts 依赖是否正常
最后检查 Qwen3-TTS 本身是否能被正常导入：
示例输出：
👉 说明 Qwen3-TTS 的 Python 依赖 全部正常。
🚀 正式启动 Qwen3-TTS
至此，所有运行环境与依赖均已确认无误。
现在可以正式启动 Qwen3-TTS：
📝 参数说明
Qwen/Qwen3-TTS-12Hz-0.6B-Base
👉 使用的模型 ID（来自 Hugging Face）
-no-flash-attn
👉 在部分显卡 / Windows 环境下更稳定
👉 可避免 Flash Attention 相关兼容性问题
⚡ 关于 -no-flash-attn 参数说明
在启动命令中，我们使用了：
这表示 不使用 flash-attn。
🔎 什么是 flash-attn（FlashAttention）？
FlashAttention 是一个使用 定制 CUDA 内核 实现的高性能注意力计算库：
- 针对 Transformer 的 Attention 计算 做了深度优化
- 目标是：
- 🚀 更快的推理 / 训练速度
- 🧠 更低的显存占用
- 目前被大量大模型项目用于加速推理和训练
🤔 那为什么一开始要禁用它？
加上
--no-flash-attn 后：- Qwen3-TTS 会走 纯 PyTorch 实现
- ✅ 稳定、通用、几乎不踩坑
- ❌ 速度会慢一些，显存占用也相对更高
👉 我们先确保：程序能正常跑起来
👉 然后再上 flash-attn 做性能优化，这是最稳妥的流程
🌐 访问 Qwen3-TTS Web 页面
当命令成功运行后，终端中会输出一个访问地址。
默认本地访问
直接在浏览器中打开：
或者直接点击终端中显示的链接即可。
局域网访问（可选）
如果你希望在 同一局域网内的其他设备（如手机、平板、其他电脑）访问：
⚠️ 是否能访问，取决于你的网络、防火墙与启动参数配置本教程暂不展开网络安全相关内容
🚀 进阶：安装 flash-attn（性能优化）
在确认 Qwen3-TTS 可以正常运行 之后，我们就可以开始安装 flash-attn，进一步提升性能。
📥 下载 flash-attn 官方 Wheel
flash-attn 不建议用 pip 直接编译安装（Windows 非常容易失败），
正确做法是：直接下载官方提供的 wheel 文件。
官方网站
🔍 选择对应的版本
请根据你的当前环境，选择以下条件完全匹配的 wheel：
- 平台：
win_amd64
- Python：
cp312
- PyTorch：
torch2.10
- CUDA：
cu12
也就是你看到的类似：
win_amd64 + cp312 + torch2.10 + cu12
复制图中命令到我们的虚拟环境中进行一个安装。
完成 flash-attn 的安装后，我们就可以 去掉
--no-flash-attn 参数，直接启动 Qwen3-TTS：✅ 说明：
- flash-attn 已生效
- Transformer Attention 会走高性能实现
- 模型运行速度更快、显存占用更低
🎉 到这里，你就可以愉快地体验 Qwen3-TTS 了！
📝 了解模型存储位置
为了避免迷糊，我们需要清楚 Qwen3-TTS 模型下载后存放在哪。
🔹 默认缓存目录
Qwen3-TTS 的模型是从 Hugging Face Hub 下载的，默认不会放在项目目录中，而是放在 HF 的缓存目录：
- Windows：
⚠️ <你的用户名> 替换成当前登录的 Windows 用户名
🔹 在虚拟环境中查看缓存目录
可以直接在虚拟环境中执行以下命令，快速获取 Hugging Face Hub 的缓存路径：
示例输出可能类似：
这就是模型默认存放的位置。
安装完后我们就可以直接使用不带--no-flash-attn的命令进行启动了。
至此我们就可以愉快的玩耍了。
🗂️ 手动下载模型 & 指定存放目录
除了默认缓存目录，我们还可以 手动下载模型到指定目录，方便管理或备份。
⚠️ 推荐在 全局环境 下操作，而不是虚拟环境，因为
huggingface-cli 是一个全局工具。1️⃣ 验证 huggingface-cli 是否可用
在终端中执行：
- 如果显示帮助信息，说明已经安装 ✅
- 如果提示命令未找到，则需要先安装
2️⃣ 安装 huggingface-cli
执行以下命令安装或更新：
目的：让 huggingface-cli 命令可用，以便手动下载或管理模型
3️⃣ 进入项目目录
切换到 Qwen3-TTS 项目目录（示例为 Windows 路径）：
💡 /d 用于切换驱动器盘符，如果你的路径在 C 盘也可以直接 cd C:\Apps\AI\Qwen3-TTS
4️⃣ 下载模型到指定目录
执行以下命令，将 Qwen3-TTS 模型下载到自定义目录：
🔹 参数说明
Qwen/Qwen3-TTS-12Hz-0.6B-Base
👉 Hugging Face 上的模型 ID
-local-dir <路径>
👉 指定下载到的目录，例如
. \models\Qwen3-TTS-12Hz-0.6B-Base- 如果缓存目录已经存在该模型，下载过程会非常快，相当于 直接复制到指定目录
🏠 使用本地模型启动 Qwen3-TTS
如果你已经将模型下载到本地指定目录，也可以在虚拟环境中直接使用本地模型启动 Qwen3-TTS。
🔹 示例命令
假设模型下载到：
在虚拟环境中执行：
说明：只需将原本命令中 模型 ID 的部分替换成本地路径即可
⚠️ 注意事项
- 这种方式 适用于模型已手动下载到本地 的情况
- 如果模型仍在 Hugging Face 缓存目录或未下载，命令会报错
- 仅在 非标准缓存管理需求 或 迁移模型 时使用
🔹 推荐方式
一般情况下，还是建议直接使用缓存中的模型：
- 不必管理本地路径
- Hugging Face 会自动处理缓存和更新
- 更加方便稳定
💡 总结：除非模型来源特殊，否则尽量使用 Hugging Face Hub 缓存方式启动 Qwen3-TTS。
至此，我们已经完成了从 Python 环境搭建 → 虚拟环境创建 → Qwen3-TTS 安装 → GPU 配置 → 模型管理 → 启动测试 的完整流程。
通过这套流程，你可以：
- 在虚拟环境中安全隔离依赖
- 使用 GPU 高效运行 Qwen3-TTS
- 灵活管理模型（缓存 / 本地目录）
- 随时扩展或升级模型版本
💡 小贴士：
- 初次使用时，建议先使用默认缓存模型，保证流程顺畅
- 熟悉环境后，可以尝试手动下载模型、启用 flash-attn 提升性能
现在，你可以开始尽情体验 Qwen3-TTS 的强大功能，尽情的玩耍啦！
Loading...