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.datacontient 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.
- 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érie | Serveur Alibaba Cloud | Tâches simultanées | Capacité du pool d’objets | Paramètre du pool de connexions |
|---|---|---|---|---|
| CosyVoice | 4 vCPU / 8 GiB | 100 | 500 | 2000 |
| CosyVoice | 8 vCPU / 16 GiB | 150 | 500 | 2000 |
| CosyVoice | 16 vCPU / 32 GiB | 200 | 500 | 2000 |
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
- Empruntez un objet avec
borrowObject. Pour Qwen-Audio-TTS/CosyVoice, appelezupdateParamAndCallback(param, callback)à chaque emprunt afin de définir les paramètres et le callback de la tâche. - Exécutez la synthèse Qwen-Audio-TTS/CosyVoice avec
calloustreamingCall. - Après une fin normale, restituez l’objet avec
returnObject. S’il est inachevé ou en échec, retirez-le avecinvalidateObjectpour que la fabrique ferme sa connexion ; ne le restituez pas directement. - Après la fin de toutes les tâches, appelez la méthode
close()du pool pour libérer ses ressources.
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.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.
Maven
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
Évaluation des performances et diagnostic
Préchauffage des connexions au démarrage et à la reprise
Préchauffage des connexions au démarrage et à la reprise
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.Évaluation de la latence et du facteur temps réel
Évaluation de la latence et du facteur temps réel
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.Attente d’emprunt d’objets et délais d’expiration
Attente d’emprunt d’objets et délais d’expiration
À
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.Pics de requêtes et limites de débit
Pics de requêtes et limites de débit
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.Bande passante et charge du serveur
Bande passante et charge du serveur
Vérifiez si la bande passante est saturée ou la concurrence trop élevée. Ajustez la concurrence ou la capacité serveur à la charge.