Xorbits Inference 部署指南：Qwen3-TTS-12Hz-1.7B-VoiceDesign 语音设计与多引擎实战-开发者社区

Xorbits Inference 部署指南：Qwen3-TTS-12Hz-1.7B-VoiceDesign 语音设计与多引擎实战

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference

Xorbits Inference（xinference）内置了 Qwen3-TTS-12Hz-1.7B-VoiceDesign 语音合成模型，它支持 text2audio 与 text2audio_voice_design 双能力，可在不提供任何参考音频的情况下通过自然语言指令设计全新音色。本文以该模型的官方文档 qwen3-tts-12hz-1.7b-voicedesign.rst 为核心，结合仓库源码说明模型规格、PyTorch/MLX 双引擎差异、启动方式与推理调用细节，帮助你快速在本地或生产环境跑通"零样本音色设计 + 文本转语音"完整链路。

模型概述：从零创造音色的 VoiceDesign 模型

根据官方模型文档，该模型的基本信息如下：

模型名称（Model Name）：Qwen3-TTS-12Hz-1.7B-VoiceDesign
模型家族（Model Family）：qwen3_tts
能力（Abilities）：text2audio、text2audio_voice_design
多语言（Multilingual）：True

它隶属于 Qwen3-TTS 系列。与系列中另外两个成员——面向基础合成的Qwen3-TTS-12Hz-1.7B-Base（能力为text2audio、text2audio_voice_cloning）和面向给定说话人克隆的Qwen3-TTS-12Hz-1.7B-CustomVoice——不同，VoiceDesign 变体的核心差异在于新增了text2audio_voice_design能力：你不需要提供参考语音，只需要用一段自然语言描述想要的音色风格，模型即可从零设计并合成出符合描述的语音，适合角色配音、有声内容定制、游戏/影视试音等"凭空造音"场景。

仓库内置模型注册表 model_spec.json 中对该模型的完整定义进一步印证了这一点：

模型 ID 为Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign（Hugging Face 分支main），同时提供 ModelScope 镜像Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign（分支master），国内网络环境可自动走 ModelScope 源；
官方声明支持 11 种语言：自动检测（auto）以及中文、英文、法文、德文、意大利文、日文、韩文、葡萄牙文、俄文、西班牙文；
依赖隔离：PyTorch 引擎的虚拟环境依赖为qwen-tts以及系统级torch、numpy、pandas，意味着运行前需确保qwen-tts包可用。

模型规格与双引擎（PyTorch / MLX）

官方文档给出的引擎与模型 ID 如下：

引擎	模型 ID（仓库配置）
PyTorch	`Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign`
MLX	`mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit`

其中 PyTorch 引擎面向 CUDA GPU 环境（默认加载到cuda:0，使用 bfloat16 精度）；MLX 引擎是面向 Apple Silicon 的 8-bit 量化版本，由 model_spec.json 中的独立条目Qwen3-TTS-12Hz-1.7B-VoiceDesign-MLX定义，依赖mlx-audio[tts]==0.4.6与soundfile，模型来源为 Hugging Face 的mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit，并固定了具体 revision（commitf90d6177）。

在源码层面，两个引擎的分发逻辑位于 engine.py：

MLXAudioTTSEngineModel（MLX 引擎）通过platform.system() == "Darwin"与platform.processor() == "arm"两个条件判断平台，仅当运行在 Apple Silicon（M 系列芯片）macOS 上时才会匹配；
PyTorchQwen3TTSAudioModel（PyTorch 引擎）是 qwen3_tts 家族在PyTorch/ 未指定引擎时的默认选择；
模型名Qwen3-TTS-12Hz-1.7B-VoiceDesign同时出现在 engine.py 的MLX_AUDIO_TTS_MODEL_NAMES集合中，说明它是双引擎共用的内置模型名。

注意：两个引擎的注册顺序决定了默认引擎。register_builtin_audio_engines()中PyTorch引擎先注册，因此在未显式指定--model-engine时，PyTorch 会成为默认引擎。

启动模型：xinference launch 命令

官方文档给出了标准启动命令：

xinference launch --model-name Qwen3-TTS-12Hz-1.7B-VoiceDesign --model-type audio --model-engine PyTorch

参数拆解：

--model-name：指定内置模型名，必须是Qwen3-TTS-12Hz-1.7B-VoiceDesign（区分大小写）；
--model-type：固定为audio，声明这是一类音频模型；
--model-engine：指定推理引擎。PyTorch 环境写PyTorch；Apple Silicon 环境可写MLX使用 8-bit 量化版。

如需在 Apple Silicon 上启用 MLX 引擎，执行：

xinference launch --model-name Qwen3-TTS-12Hz-1.7B-VoiceDesign --model-type audio --model-engine MLX

关于依赖的前置条件，从 qwen3_tts.py 的load()实现可以看出：PyTorch 引擎在加载时会尝试import qwen_tts与torch，若缺少会抛出ImportError并提示pip install qwen-tts；MLX 引擎则在 mlx_audio.py 中要求安装mlx-audio[tts]。xinference 的内置模型虚拟环境机制会自动为模型准备这些依赖，也可以提前在目标环境中确认qwen-tts（PyTorch）或mlx-audio[tts]（MLX）已就绪。

引擎分发与加载原理

模型加载后，xinference 会根据模型家族（qwen3_tts）与平台/引擎选择实现类。PyTorch 路径的加载逻辑在 qwen3_tts.py：

