Skip to main content

Práticas recomendadas para síntese de fala

Aplique práticas recomendadas de síntese de fala para envio de texto, processamento de áudio, gerenciamento de conexões e concorrência, avaliação de desempenho e diagnóstico de problemas.

Envio de texto e controle de tarefas

Ao usar uma voz clonada ou projetada, o modelo de síntese deve corresponder ao modelo de destino especificado na criação da voz. Consulte Clonagem de voz ou Design de voz para os requisitos de criação da voz.

Segmentação e temporização do envio de texto

Para Qwen-Audio-TTS e CosyVoice por WebSocket, aguarde task-started antes de enviar os segmentos de texto em ordem. O servidor segmenta o texto automaticamente: frases completas são sintetizadas imediatamente; frases incompletas ficam no buffer até serem concluídas ou até a chegada de finish-task. Intervalos longos entre segmentos aumentam o tempo total de síntese. A reprodução também pode parar se o áudio anterior terminar antes da chegada do próximo texto. Consulte Eventos do cliente Qwen-Audio-TTS ou Eventos do cliente CosyVoice para os limites por segmento, de comprimento acumulado e de intervalo de envio.
Envie o texto SSML completo de uma só vez. SSML não aceita entrada segmentada. Consulte SSML e LaTeX para modelos, vozes e interfaces compatíveis.

Conclusão e cancelamento de tarefas

Ao chamar Qwen-Audio-TTS ou CosyVoice pelo protocolo WebSocket direto, após enviar todo o texto, envie finish-task para encerrar a entrada e continue recebendo áudio até task-finished. Omitir essa notificação pode resultar em áudio incompleto. Para interromper a síntese atual, use o cancelamento de tarefa. O servidor encerra a tarefa e retorna task-finished. Consulte Cancelar uma tarefa para o uso com SDK e protocolo direto e suas condições de aplicação.

Recepção e reprodução de áudio

Recepção e armazenamento de áudio

Qwen-Audio-TTS e CosyVoice retornam áudio em formatos diferentes conforme a interface:
  • Saída HTTP sem streaming: Baixe o arquivo de áudio completo de output.audio.url. A URL é válida por 24 horas. Salve antes da expiração; depois, o áudio pode ser sintetizado novamente.
  • Saída HTTP SSE: output.audio.data contém segmentos de áudio codificados em Base64. Decodifique na ordem de recepção e acrescente ao mesmo arquivo. Consulte a API HTTP de Qwen-Audio-TTS e a API HTTP de CosyVoice para os campos da resposta.
  • Protocolo WebSocket direto: Receba áudio pelo canal binary. Eventos de texto transportam informações de frases e outros metadados. Consulte a API WebSocket de Qwen-Audio-TTS e a API WebSocket de CosyVoice para o fluxo de interação.

Compatibilidade entre formato de áudio e reprodutor

Ao salvar um arquivo completo, use a extensão correspondente ao formato solicitado e verifique se o reprodutor aceita esse formato e a taxa de amostragem. Para investigar problemas de reprodução em streaming, salve primeiro o fluxo como arquivo completo. Se o arquivo não for reproduzido, verifique o formato e o reprodutor. Se o arquivo funcionar, verifique o suporte a streaming na implementação de reprodução, como ffmpeg, pyaudio, AudioFormat ou MediaSource. O cabeçalho WAV em streaming pode não refletir o comprimento final do áudio. Se precisar de duração exata, defina format como pcm, receba todo o áudio e adicione um cabeçalho WAV com o comprimento real.

Agendamento de callbacks e reprodução

Os callbacks da síntese em tempo real executam na thread WebSocket. Lógica de negócio bloqueante pode atrasar a recepção de áudio. Grave o áudio em um buffer separado e processe em outra thread. Se a reprodução parar, verifique também a velocidade de envio do texto e a estabilidade da rede; oscilações podem interromper ou atrasar a transmissão de áudio.

