Skip to main content

Bonnes pratiques de synthèse vocale

Appliquez les bonnes pratiques de synthèse vocale pour l’envoi du texte, le traitement audio, la gestion des connexions et de la concurrence, l’évaluation des performances et le diagnostic.

Soumission du texte et contrôle des tâches

Avec une voix clonée ou conçue, le modèle de synthèse doit correspondre au modèle cible défini lors de la création de la voix. Consultez Clonage vocal ou Conception vocale pour les exigences de création des voix.

Segmentation et rythme d’envoi du texte

Pour Qwen-Audio-TTS et CosyVoice via WebSocket, attendez task-started avant d’envoyer les segments de texte dans l’ordre. Le serveur segmente automatiquement le texte : les phrases complètes sont synthétisées immédiatement ; les phrases incomplètes restent en mémoire tampon jusqu’à leur achèvement ou la réception de finish-task. De longs intervalles entre segments augmentent la durée totale de synthèse. La lecture peut aussi s’interrompre si l’audio précédent se termine avant l’arrivée du texte suivant. Consultez les Événements client Qwen-Audio-TTS ou les Événements client CosyVoice pour les limites par segment, cumulées et d’intervalle d’envoi.
Envoyez le texte SSML complet en une seule fois. SSML ne prend pas en charge les entrées segmentées. Les modèles, voix et interfaces compatibles figurent dans SSML et LaTeX.

Fin et annulation des tâches

Avec le protocole WebSocket direct de Qwen-Audio-TTS ou CosyVoice, une fois tout le texte envoyé, envoyez finish-task pour terminer l’entrée, puis continuez à recevoir l’audio jusqu’à task-finished. Sans cette notification, l’audio peut être incomplet. Pour interrompre la synthèse en cours, utilisez l’annulation de tâche. Le serveur termine la tâche et renvoie task-finished. Consultez Annuler une tâche pour l’utilisation avec les SDK et le protocole direct ainsi que les conditions applicables.

Réception et lecture audio

Réception et stockage audio

Qwen-Audio-TTS et CosyVoice renvoient l’audio sous différentes formes selon l’interface :
  • Sortie HTTP non diffusée en continu : Téléchargez le fichier audio complet depuis output.audio.url. L’URL est valide pendant 24 heures. Enregistrez le fichier avant son expiration ; vous pouvez relancer la synthèse après expiration.
  • Sortie HTTP SSE : output.audio.data contient des segments audio encodés en Base64. Décodez-les dans l’ordre de réception et ajoutez-les au même fichier. Les champs de réponse figurent dans l’API HTTP Qwen-Audio-TTS et l’API HTTP CosyVoice.
  • Protocole WebSocket direct : Recevez l’audio via le canal binary. Les événements texte transportent les informations de phrase et autres métadonnées. Le déroulement est décrit dans l’API WebSocket Qwen-Audio-TTS et l’API WebSocket CosyVoice.

Compatibilité du format audio et du lecteur

Pour enregistrer un fichier complet, utilisez une extension correspondant au format demandé et vérifiez que le lecteur accepte le format et la fréquence d’échantillonnage. Pour diagnostiquer une lecture en continu défaillante, enregistrez d’abord le flux dans un fichier complet. Si ce fichier ne se lit pas, vérifiez le format et le lecteur. S’il se lit correctement, vérifiez la prise en charge de la lecture en continu par l’implémentation, par exemple ffmpeg, pyaudio, AudioFormat ou MediaSource. L’en-tête WAV d’une sortie en continu peut ne pas refléter la longueur finale de l’audio. Si une durée exacte est requise, définissez format sur pcm, recevez l’audio complet, puis ajoutez un en-tête WAV contenant sa longueur réelle.

Ordonnancement des callbacks et de la lecture

Les callbacks de synthèse en temps réel s’exécutent dans le thread WebSocket. Une logique métier bloquante peut retarder la réception audio. Écrivez l’audio dans un tampon distinct et traitez-le dans un autre thread. Si la lecture s’interrompt, vérifiez également le rythme d’envoi du texte et la stabilité réseau : des fluctuations peuvent interrompre ou retarder le transfert audio.

Gestion des connexions et des ressources de concurrence

