Skip to main content

Connexion WebSocket à Qwen-Omni-Realtime

Connexion WebSocket à Qwen-Omni-Realtime

Périmètre d’application

Ce document concerne Qwen-Omni-Realtime. Le modèle de l’exemple est qwen3.8-omni-flash-realtime ; les configurations de qwen3.5-omni-plus-realtime et qwen3.5-omni-flash-realtime figurent dans la référence des événements. Pour les paramètres de l’ancien modèle qwen3-omni-flash-realtime-2025-09-15, consultez SDK Python.
  • Utilisez l’API Key et l’ID de l’espace de travail correspondant à la région et à l’espace de travail sélectionnés.
  • domaine de Singapour : {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com.
  • Les API Keys à longue durée de validité sont stockées sur le serveur et ne doivent pas être placées dans les navigateurs ou les applications mobiles.

Adresses et authentification

WebSocketwss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtime

qwen3.8-omni-flash-realtime doit utiliser le domaine propre à l’espace de travail. Les anciens modèles peuvent continuer à utiliser leurs domaines d’origine : Pékin utilise wss://dashscope.aliyuncs.com et Singapour utilise wss://dashscope-intl.aliyuncs.com. Pour plus d’informations, consultez SDK Python. Définissez Authorization: Bearer <API_KEY> dans l’en-tête de la requête de négociation WebSocket. Remplacez l’ID de l’espace de travail et le nom réel du modèle ; ne placez pas les API Keys à longue durée de validité dans les navigateurs ou les applications mobiles. L’en-tête facultatif user-agent identifie le client. La documentation générale d’intégration WebSocket présente également X-DashScope-WorkSpace (ID de l’espace de travail) et X-DashScope-DataInspection (configuration de vérification de conformité des données), à utiliser selon les exigences du modèle. Pour générer des API Keys temporaires et connaître leurs autorisations, consultez Générer une API Key temporaire. Les URL d’espace de travail suivantes utilisent qwen3.5-omni-plus-realtime comme modèle d’exemple.
  • Chine (Pékin) wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
  • Singapour wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
Remplacez {WorkspaceId} par l’ID de l’espace de travail de la région sélectionnée.

Configuration de la session

Envoyez session.update après avoir établi la connexion et reçu session.created. N’envoyez les entrées qu’après la confirmation session.updated ; traitez les erreurs via les événements error. Les exemples suivants correspondent à qwen3.8-omni-flash-realtime ; les autres versions doivent utiliser les configurations de leurs références d’événements respectives, sans mélanger les niveaux de champs.
{
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Tina",
    "turn_detection": {
      "type": "server_vad"
    }
  }
}

Entrées, résultats et fin

L’audio est envoyé via input_audio_buffer.append ; les formats d’entrée, les conditions de soumission et les limites des entrées image sont décrits dans Événements client. Traitez les résultats, les états et les erreurs dans Événements serveur ; l’établissement de la connexion ne signifie pas que la requête métier est terminée. Le déroulement des tours automatiques, du mode Manual, de Function Calling et de MCP est décrit dans Déroulement des interactions. Après avoir reçu les résultats nécessaires, fermez la connexion WebSocket.

Déroulement des interactions

Mode VAD

Pour activer le mode VAD, définissez le paramètre session.turn_detection.type de l’événement client sur "server_vad". Dans ce mode, le serveur effectue une détection d’activité vocale (VAD) sur l’audio entrant et répond lorsqu’il détecte la parole. Ce mode est le mode par défaut et convient aux scénarios où le client envoie continuellement l’audio au serveur.
server_vad
  • Le serveur émet l'événement input_audio_buffer.speech_started lorsqu'il détecte le début d'une parole.
  • Le client peut ajouter des données audio au tampon à tout moment en envoyant un événement input_audio_buffer.append.
  • Le serveur signale la fin de la parole via l'événement input_audio_buffer.speech_stopped.
  • Le serveur valide le tampon audio d'entrée en envoyant un événement input_audio_buffer.committed.
  • Le serveur transmet ensuite un événement conversation.item.created contenant l'élément de message utilisateur généré à partir du tampon audio.

Déroulement de Function Calling

En mode VAD, si une réponse générée par le serveur nécessite un appel d'outil, le flux d'interaction suivant se produit :
image.svg
  • Une fois la fin de la parole détectée et la réponse générée, le serveur détermine qu'un appel d'outil est nécessaire.
  • Le serveur envoie un événement response.function_call_arguments.delta contenant les données incrémentielles des arguments de l'appel d'outil.
  • Le serveur transmet un événement response.function_call_arguments.done pour indiquer que tous les arguments ont été envoyés.
  • Le client exécute l'appel d'outil et obtient le résultat.
  • Le client envoie un événement conversation.item.create contenant le résultat de l'appel d'outil.
  • Le client envoie un événement response.create pour déclencher une réponse fondée sur le résultat de l’appel d’outil.

Mode Manual

Pour activer le mode manuel, définissez le paramètre session.turn_detection de l'événement client sur null. Dans cette configuration, le client sollicite explicitement une réponse du serveur en envoyant les événements input_audio_buffer.commit et response.create. Ce mode convient particulièrement aux scénarios de type « push-to-talk », comme l'envoi de messages vocaux dans les applications de messagerie.
manual
  • Le client peut ajouter des données audio au tampon en envoyant un événement input_audio_buffer.append.
  • Le client valide le tampon audio d'entrée en envoyant un événement input_audio_buffer.commit. Cette validation crée un nouvel élément de message utilisateur dans la conversation.
  • Le serveur répond en envoyant un événement input_audio_buffer.committed.
  • Le client envoie un événement response.create pour déclencher la génération de la réponse finale par le modèle.
  • Le serveur répond en envoyant un événement conversation.item.created.

