README.md

# Qwen3-TTS
## 论文
[Qwen3-TTS Technical Report](https://arxiv.org/abs/2601.15621)

## 模型简介
由通义千问（Qwen）开发的一系列强大的语音生成能力，全面支持声音克隆、音色设计、超高质量拟人化语音合成以及基于自然语言的语音控制，为开发者和用户提供了目前最丰富的语音生成功能集。
<div align=center>
    <img src="./doc/qwen3-tts.png"/>
</div>
Qwen3-TTS 覆盖10种主要语言（中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文和意大利文），并提供多种方言音色配置，以满足全球化的应用需求。此外，该模型具备强大的上下文理解能力，可根据指令和文本语义自适应调节语调、语速和情感表达，并对含噪声的输入文本展现出显著增强的鲁棒性。<br>
主要特性如下：<br>
强大的语音表征能力：基于自研的 Qwen3-TTS-Tokenizer-12Hz，实现对语音信号的高效声学压缩与高维语义建模，完整保留副语言信息（如语气、情绪）及声学环境特征，并通过轻量级非 DiT 架构实现高速、高保真的语音重建。<br>
通用端到端架构：采用离散多码本语言模型（LM）架构，实现全信息端到端语音建模，彻底规避了传统“语言模型 + DiT”方案中存在的信息瓶颈与级联误差问题，显著提升模型的通用性、生成效率和性能上限。<br>
极致低延迟流式生成：基于创新的双轨混合流式生成架构，单个模型同时支持流式与非流式生成模式。在用户仅输入单个字符后即可立即输出首个音频包，端到端合成延迟低至 97 毫秒，充分满足实时交互场景的严苛要求。<br>
智能文本理解与语音控制：支持由自然语言指令驱动的语音生成，可灵活调控音色、情感、韵律等多维度声学属性。通过深度融合文本语义理解能力，模型能自适应调整语调、节奏与情感表达，实现“所想即所听”的拟人化语音输出。<br>


## 环境依赖
| 软件 | 版本 |
| :------: | :------: |
| DTK | 26.04 |
| python | 3.10.12 |
| transformers | 4.57.6 |
| vllm | 0.18.1+das.dtk2604 |
| torchaudio | 2.10.0 |
| vllm-omni | 0.18.0 |

推荐使用镜像:harbor.sourcefind.cn:5443/dcu/admin/base/custom:vllm018-ubuntu22.04-dtk26.04-nemotron-20260422

```bash
docker run -it \
    --shm-size 60g \
    --network=host \
    --name qwen3-tts \
    --privileged \
    --device=/dev/kfd \
    --device=/dev/dri \
    --device=/dev/mkfd \
    --group-add video \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    -u root \
    -v /opt/hyhal/:/opt/hyhal/:ro \
    -v /path/your_code_data/:/path/your_code_data/ \
    harbor.sourcefind.cn:5443/dcu/admin/base/custom:vllm018-ubuntu22.04-dtk26.04-nemotron-20260422 bash
```
更多镜像可前往[光源](https://sourcefind.cn/#/service-list)下载使用。

关于本项目DCU显卡所需的特殊深度学习库可从[光合](https://developer.sourcefind.cn/tool/)开发者社区下载安装，其它包参照requirements.txt安装：
```
pip install -r requirements.txt
```

镜像内其他环境配置
```
pip install vllm-omni==0.18.0 --no-build-isolation
pip install torchaudio-2.10.0-cp310-cp310-linux_x86_64.whl --no-deps
```


## 数据集
暂无

## 训练
暂无

## 推理

### transformers
#### 单机推理
```
VoiceDesign
python test_model_12hz_voice_design.py

CustomVoice
python test_model_12hz_custom_voice.py

VoiceClone
python test_model_12hz_base.py
```
### vllm
#### 单机推理
VoiceDesign
```bash
## serve启动
vllm-omni serve Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-VoiceDesign \
    --stage-configs-path qwen3_tts.yaml \
    --omni \
    --port 8001 \
    --trust-remote-code \
    --enforce-eager \
    --served-model-name qwen3-tts

## client访问
curl -X POST http://localhost:8001/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{
        "model":"qwen3-tts",
        "input": "其实我真的有发现，我是一个特别善于观察别人情绪的人。",
        "voice": "vivian",
        "instructions": "用特别开心的语气说",
        "task_type": "VoiceDesign",
        "x_vector_only_mode": null,
        "ref_text": null,
        "ref_audio": null}' \
    --output output_design.wav
```

CustomVoice
```bash
## serve启动
vllm-omni serve Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-CustomVoice \
    --stage-configs-path qwen3_tts.yaml \
    --omni \
    --port 8001 \
    --trust-remote-code \
    --enforce-eager \
    --served-model-name qwen3-tts

## client访问
curl -X POST http://localhost:8001/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{
        "model":"qwen3-tts",
        "input": "你好，我是通义千问",
        "voice": "vivian",
        "language": "Chinese",
        "task_type": "CustomVoice",
        "x_vector_only_mode": null,
        "ref_text": null,
        "ref_audio": null}' \
    --output output_custom.wav
```

VoiceClone
```bash
## serve启动
vllm-omni serve Qwen3-TTS/Qwen3-TTS-12Hz-1.7B-Base \
    --stage-configs-path qwen3_tts.yaml \
    --omni \
    --port 8001 \
    --trust-remote-code \
    --enforce-eager \
    --served-model-name qwen3-tts

## client访问
REF_AUDIO_B64=$(base64 -w 0 output_audio/output.wav)
curl -X POST http://localhost:8001/v1/audio/speech \
    -H "Content-Type: application/json" \
    --output output_base.wav \
    -d @- <<JSON
  {
    "model": "qwen3-tts",
    "input": "哥哥，欢迎回家，要抱抱",
    "language": "Chinese",
    "task_type": "Base",
    "x_vector_only_mode": false,
    "ref_text": "哥哥，你回来啦，人家等了你好久好久了，要抱抱！",
    "ref_audio": "data:audio/wav;base64,${REF_AUDIO_B64}",
    "max_new_tokens": 256
  }
JSON


```


## 效果展示

示例输出音频：output_audio\output.wav

### 精度
`DCU与GPU精度一致，推理框架：transformers,vllm`

## 预训练权重
| 模型名称  | 权重大小  | DCU型号  | 最低卡数需求 |下载地址|
|:-----:|:----------:|:----------:|:---------------------:|:----------:|
| Qwen3-TTS-12Hz-1.7B-VoiceDesign | 1.7B | K100AI,BW1000 | 1 | [Modelscope](https://www.modelscope.cn/models/Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign)|
| Qwen3-TTS-12Hz-1.7B-CustomVoice | 1.7B | K100AI,BW1000 | 1 | [Modelscope](https://www.modelscope.cn/models/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice)|
| Qwen3-TTS-12Hz-1.7B-Base | 1.7B | K100AI,BW1000 | 1 | [Modelscope](https://www.modelscope.cn/models/Qwen/Qwen3-TTS-12Hz-1.7B-Base)|

## 源码仓库及问题反馈
- https://developer.sourcefind.cn/codes/modelzoo/qwen3-tts_pytorch

## 参考资料
- https://github.com/QwenLM/Qwen3-TTS