Réutilisation des connexions et isolation des tâches

Lors des appels directs à Qwen-Audio-TTS ou CosyVoice par le protocole WebSocket, une connexion peut traiter plusieurs tâches successivement. Après task-finished, envoyez run-task avec un nouveau task_id, puis le texte selon le flux de la famille de modèles. Suivez la même séquence après une annulation. Pour Qwen-Audio-TTS, CosyVoice, les connexions se ferment après 60 secondes d’inactivité suivant la tâche. Évaluez l’appel après une longue inactivité comme une nouvelle connexion. Avec client.audio.tts.connect du SDK Python, la session ferme par défaut sa connexion sous-jacente à la fin ou à l’annulation d’une tâche. Pour réutiliser une connexion, créez une connexion partagée avec client.ws_connection() et transmettez-la par connection=. L’appelant la ferme avec WsConnection.close.

Identité de connexion et périmètre d’isolation

La clé API est envoyée dans l’en-tête Authorization uniquement pendant la négociation WebSocket. Les messages run-task suivants ne la contiennent pas. Modifier la clé dans les paramètres ou la configuration globale ne change pas l’identité d’une connexion existante, ce qui peut entraîner une attribution inattendue de l’identité, des quotas ou des frais.
  • Java SDK
  • Python SDK
En Java, créez un pool indépendant pour chaque clé API et utilisez toujours la même clé dans un pool. Pour Qwen-Audio-TTS/CosyVoice, appelez updateParamAndCallback à chaque emprunt. Cette méthode ne réauthentifie pas une connexion existante.

Planification de la concurrence et des ressources

Les pools conservent les objets de synthèse et leurs connexions WebSocket pour réduire les créations d’objets, les négociations TCP/TLS et les mises à niveau du protocole. Les séries de modèles et SDK suivants prennent en charge les pools :
  • Qwen-Audio-TTS, CosyVoice : pools Python et Java.
Configurez les pools selon le nombre de tâches simultanées attendu et la capacité du serveur. Les limites des modèles sont calculées par compte Alibaba Cloud et partagées par ses utilisateurs RAM, espaces de travail et clés API. Pour les limites de fréquence et de concurrence, consultez Limites de débit. Commencez avec une capacité de pool de 1,5 à 2 fois la concurrence de pointe, puis ajustez-la à la charge réelle. Le pool Python peut créer des objets supplémentaires lorsque tous les objets sont empruntés. Ces objets nécessitent de nouvelles connexions lors de leur utilisation.
  • Référence de configuration du serveur
  • Paramètres des pools de ressources Java
Les configurations Alibaba Cloud suivantes servent de référence lorsque seul le service de synthèse indiqué est exécuté. La concurrence par serveur désigne les tâches de synthèse simultanées. Ajustez la configuration à la charge réelle.La configuration du pool de connexions dans ce tableau est une valeur de référence commune à DASHSCOPE_CONNECTION_POOL_SIZE, DASHSCOPE_MAXIMUM_ASYNC_REQUESTS et DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST. Pour ces configurations de référence, définissez les trois valeurs sur 2000. Définissez la capacité du pool d’objets avec la variable d’environnement de l’exemple correspondant.
SérieServeur Alibaba CloudTâches simultanéesCapacité du pool d’objetsParamètre du pool de connexions
CosyVoice4 vCPU / 8 GiB1005002000
CosyVoice8 vCPU / 16 GiB1505002000
CosyVoice16 vCPU / 32 GiB2005002000

Cycle de vie des objets

Configurez la clé API et le point de terminaison, puis créez un pool d’objets partagé entre les tâches de l’application.
  • Java SDK
  • Python SDK
  1. Empruntez un objet avec borrowObject. Pour Qwen-Audio-TTS/CosyVoice, appelez updateParamAndCallback(param, callback) à chaque emprunt afin de définir les paramètres et le callback de la tâche.
  2. Exécutez la synthèse Qwen-Audio-TTS/CosyVoice avec call ou streamingCall.
  3. Après une fin normale, restituez l’objet avec returnObject. S’il est inachevé ou en échec, retirez-le avec invalidateObject pour que la fabrique ferme sa connexion ; ne le restituez pas directement.
  4. Après la fin de toutes les tâches, appelez la méthode close() du pool pour libérer ses ressources.
