Qwen3-TTS—它来了它来了！

文章详细介绍了阿里巴巴 Qwen 团队最新发布的 Qwen3-TTS 语音生成模型系列。该系列模型采用自研 12Hz Tokenizer 和通用端到端架构，有效规避了传统 LM+DiT 方案的信息瓶颈。其核心亮点包括：支持 10 种主流语言及方言、具备 3 秒极速声音克隆能力、支持基于自然语言指令的“声音设计”以及低至 97ms 的流式生成延迟。文章还提供了详细的模型分类（Base/CustomVoice/VoiceDesign）、环境配置指南、Python API 调用示例以及 Web UI 和 vLLM 部署方案，为开发者提供了全栈式的语音合成解决方案。

我们正式发布 Qwen3-TTS —— 这是由 Qwen 团队研发的一系列强大语音生成模型，提供全面且先进的语音合成能力，包括：声音克隆、声音设计、超高质量、类人自然语音生成、基于自然语言的语音控制。

Qwen3-TTS 为开发者和用户带来了目前功能最全面的语音生成解决方案之一，覆盖从个性化语音到高保真语音合成的多种应用场景。

简介

Qwen3-TTS 支持 10 种主流语言（中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文、意大利文），并覆盖多种方言音色，可满足全球化应用需求。

此外，模型具备强大的上下文理解能力，能够根据指令和文本语义，自适应地调节语气、语速和情绪表达，同时对噪声文本输入表现出显著更强的鲁棒性。

1. 强大的语音表示能力

•采用自研 Qwen3-TTS-Tokenizer-12Hz•实现高效的声学压缩与高维语义建模•完整保留副语言信息（如情绪、语调）和声学环境特征•基于轻量级非 DiT 架构，实现高速、高保真的语音重建

2. 通用端到端架构

•采用离散多码本语言模型（LM）架构•实现全信息端到端语音建模•完全规避传统 LM + DiT 方案中的信息瓶颈与级联误差•显著提升模型的通用性、生成效率与性能上限

3. 极低延迟的流式生成

•基于创新的 双轨混合流式生成架构（Dual-Track）•单一模型同时支持流式与非流式生成•输入单个字符即可立即输出首个音频包•端到端语音合成延迟最低可达 97ms•满足高实时性的人机交互场景需求

4. 智能文本理解与语音控制

•支持通过自然语言指令驱动语音生成•可灵活控制音色、情绪、韵律等多维声学属性•深度融合文本语义理解，自动调节语气、节奏与情感表达•实现接近“所想即所听”的真实语音效果

Model Architecture｜模型架构

Released Models Description and Download

以下是目前已发布的 Qwen3-TTS 模型介绍与下载信息。技术报告中提及的其他模型将于近期陆续发布，请根据实际需求选择合适的模型。

在使用 qwen-tts 包或 vLLM 加载模型时，


系统会根据模型名称自动下载对应的模型权重。

如果你的运行环境不适合在执行期间联网下载权重， 可以参考后续提供的命令，将模型权重手动下载到本地目录。

# Download through ModelScope
pip install -U modelscope
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz--local_dir ./Qwen3-TTS-Tokenizer-12Hz
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice--local_dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign--local_dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-Base--local_dir ./Qwen3-TTS-12Hz-1.7B-Base
modelscope download --model Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice--local_dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-12Hz-0.6B-Base--local_dir ./Qwen3-TTS-12Hz-0.6B-Base


# Download through Hugging Face
pip install -U "huggingface_hub[cli]"
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz--local-dir ./Qwen3-TTS-Tokenizer-12Hz
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice--local-dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign--local-dir ./Qwen3-TTS-12Hz-1.7B-VoiceDesign
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base--local-dir ./Qwen3-TTS-12Hz-1.7B-Base
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice--local-dir ./Qwen3-TTS-12Hz-0.6B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-12Hz-0.6B-Base--local-dir ./Qwen3-TTS-12Hz-0.6B-Base

快速开始

环境配置