Gerenciamento de conexões e recursos de concorrência

Reutilização de conexões e isolamento de tarefas

Ao chamar Qwen-Audio-TTS ou CosyVoice diretamente pelo protocolo WebSocket, uma conexão pode processar várias tarefas sequencialmente. Após receber task-finished, envie run-task com um novo task_id e, em seguida, o texto conforme o fluxo da família de modelos. Use a mesma sequência após o cancelamento. Para Qwen-Audio-TTS, CosyVoice, as conexões fecham após 60 segundos ociosas depois da tarefa. Avalie a chamada após longa inatividade como uma nova conexão. Com client.audio.tts.connect no SDK Python, a sessão fecha a conexão subjacente por padrão ao concluir ou cancelar a tarefa. Para reutilizar uma conexão, crie uma conexão compartilhada com client.ws_connection() e passe-a por connection=. O chamador fecha a conexão compartilhada com WsConnection.close.

Identidade da conexão e limites de isolamento

A chave de API é enviada no cabeçalho Authorization somente durante o handshake WebSocket. As mensagens run-task seguintes não a incluem. Alterar a chave nos parâmetros ou na configuração global não muda a identidade da conexão existente, o que pode atribuir identidade, uso de cota ou cobranças de forma diferente da esperada.
  • Java SDK
  • Python SDK
Em Java, crie um pool independente para cada chave de API e use sempre a mesma chave em um pool. Para Qwen-Audio-TTS/CosyVoice, chame updateParamAndCallback sempre que obtiver um objeto. Esse método não autentica novamente uma conexão existente.

Planejamento de concorrência e recursos

Pools mantêm objetos de síntese e conexões WebSocket para reduzir a criação de objetos, os handshakes TCP/TLS e as atualizações de protocolo. As séries de modelos e os SDKs a seguir oferecem suporte a pools de objetos:
  • Qwen-Audio-TTS, CosyVoice: pools de objetos Python e Java.
Configure os pools para o número esperado de tarefas simultâneas e a capacidade do servidor. Os limites dos modelos são calculados por conta Alibaba Cloud e compartilhados por seus usuários RAM, espaços de trabalho e chaves de API. Para limites de frequência e concorrência, veja Limites de taxa. Comece com uma capacidade de pool de 1,5 a 2 vezes a concorrência de pico e ajuste conforme a carga real. O pool Python pode criar objetos adicionais quando todos estão emprestados. Esses objetos precisam de novas conexões quando são usados.
  • Referência de configuração do servidor
  • Parâmetros de pools de recursos Java
As configurações de servidores Alibaba Cloud a seguir são referências para executar apenas o serviço de síntese indicado. A concorrência por servidor representa tarefas de síntese simultâneas. Ajuste a configuração à carga real.A configuração do pool de conexões nesta tabela é o valor de referência para as três variáveis: DASHSCOPE_CONNECTION_POOL_SIZE, DASHSCOPE_MAXIMUM_ASYNC_REQUESTS e DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST. Nessas configurações de referência, defina as três como 2000. Defina a capacidade do pool de objetos pela variável de ambiente do exemplo correspondente.
SérieServidor Alibaba CloudTarefas simultâneasCapacidade do pool de objetosConfiguração do pool de conexões
CosyVoice4 vCPU / 8 GiB1005002000
CosyVoice8 vCPU / 16 GiB1505002000
CosyVoice16 vCPU / 32 GiB2005002000

Ciclo de vida dos objetos

Configure a chave de API e o endpoint e crie um pool de objetos compartilhado pelas tarefas da aplicação.
  • Java SDK
  • Python SDK
  1. Obtenha um objeto com borrowObject. Para Qwen-Audio-TTS/CosyVoice, chame updateParamAndCallback(param, callback) a cada obtenção para definir os parâmetros e o callback da tarefa.
  2. Execute a síntese Qwen-Audio-TTS/CosyVoice com call ou streamingCall.
  3. Após a conclusão normal, devolva o objeto com returnObject. Se estiver incompleto ou com falha, descarte-o com invalidateObject para que a factory feche a conexão; não o devolva diretamente.
  4. Após todas as tarefas terminarem, chame o close() do pool para liberar os recursos.
