Qwen3-TTS localmente: síntese de voz e vozes clonada

#Por que Qwen3-TTS em vez de uma voz na nuvem

Os serviços online de síntese de voz soam bem, mas cada frase que você confia a eles sai da sua máquina, é cobrada por caractere e depende de uma conta que pode ser encerrada. Para um leitor de documentos internos, um assistente de automação residencial ou um protótipo de aplicativo, uma voz que funciona inteiramente localmente elimina essas três dependências de uma só vez.

No ecossistema aberto, duas famílias coexistiam até então. De um lado, os modelos muito leves, como Piper ou Kokoro: rápidos no processador, vozes fixas, sem clonagem. Do outro, modelos mais pesados e expressivos, geralmente centrados no inglês e no chinês. O Qwen3-TTS fica entre os dois: pesos compactos, mas uma arquitetura do tipo LLM que aceita instruções de estilo em linguagem natural e suporte explícito ao francês desde o lançamento.

A particularidade da família é ser dividida em três comportamentos, em vez de um único modelo que faz tudo. Você baixa apenas a variante correspondente à sua necessidade, o que faz diferença em uma GPU de 8 ou 12 GB compartilhada com um LLM de texto.

#Modelos disponíveis: Base, CustomVoice, VoiceDesign

Au lancement, la famille comprend deux tailles de modèle, 0,6 et 1,7 milliard de paramètres, déclinées en trois variantes fonctionnelles, plus un tokenizer audio partagé. Les identifiants Hugging Face suivent le motif Qwen/Qwen3-TTS-12Hz-<tamanho>-<variante>. Le « 12Hz » désigne la fréquence du codec audio: le modèle produit douze trames de jetons acoustiques par seconde de parole, ce qui explique sa frugalité en calcul par rapport à des codecs plus denses.

CustomVoice

Vozes predefinidas, cada uma com um timbre e um idioma de origem, controláveis por uma instrução de estilo («fale devagar, com um tom tranquilizador»). Esta é a variante a escolher para ler um texto sem precisar se preocupar com a voz. Disponível em 0,6B e 1,7B.

VoiceDesign

Você descreve a voz desejada em linguagem natural (idade, gênero percebido, energia, sotaque, emoção) e o modelo a inventa. Nenhuma gravação de referência, portanto nenhuma pessoa real é imitada. Publicada em 1,7B.

Base

Clonagem a partir de um trecho de áudio de alguns segundos e de sua transcrição. Esta é a variante mais poderosa e a única que envolve uma questão de consentimento, tratada mais adiante. Disponível em 0,6B e 1,7B.

Tokenizer-12Hz

O codec de áudio que codifica e decodifica a fala. Ele é baixado automaticamente pelas variantes acima; você só precisa manipulá-lo em casos de uso avançado.

Os idiomas anunciados são chinês, inglês, japonês, coreano, alemão, francês, russo, português, espanhol e italiano, além de vários dialetos chineses. O parâmetro de idioma aceita um nome explícito, como “French”, ou “Auto”, para deixar o modelo detectar o idioma do texto. Para francês, forçar o valor evita hesitações de pronúncia em nomes próprios e anglicismos.

#Pré-requisitos de hardware e software

Sistema

Linux x86_64 é o alvo documentado pelo repositório. macOS e Windows são possíveis, com as ressalvas detalhadas na seção dedicada.

GPU

Uma placa NVIDIA com CUDA é o caminho previsto. Uma RTX 3060 de 12 GB é mais que suficiente apenas para a 1,7B; a execução no processador funciona para testar uma frase, mas não é adequada para uso interativo.

Python

O repositório recomenda Python 3.12 em um ambiente virtual dedicado. Evite instalar no ambiente do sistema ou no ambiente de outro projeto de áudio: as versões de PyTorch e transformers exigidas pelo pacote podem entrar em conflito.

Espaço em disco

Considere alguns gigabytes por variante baixada, no cache do Hugging Face (~/.cache/huggingface por padrão).

Rede