快速使用 Qwen3-TTS 的最简单方式，是直接从 PyPI 安装 qwen-tts Python 包。


该方式会自动安装所需的运行时依赖，并允许你加载所有已发布的 Qwen3-TTS 模型。

⚠️ 强烈建议使用一个全新的、隔离的环境，以避免与现有 Python 包产生依赖冲突。

1️⃣ 创建独立的 Python 环境

以下示例使用 Python 3.12 创建一个干净的 Conda 环境：

conda create -n qwen3-tts python=3.12-y
conda activate qwen3-tts

然后安装 Qwen3-TTS：

pip install -U qwen-tts

2️⃣ 从源码安装（适用于本地开发 / 二次修改） 如果你需要对代码进行开发或自定义修改，可以使用 可编辑模式（editable mode） 从源码安装：

git clone https://github.com/QwenLM/Qwen3-TTS.git
cd Qwen3-TTS
pip install -e .

3️⃣ 使用 FlashAttention 2（推荐） 为了显著降低 GPU 显存占用并提升性能，推荐安装 FlashAttention 2：

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

如果你的机器 内存少于 96GB，但 CPU 核心数较多，建议限制并行编译任务数：

MAX_JOBS=4 pip install -U flash-attn --no-build-isolation

此外，你的硬件还需要兼容 FlashAttention 2。 更多硬件与环境要求，请参考 FlashAttention 官方仓库文档^[1]。

需要注意的是，FlashAttention 2 仅在模型以以下精度加载时可用： torch.float16和torch.bfloat16。

Python Package Usage｜Python 包使用说明

安装完成后，你可以导入 Qwen3TTSModel，用于实现：自定义音色语音合成（Custom Voice TTS），声音设计（Voice Design），声音克隆（Voice Clone）。模型权重可以通过以下两种方式指定：Hugging Face 模型 ID（推荐），本地已下载的模型目录路径。对于下文所有 generate_* 相关函数， 除了示例中展示并明确说明的参数外，你还可以额外传入 Hugging Face Transformers 中 model.generate 支持的生成参数，例如：max_new_tokens， top_p等等。

Custom Voice Generate｜自定义音色生成

对于 自定义音色模型


（Qwen3-TTS-12Hz-1.7B-CustomVoice / Qwen3-TTS-12Hz-0.6B-CustomVoice）：

你只需调用 generate_custom_voice，并传入：

•文本（单条字符串或批量列表）•语言（language）•说话人（speaker）•可选的自然语言指令（instruct）

你还可以通过以下方法查询当前模型支持的内容：

•model.get_supported_speakers()：查看可用说话人•model.get_supported_languages()：查看支持语言

import torch
import soundfile as sf
from qwen_tts importQwen3TTSModel


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


# Single Inference
wavs, sr = model.generate_custom_voice(
    text="其实我真的有发现，我是一个特别善于观察别人情绪的人。",
    language="Chinese",
# 传入 `Auto`（或省略）可自动识别语言；
# 如果目标语言已知，建议显式指定
    speaker="Vivian",
    instruct="用特别愤怒的语气说",# 若不需要可省略
)


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


批量推理（BatchInference）
wavs, sr = model.generate_custom_voice(
    text=[
"其实我真的有发现，我是一个特别善于观察别人情绪的人。",
"She said she would be here by noon."
],
    language=["Chinese","English"],
    speaker=["Vivian","Ryan"],
    instruct=["","Very happy."]
)


sf.write("output_custom_voice_1.wav", wavs[0], sr)
sf.write("output_custom_voice_2.wav", wavs[1], sr)

Qwen3-TTS-12Hz-1.7B/0.6B-CustomVoice 模型的支持说话人列表，以下是每个说话人的描述以及其母语。为了获得最佳语音质量，建议使用每个说话人的母语。当然，所有说话人均可使用模型支持的任意语言进行表达。

Voice Design｜声音设计

对于 声音设计模型（Qwen3-TTS-12Hz-1.7B-VoiceDesign），