En Java, si maxIdle est inférieur à maxTotal, les objets restitués au-delà de la capacité inactive sont détruits. Si destroyObject dans la fabrique ne ferme pas le WebSocket, sa connexion peut rester ouverte après la destruction.
Après une interruption due à une erreur client, le serveur peut encore considérer la tâche précédente comme active. Réutiliser cette connexion pour un nouveau run-task provoque une erreur de séquence du protocole (Invalid action('run-task')! Please follow the protocol!). Fermez la connexion, retirez l’objet, puis créez une connexion pour les tâches suivantes. Créer fréquemment des objets sans fermer les anciennes connexions peut augmenter continuellement le nombre de connexions et la consommation de ressources du serveur. Vérifiez la restitution des objets à la fin des tâches et la fermeture des connexions inutilisées.

Exemples de pool d’objets

  • Obtenez une clé API et définissez DASHSCOPE_API_KEY. Utilisez la clé de la région appelée.
  • Remplacez {WorkspaceId} par l’ID d’espace de travail de la région et configurez son point de terminaison WebSocket.
  • Java SDK
  • Python SDK
  • Qwen-Audio-TTS, CosyVoice : SDK Java DashScope 2.16.6 ou version ultérieure.
Les exemples Java nécessitent aussi Apache Commons Pool 2. Configurez les dépendances avec 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>
Les exemples utilisent qwen-audio-3.1-tts-flash et longanhuan_v3.1 pour trois tâches simultanées. Avec CosyVoice, remplacez le modèle et la voix par cosyvoice-v3-flash et longanyang. Consultez Synthèse vocale en temps réel pour les autres modèles et voix.
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();
        }
    }
}

Évaluation des performances et diagnostic

Le pool Python établit les connexions à l’initialisation. Java GenericObjectPool crée les objets à la demande et se connecte à la première synthèse. Le préchauffage des connexions Java nécessite donc de véritables requêtes de synthèse.Après le démarrage ou le rétablissement du réseau, préchauffez les connexions et augmentez progressivement la concurrence. Avant les tests de performance, préchauffez au niveau de concurrence cible, par exemple pendant 1 à 2 minutes, puis mesurez lorsque les connexions sont réutilisées de manière stable. L’augmentation progressive de la concurrence évite le blocage causé par l’établissement simultané de nombreuses connexions WebSocket.
Le premier appel inclut l’établissement de la connexion WebSocket. Mesurez sa latence du premier audio et sa durée totale séparément des appels réutilisant une connexion. Le facteur temps réel (RTF, durée totale de synthèse / durée audio) permet aussi d’évaluer la vitesse de synthèse.La latence du premier audio mesurée par le SDK inclut l’établissement de la connexion et le transfert réseau ; elle ne représente donc pas uniquement l’inférence du modèle. Pour Qwen-Audio-TTS/CosyVoice, les objets Python fournissent get_first_package_delay() pour cette latence et get_last_request_id() pour l’ID permettant de corréler les journaux de requête. Les objets Java fournissent getLastRequestId() pour l’ID de requête.
À maxTotal, un emprunt dans un pool Java attend un objet disponible. Vérifiez la capacité, les restitutions et la fermeture des connexions pour éviter les délais d’attente supplémentaires.
Les reconnexions massives au démarrage, après une interruption réseau ou après de nombreuses erreurs serveur peuvent accumuler des tâches. À la reprise des connexions, leur soumission simultanée peut provoquer un pic et déclencher les limites du compte.Recherchez des problèmes réseau ou de nombreuses erreurs avant le pic, par exemple Requests rate limit exceeded, please try again later.. Contrôlez la concurrence au démarrage et à la reprise. En Java, maxTotal limite le nombre d’objets empruntés simultanément dans le même pool.Vérifiez les quotas du compte. Pour demander une augmentation, suivez la procédure de la page Limites de débit. Ajustez les caractéristiques des serveurs ou ajoutez des serveurs selon la charge réelle.
Vérifiez si la bande passante est saturée ou la concurrence trop élevée. Ajustez la concurrence ou la capacité serveur à la charge.