Em Java, quando maxIdle é menor que maxTotal, os objetos devolvidos que excedem a capacidade ociosa são destruídos. Se o destroyObject da factory não fechar o WebSocket, a conexão pode continuar aberta após a destruição.
Após um erro do cliente interromper uma tarefa, o servidor pode ainda considerar a tarefa anterior ativa. Reutilizar essa conexão para um novo run-task causa um erro na sequência do protocolo (Invalid action('run-task')! Please follow the protocol!). Feche a conexão e descarte o objeto; em seguida, estabeleça uma nova conexão para as próximas tarefas. Criar objetos de síntese com frequência sem fechar conexões antigas pode aumentar continuamente o número de conexões e o uso de recursos do servidor. Verifique a devolução dos objetos após as tarefas e o fechamento das conexões sem uso.

Exemplos de pool de objetos

  • Obtenha uma chave de API e defina DASHSCOPE_API_KEY. Use a chave da região chamada.
  • Substitua {WorkspaceId} pelo ID do workspace da região e configure o endpoint WebSocket correspondente.
  • Java SDK
  • Python SDK
  • Qwen-Audio-TTS, CosyVoice: SDK Java DashScope 2.16.6 ou posterior.
Os exemplos Java também exigem Apache Commons Pool 2. Configure as dependências com Maven ou Gradle:
Maven
<dependencies>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>dashscope-sdk-java</artifactId>
        <version>2.23.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-pool2</artifactId>
        <version>2.12.0</version>
    </dependency>
</dependencies>
Os exemplos usam qwen-audio-3.1-tts-flash e longanhuan_v3.1 em três tarefas simultâneas. Para CosyVoice, altere modelo e voz para cosyvoice-v3-flash e longanyang. Para outros modelos e requisitos de voz, veja Síntese de fala em tempo real.
Java
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisAudioFormat;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import org.apache.commons.pool2.BasePooledObjectFactory;
import org.apache.commons.pool2.PooledObject;
import org.apache.commons.pool2.impl.DefaultPooledObject;
import org.apache.commons.pool2.impl.GenericObjectPool;
import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
import java.time.Duration;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicReference;

public class PooledTts {
    static class Factory extends BasePooledObjectFactory<SpeechSynthesizer> {
        public SpeechSynthesizer create() { return new SpeechSynthesizer(); }
        public PooledObject<SpeechSynthesizer> wrap(SpeechSynthesizer value) {
            return new DefaultPooledObject<>(value);
        }
        public void destroyObject(PooledObject<SpeechSynthesizer> value) {
            value.getObject().getDuplexApi().close(1000, "done");
        }
    }

    static void synthesize(GenericObjectPool<SpeechSynthesizer> pool, int index) throws Exception {
        SpeechSynthesizer synthesizer = pool.borrowObject();
        boolean successful = false;
        AtomicReference<Exception> error = new AtomicReference<>();
        try (FileOutputStream audio = new FileOutputStream("output_" + index + ".mp3")) {
            SpeechSynthesisParam param = SpeechSynthesisParam.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-audio-3.1-tts-flash")
                .voice("longanhuan_v3.1")
                .format(SpeechSynthesisAudioFormat.MP3_24000HZ_MONO_256KBPS)
                .build();
            synthesizer.updateParamAndCallback(param, new ResultCallback<SpeechSynthesisResult>() {
                public void onEvent(SpeechSynthesisResult result) {
                    ByteBuffer buffer = result.getAudioFrame();
                    if (buffer != null) {
                        byte[] bytes = new byte[buffer.remaining()];
                        buffer.get(bytes);
                        try { audio.write(bytes); }
                        catch (Exception e) { error.set(e); }
                    }
                }
                public void onComplete() {}
                public void onError(Exception e) { error.set(e); }
            });
            synthesizer.streamingCall("Hello, welcome to Alibaba Cloud Model Studio.");
            synthesizer.streamingComplete(60000);
            if (error.get() != null) { throw error.get(); }
            successful = true;
        } finally {
            if (successful) { pool.returnObject(synthesizer); }
            else { pool.invalidateObject(synthesizer); }
        }
    }