你可以使用 generate_voice_design 来传入目标文本和自然语言指令，进行个性化声音设计。

import torch
import soundfile as sf
from qwen_tts importQwen3TTSModel


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


# single inference
wavs, sr = model.generate_voice_design(
    text="哥哥，你回来啦，人家等了你好久好久了，要抱抱！",
    language="Chinese",
    instruct="体现撒娇稚嫩的萝莉女声，音调偏高且起伏明显，营造出黏人、做作又刻意卖萌的听觉效果。",
)
sf.write("output_voice_design.wav", wavs[0], sr)


# batch inference
wavs, sr = model.generate_voice_design(
    text=[
"哥哥，你回来啦，人家等了你好久好久了，要抱抱！",
"It's in the top drawer... wait, it's empty? No way, that's impossible! I'm sure I put it there!"
],
    language=["Chinese","English"],
    instruct=[
"体现撒娇稚嫩的萝莉女声，音调偏高且起伏明显，营造出黏人、做作又刻意卖萌的听觉效果。",
"Speak in an incredulous tone, but with a hint of panic beginning to creep into your voice."
]
)
sf.write("output_voice_design_1.wav", wavs[0], sr)
sf.write("output_voice_design_2.wav", wavs[1], sr)

Voice Clone｜声音克隆

对于 声音克隆模型（Qwen3-TTS-12Hz-1.7B/0.6B-Base），


要克隆某个声音并合成新内容，你只需要提供一个参考音频（ref_audio）和对应的文本转录（ref_text）。

参考音频（ref_audio）可以是以下任意形式：

•本地文件路径•URL 链接•base64 编码字符串•(numpy_array, sample_rate) 元组

如果你设置 x_vector_only_mode=True，则只使用说话人的 x-vector 嵌入，因此 ref_text 是可选的，但这可能会降低克隆质量。

import torch
import soundfile as sf
from qwen_tts importQwen3TTSModel


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


# 参考音频 URL
ref_audio ="https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-TTS-Repo/clone.wav"
# 参考文本内容
ref_text  ="Okay. Yeah. I resent you. I love you. I respect you. But you know what? You blew it! And thanks to you."


# 生成声音克隆
wavs, sr = model.generate_voice_clone(
    text="I am solving the equation: x = [-b ± √(b²-4ac)] / 2a? Nobody can — it's a disaster (◍•͈⌔•͈◍), very sad!",
    language="English",
    ref_audio=ref_audio,
    ref_text=ref_text,
)


# 保存合成的音频
sf.write("output_voice_clone.wav", wavs[0], sr)

如果您需要在多个生成过程中复用相同的参考提示（以避免重新计算提示特征），可以使用 create_voice_clone_prompt 创建一次提示，并通过 voice_clone_prompt 传递它。

# 创建语音克隆提示
prompt_items = model.create_voice_clone_prompt(
    ref_audio=ref_audio,# 参考音频
    ref_text=ref_text,# 参考文本
    x_vector_only_mode=False,# 是否仅使用X向量（通常为False，表示使用完整的语音特征）
)


# 生成语音克隆
wavs, sr = model.generate_voice_clone(
    text=["Sentence A.","Sentence B."],# 要生成的文本
    language=["English","English"],# 生成语音的语言
    voice_clone_prompt=prompt_items,# 传递先前创建的语音克隆提示
)


# 保存生成的语音为WAV文件
sf.write("output_voice_clone_1.wav", wavs[0], sr)
sf.write("output_voice_clone_2.wav", wavs[1], sr)

如需了解更多可复用的语音克隆提示、批量克隆和批量推理的示例代码，请参考相关的示例代码。通过这些示例和 generate_voice_clone 函数的描述，您可以探索更多高级的使用模式。

语音设计与克隆

如果您希望设计一个可复用的声音，就像克隆的说话者一样，以下是一个实用的工作流程：

1.使用 VoiceDesign 模型合成一个短的参考音频，确保与目标角色相匹配。2.将该音频输入 create_voice_clone_prompt 来构建一个可复用的提示。3.调用 generate_voice_clone 并传入 voice_clone_prompt 来生成新内容，无需每次都重新提取特征。