Somente na primeira inicialização, para baixar os pesos. Depois, tudo funciona offline.

Um último pré-requisito não é técnico: se você pretende usar a variante Base, tenha uma gravação cuja voz você tenha o direito de utilizar. A própria voz é o caso mais simples e seguro para aprender.

#Etapa 1: instalar o pacote qwen-tts

O pacote Python oficial se chama qwen-tts no PyPI e é importado com o nome qwen_tts. Ele instala PyTorch e transformers como dependências. A instalação abaixo usa um ambiente virtual padrão; o conda também funciona bem, se for o seu hábito.

# Environnement isolé
python3.12 -m venv ~/qwen3-tts
source ~/qwen3-tts/bin/activate
pip install --upgrade pip

# Paquet officiel
pip install -U qwen-tts

# Lecture et écriture de fichiers audio pour les exemples
pip install soundfile

O repositório oferece opcionalmente o FlashAttention 2 para acelerar a inferência em GPUs recentes. Sua compilação é demorada e falha em algumas combinações de CUDA/PyTorch. Ele não é indispensável: sem ele, o modelo usa a atenção padrão do PyTorch. Instale-o somente depois que o restante estiver funcionando.

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

Verifique se o import passe e se o PyTorch reconhece corretamente sua GPU antes de prosseguir.

python -c "import torch, qwen_tts; print(torch.__version__, torch.cuda.is_available())"

#Etapa 2: gerar uma primeira frase em francês com o Qwen3-TTS

A variante CustomVoice é a mais direta para um primeiro teste: não requer gravação de referência nem descrição a ser redigida. Carregamos o modelo, escolhemos uma voz na lista do repositório, informamos o texto e o idioma. A primeira chamada baixa os pesos do Hugging Face.

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,
)

wavs, sr = model.generate_custom_voice(
    text="Bonjour, ceci est un test de synthèse vocale locale avec Qwen3-TTS.",
    language="French",
    speaker="Ryan",
    instruct="Ton calme et posé, débit modéré.",
)

sf.write("sortie_custom_voice.wav", wavs[0], sr)
print("Fichier écrit à", sr, "Hz")

Três parâmetros merecem uma explicação. O campo speaker designa uma das vozes predefinidas; a lista exata, com o idioma de origem e a descrição de cada timbre, está no README e na página do modelo CustomVoice no Hugging Face. Todas essas vozes podem ler em francês, mas cada uma mantém um sotaque coerente com seu idioma nativo, o que é uma escolha estética, não um defeito. O campo instruct é uma instrução de estilo em linguagem natural: emoção, ritmo, intenção. Ele é opcional. Por fim, a função retorna uma lista de formas de onda e a taxa de amostragem, permitindo processar vários textos em lote.

textes = [
    "Première phrase à lire.",
    "Deuxième phrase, avec une intonation différente.",
]
wavs, sr = model.generate_custom_voice(
    text=textes,
    language=["French", "French"],
    speaker=["Ryan", "Serena"],
    instruct=["Neutre.", "Enjouée, un peu plus rapide."],
)
for i, w in enumerate(wavs):
    sf.write(f"lot_{i}.wav", w, sr)

#Etapa 3: criar uma voz por descrição

O VoiceDesign atende a uma necessidade frequente: você quer uma voz que não existe na lista, sem imitar ninguém. Descrevemos o resultado em uma ou duas frases, e o modelo produz um timbre coerente com a instrução. É também a variante preferível para um produto, pois nenhuma voz real é reproduzida.

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,
)

wavs, sr = model.generate_voice_design(
    text="Votre rendez-vous est confirmé pour demain à quatorze heures.",
    language="French",
    instruct="Voix féminine d'une quarantaine d'années, grave et chaleureuse, "
             "articulation nette, rythme lent, sans emphase.",
)

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

