Principales interfaces et paramètres de requête pour Qwen-Omni en temps réel via le SDK DashScope Python.
Consultez la documentation Qwen-Omni-Realtime Python SDK actuelle.
Pour la connexion et l’authentification, consultez Connexion WebSocket. Pour les champs des événements et les exemples JSON, consultez Événements client et Événements serveur.
La version de votre SDK doit être 1.25.17 ou ultérieure. Avant de commencer, consultez la rubrique Flux d'interaction multimodale en temps réel.
Téléchargez l'exemple de code depuis GitHub. Trois méthodes d'appel sont disponibles :
Définissez les paramètres de requête suivants dans le constructeur (init) de la classe OmniRealtimeConversation.
Configurez les paramètres de requête suivants à l'aide de la méthode update_session.
Importez cette classe avec
Le serveur renvoie des événements de réponse et des données via des callbacks. Implémentez les méthodes de callback pour traiter les réponses du serveur.
Importez cette interface avec
Le modèle temps réel Qwen-Omni utilise le flux audio comme chronologie d'entrée. Les images sont insérées dans le flux audio en fonction de leur heure d'envoi. Vous pouvez ajouter des images à n'importe quel moment de la chronologie audio.
Dans les scénarios d'interaction en temps réel, vous pouvez activer ou désactiver l'entrée vidéo à tout moment.
Pour les interactions en temps réel, nous recommandons d'envoyer des images à une fréquence de 1 ou 2 ips et l'audio par paquets de 100 ms.
Lorsque turn_detection est activé, il prend en charge deux modes : server_vad et semantic_vad :
Qwen-Omni real-time est un modèle multimodal de bout en bout. Sa sortie texte constitue une réponse à l'entrée, et non une transcription directe de l'audio d'entrée. Un modèle ASR distinct est nécessaire pour la transcription. Actuellement, le modèle est déterminé par la configuration intégrée et n'est pas configurable.
Prérequis
La version de votre SDK doit être 1.25.17 ou ultérieure. Avant de commencer, consultez la rubrique Flux d'interaction multimodale en temps réel.
Premiers pas
Téléchargez l'exemple de code depuis GitHub. Trois méthodes d'appel sont disponibles :
-
Exemple de conversation audio : capture l'entrée audio en temps réel depuis le microphone, active le mode VAD pour détecter automatiquement le début et la fin de la parole, et prend en charge l'interruption vocale.
Le paramètre
enable_turn_detectiondoit être défini sur True.Nous vous recommandons d'utiliser un casque pour la lecture audio afin d'éviter que les échos ne déclenchent une interruption vocale.
-
Exemple de conversation audio et vidéo : capture les entrées audio et vidéo en temps réel depuis le microphone et la caméra, active le mode VAD pour détecter automatiquement le début et la fin de la parole, et prend en charge l'interruption vocale.
Le paramètre
enable_turn_detectiondoit être défini sur True.Nous vous recommandons d'utiliser un casque pour la lecture audio afin d'éviter que les échos ne déclenchent une interruption vocale.
-
Appel local : utilise des fichiers audio et image locaux comme entrée et active le mode Manuel, qui permet de contrôler manuellement le rythme d'envoi.
Le paramètre
enable_turn_detectiondoit être défini sur False.
Paramètres de requête
Définissez les paramètres de requête suivants dans le constructeur (init) de la classe OmniRealtimeConversation.
| Paramètre | Type | Description |
|---|---|---|
| model | str | Modèle Qwen-Omni à utiliser. Consultez la Liste des modèles. |
| callback | OmniRealtimeCallback | Instance de callback chargée de gérer les événements côté serveur. |
| url | str | Adresse d'appel :
{WorkspaceId} par votre véritable ID d'espace de travail. |
| Paramètre | Type | Description |
|---|---|---|
| output_modalities | list[MultiModality] | Modalité de sortie du modèle. Définissez [MultiModality.TEXT] pour le texte uniquement, ou [MultiModality.TEXT, MultiModality.AUDIO] pour combiner audio et texte. |
| voice | str | Voix utilisée pour la sortie audio. Pour les voix prises en charge, consultez la Liste des voix.Voix par défaut :
|
| input_audio_format | AudioFormat | Format de l'audio d'entrée utilisateur. Seul PCM_16000HZ_MONO_16BIT est actuellement pris en charge, correspondant à un flux audio PCM avec une fréquence d'échantillonnage de 16 kHz. |
| output_audio_format | AudioFormat | Format de l'audio de sortie du modèle. Seul PCM_24000HZ_MONO_16BIT est actuellement pris en charge, correspondant à un flux audio PCM avec une fréquence d'échantillonnage de 24 kHz. |
| smooth_output | bool | Ce paramètre est pris en charge uniquement par qwen3-omni-flash-realtime-2025-09-15.
|
| instructions | str | Message système définissant l'objectif ou le rôle du modèle.Exemple : Vous êtes un assistant IA pour un hôtel cinq étoiles. Répondez aux questions des clients concernant les types de chambres, les équipements, les tarifs et les politiques de réservation. Soyez précis et aimable. Adoptez toujours une attitude professionnelle et serviable. Ne fournissez aucune information non vérifiée ou extérieure au périmètre des services de l'hôtel. |
| enable_input_audio_transcription | bool | Active la reconnaissance vocale pour l'audio d'entrée. |
| input_audio_transcription_model | str | Modèle de reconnaissance vocale pour la transcription de l'audio d'entrée. La valeur est toujours qwen3-asr-flash-realtime. Ce paramètre n'est pas configurable. |
| turn_detection_type | str | Type de détection d'activité vocale (VAD). Valeurs valides :
|
| turn_detection_threshold | float | Seuil de détection VAD. Augmentez cette valeur dans les environnements bruyants et diminuez-la dans les environnements calmes.
|
| turn_detection_silence_duration_ms | int | Durée de silence indiquant la fin de la parole. Si cette durée est dépassée, le modèle déclenche une réponse. Valeur par défaut : 800. Valeurs valides : [200, 6000]. |
| turn_detection_param | dict | Paramètres de configuration supplémentaires pour turn_detection. Prend actuellement en charge idle_timeout_ms (int) : délai d'inactivité en millisecondes. S'applique uniquement aux modèlesqwen3.5-omni-plus-realtimeetqwen3.5-omni-flash-realtimeen modeserver_vad. Une fois la lecture audio terminée par le serveur, si l'utilisateur reste silencieux au-delà de cette durée (aucun événement speech.started déclenché), le modèle génère proactivement une réponse pour inviter l'utilisateur à poursuivre la conversation. Plage valide : [5000, 30000].Exemple : turn_detection_param={'idle_timeout_ms': 5000} |
| enable_search | bool | Ce paramètre n'est effectif qu'avec la série de modèles Qwen3.5-Omni-Realtime.Active la recherche web. Valeur par défaut : false. Lorsqu'elle est activée, cette option permet au modèle d'effectuer des recherches sur le web pour répondre aux questions en temps réel.L'appel d'outils (tools) et la recherche web (enable_search) sont incompatibles. Vous ne pouvez pas activer les deux simultanément. |
| search_options | object | Options de recherche web. Ne prend effet que lorsque enable_search est activé.Actuellement, seul enable_source (Boolean) est configurable ; il contrôle le retour des sources des résultats de recherche. Définissez-le sur true pour l'activer. Exemple : search_options={'enable_source': True}. |
| tools | list[dict] | Ce paramètre n'est effectif qu'avec la série de modèles Qwen3.5-Omni-Realtime.Définitions des outils. Lorsqu'ils sont fournis, le modèle peut appeler des outils externes pour répondre aux questions de l'utilisateur. Si un outil est appelé, le modèle ne génère pas d'audio et retourne uniquement les paramètres d'appel de l'outil.Chaque outil est un dictionnaire contenant les champs suivants :
|
| temperature | float | Température d'échantillonnage contrôlant la diversité du contenu.Des valeurs élevées produisent un contenu plus diversifié, tandis que des valeurs faibles génèrent un contenu plus déterministe.Valeurs valides : [0, 2).Étant donné que temperature et top_p contrôlent tous deux la diversité du contenu, nous vous recommandons de ne modifier qu'un seul de ces paramètres.
|
| top_p | float | Seuil de probabilité pour l'échantillonnage par noyau, contrôlant la diversité du contenu.Des valeurs élevées produisent un contenu plus diversifié, tandis que des valeurs faibles génèrent un contenu plus déterministe.Valeurs valides : (0, 1,0].Étant donné que temperature et top_p contrôlent tous deux la diversité du contenu, nous vous recommandons de ne modifier qu'un seul de ces paramètres.Valeurs top_p par défaut :
|
| top_k | integer | Taille de l'ensemble de candidats pour l'échantillonnage. Par exemple, une valeur de 50 signifie que seuls les 50 tokens ayant obtenu les scores les plus élevés constituent l'ensemble de candidats. Des valeurs plus grandes augmentent l'aléatoire, tandis que des valeurs plus petites renforcent le déterminisme. Définissez ce paramètre sur None ou sur une valeur supérieure à 100 pour désactiver top_k et utiliser uniquement top_p.La valeur doit être supérieure ou égale à 0.Valeurs top_k par défaut :
|
| max_tokens | integer | Nombre maximal de tokens à retourner.Le paramètreLes valeurs par défaut et maximales correspondent à la longueur de sortie maximale du modèle. Consultez la console Model Studio pour plus de détails.Utilisez max_tokens pour limiter la longueur de sortie lors de la génération de résumés ou de mots-clés, afin de maîtriser les coûts ou de réduire le temps de réponse. |
| repetition_penalty | float | Contrôle la répétition dans les séquences générées. Des valeurs plus élevées réduisent les répétitions. Une valeur de 1,0 signifie aucune pénalité. La valeur doit être supérieure à 0.Valeurs repetition_penalty par défaut :
|
| presence_penalty | float | Contrôle la répétition du contenu dans la sortie du modèle.Valeurs valides : [-2,0, 2,0]. Les valeurs positives réduisent les répétitions, tandis que les valeurs négatives les augmentent.Valeurs presence_penalty par défaut :
|
| seed | integer | Rend la génération plus déterministe, garantissant ainsi des résultats cohérents entre différentes exécutions.L'utilisation de la même seed avec des paramètres identiques produit autant que possible le même résultat.Valeurs valides : de 0 à 231−1. Valeur par défaut : -1. |
Interfaces principales
Classe OmniRealtimeConversation
Importez cette classe avec from dashscope.audio.qwen_omni import OmniRealtimeConversation.
| Signature de la méthode | Événement de réponse serveur (délivré par callback) | Description |
|---|---|---|
Événement serveurSession crééesession.updated Configuration de session mise à jour | Établit une connexion avec le serveur. | |
session.updatedConfiguration de session mise à jour | Met à jour la configuration de la session. Pour plus de détails sur les paramètres, consultez Paramètres de requête.Après la connexion, le serveur renvoie des configurations de session par défaut. Appelez cette méthode immédiatement après la connexion pour mettre à jour les paramètres.Lorsque le serveur reçoit l'événement session.update, il valide les paramètres. Les paramètres non valides renvoient une erreur ; sinon, le serveur met à jour la configuration de la session. | |
| Aucun | Ajoute des données audio encodées en Base64 au tampon d'entrée cloud. Ce tampon est un stockage temporaire dans lequel vous pouvez écrire et valider ultérieurement.
| |
| Aucun | Ajoute des données d'image encodées en Base64 au tampon vidéo cloud. Cette méthode accepte des images locales ou des captures de flux vidéo en temps réel.Limites d'entrée d'image :
| |
input_audio_buffer.clearedSupprime l'audio reçu par le serveur | Supprime l'audio du tampon cloud actuel. | |
input_audio_buffer.committedLe serveur a reçu l'audio validé | Valide l'audio et la vidéo du tampon cloud. Renvoie une erreur si le tampon est vide.
| |
Événement serveurLe serveur commence à générer une réponseresponse.output_item.added Nouveau contenu de sortie disponible dans la réponseÉvénement serveur Élément de conversation crééresponse.content_part.added Nouveau contenu de sortie ajouté à l'élément de message de l'assistantresponse.audio_transcript.delta Texte transcrit généré de manière incrémentielleresponse.audio.delta Audio généré de manière incrémentielle par le modèleresponse.audio_transcript.done Transcription du texte terminéeresponse.audio.done Génération audio terminéeresponse.content_part.done Streaming du contenu texte ou audio pour le message de l'assistant terminéresponse.output_item.done Streaming de l'ensemble de l'élément de sortie pour le message de l'assistant terminéresponse.done Réponse terminée | Demande au serveur de créer une réponse du modèle.Lorsque vous configurez une session en mode « turn_detection », le serveur crée automatiquement une réponse du modèle. | |
| Aucun | Annule la réponse en cours. S'il n'y a aucune réponse à annuler, le serveur répond par une erreur. | |
| Aucun | Envoie un événement conversation.item.create au serveur. Dans les scénarios d'appel d'outil, utilisez cette méthode pour renvoyer le résultat d'exécution de l'outil au serveur.Le paramètre item est un dictionnaire qui doit contenir les champs suivants :
| |
| Aucun | Termine la tâche et ferme la connexion. | |
| Aucun | Récupère le session_id de la tâche actuelle. | |
| Aucun | Récupère le response_id de la dernière réponse. |
Interface de callback (OmniRealtimeCallback)
Le serveur renvoie des événements de réponse et des données via des callbacks. Implémentez les méthodes de callback pour traiter les réponses du serveur.
Importez cette interface avec from dashscope.audio.qwen_omni import OmniRealtimeCallback.
| Méthode | Paramètres | Valeur de retour | Description |
|---|---|---|---|
| Aucun | Aucun | Appelée une fois la connexion au serveur établie. | |
| message : Un événement de réponse serveur. | Aucun | Contient les réponses aux appels d'interface ainsi que le texte et l'audio générés par le modèle. Consultez Événements serveur. | |
| close_status_code : Le code d'état pour la fermeture du WebSocket.close_msg : Le message de fermeture du WebSocket. | Aucun | Appelée après la fermeture de la connexion par le serveur. |
FAQ
Q : Comment aligner l'audio d'entrée et les images ?
Le modèle temps réel Qwen-Omni utilise le flux audio comme chronologie d'entrée. Les images sont insérées dans le flux audio en fonction de leur heure d'envoi. Vous pouvez ajouter des images à n'importe quel moment de la chronologie audio.
Dans les scénarios d'interaction en temps réel, vous pouvez activer ou désactiver l'entrée vidéo à tout moment.
Q : Quelle est la fréquence recommandée pour l'entrée d'images et d'audio ?
Pour les interactions en temps réel, nous recommandons d'envoyer des images à une fréquence de 1 ou 2 ips et l'audio par paquets de 100 ms.
Q : Quelles sont les différences entre les deux modes du commutateur turn_detection ?
Lorsque turn_detection est activé, il prend en charge deux modes : server_vad et semantic_vad :
-
Activation de « turn_detection » :
- État d'entrée : Le VAD cloud détecte la fin d'une phrase dans l'audio d'entrée et déclenche immédiatement l'inférence Qwen-Omni pour renvoyer le texte et la parole de réponse.
- État de réponse : Dans cet état, vous pouvez continuer à envoyer des entrées audio et vidéo sans interruption pendant que le modèle répond. Une fois la réponse terminée, l'état revient à l'état d'entrée pour attendre la prochaine entrée vocale.
- Interruption : Si l'utilisateur commence à parler pendant que le modèle répond, une interruption se déclenche. Le service arrête immédiatement la réponse en cours et passe à l'état d'entrée.
-
Désactivation de « turn_detection » :
- Vous devez déterminer manuellement la fin d'un cycle d'entrée audio et vidéo, puis déclencher l'inférence Qwen-Omni pour obtenir une réponse à l'aide de commit et create_response.
- Pendant que le modèle répond, vous devez cesser d'envoyer des entrées audio et vidéo. Vous ne pouvez reprendre l'entrée pour le cycle suivant qu'une fois la réponse du modèle terminée.
- Vous devez utiliser la méthode cancel_response pour interrompre la réponse du modèle.