这种方法特别适用于需要多个台词中保持一致的角色声音。

import torch
import soundfile as sf
from qwen_tts importQwen3TTSModel


# 使用 VoiceDesign 模型创建目标风格的参考音频
design_model =Qwen3TTSModel.from_pretrained(
"Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",# 预训练模型
    device_map="cuda:0",# 使用 GPU
    dtype=torch.bfloat16,# 精度设置
    attn_implementation="flash_attention_2",# 注意力实现方式
)


ref_text ="H-hey! You dropped your... uh... calculus notebook? I mean, I think it's yours? Maybe?"
ref_instruct ="Male, 17 years old, tenor range, gaining confidence - deeper breath support now, though vowels still tighten when nervous"
ref_wavs, sr = design_model.generate_voice_design(
    text=ref_text,
    language="English",# 语言为英语
    instruct=ref_instruct  # 设计指令
)
sf.write("voice_design_reference.wav", ref_wavs[0], sr)# 保存参考音频


# 使用参考音频创建可复用的语音克隆提示
clone_model =Qwen3TTSModel.from_pretrained(
"Qwen/Qwen3-TTS-12Hz-1.7B-Base",# 基础模型
    device_map="cuda:0",# 使用 GPU
    dtype=torch.bfloat16,# 精度设置
    attn_implementation="flash_attention_2",# 注意力实现方式
)


voice_clone_prompt = clone_model.create_voice_clone_prompt(
    ref_audio=(ref_wavs[0], sr),# 参考音频或 "voice_design_reference.wav"
    ref_text=ref_text,# 参考文本
)


# 要生成的句子
sentences =[
"No problem! I actually... kinda finished those already? If you want to compare answers or something...",
"What? No! I mean yes but not like... I just think you're... your titration technique is really precise!",
]


# 使用同一个提示多次生成单独的语音
wavs, sr = clone_model.generate_voice_clone(
    text=sentences[0],
    language="English",
    voice_clone_prompt=voice_clone_prompt,
)
sf.write("clone_single_1.wav", wavs[0], sr)


wavs, sr = clone_model.generate_voice_clone(
    text=sentences[1],
    language="English",
    voice_clone_prompt=voice_clone_prompt,
)
sf.write("clone_single_2.wav", wavs[0], sr)


# 或者批量生成语音
wavs, sr = clone_model.generate_voice_clone(
    text=sentences,
    language=["English","English"],# 多个句子的语言
    voice_clone_prompt=voice_clone_prompt,
)
for i, w in enumerate(wavs):
    sf.write(f"clone_batch_{i}.wav", w, sr)

分词器编码与解码

如果您仅仅是为了传输或训练等目的对音频进行编码和解码，Qwen3TTSTokenizer 支持通过路径、URL、numpy 波形以及字典/列表等格式进行编码和解码。例如：

import soundfile as sf
from qwen_tts importQwen3TTSTokenizer


# 加载预训练的 Qwen3TTSTokenizer
tokenizer =Qwen3TTSTokenizer.from_pretrained(
"Qwen/Qwen3-TTS-Tokenizer-12Hz",# 预训练模型
    device_map="cuda:0",# 使用 GPU
)


enc = tokenizer.encode("https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-TTS-Repo/tokenizer_demo_1.wav")
wavs, sr = tokenizer.decode(enc)
sf.write("decode_output.wav", wavs[0], sr)

如需了解更多关于分词器的示例（包括不同输入格式和批量使用的情况），请参考相关的示例代码。通过这些示例和 Qwen3TTSTokenizer 的描述，您可以探索更复杂的使用模式。

启动本地 Web UI 演示

要启动 Qwen3-TTS 的 Web UI 演示，只需安装 qwen-tts 包并运行 qwen-tts-demo。使用以下命令可以查看帮助信息：

qwen-tts-demo --help

您可以使用以下命令启动不同模型的演示：