    public static void main(String[] args) throws Exception {
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
        GenericObjectPoolConfig<SpeechSynthesizer> config = new GenericObjectPoolConfig<>();
        int poolSize = Integer.parseInt(System.getenv().getOrDefault("COSYVOICE_OBJECTPOOL_SIZE", "500"));
        config.setMaxTotal(poolSize);
        config.setMaxIdle(poolSize);
        config.setMaxWait(Duration.ofSeconds(60));
        ExecutorService executor = Executors.newFixedThreadPool(3);
        try (GenericObjectPool<SpeechSynthesizer> pool = new GenericObjectPool<>(new Factory(), config)) {
            java.util.List<Future<?>> futures = new java.util.ArrayList<>();
            for (int i = 0; i < 3; i++) {
                final int index = i;
                futures.add(executor.submit(() -> {
                    try { synthesize(pool, index); }
                    catch (Exception e) { throw new RuntimeException(e); }
                }));
            }
            for (Future<?> future : futures) { future.get(); }
        } finally {
            executor.shutdownNow();
        }
    }
}

Avaliação de desempenho e diagnóstico

O pool Python estabelece conexões durante a inicialização. Java GenericObjectPool cria objetos sob demanda e conecta na primeira síntese. Por isso, o aquecimento das conexões Java exige solicitações reais de síntese.Após a inicialização ou a recuperação da rede, execute o aquecimento e aumente a concorrência gradualmente. Antes dos testes de desempenho, aqueça com a concorrência desejada, por exemplo por 1 a 2 minutos, e colete medições quando as conexões estiverem sendo reutilizadas de forma estável. Aumentar a concorrência gradualmente evita o bloqueio causado pelo estabelecimento de muitas conexões WebSocket ao mesmo tempo.
A primeira chamada inclui o custo de estabelecer a conexão WebSocket. Meça a latência do primeiro áudio e o tempo total separadamente das chamadas que reutilizam conexões. O fator de tempo real (RTF, tempo total de síntese / duração do áudio) também permite avaliar a velocidade da síntese.A latência do primeiro áudio medida pelo SDK inclui o estabelecimento da conexão e a transmissão pela rede; portanto, não representa apenas o tempo de inferência do modelo. Para Qwen-Audio-TTS/CosyVoice, os objetos Python oferecem get_first_package_delay() para essa latência e get_last_request_id() para o ID usado na correlação dos logs de solicitações. Os objetos Java oferecem getLastRequestId() para o ID da solicitação.
Ao atingir maxTotal, o empréstimo de um pool Java aguarda um objeto disponível. Verifique capacidade, devoluções e fechamento de conexões para evitar espera adicional por objetos.
Reconexões em massa na inicialização, após interrupções de rede ou após muitos erros do servidor podem acumular tarefas. Quando as conexões se recuperam, o envio simultâneo dessas tarefas pode gerar picos e acionar os limites da conta.Verifique problemas de rede ou muitos erros antes do pico, como Requests rate limit exceeded, please try again later.. Controle a concorrência na inicialização e na recuperação. Em Java, maxTotal limita o número de objetos obtidos simultaneamente do mesmo pool.Confira as cotas da conta. Para solicitar aumento, siga o procedimento em Limites de taxa. Ajuste as especificações dos servidores ou adicione servidores conforme a carga real.
Verifique se a banda de rede está saturada ou a concorrência está muito alta. Ajuste a concorrência ou a capacidade do servidor à carga.