A descrição funciona melhor quando apresenta características acústicas (altura, velocidade, energia, nitidez) do que quando usa metáforas. «Voz masculina grave, lenta e aveludada» produz resultados mais estáveis do que «voz de apresentador de rádio noturno». Uma voz criada dessa forma não é fixa de uma chamada para outra: se você precisa da mesma voz em centenas de frases, gere primeiro um trecho que agrade a você e depois use-o como referência com a variante Base. Assim, você clona uma voz sintética, o que não apresenta nenhum problema de consentimento.

#Etapa 4: clonar uma voz, com o consentimento de seu proprietário

A variante Base reproduz um timbre a partir de um breve trecho de áudio e de sua transcrição. Alguns segundos de fala nítida são suficientes para obter uma voz reconhecível. É a função mais impressionante da família e a que exige mais rigor antes mesmo de escrever uma linha de código.

Para preparar a referência, grave uma frase de cinco a dez segundos em um local silencioso, sem música de fundo nem reverberação, falando naturalmente. Transcreva-a palavra por palavra, incluindo a pontuação: é esse texto que o modelo alinha ao áudio para aprender o timbre. Um arquivo WAV mono é o formato mais seguro.

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,
)

wavs, sr = model.generate_voice_clone(
    text="Voici une phrase que je n'ai jamais prononcée, lue avec ma propre voix.",
    language="French",
    ref_audio="ma_reference.wav",
    ref_text="Bonjour, je m'appelle Thomas et j'enregistre cette phrase pour tester le clonage.",
)

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

O repositório documenta dois usos avançados úteis em produção. Primeiro, a possibilidade de pré-calcular uma “impressão digital” da voz de referência de uma vez por todas e depois reutilizá-la em cada frase sem recarregar o áudio: é disso que você precisa para um leitor de documentos ou um assistente que fala continuamente. Depois, um modo em que somente a impressão digital do locutor é usada, sem a transcrição, mais rápido, mas menos fiel. Os nomes exatos desses parâmetros estão no README; eles mudaram entre as primeiras versões do pacote, daí a importância de ler a documentação instalada em vez de um tutorial desatualizado.

O que melhora o resultado

Uma referência limpa, uma transcrição exata, um idioma forçado em vez de « Auto » e um texto-alvo pontuado (o modelo respira nas vírgulas e nos pontos).

O que prejudica o resultado

Ruído de fundo, uma referência curta ou longa demais, um sussurro, uma transcrição aproximada e números escritos em algarismos em vez de por extenso nos casos ambíguos.

O que deve ser documentado

Quem deu o consentimento, para qual uso, em que data e onde a gravação é armazenada. Um simples arquivo de texto ao lado da referência basta para um projeto pessoal; um registro de tratamento de dados de verdade para uso profissional.

#Etapa 5: interface web e servidor

O pacote instala uma demonstração do Gradio pela linha de comando, prática para testar as vozes e as instruções sem escrever um script. Ela carrega um modelo na inicialização e disponibiliza uma página web local.

qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 127.0.0.1 --port 8000

Mantenha o endereço de escuta em 127.0.0.1 enquanto a máquina não estiver protegida: o Gradio não autentica ninguém por padrão, e uma interface de clonagem de voz exposta em uma rede não é algo trivial. Se você precisar acessá-la de outro computador, use um túnel SSH ou um proxy reverso com autenticação, como faria com qualquer serviço local.

Para uma integração com aplicativos, a equipe Qwen recomenda o vLLM-Omni, a extensão multimodal do vLLM, que permite disponibilizar o modelo com uma API HTTP e saída em fluxo (o áudio começa a ser produzido antes do fim da geração). É o caminho a estudar para um assistente de voz em que a latência é importante; para a geração em lote de arquivos de áudio, o script Python direto é suficiente e evita uma camada adicional.

#Apple Silicon e Windows: alternativas da comunidade, identificadas como tal

O repositório oficial documenta o Linux com CUDA. Nas outras plataformas, o que segue pertence ao ecossistema da comunidade: nós mesmos não verificamos esses caminhos, e o estado deles muda de um mês para outro.

Mac Apple Silicon