Déroulement de Function Calling

image.svg
En mode manuel, lorsqu'une réponse générée par le serveur requiert un appel d'outil, le processus suivant s'applique :
  • Après réception d'un événement response.create provenant du client, le serveur génère une réponse et identifie la nécessité d'un appel d'outil.
  • Le serveur envoie un événement response.function_call_arguments.delta contenant les données incrémentielles des arguments de l'appel d'outil.
  • Un événement response.function_call_arguments.done signale la fin du transfert des arguments.
  • Le client exécute l'appel d'outil et obtient le résultat.
  • Le client transmet le résultat obtenu en utilisant un événement conversation.item.create.
  • Le client envoie un événement response.create pour déclencher la génération de la réponse finale par le modèle.
  • Le serveur produit une réponse fondée sur le résultat de l'outil et la transmet au client via des événements response.audio.delta ou response.text.delta.

Appels d’outils MCP

Ce déroulement s’applique à Qwen3.8-Omni-Flash-Realtime avec le mode VAD ou Manual. Function Calling et MCP peuvent être configurés ensemble dans session.tools. Ils ne peuvent pas être utilisés avec la recherche web (enable_search). Model Studio ne facture pas de frais supplémentaires pour les appels d’outils MCP. L’inférence du modèle reste soumise à sa tarification.

Découverte des outils

Après la configuration des serveurs MCP par le client avec session.update, le service Realtime découvre leurs outils de manière asynchrone :
Séquence de découverte des outils MCP
Dans les diagrammes de séquence de cette section, opt indique une exécution lorsqu’une condition est remplie, alt indique des branches alternatives choisies selon une condition et par indique un traitement parallèle.
  1. Envoyez session.update avec les entrées MCP dans session.tools.
  2. Traitez mcp_list_tools.in_progress, qui peut arriver avant session.updated. session.updated confirme l’acceptation de la configuration, mais pas la disponibilité des outils.
  3. Le service découvre les outils. Il envoie conversation.item.created avec un élément mcp_list_tools, suivi de mcp_list_tools.completed ou mcp_list_tools.failed avec le même item_id. L’élément contient les outils filtrés finaux ou une erreur.
L’entrée audio et response.create peuvent continuer pendant la découverte, mais seules les Responses créées après la fin de la découverte peuvent utiliser les outils correspondants.

Appels MCP et continuation

Lorsque le modèle sélectionne un outil MCP, le service Realtime exécute l’appel. Si une approbation est nécessaire, le client répond d’abord à la demande d’approbation :
Séquence des appels d’outils MCP, de l’approbation et de la continuation
  1. Le serveur crée un élément mcp_call via response.output_item.added.
  2. Concaténez zéro ou plusieurs fragments response.mcp_call_arguments.delta. La chaîne JSON complète de response.mcp_call_arguments.done fait autorité.
  3. Si une approbation est nécessaire, traitez conversation.item.created avec item.type="mcp_approval_request". Décidez d’autoriser ou non l’appel, puis répondez avec conversation.item.create, item.type="mcp_approval_response", l’item.id exact de l’approbation et le booléen approve. L’approbation est obligatoire par défaut.
  4. Les appels approuvés, ou configurés pour ne pas nécessiter d’approbation, émettent response.mcp_call.in_progress. Le service exécute l’appel MCP, puis émet response.mcp_call.completed ou response.mcp_call.failed. Un rejet ou un dépassement du délai d’approbation émet failed sans exécution.
  5. Traitez response.output_item.done pour l’élément final de l’appel. Le response.done parent arrive après que chaque élément MCP de cette Response a atteint un état final. Son response.output contient les instantanés finaux : les appels réussis ont completed et output ; les appels échoués ont failed et error.
  6. Pour générer une réponse du modèle à partir des résultats MCP, envoyez un seul response.create après le response.done parent. Ne joignez pas les résultats MCP : ils sont déjà dans la conversation. N’utilisez pas le retour manuel function_call_output pour ces appels MCP exécutés par le serveur.
Consultez la configuration MCP du client, les réponses d’approbation, les événements serveur MCP et les éléments de conversation MCP.

Limites d’utilisation

Les contraintes MCP par défaut suivantes s’appliquent à chaque session :
ÉlémentValeur par défaut
Serveurs MCP8
Outils MCP128
Délai d’attente de la découverte des outils30 secondes
Délai d’attente de l’approbation60 secondes
Délai d’exécution des outils30 secondes
Taille d’une réponse du serveur en amont2 MB
Taille cumulée des résultats des outils8 MB
Nombre cumulé d’appels d’outils256

Gestion des erreurs

Si la négociation échoue, vérifiez le domaine, la région, l’espace de travail, l’API Key, le nom du modèle, son activation et ses autorisations. Après l’établissement de la connexion, localisez le problème à partir de l’événement error et consultez Codes d’erreur. Conservez l’ID de l’événement pour le diagnostic ; l’absence de réponse ne prouve pas que le protocole n’est pas pris en charge.

SDK et références