Qwen3-TTS

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #llm #machine-learning #rust #deep-learning #docker #macos #java #kubernetes #pytorch #ios

(★ 12,982)

Qwen3-TTS는 Alibaba Cloud의 Qwen 팀이 개발한 오픈소스 TTS 모델 시리즈로, 안정적이고 표현력 있는 스트리밍 음성 생성, 자유로운 형식의 음성 디자인, 그리고 생생한 음성 복제를 지원합니다.

Qwen3-TTS 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Qwen3-TTS

![](https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-TTS-Repo/qwen3_tts_logo.png)

🤗 [Hugging Face](https://huggingface.co/collections/Qwen/qwen3-tts)   |   🤖 [ModelScope](https://modelscope.cn/collections/Qwen/Qwen3-TTS)   |   📑 [Blog](https://qwen.ai/blog?id=qwen3tts-0115)   |   📑 [Paper](https://arxiv.org/abs/2601.15621)  
  
🖥️ [Hugging Face Demo](https://huggingface.co/spaces/Qwen/Qwen3-TTS)   |    🖥️ [ModelScope Demo](https://modelscope.cn/studios/Qwen/Qwen3-TTS)   |   💬 [WeChat (微信)](https://github.com/QwenLM/Qwen/blob/main/assets/wechat.png)   |   🫨 [Discord](https://discord.gg/CV4E9rpNSD)   |   📑 [API](https://help.aliyun.com/zh/model-studio/qwen-tts-realtime)

Qwen에서 개발한 강력한 음성 생성 기능 시리즈인 \*\*Qwen3-TTS\*\*를 공개합니다. 이 모델은 음성 복제(Voice Clone), 음성 디자인(Voice Design), 초고품질의 사람 같은 음성 생성, 자연어 기반 음성 제어 기능을 포괄적으로 지원합니다. 개발자와 사용자에게 가장 광범위한 음성 생성 기능 세트를 제공합니다.
## News
\* 2026.1.22: 🎉🎉🎉 Qwen3-TTS-Tokenizer-12Hz를 기반으로 한 [Qwen3-TTS](https://huggingface.co/collections/Qwen/qwen3-tts) 시리즈(0.6B/1.7B)를 출시했습니다. [블로그](https://qwen.ai/blog?id=qwen3tts-0115)를 확인해 주세요!
## Contents 
- [Overview](#overview)
- [Introduction](#introduction)
- [Model Architecture](#model-architecture)
- [Released Models Description and Download](#released-models-description-and-download)
- [Quickstart](#quickstart)
- [Environment Setup](#environment-setup)
- [Python Package Usage](#python-package-usage)
- [Custom Voice Generation](#custom-voice-generate)
- [Voice Design](#voice-design)
- [Voice Clone](#voice-clone)
- [Voice Design then Clone](#voice-design-then-clone)
- [Tokenizer Encode and Decode](#tokenizer-encode-and-decode)
- [Launch Local Web UI Demo](#launch-local-web-ui-demo)
- [DashScope API Usage](#dashscope-api-usage)
- [vLLM Usage](#vllm-usage)
- [Fine Tuning](#fine-tuning)
- [Evaluation](#evaluation)
- [Citation](#citation)
## Overview
### Introduction

![](https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-TTS-Repo/qwen3_tts_introduction.png)

Qwen3-TTS는 글로벌 애플리케이션의 요구를 충족하기 위해 10개의 주요 언어(중국어, 영어, 일본어, 한국어, 독일어, 프랑스어, 러시아어, 포르투갈어, 스페인어, 이탈리아어)와 다양한 방언 음성 프로필을 지원합니다. 또한, 모델은 강력한 문맥 이해 능력을 갖추고 있어 지시사항과 텍스트 의미에 기반해 어조, 말하기 속도, 감정 표현을 적응적으로 제어할 수 있으며, 노이즈가 있는 입력 텍스트에 대해 현저히 향상된 강건성을 보여줍니다. 주요 특징:
* \*\*강력한 음성 표현(Powerful Speech Representation)\*\*: 자체 개발한 Qwen3-TTS-Tokenizer-12Hz를 기반으로 음성 신호의 효율적인 음향 압축과 고차원 의미 모델링을 달성합니다. 준언어적 정보와 음향 환경 특성을 온전히 보존하며, 경량화된 비 DiT 아키텍처를 통해 고속, 고충실도의 음성 복원을 가능하게 합니다.
* \*\*범용 엔드투엔드 아키텍처(Universal End-to-End Architecture)\*\*: 이산형 멀티 코드북 LM 아키텍처를 활용하여 완전한 정보의 엔드투엔드 음성 모델링을 구현합니다. 이는 전통적인 LM+DiT 방식에 내재된 정보 병목 현상과 연쇄 오류를 완전히 우회하여 모델의 범용성, 생성 효율성 및 성능 한계를 크게 향상시킵니다.
* \*\*극도로 낮은 지연 시간의 스트리밍 생성(Extreme Low-Latency Streaming Generation)\*\*: 혁신적인 Dual-Track 하이브리드 스트리밍 생성 아키텍처를 바탕으로 단일 모델이 스트리밍 및 비스트리밍 생성을 모두 지원합니다. 단일 문자가 입력된 직후 첫 번째 오디오 패킷을 즉시 출력할 수 있으며, 엔드투엔드 합성 지연 시간이 97ms로 낮아 실시간 상호작용 시나리오의 엄격한 요구 사항을 충족합니다.
* \*\*지능형 텍스트 이해 및 음성 제어(Intelligent Text Understanding and Voice Control)\*\*: 자연어 지시사항으로 구동되는 음성 생성을 지원하여 음색, 감정, 운율 등 다차원적인 음향 속성을 유연하게 제어할 수 있습니다. 텍스트 의미 이해를 깊이 있게 통합함으로써 모델이 어조, 리듬, 감정 표현을 적응적으로 조절하여 생생한 "상상하는 대로 들리는" 출력을 달성합니다.
### 모델 아키텍처 (Model Architecture)

![](https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-TTS-Repo/overview.png)

### 출시된 모델 설명 및 다운로드
다음은 이미 출시된 Qwen3-TTS 모델에 대한 소개 및 다운로드 정보입니다. 기술 보고서에 언급된 다른 모델들도 가까운 시일 내에 출시될 예정입니다. 자신의 필요에 맞는 모델을 선택하여 다운로드하세요.
| Tokenizer Name | Description |
|---------------------------------|-------------|
| Qwen3-TTS-Tokenizer-12Hz | 입력 음성을 코드로 인코딩하고 이를 다시 음성으로 디코딩할 수 있는 Qwen3-TTS-Tokenizer-12Hz 모델입니다. |
| Model | Features | Language Support | Streaming | Instruction Control |
|---|---|---|---|---|
| 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을 사용하여 모델을 로드하는 동안, 모델 이름에 따라 모델 가중치가 자동으로 다운로드됩니다. 하지만 실행 중에 가중치를 다운로드하기 곤란한 런타임 환경인 경우, 다음 명령어를 참고하여 모델 가중치를 로컬 디렉터리에 수동으로 다운로드할 수 있습니다:
```bash
# Download through ModelScope (recommended for users in Mainland China)
pip install -U modelscope
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz --local\_dir ./Qwen3-TTS-Tokenizer-12Hz
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz-1.7B-CustomVoice --local\_dir ./Qwen3-TTS-Tokenizer-12Hz-1.7B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz-1.7B-VoiceDesign --local\_dir ./Qwen3-TTS-Tokenizer-12Hz-1.7B-VoiceDesign
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz-1.7B-Base --local\_dir ./Qwen3-TTS-Tokenizer-12Hz-1.7B-Base
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz-0.6B-CustomVoice --local\_dir ./Qwen3-TTS-Tokenizer-12Hz-0.6B-CustomVoice
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz-0.6B-Base --local\_dir ./Qwen3-TTS-Tokenizer-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-Tokenizer-12Hz-1.7B-CustomVoice --local-dir ./Qwen3-TTS-Tokenizer-12Hz-1.7B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz-1.7B-VoiceDesign --local-dir ./Qwen3-TTS-Tokenizer-12Hz-1.7B-VoiceDesign
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz-1.7B-Base --local-dir ./Qwen3-TTS-Tokenizer-12Hz-1.7B-Base
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz-0.6B-CustomVoice --local-dir ./Qwen3-TTS-Tokenizer-12Hz-0.6B-CustomVoice
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz-0.6B-Base --local-dir ./Qwen3-TTS-Tokenizer-12Hz-0.6B-Base
```
## Quickstart
### Environment Setup
Qwen3-TTS를 빠르게 사용하는 가장 쉬운 방법은 PyPI에서 `qwen-tts` 파이썬 패키지를 설치하는 것입니다. 이렇게 하면 필요한 런타임 종속성이 가져와지며, 출시된 모든 Qwen3-TTS 모델을 로드할 수 있습니다. 기존 패키지와의 종속성 충돌을 방지하기 위해 \*\*새롭고 격리된 환경\*\*을 사용하는 것을 권장합니다. 다음과 같이 깨끗한 Python 3.12 환경을 생성할 수 있습니다:
```bash
con

da create -n qwen3-tts python=3.12 -y
conda activate qwen3-tts
```
then run:
```bash
pip install -U qwen-tts
```
코드를 로컬에서 개발하거나 수정하려면, 편집 가능(editable) 모드로 소스에서 설치하세요.
```bash
git clone https://github.com/QwenLM/Qwen3-TTS.git
cd Qwen3-TTS
pip install -e .
```
또한, GPU 메모리 사용량을 줄이기 위해 FlashAttention 2를 사용하는 것을 권장합니다.
```bash
pip install -U flash-attn --no-build-isolation
```
사용 중인 시스템의 RAM이 96GB 미만이고 CPU 코어가 많은 경우 다음을 실행하세요.
```bash
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`으로 로드된 경우에만 사용할 수 있습니다.
### Python 패키지 사용법
설치 후 `Qwen3TTSModel`을 임포트하여 커스텀 음성 TTS, 음성 디자인, 음성 복제를 실행할 수 있습니다. 모델 가중치는 Hugging Face 모델 ID(권장) 또는 다운로드한 로컬 디렉토리 경로로 지정할 수 있습니다. 아래의 모든 `generate\_\*` 함수에서는 표시되고 명시적으로 문서화된 파라미터 외에도 Hugging Face Transformers `model.generate`에서 지원하는 생성 kwargs(예: `max\_new\_tokens`, `top\_p` 등)를 전달할 수 있습니다.
#### 커스텀 음성 생성 (Custom Voice Generate)
커스텀 음성 모델(`Qwen3-TTS-12Hz-1.7B/0.6B-CustomVoice`)의 경우, 단일 문자열 또는 배치 리스트를 `language`, `speaker`, 선택적 `instruct`와 함께 `generate\_custom\_voice`에 전달하기만 하면 됩니다. 또한 `model.get\_supported\_speakers()`와 `model.get\_supported\_languages()`를 호출하여 현재 모델이 지원하는 화자와 언어를 확인할 수 있습니다.
```python
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",
)
# single inference
wavs, sr = model.generate\_custom\_voice(
text="其实我真的有发现，我是一个特别善于观察别人情绪的人。",
language="Chinese", # Pass `Auto` (or omit) for auto language adaptive; if the target language is known, set it explicitly.
speaker="Vivian",
instruct="用特别愤怒的语气说", # Omit if not needed.
)
sf.write("output\_custom\_voice.wav", wavs[0], sr)
# batch inference
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` 모델에서 지원하는 화자 목록과 화자 설명은 다음과 같습니다. 최상의 품질을 위해 각 화자의 모국어를 사용하는 것을 권장합니다. 물론 각 화자는 모델이 지원하는 모든 언어로 말할 수 있습니다.
| Speaker | Voice Description | Native language |
| --- | --- | --- |
| Vivian | Bright, slightly edgy young female voice. | Chinese |
| Serena | Warm, gentle young female voice. | Chinese |
| Uncle\_Fu | Seasoned male voice with a low, mellow timbre. | Chinese |
| Dylan | Youthful Beijing male voice with a clear, natural timbre. | Chinese (Beijing Dialect) |
| Eric | Lively Chengdu male voice with a slightly husky brightness. | Chinese (Sichuan Dialect) |
| Ryan | Dynamic male voice with strong rhythmic drive. | English |
| Aiden | Sunny American male voice with a clear midrange. | English |
| Ono\_Anna | Playful Japanese female voice with a light, nimble timbre. | Japanese |
| Sohee | Warm Korean female voice with rich emotion. | Korean |
#### 음성 디자인 (Voice Design)
음성 디자인 모델(`Qwen3-TTS-12Hz-1.7B-VoiceDesign`)의 경우, `generate\_voice\_design`을 사용하여 타겟 텍스트와 자연어 `instruct` 설명을 제공할 수 있습니다.
```python
import torch
import soundfile as sf
from qwen\_tts import Qwen3TTSModel
model = Qwen

3TTSModel.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`로 설정하면 화자 임베딩만 사용되므로 `ref\_text`가 필요하지 않지만, 클론 품질이 저하될 수 있습니다.
```python
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 ± √(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`를 통해 전달하세요.
```python
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` 함수 설명을 통해 더 고급 사용법을 탐색할 수 있습니다.
#### Voice Design 후 Clone
복제된 화자처럼 재사용할 수 있는 디자인된 음성을 원하시는 경우, 실용적인 워크플로우는 다음과 같습니다: (1) \*\*VoiceDesign\*\* 모델을 사용하여 타겟 페르소나와 일치하는 짧은 참조 클립을 합성하고, (2) 해당 클립을 `create\_voice\_clone\_prompt`에 입력하여 재사용 가능한 프롬프트를 빌드한 후, (3) 매번 피처를 다시 추출하지 않고 `voice\_clone\_prompt`와 함께 `generate\_voice\_clone`을 호출하여 새로운 콘텐츠를 생성합니다. 이는 여러 대사에 걸쳐 일관된 캐릭터 음성을 유지하고 싶을 때 특히 유용합니다.
```python
import torch
import soundfile as sf
from qwen\_tts import Qwen3TTSModel
# create a reference audio in the target style using the VoiceDesign model
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 = "Mal

e, 17세, 테너 음역대, 자신감을 얻어가는 중 - 이제 호흡 지지가 더 깊어졌지만, 긴장하면 여전히 모음이 조여짐"
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 = 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 파형, 딕셔너리/리스트 페이로드를 사용한 인코딩/디코딩을 지원합니다. 예시:
```python
import soundfile as sf
from qwen\_tts import Qwen3TTSTokenizer
tokenizer = Qwen3TTSTokenizer.from\_pretrained(
"Qwen/Qwen3-TTS-Tokenizer-12Hz",
device\_map="cuda:0",
)
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)
```
다양한 입력 형식과 배치 사용법을 포함한 더 많은 토크나이저 예시를 보려면 [예제 코드](https://github.com/QwenLM/Qwen3-TTS/blob/main/examples/test\_tokenizer\_12hz.py)를 참조하세요. 이러한 예제와 `Qwen3TTSTokenizer`의 설명을 통해 더 고급 사용 패턴을 탐색할 수 있습니다.
### 로컬 웹 UI 데모 실행
Qwen3-TTS 웹 UI 데모를 실행하려면 `qwen-tts` 패키지를 설치하고 `qwen-tts-demo`를 실행하기만 하면 됩니다. 도움말을 보려면 아래 명령어를 사용하세요:
```bash
qwen-tts-demo --help
```
데모를 실행하려면 다음 명령어를 사용할 수 있습니다:
```bash
# 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
# Base 모델
qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base --ip 0.0.0.0 --port 8000
```
그런 다음 `http://:8000`을 열거나 VS Code와 같은 도구에서 포트 포워딩을 통해 접속하세요.
#### Base 모델 HTTPS 참고 사항
서버 배포 후 브라우저 마이크 권한 문제를 방지하기 위해, Base 모델 배포의 경우 gradio 서비스를 \*\*HTTPS\*\*로 실행하는 것이 권장되거나 필수적입니다(특히 원격으로 접속하거나 최신 브라우저/게이트웨이 뒤에서 접속할 때). HTTPS를 활성화하려면 `--ssl-certfile`과 `--ssl-keyfile`을 사용하세요. 먼저 개인키와 자체 서명된 인증서(365일 유효)를 생성해야 합니다:
```bash
openssl req -x509 -newkey rsa:2048 \
-keyout key.pem -out cert.pem \
-days 365 -nodes \
-subj "/CN=localhost"
```
그런 다음 HTTPS로 데모를 실행합니다:
```bash
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
```
그리고 `https://:8000`을 열어 체험해 보세요. 브라우저에 경고가 표시되더라도 자체 서명된 인증서에서는 정상적인 현상입니다. 프로덕션 환경에서는 정식 인증서를 사용하세요.
### DashScope API 사용법
추가로

Qwen3-TTS를 탐색할 때, 더 빠르고 효율적인 경험을 위해 DashScope API를 사용해 보시는 것을 권장합니다. 자세한 API 정보 및 문서는 다음을 참고해 주세요:

| API 설명 | API 문서 (중국 본토) | API 문서 (해외) |
|------------------|-----------------------------------|------------------------------------|
| 커스텀 음성 모델용 Qwen3-TTS 실시간 API. | [https://help.aliyun.com/zh/model-studio/qwen-tts-realtime](https://help.aliyun.com/zh/model-studio/qwen-tts-realtime) | [https://www.alibabacloud.com/help/en/model-studio/qwen-tts-realtime](https://www.alibabacloud.com/help/en/model-studio/qwen-tts-realtime) |
| 음성 복제 모델용 Qwen3-TTS 실시간 API. | [https://help.aliyun.com/zh/model-studio/qwen-tts-voice-cloning](https://help.aliyun.com/zh/model-studio/qwen-tts-voice-cloning) | [https://www.alibabacloud.com/help/en/model-studio/qwen-tts-voice-cloning](https://www.alibabacloud.com/help/en/model-studio/qwen-tts-voice-cloning) |
| 음성 디자인 모델용 Qwen3-TTS 실시간 API. | [https://help.aliyun.com/zh/model-studio/qwen-tts-voice-design](https://help.aliyun.com/zh/model-studio/qwen-tts-voice-design) | [https://www.alibabacloud.com/help/en/model-studio/qwen-tts-voice-design](https://www.alibabacloud.com/help/en/model-studio/qwen-tts-voice-design) |

## vLLM 사용법
vLLM은 Qwen3-TTS에 대한 day-0 지원을 공식 제공합니다! Qwen3-TTS 배포 및 추론을 위해 vLLM-Omni를 사용해 보세요. 설치 및 자세한 내용은 [vLLM-Omni 공식 문서](https://docs.vllm.ai/projects/vllm-omni/en/latest/getting\_started/quickstart/#installation)를 확인해 주시기 바랍니다. 현재는 오프라인 추론만 지원됩니다. 온라인 서빙은 추후 지원될 예정이며, vLLM-Omni는 추론 속도 및 스트리밍 기능 등의 영역에서 Qwen3-TTS에 대한 지원과 최적화를 계속해서 제공할 것입니다.

### 오프라인 추론
vLLM-Omni를 사용하여 로컬에서 Qwen3-TTS를 추론할 수 있습니다. 오디오 출력을 생성할 수 있는 예제들을 [vLLM-Omni 저장소](https://github.com/vllm-project/vllm-omni/tree/main/examples/offline\_inference/qwen3\_tts)에 제공하고 있습니다:

```bash
# git clone https://github.com/vllm-project/vllm-omni.git
# cd vllm-omni/examples/offline\_inference/qwen3\_tts
# Run a single sample with CustomVoice task
python end2end.py --query-type CustomVoice
# Batch sample (multiple prompts in one run) with CustomVoice task:
python end2end.py --query-type CustomVoice --use-batch-sample
# Run a single sample with VoiceDesign task
python end2end.py --query-type VoiceDesign
# Batch sample (multiple prompts in one run) with VoiceDesign task:
python end2end.py --query-type VoiceDesign --use-batch-sample
# Run a single sample with Base task in icl mode-tag
python end2end.py --query-type Base --mode-tag icl
```

## 파인튜닝
Qwen3-TTS 파인튜닝에 대한 자세한 지침은 [Qwen3-TTS-Finetuning](finetuning/)을 참고해 주세요.

## 평가
평가 과정에서 모든 모델은 `dtype=torch.bfloat16`으로 추론을 실행했으며 `max\_new\_tokens=2048`로 설정했습니다. 기타 모든 샘플링 파라미터는 체크포인트의 `generate\_config.json`에 있는 기본값을 사용했습니다. Seed-Test 및 InstructTTS-Eval 테스트 세트의 경우 `language="auto"`로 설정하였고, 나머지 모든 테스트 세트에는 해당 `language`를 명시적으로 전달했습니다. 자세한 결과는 아래와 같습니다.

음성 생성 벤치마크
\*Seed-TTS 테스트 세트에서의 제로샷 음성 생성. 성능은 단어 오류율(WER, ↓)로 측정되며, 낮을수록 좋습니다.\*

| 데이터셋 | 모델 | 성능 | |
| --- | --- | --- | --- |
| *내용 일치도 (Content Consistency)* | | | |
| SEED *test-zh* | *test-en* | Seed-TTS (Anastassiou et al., 2024) | 1.12 | 2.25 |
| MaskGCT (Wang et al., 2024) | 2.27 | 2.62 |
| E2 TTS (Eskimez et al., 2024) | 1.97 | 2.19 |
| F5-TTS (Chen et al., 2024) | 1.56 | 1.83 |
| Spark TTS (Wang et al., 2025) | 1.20 | 1.98 |
| Llasa-8B (Ye et al., 2025b) | 1.59 | 2.97 |
| KALL-E (Xia et al., 2024) | 0.96 | 1.94 |
| FireRedTTS 2 (Xie et al., 2025) | 1.14 | 1.95 |
| CosyVoice 3 (Du et al., 2025) | **0.71** | 1.45 |
| MiniMax-Speech (Zhang et al., 2025a) | 0.83 | 1.65 |
| Qwen3-TTS-25Hz-0.6B-Base | 1.18 | 1.64 |
| Qwen3-TTS-25Hz-1.7B-Base | 1.10 | 1.49 |
| Qwen3-TTS-12Hz-0.6B-Base | 0.92 | 1.32 |
| Qwen3-TTS-12Hz-1.7B-Base | 0.77 | **1.24** |

\*TTS 다국어 테스트 셋에서의 다국어 음성 생성. 성능은 내용 일치도의 경우 단어 오류율(WER, ↓), 화자 유사도의 경우 코사인 유사도(SIM, ↑)로 측정됩니다.\*

| 언어 | Qwen3-TTS-25Hz | | Qwen3-TTS-12Hz | | MiniMax | ElevenLabs |
| --- | --- | --- | --- | --- | --- | --- |
| 0.6B-Base | 1.7B-Base | 0.6B-Base | 1.7B-Base |
| *내용 일치도 (Content Consistency)* | | | | | | |
| 중국어 | 1.108 | **0.777** | 1.145 | 0.928 | 2.252 | 16.026 |
| 영어 | 1.048 | 1.014 | **0.836** | 0.934 | 2.164 | 2.339 |
| 독일어 | 1.501 | 0.960 | 1.089 | 1.235 | 1.906 | **0.572** |
| 이탈리아어 | 1.169 | 1.105 | 1.534 | **0.948** | 1.543 | 1.743 |
| 포르투갈어 | 2.046 | 1.778 | 2.254 | 1.526 | 1.877 | **1.331** |
| 스페인어 | 2.031 | 1.491 | 1.491 | 1.126 | **1.029** | 1.084 |
| 일본어 | 4.189 | 5.121 | 6.404 | 3.823 | **3.519** | 10.646 |
| 한국어 | 2.852 | 2.631 | **1.741** | 1.755 | 1.747 | 1.865 |
| 프랑스어 | 2.852 | **2.631** | 2.931 | 2.858 | 4.099 | 5.216 |
| 러시아어 | 5.957 | 4.535 | 4.458 | **3.212** | 4.281 | 3.878 |
| *화자 유사도 (Speaker Similarity)* | | | | | | |
| 중국어 | 0.797 | 0.796 | **0.811** | 0.799 | 0.780 | 0.677 |
| 영어 | 0.811 | 0.815 | **0.829** | 0.775 | 0.756 | 0.613 |
| 독일어 | 0.749 | 0.737 | 0.769 | **0.775** | 0.733 | 0.614 |
| 이탈리아어 | 0.722 | 0.718 | 0.792 | **0.817** | 0.699 | 0.579 |
| 포르투갈어 | 0.790 | 0.783 | 0.794 | **0.817** | 0.805 | 0.711 |
| 스페인어 | 0.732 | 0.731 | 0.812 | **0.814** | 0.762 | 0.615 |
| 일본어 | **0.810** | 0.807 | 0.798 | 0.788 | 0.776 | 0.738 |
| 한국어 | **0.824** | 0.814 | 0.812 | 0.799 | 0.779 | 0.700 |
| 프랑스어 | 0.698 | 0.703 | 0.700 | **0.714** | 0.628 | 0.535 |
| 러시아어 | 0.734 | 0.744 | 0.781 | **0.792** | 0.761 | 0.676 |

\*크로스링구얼 벤치마크에서의 교차 언어 음성 생성. 성능은 혼합 오류율(영어의 경우 WER, 기타 언어의 경우 CER, ↓)로 측정됩니다.\*

| 작업 (Task) | Qwen3-TTS-25Hz-1.7B-Base | Qwen3-TTS-12Hz-1.7B-Base | CosyVoice3 | CosyVoice2 |
| --- | --- | --- | --- | --- |
| en-to-zh | 5.66 | **4.77** | 5.09 | 13.5 |
| ja-to-zh | 3.92 | 3.43 | **3.05** | 48.1 |
| ko-to-zh | 1.14 | 1.08 | **1.06** | 7.70 |
| zh-to-en | 2.91 | **2.77** | 2.98 | 6.47 |
| ja-to-en | 3.95 | **3.04** | 4.20 | 17.1 |
| ko-to-en | 3.48 | **3.09** | 4.19 | 11.2 |
| zh-to-ja | 9.29 | 8.40 | **7.08** | 13.1 |
| en-to-ja | 7.74 | 7.21 | **6.80** | 14.9 |
| ko-to-ja | 4.17 | **3.67** | 3.93 | 5.86 |
| zh-to-ko | 8.12 | **4.82** | 14.4 | 24.8 |
| en-to-ko | 6.83 | **5.14** | 5.87 | 21.9 |
| ja-to-ko | 6.86 | **5.59** | 7.92 | 21.5 |

\*InstructTTSEval에서의 제어 가능한 음성 생성. 성능은 속성 인식 및 합성 정확도(APS), 설명-음성 일치도(DSD), 응답 정밀도(RP)로 측정됩니다.\*

| 유형 | 모델 | InstructTTSEval-ZH | | | InstructTTSEval-EN | | |
| --- | --- | --- | --- | --- | --- | --- | --- |
| APS (↑) | DSD (↑) | RP (↑) | APS (↑) | DSD (↑) | RP (↑) |
| *Target Speaker* | Gemini-flash | 88.2 | **90.9** | **77.3** | **92.3** | **93.8** | **80.1** |
| Gemini-pro | **89.0** | 90.1 | 75.5 | 87.6 | 86.0 | 67.2 |
| Qwen3TTS-25Hz-1.7B-CustomVoice | 83.1 | 75.0 | 63.0 | 79.0 | 82.8 | 69.3 |
| Qwen3TTS-12Hz-1.7B-CustomVoice | 83.0 | 77.8 | 61.2 | 77.3 | 77.1 | 63.7 |
| GPT-4o-mini-tts | 54.9 | 52.3 | 46.0 | 76.4 | 74.3 | 54.8 |
| *Voice Design* | Qwen3TTS-12Hz-1.7B-VD | **85.2** | **81.1** | **65.1** | 82.9 | **82.4** | **68.4** |
| Mimo-Audio-7B-Instruct (Zhang et al., 2025b) | 75.7 | 74.3 | 61.5 | 80.6 | 77.6 | 59.5 |
| VoiceSculptor (Hu et al., 2026) | 75.7 | 64.7 | 61.5 | - | - | - |
| Hume | - | - | - | **83.0** | 75.3 | 54.3 |
| VoxInstruct (Zhou et al., 2024) | 47.5 | 52.3 | 42.6 | 54.9 | 57.0 | 39.3 |
| Parler-tts-mini (Lyth & King, 2024) | - | - | - | 63.4 | 48.7 | 28.6 |
| Parler-tts-large (Lyth & King, 2024) | - | - | - | 60.0 | 45.9 | 31.2 |
| PromptTTS (Guo et al., 2023) | - | - | - | 64.3 | 47.2 | 31.4 |
| PromptStyle (Liu et al., 2023) | - | - | - | 57.4 | 46.4 | 30.9 |

\*TTS 다국어 테스트 셋에서의 Target-Speaker 다국어 음성 생성 성능. 성능은 단어 오류율(WER, ↓)로 측정됩니다.\*

| 언어 | Qwen3-TTS-25Hz | | Qwen3-TTS-12Hz | | GPT-4o-Audio Preview |
| --- | --- | --- | --- | --- | --- |
| 0.6B-CustomVoice | 1.7B-CustomVoice | 0.6B-CustomVoice | 1.7B-CustomVoice |
| 중국어 | 0.874 | **0.708** | 0.944 | 0.903 | 3.519 |
| 영어 | 1.332 | 0.936 | 1.188 | **0.899** | 2.197 |
| 독일어 | 0.990 | **0.634** | 2.722 | 1.057 | 1.161 |
| 이탈리아어 | 1.861 | 1.271 | 2.545 | 1.362 | **1.194** |
| 포르투갈어 | 1.728 | 1.854 | 3.219 | 2.681 | **1.504** |
| 스페인어 | 1.309 | 1.284 | **1.154** | 1.330 | 4.000 |
| 일본어 | **3.875** | 4.518 | 6.877 | 4.924 | 5.001 |
| 한국어 | 2.202 | 2.274 | 3.053 | **1.741** | 2.763 |
| 프랑스어 | 3.865 | **3.080** | 3.841 | 3.781 | 3.605 |
| 러시아어 | 6.529 | **4.444** | 5.809 | 4.734 | 5.250 |

\*장문 음성 생성 결과. 성능은 단어 오류율(WER, ↓)로 측정됩니다.\*

| 데이터셋 | 모델 | 성능 | |
| --- | --- | --- | --- |
| *Content Consistency* | | | |
| *long-zh* | *long-en* | Higgs-Audio-v2 (chunk) (Boson AI, 2025) | 5.505 | 6.917 |
| VibeVoice (Peng et al., 2025) | 22.619 | 1.780 |
| VoxCPM (Zhou et al., 2025) | 4.835 | 7.474 |
| Qwen3-TTS-25Hz-1.7B-CustomVoice | **1.517** | **1.225** |
| Qwen3-TTS-12Hz-1.7B-CustomVoice | 2.356 | 2.812 |

Speech Tokenizer 벤치마크
\*ASR 태스크에서의 다양한 지도 학습 기반 의미론적 음성 토크나이저 간 비교.\*

| 모델 | 코드북 크기 | FPS | C.V. EN | C.V. CN | Fluers EN | Fluers CN |
| --- | --- | --- | --- | --- | --- | --- |
| S3 Tokenizer(VQ) (Du et al., 2024a) | 4096 | 50 | 12.06 | 15.38 | - | - |
| S3 Tokenizer(VQ) (Du et al., 2024a) | 4096 | 25 | 11.56 | 18.26 | 7.65 | 5.03 |
| S3 Tokenizer(FSQ) (Du et al., 2024a) | 6561 | 25 | 10.67 | **7.29** | 6.58 | 4.43 |
| Qwen-TTS-Tokenizer-25Hz (Stage 1) | 32768 | 25 | **7.51** | 10.73 | **3.07** | **4.23** |
| Qwen-TTS-Tokenizer-25Hz (Stage 2) | 32768 | 25 | 10.40 | 14.99 | 4.14 | 4.67 |

\*의미론적 관련 음성 토크나이저 간 비교.\*

| Model | NQ | Codebook Size | FPS | PESQ\_WB | PESQ\_NB | STOI | UTMOS | SIM |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| SpeechTokenizer (Zhang et al., 2023a) | 8 | 1024 | 50 | 2.60 | 3.05 | 0.92 | 3.90 | 0.85 |
| X-codec (Ye et al., 2025a) | 2 | 1024 | 50 | 2.68 | 3.27 | 0.86 | 4.11 | 0.84 |
| X-codec 2 (Ye et al., 2025b) | 1 | 65536 | 50 | 2.43 | 3.04 | 0.92 | 4.13 | 0.82 |
| XY-Tokenizer (Gong et al., 2025) | 8 | 1024 | 12.5 | 2.41 | 3.00 | 0.91 | 3.98 | 0.83 |
| Mimi (Défossez et al., 2024) | 16 | 2048 | 12.5 | 2.88 | 3.42 | 0.94 | 3.87 | 0.87 |
| FireredTTS 2 Tokenizer (Xie et al., 2025) | 16 | 2048 | 12.5 | 2.73 | 3.28 | 0.94 | 3.88 | 0.87 |
| Qwen-TTS-Tokenizer-12Hz | 16 | 2048 | 12.5 | **3.21** | **3.68** | **0.96** | **4.16** | **0.95** |

## Citation
저희의 논문과 코드가 연구에 유익하였다면 star :star:와 인용 :pencil:을 부탁드립니다 :)
```BibTeX
@article{Qwen3-TTS,
title={Qwen3-TTS Technical Report},
author={Hangrui Hu and Xinfa Zhu and Ting He and Dake Guo and Bin Zhang and Xiong Wang and Zhifang Guo and Ziyue Jiang and Hongkun Hao and Zishan Guo and Xinyu Zhang and Pei Zhang and Baosong Yang and Jin Xu and Jingren Zhou and Junyang Lin},
journal={arXiv preprint arXiv:2601.15621},
year={2026}
}
```
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=QwenLM/Qwen3-TTS&type=Date)](https://star-history.com/#QwenLM/Qwen3-TTS&Date)

Qwen3-TTS

Qwen3-TTS 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Qwen3-TTS

Qwen3-TTS 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README