self._model = Qwen3TTSModel.from_pretrained( self._model_path, device_map=self._device if self._device else "cuda:0", dtype=torch.bfloat16, attn_implementation="flash_attention_2", # 仅当检测到 flash-attn 时 )

关键细节：

默认设备为cuda:0，dtype 固定为torch.bfloat16；
当环境中可用 flash-attention 时（通过 utils.py 的is_flash_attn_available()判断），会自动采用flash_attention_2注意力实现加速；否则退回默认实现，保证兼容性；
MLX 路径则通过 mlx_audio.py 调用mlx_audio.tts.utils.load加载，并配合MLXModelThreadMixin将 load 与推理固定到单一持久线程执行，规避 MLX 在跨线程场景下的 GPU stream 绑定问题。

能力分派：VoiceDesign / CustomVoice / 声音克隆如何抉择

模型加载后，能力分派的入口位于 qwen3_tts.py 的speech()方法。其逻辑会根据model_family.model_name的后缀做分支：

模型名以VoiceDesign结尾：调用self._model.generate_voice_design(text=input, language=language, instruct=instruct, **kwargs)——这正是本文档对应模型的核心路径。instruct参数承载自然语言音色描述，例如"一位沉稳的中年男性旁白"；
模型名以CustomVoice结尾：调用generate_custom_voice，此时voice参数必须是模型支持的说话人；
Base 模型（两者都不是）：不提供上述两种生成能力，必须同时提供prompt_speech与prompt_text走generate_voice_clone声音克隆路径。

语言参数方面（qwen3_tts.py），默认language="chinese"，且会先通过self._model.get_supported_languages()校验，传入不支持的语种会抛出带支持列表的ValueError，因此language需从模型支持的语言中选择（如chinese、english等，或使用auto）。

另外，无论哪个引擎，都会通过apply_audio_seed(kwargs)/apply_mlx_audio_seed(kwargs)消费可选的seed参数（见 utils.py），用于同时对 Python、NumPy、Torch（以及 MLX）随机数种子做设置，从而实现多次生成结果的可复现。

推理调用：OpenAI 兼容语音接口与 Python 客户端

xinference 将语音合成暴露为 OpenAI 兼容的 REST 接口/v1/audio/speech，路由注册位于 audio.py。若开启鉴权，该接口受models:readscope 保护。

REST API 调用（curl）

curl -X POST http://localhost:9997/v1/audio/speech \ -H "Content-Type: application/json" \ -d '{ "model": "<model_uid>", "input": "你好，我是由 VoiceDesign 模型合成的语音。", "voice": "", "response_format": "mp3", "speed": 1.0, "stream": false, "kwargs": { "language": "chinese", "instruct": "亲切温和的女性嗓音，语速平缓" } }' --output output.mp3

字段说明：

model：启动模型后生成的模型 UID（可在xinference list中查看）；
input：待合成的文本，Python 客户端文档标注最大长度 4096 字符；
voice：VoiceDesign 路径下可留空，音色由kwargs.instruct控制；
response_format：默认mp3，底层经 soundfile 编码，亦可尝试wav等格式；
speed：语速系数，默认1.0；
stream：流式输出标记。注意：从 qwen3_tts.py 与 mlx_audio.py 看，两个引擎目前都不支持流式生成，stream=true会直接抛异常；
kwargs：透传给底层模型生成函数的附加参数，VoiceDesign 场景下关键的是language（默认chinese）与instruct（音色指令）。

Python 客户端调用

使用仓库自带的同步客户端（restful_client.py）：

from xinference.client import Client client = Client("http://localhost:9997") model_uid = client.launch_model( model_name="Qwen3-TTS-12Hz-1.7B-VoiceDesign", model_type="audio", model_engine="PyTorch", ) audio = client.speech( model=model_uid, input="欢迎使用 Xinference 零样本音色设计语音合成。", voice="", response_format="mp3", speed=1.0, stream=False, language="chinese", instruct="低沉而富有磁性的男声，适合纪录片旁白", ) with open("output.mp3", "wb") as f: f.write(audio)

说明：

client.speech的参数中，input、voice、response_format、speed、stream为显式形参，其余**kwargs（如language、instruct、seed）会被序列化为kwargsJSON 字段提交给后端；
如需可复现结果，可在kwargs中传入seed整数；
结果返回音频二进制（bytes），直接写文件即可；若本机环境允许，也可安装 soundfile 后在内存中解码。

常见问题与排查

提示Failed to import module 'qwen-tts'：PyTorch 引擎依赖缺失，按提示pip install qwen-tts后重启模型（qwen3_tts.py）；
提示Language 'xx' is not supported：language传入了模型不支持的语言，改用chinese/english等文档所列语言或auto；
流式请求报错：当前实现不支持流式输出，将stream设为false；
MLX 引擎在非 Apple Silicon 上不可用：MLX 引擎仅匹配 Darwin + arm 平台，x86/Linux 请使用 PyTorch 引擎；
音色不达预期：尝试更具体、更结构化的instruct描述（如性别、年龄段、情绪、语速、风格），并可配合seed固定随机性做对比实验。

小结

Qwen3-TTS-12Hz-1.7B-VoiceDesign 是 xinference 内置语音模型家族中主打"自然语言定义音色"的变体：一条xinference launch命令即可启动，PyTorch 引擎面向 CUDA 环境、MLX 引擎面向 Apple Silicon 的 8-bit 量化部署，推理侧通过 OpenAI 兼容的/v1/audio/speech接口或Client.speech调用，在kwargs中透传language与instruct即可实现零样本、无参考音频的音色设计与语音合成，适合快速搭建个性化 TTS 应用。

如需查看该模型的相邻变体（Base / CustomVoice）与完整内置音频模型清单，可继续阅读 doc/source/models/builtin/audio 目录下的对应文档。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考