本地运行 Qwen3-TTS：语音合成与声音 已克隆

#为什么选择 Qwen3-TTS，而不是云端声音

在线语音合成服务听起来效果不错，但您交给它们的每句话都会离开您的设备，按字符收费，并且依赖一个可能被关闭的账户。对于内部文档阅读器、智能家居助手或应用原型，完全在本地运行的声音可以一次性消除这三种依赖。

在开放生态中，迄今为止一直并存着两类方案。一类是 Piper 或 Kokoro 这类非常轻量的模型：在处理器上运行速度快、声音固定，且不支持克隆。另一类是更大、更具表现力的模型，通常以英语和中文为主。Qwen3-TTS 介于两者之间：权重紧凑，但采用类似 LLM 的架构，接受自然语言风格指令，并且从发布之初就明确支持法语。

这个系列的特点是分为三种行为，而不是由一个模型包办所有任务。你只需下载符合需求的变体；当 GPU 还要与文本 LLM 共享时，尤其是 8 或 12 GB 的 GPU，这一点很重要。

#可用模型：Base、CustomVoice、VoiceDesign

发布时，该系列包含两种模型大小，即 0,6 和 1,7 十亿参数，分为三种功能变体，另有一个共享的音频 tokenizer。Hugging Face 标识符遵循 Qwen/Qwen3-TTS-12Hz-<大小>-<变体> 的模式。“12Hz”指音频编解码器的频率：模型每秒语音生成十二帧声学 token，这解释了与更密集的编解码器相比其计算资源消耗较低的原因。

CustomVoice

预定义声音，每种声音都有自己的音色和原始语言，并可通过风格指令控制（“说慢一点，语气令人安心”）。如果只是想朗读文本而不想操心选择声音，这是应当采用的变体。提供 0,6B 和 1,7B 版本。

VoiceDesign

你可以用自然语言描述想要的声音（年龄、感知性别、活力、口音、情绪），模型会据此生成。无需参考录音，因此不会模仿任何真实人物。该版本以 1,7B 发布。

Base

根据几秒钟的音频片段及其转录进行克隆。这是功能最强的变体，也是唯一涉及同意问题的变体，相关内容将在下文介绍。提供 0,6B 和 1,7B 版本。

Tokenizer-12Hz

对语音进行编码和解码的音频编解码器。上述变体会自动下载它；只有在高级用法中才需要手动处理。

支持的语言包括中文、英语、日语、韩语、德语、法语、俄语、葡萄牙语、西班牙语和意大利语，此外还包括多个中文方言。语言参数可以接受“French”这样的明确名称，也可以接受“Auto”，让模型自动检测文本语言。对于法语，强制指定语言值可以避免专有名词和英语借词的发音犹豫。

#硬件和软件先决条件

系统

仓库中记录的目标平台是 Linux x86_64。macOS 和 Windows 也可以使用，但有详细的限制说明，见专门章节。

GPU

带 CUDA 的 NVIDIA 是预期方案。单独运行 1,7B 时，一块 RTX 3060 12 GB 的显卡绰绰有余；使用处理器运行可以测试一句话，但不适合交互式使用。

Python

仓库建议在专用虚拟环境中使用 Python 3.12。请避免安装到系统环境或其他音频项目的环境中：软件包要求的 PyTorch 和 transformers 版本可能发生冲突。

磁盘空间

每个下载的变体预计占用几个 GB，文件位于 Hugging Face 缓存中（默认为 ~/.cache/huggingface）。

网络

仅在首次启动时用于下载权重。之后即可完全离线运行。

最后还有一项非技术性前提：如果你打算使用 Base 变体，请准备一段你有权使用其声音的录音。使用自己的声音是学习时最简单、最安全的情况。

#第 1 步：安装 qwen-tts 包

官方 Python 软件包在 PyPI 上名为 qwen-tts，导入时使用 qwen_tts。它会将 PyTorch 和 transformers 作为依赖项一并安装。下面的安装过程使用标准虚拟环境；如果你习惯使用 conda，也同样可以。

# Environnement isolé
python3.12 -m venv ~/qwen3-tts
source ~/qwen3-tts/bin/activate
pip install --upgrade pip

# Paquet officiel
pip install -U qwen-tts

# Lecture et écriture de fichiers audio pour les exemples
pip install soundfile

该仓库可选提供 FlashAttention 2，用于加速新款 GPU 上的推理。它的编译时间较长，并且在某些 CUDA/PyTorch 组合上会失败。这并非必需：没有它时，模型会使用 PyTorch 的标准注意力机制。请仅在其他部分运行正常后再安装。

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

在继续之前，请确认 import passe，并确认 PyTorch 能正确识别您的 GPU。

python -c "import torch, qwen_tts; print(torch.__version__, torch.cuda.is_available())"

#步骤 2：使用 Qwen3-TTS 生成第一句法语语音