O pacote oficial depende do PyTorch; é possível tentar device_map="mps" com dtype float16 ou float32 (bfloat16 nem sempre é compatível com MPS), esperando encontrar operações não compatíveis. O caminho mais natural no Mac é uma adaptação para MLX: o projeto comunitário mlx-audio anunciou suporte ao Qwen3-TTS. Verifique no repositório quais variantes são contempladas e com que nível de maturidade antes de se comprometer.

Windows nativo

O PyTorch com CUDA normalmente é instalado sem problemas, mas o FlashAttention é difícil de compilar no Windows: deixe-o de lado e use a atenção padrão. Algumas dependências de áudio exigem binários do sistema (ffmpeg no PATH, por exemplo). Instaladores de terceiros de « um clique » circulam por aí; eles frequentemente incluem uma versão fixa do pacote, e é preciso ler o que instalam.

Windows via WSL2

Este é o caminho mais próximo da documentação oficial: uma distribuição Ubuntu no WSL2 com o driver NVIDIA recente do Windows reconhece a GPU e segue exatamente os comandos deste guia. O custo é uma camada adicional e um acesso aos arquivos do Windows ligeiramente mais lento.

#Solução de problemas

CUDA out of memory ao carregar

Outro processo está ocupando a placa (Ollama, um navegador com aceleração, uma sessão do Stable Diffusion). Verifique com nvidia-smi, libere recursos ou mude para a variante 0,6B.

Download interrompido ou repositório não encontrado

Verifique o identificador exato do modelo na página do Hugging Face da organização Qwen; os nomes das variantes podem ter mudado desde a redação. Um download parcial é retomado ao executar o script novamente.

Erro de import liée no transformers ou torch

Conflito de versões com outro projeto instalado no mesmo ambiente. Crie novamente um ambiente virtual limpo e reinstale apenas qwen-tts e soundfile.

Pronúncia estranha em francês

Force language="French" em vez de “Auto”, escreva os números por extenso quando a leitura for ambígua e use pontuação. As siglas são lidas melhor quando separadas por pontos ou espaços.

A voz clonada não se parece com a referência

Faça novamente a gravação da referência em um ambiente silencioso, verifique a transcrição palavra por palavra e teste a 1,7B se você estava usando a 0,6B. Um trecho longo demais não ajuda: alguns segundos de fala nítida valem mais que um minuto com ruído.

Silêncio ou arquivo vazio

Verifique se você está escrevendo wavs[0], e não a lista inteira, e se a taxa de amostragem retornada pelo modelo é a mesma passada ao soundfile.

Lentidão extrema

O modelo provavelmente está rodando na CPU. O teste torch.cuda.is_available() da etapa 1 deve retornar True; caso contrário, reinstale o PyTorch com a versão do CUDA correspondente ao seu driver.

#Para se aprofundar

O Qwen3-TTS cobre a parte de « falar » de uma cadeia de voz local. Para a outra metade, a compreensão, e para comparar com modelos de síntese mais leves, o site já aborda vários temas relacionados. As versões dos pacotes e modelos citados neste guia são as do repositório QwenLM/Qwen3-TTS no momento da redação; em caso de divergência, o repositório e as páginas do Hugging Face prevalecem.

Kokoro TTS: uma voz local convincente e leve

O modelo de 82 milhões de parâmetros que fala mais rápido que o tempo real no processador, sem clonagem. A escolha certa quando a economia de recursos é mais importante que a expressividade. https://quelllm.fr/guide/kokoro-tts-voix-locale

Assistente de voz 100 % local: Whisper + Ollama + Piper

A cadeia completa: escuta, raciocínio, resposta falada. O Qwen3-TTS pode substituir o Piper na síntese se sua GPU permitir. https://quelllm.fr/guide/assistant-vocal-local-whisper-piper

Ficha do modelo Voxtral 4B TTS

O outro modelo aberto recente de síntese de voz do lado europeu, para situar o Qwen3-TTS no cenário sem comparação numérica. https://quelllm.fr/modele/voxtral-4b-tts