Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice · Hugging Face 来源: https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice ## https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#overview概述 ### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#introduction介绍 Qwen3-TTS 覆盖10种主要语言（中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文和意大利文）以及多种方言语音配置，以满足全球应用需求。此外，该模型具有强大的上下文理解能力，能够根据指令和文本语义自适应控制语气、语速和情感表达，并对噪声输入文本表现出显著的鲁棒性提升。主要特点： - 强大的语音表示：基于自研的 Qwen3-TTS-Tokenizer-12Hz，实现对语音信号的高效声学压缩和高维语义建模。它完整保留了副语言信息和声学环境特征，通过轻量级非 DiT 架构实现高速、高保真的语音重建。 - 通用端到端架构：采用离散多码本语言模型架构，实现全信息端到端语音建模。这完全规避了传统 LM+DiT 方案中的信息瓶颈和级联误差，显著提升了模型的通用性、生成效率和性能天花板。 - 极致低延迟流式生成：基于创新的双轨混合流式生成架构，单个模型同时支持流式和非流式生成。可在输入单个字符后立即输出首个音频包，端到端合成延迟低至 97ms，满足实时交互场景的严苛要求。 - 智能文本理解与语音控制：支持基于自然语言指令的语音生成，可灵活控制音色、情感、韵律等多维声学属性。通过深度融合文本语义理解，模型自适应调整语气、节奏和情感表达，实现“所想即所听”的逼真输出。 ### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#model-architecture模型架构 ### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#released-models-description-and-download已发布模型描述与下载 以下是 Qwen3-TTS 已发布模型的介绍和下载信息。技术报告中提到的其他模型将在近期发布。请根据需求选择并下载模型。 Tokenizer 名称描述Qwen3-TTS-Tokenizer-12HzQwen3-TTS-Tokenizer-12Hz 模型，可将输入的语音编码为码本，并解码回语音。模型特征语言支持流式指令控制Qwen3-TTS-12Hz-1.7B-VoiceDesign基于用户提供的描述进行语音设计。中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文、意大利文✅✅Qwen3-TTS-12Hz-1.7B-CustomVoice通过用户指令对目标音色提供风格控制；支持9种优质音色，涵盖性别、年龄、语言和方言的多种组合。中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文、意大利文✅✅Qwen3-TTS-12Hz-1.7B-Base基础模型，支持从用户音频输入进行3秒快速语音克隆；可用于微调（FT）其他模型。中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文、意大利文✅Qwen3-TTS-12Hz-0.6B-CustomVoice支持9种优质音色，涵盖性别、年龄、语言和方言的多种组合。中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文、意大利文✅Qwen3-TTS-12Hz-0.6B-Base基础模型，支持从用户音频输入进行3秒快速语音克隆；可用于微调（FT）其他模型。中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文、意大利文✅ 在 qwen-tts 包或 vLLM 中加载模型时，模型权重将根据模型名称自动下载。但如果您的运行时环境不利于在执行期间下载权重，可以参考以下命令手动将模型权重下载到本地目录： # 通过 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 # 通过 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 ## https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#quickstart快速入门 ### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#environment-setup环境设置 快速使用 Qwen3-TTS 最简单的方法是从 PyPI 安装 qwen-tts Python 包。这将拉取所需的运行时依赖，并允许您加载任何已发布的 Qwen3-TTS 模型。我们建议使用全新的、隔离的环境以避免与现有包的依赖冲突。您可以像这样创建一个干净的 Python 3.12 环境： conda create -n qwen3-tts python=3.12 -y conda activate qwen3-tts 然后运行： pip install -U qwen-tts 如果您想在本地开发或修改代码，请从源码以可编辑模式安装。 git clone https://github.com/QwenLM/Qwen3-TTS.git cd Qwen3-TTS pip install -e . 此外，我们建议使用 FlashAttention 2 来减少 GPU 内存使用。 pip install -U flash-attn --no-build-isolation 如果您的机器内存小于 96GB 且 CPU 核心较多，请运行： MAX_JOBS=4 pip install -U flash-attn --no-build-isolation 同时，您需要拥有与 FlashAttention 2 兼容的硬件。更多信息请参阅 FlashAttention 仓库 (https://github.com/Dao-AILab/flash-attention) 的官方文档。FlashAttention 2 仅在模型以 torch.float16 或 torch.bfloat16 加载时可用。 ### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#python-package-usagePython 包使用 安装后，您可以导入 Qwen3TTSModel 来运行自定义语音 TTS、语音设计和语音克隆。模型权重可以指定为 Hugging Face 模型 ID（推荐）或您下载的本地目录路径。对于下面的所有 generate_* 函数，除了显示和明确记录的参数外，您还可以传递 Hugging Face Transformers model.generate 支持的生成 kwargs，例如 max_new_tokens、top_p 等。 #### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#custom-voice-generate自定义语音生成 对于自定义语音模型（Qwen3-TTS-12Hz-1.7B/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 import Qwen3TTSModel model = Qwen3TTSModel.from_pretrained( "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice", device_map="cuda:0", dtype=torch.bfloat16, attn_implementation="flash_attention_2", ) # 单次推理 wavs, sr = model.generate_custom_voice( text="其实我真的有发现,我是一个特别善于观察别人情绪的人。", language="Chinese", # 传递 `Auto`（或省略）以自动适配语言；如果已知目标语言，请显式设置。 speaker="Vivian", instruct="用特别愤怒的语气说", # 如果不需要可省略。 ) sf.write("output_custom_voice.wav", wavs[0], sr) # 批量推理 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 模型，支持的说话者列表和描述如下。我们建议使用每个说话者的母语以获得最佳质量。当然，每个说话者都可以说模型支持的任何语言。 说话者语音描述母语Vivian明亮、略带尖刺的年轻女声。中文Serena温暖、温柔的年轻女声。中文Uncle_Fu低沉、圆润的成熟男声。中文Dylan充满活力的北京男声，音色清晰自然。中文（北京方言）Eric活泼的成都男声，略带沙哑的明亮感。中文（四川方言）Ryan动感男声，节奏感强。英文Aiden阳光的美国男声，中音清晰。英文Ono_Anna俏皮的日本女声，音色轻盈灵活。日文Sohee温暖的韩国女声，情感丰富。韩文 #### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#voice-design语音设计 对于语音设计模型（Qwen3-TTS-12Hz-1.7B-VoiceDesign），您可以使用 generate_voice_design 来提供目标文本和自然语言的 instruct 描述。 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, attn_implementation="flash_attention_2", ) # 单次推理 wavs, sr = model.generate_voice_design( text="哥哥,你回来啦,人家等了你好久好久了,要抱抱!", language="Chinese", instruct="体现撒娇稚嫩的萝莉女声,音调偏高且起伏明显,营造出黏人、做作又刻意卖萌的听觉效果。", ) sf.write("output_voice_design.wav", wavs[0], sr) # 批量推理 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) #### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#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，则仅使用说话者嵌入，因此 ref_text 不是必需的，但克隆质量可能会降低。 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, attn_implementation="flash_attention_2", ) 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 ± √(b2-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, ) wavs, sr = model.generate_voice_clone( text=["Sentence A.", "Sentence B."], language=["English", "English"], voice_clone_prompt=prompt_items, ) sf.write("output_voice_clone_1.wav", wavs[0], sr) sf.write("output_voice_clone_2.wav", wavs[1], sr) 有关可重用语音克隆提示、批量克隆和批量推理的更多示例，请参考示例代码 (https://github.com/QwenLM/Qwen3-TTS/blob/main/examples/test_model_12hz_base.py)。通过这些示例和 generate_voice_clone 函数描述，您可以探索更高级的用法模式。 #### https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice#voice-design-then-clone先语音设计再克隆 如果您想要一个可像克隆说话者一样重复使用的设计语音，一个实用的工作流程是：（1）使用 VoiceDesign 模型合成一个匹配目标角色的简短参考片段，（2）将该片段输入 create_voice_clone_prompt 以构建可重用提示，然后（3）调用 generate_voice_clone 并传递 voice_clone_prompt 来生成新内容，而无需每次都重新提取特征。当您想要跨多个句子保持一致的字符语音时，这特别有用。 `` import torch import soundfile as sf from qwen_tts import Qwen3TTSModel # 使用 VoiceDesign 模型创建目标风格的参考音频 design_model = Qwen3TTSModel.from_pretrained( “Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign”, device_map=“cuda:0”, 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”, 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 =