CustomVoice 变体最适合首次尝试：无需录制参考音频，也无需撰写描述。加载模型，从仓库列表中选择一种声音，传入文本和语言即可。首次调用会从 Hugging Face 下载权重。

import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    device_map="cuda:0",
    dtype=torch.bfloat16,
)

wavs, sr = model.generate_custom_voice(
    text="Bonjour, ceci est un test de synthèse vocale locale avec Qwen3-TTS.",
    language="French",
    speaker="Ryan",
    instruct="Ton calme et posé, débit modéré.",
)

sf.write("sortie_custom_voice.wav", wavs[0], sr)
print("Fichier écrit à", sr, "Hz")

有三个参数需要说明。speaker 字段表示一个预定义声音；完整列表，以及每种声音的原始语言和音色描述，列在 README 和 CustomVoice 模型的 Hugging Face 页面中。所有这些声音都能朗读法语，但每种声音都会保留与其母语一致的口音，这是审美选择，而不是缺陷。instruct 字段是用自然语言编写的风格指令：情绪、节奏、意图。它是可选的。最后，该函数会返回一个波形列表和采样频率，因此可以批量处理多段文本。

textes = [
    "Première phrase à lire.",
    "Deuxième phrase, avec une intonation différente.",
]
wavs, sr = model.generate_custom_voice(
    text=textes,
    language=["French", "French"],
    speaker=["Ryan", "Serena"],
    instruct=["Neutre.", "Enjouée, un peu plus rapide."],
)
for i, w in enumerate(wavs):
    sf.write(f"lot_{i}.wav", w, sr)

#步骤 3：通过描述设计声音

VoiceDesign 解决了一个常见需求：您想要一个列表中不存在、又不模仿任何人的声音。只需用一两句话描述目标效果，模型就会生成与指令一致的音色。这也是产品开发中更值得优先选择的变体，因为它不会复现任何真实声音。

import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
    device_map="cuda:0",
    dtype=torch.bfloat16,
)

wavs, sr = model.generate_voice_design(
    text="Votre rendez-vous est confirmé pour demain à quatorze heures.",
    language="French",
    instruct="Voix féminine d'une quarantaine d'années, grave et chaleureuse, "
             "articulation nette, rythme lent, sans emphase.",
)

sf.write("sortie_voice_design.wav", wavs[0], sr)

当描述的是声学特征（音高、速度、能量、清晰度）而不是隐喻时，效果更好。“夜间电台主持人的声音”得到的结果不如“低沉、缓慢、柔和的男声”稳定。这样设计出的声音并不是每次调用都完全固定的：如果您需要在数百句话中保持同一个声音，请先生成一段满意的片段，然后将其与 Base 变体搭配用作参考。这样克隆的是合成声音，不存在任何同意问题。

#第 4 步：在获得声音所有者同意的情况下克隆声音

Base 变体根据一段短音频及其转录复现音色。几秒钟干净的语音就足以获得可识别的声音。这是整个系列中最令人印象深刻的功能，也是甚至在编写一行代码之前就要求最高严谨性的功能。

准备参考音频时，在安静的地方录制一段五到十秒的句子，不要有背景音乐或混响，并以自然方式说话。请逐字转录，包括标点：模型会用这段文本将音频对齐，以学习音色。单声道 WAV 文件是最稳妥的格式。

import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
    device_map="cuda:0",
    dtype=torch.bfloat16,
)

wavs, sr = model.generate_voice_clone(
    text="Voici une phrase que je n'ai jamais prononcée, lue avec ma propre voix.",
    language="French",
    ref_audio="ma_reference.wav",
    ref_text="Bonjour, je m'appelle Thomas et j'enregistre cette phrase pour tester le clonage.",
)

sf.write("sortie_clone.wav", wavs[0], sr)

该仓库记录了两种适用于生产环境的高级用法。首先，可以一次性预计算参考语音的“音色指纹”，然后在每个句子上重复使用，而无需重新加载音频：文档阅读器或持续说话的助手正需要这一功能。其次，还有一种仅使用说话人指纹、不使用转录的模式，速度更快但保真度较低。这些参数的确切名称见 README；它们在软件包的早期版本之间发生过变化，因此应阅读已安装的文档，而不是过时的教程。

能够改善效果的因素

干净的参考音频、准确的转录、强制指定语言而不是“Auto”，以及带有标点的目标文本（模型会在逗号和句号处换气）。

会降低效果的因素

背景噪声、过短或过长的参考音频、耳语、粗略的转录，以及在有歧义的情况下用数字而不是文字书写的数字。

需要记录的内容

谁给出了同意、用于什么用途、日期是哪天，以及录音保存在哪里。个人项目中，在参考音频旁放一个简单的文本文件就足够；专业用途则需要一份正式的处理活动记录。

#第 5 步：Web 界面和服务器