CustomVoice模型：
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice--ip 0.0.0.0--port 8000


VoiceDesign模型：
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign--ip 0.0.0.0--port 8000


基础模型：
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base--ip 0.0.0.0--port 8000

启动演示后，您可以在浏览器中打开 http://<your-ip>:8000 进行访问，或者通过像 VS Code 等工具进行端口转发来访问演示。

基础模型 HTTPS 注意事项

为了避免在部署服务器后出现浏览器麦克风权限问题，特别是在远程访问或使用现代浏览器/网关时，建议/要求在基础模型的部署中通过 HTTPS 运行 Gradio 服务。您可以使用 --ssl-certfile 和 --ssl-keyfile 来启用 HTTPS。

步骤 1：生成私钥和自签名证书

首先，我们需要生成一个私钥和一个自签名证书（有效期为365天）：

openssl req -x509 -newkey rsa:2048 \
-keyout key.pem -out cert.pem \
-days 365-nodes \
-subj "/CN=localhost"

步骤 2：使用 HTTPS 启动演示 然后，使用以下命令启动演示服务并启用 HTTPS：

qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base \
--ip 0.0.0.0--port 8000 \
--ssl-certfile cert.pem \
--ssl-keyfile key.pem \
--no-ssl-verify

步骤 3：访问演示

启动后，您可以通过 https://<your-ip>:8000来访问演示。如果浏览器显示警告，这是因为使用了自签名证书，这是预期的情况。对于生产环境，请使用真正的证书。

DashScope API 使用

为了更快更高效地探索 Qwen3-TTS，我们建议您尝试使用我们的 DashScope API。有关详细的 API 信息和文档，请参考以下链接：

vLLM 使用

vLLM 官方提供了对 Qwen3-TTS 的 Day-0 支持！欢迎使用 vLLM-Omni 来部署和推理 Qwen3-TTS。有关安装和更多详细信息，请查看 vLLM-Omni 官方文档。目前仅支持离线推理，在线服务将在后续支持，vLLM-Omni 将继续在推理速度和流媒体能力等方面提供支持和优化。

离线推理

您可以使用 vLLM-Omni 在本地对 Qwen3-TTS 进行推理，我们在 vLLM-Omni 仓库中提供了示例，可以生成音频输出：

1.克隆 vLLM-Omni 仓库：

 git clone https://github.com/vllm-project/vllm-omni.git

2.进入示例目录：

 cd vllm-omni/examples/offline_inference/qwen3_tts

3.使用 CustomVoice 任务运行单个样本：

 python end2end.py --query-type CustomVoice

4.使用 CustomVoice 任务批量运行（一次运行多个提示）：

 python end2end.py --query-type CustomVoice--use-batch-sample

5.使用 VoiceDesign 任务运行单个样本：

 python end2end.py --query-type VoiceDesign

6.使用 VoiceDesign 任务批量运行（一次运行多个提示）：

 python end2end.py --query-type VoiceDesign--use-batch-sample

7.使用 Base 任务并选择 icl 模式标签运行单个样本：

 python end2end.py --query-type Base--mode-tag icl

https://github.com/QwenLM/Qwen3-TTS

References

[1] FlashAttention 官方仓库文档:https://github.com/Dao-AILab/flash-attention


[2]实时 API 文档 - 自定义语音模型:https://help.aliyun.com/zh/model-studio/qwen-tts-realtime


[3]Real-time API - Custom Voice Model:https://www.alibabacloud.com/help/en/model-studio/qwen-tts-realtime


[4]实时 API 文档 - 语音克隆模型:https://help.aliyun.com/zh/model-studio/qwen-tts-voice-cloning


[5]Real-time API - Voice Cloning Model:https://www.alibabacloud.com/help/en/model-studio/qwen-tts-voice-cloning


[6]实时 API 文档 - 语音设计模型:https://help.aliyun.com/zh/model-studio/qwen-tts-voice-design


[7]Real-time API - Voice Design Model: https://www.alibabacloud.com/help/en/model-studio/qwen-tts-voice-design