该软件包会通过命令行安装一个 Gradio 演示程序，便于在不编写脚本的情况下试用语音和提示词。它会在启动时加载模型，并提供一个本地网页。

qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 127.0.0.1 --port 8000

在机器受到保护之前，请将监听地址保持为 127.0.0.1：Gradio 默认不会对任何人进行身份验证，而将语音克隆界面暴露在网络上并非无害。如果必须从另一台设备访问，请像访问任何本地服务一样，通过 SSH 隧道或带身份验证的反向代理访问。

对于应用集成，Qwen 团队推荐使用 vLLM-Omni，即 vLLM 的多模态扩展。它可以通过 HTTP API 提供模型服务，并支持流式输出（声音会在生成结束前开始输出）。对于注重延迟的语音助手，这是值得研究的方案；而对于批量生成音频文件，直接使用 Python 脚本就足够了，还能省去一层额外封装。

#Apple Silicon 和 Windows：社区方案，并明确标注为此类

官方仓库记录的是使用 CUDA 的 Linux。对于其他平台，以下内容属于社区生态：我们没有亲自验证这些路径，而且它们的状态每个月都可能变化。

搭载 Apple Silicon 的 Mac

官方软件包基于 PyTorch；可以尝试将 device_map="mps" 与 dtype float16 或 float32 配合使用（MPS 不一定支持 bfloat16），但要预期会遇到不受支持的操作。在 Mac 上，最自然的方案是使用 MLX 移植版：社区项目 mlx-audio 已宣布支持 Qwen3-TTS。在投入使用前，请在其仓库中确认支持哪些变体以及成熟度如何。

原生 Windows

PyTorch 与 CUDA 通常可以正常安装，但 FlashAttention 在 Windows 下很难编译：请跳过它，使用默认注意力机制。某些音频依赖项需要系统二进制文件（例如 PATH 中的 ffmpeg）。第三方“一键式”安装程序正在流传；它们通常捆绑固定版本的软件包，因此必须查看其安装内容。

通过 WSL2 使用 Windows

这是最接近官方文档的方案：在 WSL2 下运行 Ubuntu，并使用较新的 NVIDIA Windows 驱动，即可识别 GPU，且完全按照本指南中的命令执行。代价是多了一层环境，并且访问 Windows 文件的速度会稍慢。

#故障排除

加载时 CUDA 内存不足

另一个进程正在占用显卡（Ollama、启用了硬件加速的浏览器或 Stable Diffusion 会话）。请使用 nvidia-smi 检查，释放显存，或切换到 0,6B 变体。

下载中断或找不到仓库

请在组织 Qwen 的 Hugging Face 页面上核对模型的准确标识符；变体名称可能已在撰写后发生变化。部分下载可以通过重新运行脚本继续。

transformers 或 torch 中的 import liée 错误

与同一环境中安装的其他项目发生版本冲突。请重新创建一个干净的虚拟环境，只安装 qwen-tts 和 soundfile。

法语发音奇怪

请将 language="French" 强制设为“Auto”以外的值；当数字的读法可能含糊时，请用文字拼写，并注意标点。缩写词在字母之间加入句点或空格后更易读。

克隆出的声音不像参考声音

在安静的环境中重新录制参考音频，逐字核对转录；如果之前使用的是 0,6B，请测试 1,7B。片段过长并没有帮助：几秒钟清晰的语音胜过一分钟嘈杂的录音。

静音或空文件

请确认你写的是 wavs[0]，而不是整个列表，并确认模型返回的采样率就是传给 soundfile 的采样率。

极度缓慢

模型可能运行在 CPU 上。第 1 步中的 torch.cuda.is_available() 测试必须返回 True；否则，请安装与您的驱动对应的 CUDA 版本的 PyTorch。

#深入了解

Qwen3-TTS 覆盖本地语音链路中的“说话”部分。至于另一半——理解，以及与更轻量的合成模型进行比较，该网站已经介绍了多个相关主题。本指南中提及的软件包和模型版本，是撰写时 QwenLM/Qwen3-TTS 仓库中的版本；如有差异，以仓库和 Hugging Face 页面为准。

Kokoro TTS：轻量、声音表现出色的本地语音合成

一个拥有 82 百万参数、无需克隆即可在处理器上以高于实时的速度说话的模型。适合优先考虑节省资源而非表现力的场景。 https://quelllm.fr/guide/kokoro-tts-voix-locale

100 % 本地语音助手：Whisper + Ollama + Piper

完整链路包括监听、推理和语音回复。如果您的 GPU 支持，Qwen3-TTS 可以在其中替代 Piper 负责语音合成。https://quelllm.fr/guide/assistant-vocal-local-whisper-piper

Voxtral 4B TTS 模型页面

欧洲方面近期出现的另一款开放式语音合成模型，用于在不进行量化比较的情况下说明 Qwen3-TTS 所处的生态位置。https://quelllm.fr/modele/voxtral-4b-tts