Skip to main content

SDK Java Qwen-Omni-Realtime

Présentation des interfaces clés et des paramètres de requête pour le SDK Java DashScope dédié à Qwen-Omni real-time Qwen-Omni-Realtime .

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.

Prérequis

La version de votre SDK Java doit être v2.22.15 ou ultérieure. Avant de commencer, consultez le flux d'interaction multimodale en temps réelFlux d'interaction multimodale en temps réel.

Démarrage rapide

Téléchargez l'exemple de code depuis GitHubhttps://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni. Trois méthodes d'appel sont disponibles :
  1. Exemple de conversation audiohttps://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/java : capture l'audio en temps réel depuis un microphone, active le mode Voice Activity Detection (VAD)Qwen-Omni-Realtime qui détecte automatiquement le début et la fin de la parole, et prend en charge l'interruption vocale.
    Définissez le paramètre enableTurnDetection sur true .
    Utilisez un casque pour la lecture audio afin d'éviter que les échos ne déclenchent une interruption vocale.
  2. Exemple de conversation audio et vidéohttps://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/java : capture l'audio et la vidéo en temps réel depuis un microphone et une caméra, active le mode VADQwen-Omni-Realtime et prend en charge l'interruption vocale.
    Définissez le paramètre enableTurnDetection sur true .
    Utilisez un casque pour la lecture audio afin d'éviter que les échos ne déclenchent une interruption vocale.
  3. Appel localhttps://github.com/aliyun/alibabacloud-bailian-speech-demo/tree/master/samples/conversation/omni/java : utilise des fichiers audio et des images locaux comme entrée et active le mode manuelQwen-Omni-Realtime qui vous permet de contrôler manuellement le rythme d'envoi.
    Définissez le paramètre enableTurnDetection sur false .

Paramètres de requête

Configurez les paramètres de requête suivants à l'aide des méthodes chaînées ou des setters de l'objet OmniRealtimeParam, puis transmettez-le au constructeur OmniRealtimeConversation.
ParamètreTypeDescription
modelStringLe modèle Qwen-Omni à utiliser. Consultez la liste des modèles.
urlStringL'URL de l'endpoint :
  • Région Singapour : wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime
  • Région Pékin : wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime
Remplacez {WorkspaceId} par votre ID d'espace de travail réel.
Alibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions Chine (Pékin) et Singapour. Les nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • Chine (Pékin) : passez de wss://dashscope.aliyuncs.com à wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : passez de wss://dashscope-intl.aliyuncs.com à wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} correspond à votre ID d'espace de travail, visible sur la page Workspace Details de la console Alibaba Cloud Model Studio. Le domaine existant reste entièrement fonctionnel.
Configurez les paramètres de requête suivants à l'aide des méthodes chaînées ou des setters de l'objet OmniRealtimeConfig, puis transmettez-le à la méthode updateSession.
ParamètreTypeDescription
modalitiesList<OmniRealtimeModality>La modalité de sortie du modèle. Définissez sur [OmniRealtimeModality.TEXT] pour le texte uniquement, ou sur [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] pour l'audio et le texte.
voiceStringLa voix utilisée pour la sortie audio. Pour consulter les voix prises en charge, reportez-vous à la liste des voix.Voix par défaut :
  • Modèle de la série Qwen3,5-Omni : « Tina »
  • qwen3-omni-flash-realtime-2025-09-15 : « Cherry »
inputAudioFormatOmniRealtimeAudioFormatLe format de l'audio entrant de l'utilisateur. Actuellement, seul PCM_16000HZ_MONO_16BIT est pris en charge, ce qui représente un flux audio PCM avec un taux d'échantillonnage de 16 kHz.
outputAudioFormatOmniRealtimeAudioFormatLe format de l'audio sortant du modèle. Actuellement, seul PCM_24000HZ_MONO_16BIT est pris en charge, ce qui représente un flux audio PCM avec un taux d'échantillonnage de 24 kHz.
instructionsStringUn message système définissant l'objectif ou le rôle du modèle.Exemple : « Vous êtes un agent de service client 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 avec précision et convivialité. Restez toujours professionnel et utile. Ne fournissez pas d'informations non vérifiées ou hors du périmètre des services de l'hôtel. »
Définissez instructions à l'aide de la méthode parameters de l'instance OmniRealtimeConfig :
conversation.updateSession(OmniRealtimeConfig.builder()
            .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
            .voice("Tina")
            .enableTurnDetection(true)
            .enableInputAudioTranscription(true)
            .parameters(Map.of(
                    "instructions", "You are a personal assistant named Xiaoyun"
            ))
            .build()
    );
smooth_outputBooleanCe paramètre est pris en charge uniquement par qwen3-omni-flash-realtime-2025-09-15.
  • true : le modèle fournit des réponses conversationnelles.
  • false : le modèle fournit des réponses plus formelles, de style écrit.
    Cependant, les performances peuvent être sous-optimales si le contenu est difficile à lire à haute voix.
  • null : valeur par défaut. Le modèle choisit automatiquement entre les styles de réponse conversationnels et formels.
Définissez smooth_output à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.
enableInputAudioTranscriptionBooleanActive la reconnaissance vocale pour l'audio entrant.
InputAudioTranscriptionStringModèle de reconnaissance vocale utilisé pour la transcription de l'audio entrant. La valeur est toujours qwen3-asr-flash-realtime. Ce paramètre n'est pas configurable.
enableTurnDetectionBooleanActive la détection d'activité vocale (VAD). Si cette option est désactivée, vous devez soumettre manuellement l'audio pour générer une réponse.
turnDetectionTypeStringLe type de VAD. Valeurs valides :
  • server_vad (par défaut) : détecte la fin de la parole de l'utilisateur en se basant sur les caractéristiques acoustiques.
  • semantic_vad : détecte la fin de la parole de l'utilisateur en se basant sur la validité sémantique. Ce mode peut filtrer les paroles insignifiantes, telles que les backchannels et le bruit de fond. Cette option est prise en charge uniquement par le modèle de la série Qwen3,5-Omni-Realtime.
turnDetectionThresholdFloatSeuil de détection VAD. Augmentez cette valeur dans les environnements bruyants et diminuez-la dans les environnements calmes.
  • Plus la valeur est proche de -1, plus il est probable que le bruit soit détecté comme de la parole.
  • Plus la valeur est proche de 1, moins il est probable que le bruit soit détecté comme de la parole.
Par défaut : 0,5. Valeurs valides : [-1,0, 1,0].
turnDetectionSilenceDurationMsIntegerDuré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. Par défaut : 800. Valeurs valides : [200, 6000].
turnDetectionParamMapParamètres de configuration supplémentaires pour turn_detection. Prend actuellement en charge idle_timeout_ms (Integer) : le délai d'inactivité en millisecondes. S'applique uniquement aux modèlesqwen3,5-omni-plus-realtimeetqwen3,5-omni-flash-realtimeen modeserver_vad. Une fois que le serveur a terminé la lecture audio et que 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 : turnDetectionParam(Map.of("idle_timeout_ms", 5000))
enable_searchBooleanCe paramètre prend effet uniquement lorsque vous utilisez le modèle de la série Qwen3,5-Omni-Realtime.Active la recherche web. Par défaut : false. Lorsqu'il est activé, le modèle peut effectuer des recherches sur le web pour répondre aux questions en temps réel.
Les paramètres enable_search et search_options doivent être définis à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. Le processus est identique à celui d'instructions.
L'appel d'outils (tools) et la recherche web (enable_search) sont incompatibles et ne peuvent pas être activés simultanément.
search_optionsObjectParamètres des options de recherche web. Ce paramètre prend effet uniquement après l'activation d'enable_search. Vous pouvez définir enable_source (Boolean) sur true pour retourner une liste des sources des résultats de recherche.
Définissez search_options à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.
toolsList<Map<String, Object>>Ce paramètre prend effet uniquement lorsque vous utilisez le modèle de la série 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 des utilisateurs. 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 une Map contenant les champs suivants :
  • type (String, obligatoire) : la valeur est fixée à « function ».
  • function (Map, obligatoire) : la définition de la fonction de l'outil. Ce champ contient les sous-champs suivants :
    • name (String, obligatoire) : un nom personnalisé pour la fonction de l'outil. Nous vous recommandons d'utiliser le même nom que la fonction, par exemple get_current_weather ou get_current_time.
    • description (String, facultatif) : une description de la fonction de l'outil. Le modèle utilise cette description pour décider s'il doit appeler la fonction.
    • parameters (Map, facultatif) : descriptions des paramètres d'entrée. Le modèle les utilise pour extraire les paramètres. Si la fonction de l'outil ne nécessite aucun paramètre d'entrée, vous n'avez pas besoin de spécifier ce champ. Ce champ contient les sous-champs suivants :
      • type (String, obligatoire) : la valeur est fixée à « object ».
      • properties (Map, facultatif) : décrit le nom, le type de données et la description de chaque paramètre d'entrée. La clé correspond au nom du paramètre et la valeur est une Map contenant le type de données (type) et la description (description).
      • required (List, facultatif) : spécifie quels paramètres d'entrée sont obligatoires.
Définissez search_options à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.
temperatureFloatTempérature d'échantillonnage contrôlant la diversité du contenu.Des valeurs plus élevées produisent un contenu plus diversifié ; des valeurs plus faibles produisent 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 n'en définir qu'un seul.Valeurs par défaut de temperature :
  • Modèle de la série Qwen3,5-Omni-Realtime : 0,7
  • qwen3-omni-flash-realtime-2025-09-15 : 0,9
Définissez le paramètre temperature à l'aide de la méthode parameters de l'instance OmniRealtimeConfig, de la même manière que vous définissez le paramètre instructions.
top_pFloatSeuil de probabilité pour l'échantillonnage par noyau (nucleus sampling), contrôlant la diversité du contenu.Des valeurs plus élevées produisent un contenu plus diversifié ; des valeurs plus faibles produisent 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 n'en définir qu'un seul.Valeurs par défaut de top_p :
  • Modèle de la série Qwen3,5-Omni-Realtime : 0,8
  • qwen3-omni-flash-realtime-2025-09-15 : 1,0
Définissez top_p à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.
top_kIntegerTaille de l'ensemble de candidats pour l'échantillonnage. Par exemple, 50 signifie que seuls les 50 jetons ayant les scores les plus élevés forment l'ensemble de candidats. Des valeurs plus grandes augmentent l'aléatoire ; des valeurs plus petites augmentent le déterminisme. Définissez 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 par défaut de top_k :
  • Modèle de la série Qwen3,5-Omni-Realtime : 20
  • qwen3-omni-flash-realtime-2025-09-15 : 50
Définissez top_k à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.
max_tokensIntegerNombre maximal de jetons à retourner.
Le paramètre max_tokens n'affecte pas le processus de génération du modèle. Si le nombre de jetons générés par le modèle dépasse max_tokens, le contenu retourné est tronqué.
Les valeurs par défaut et maximales correspondent à la longueur de sortie maximale du modèle. Consultez la liste des modèles pour plus de détails.Utilisez max_tokens pour limiter la longueur de sortie lors de la génération de résumés, de mots-clés, pour contrôler les coûts ou réduire le temps de réponse.
Définissez max_tokens à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.
repetition_penaltyFloatContrôle la répétition dans les séquences générées. Des valeurs plus élevées réduisent la répétition. 1,0 signifie aucune pénalité. Doit être supérieur à 0.Valeurs par défaut de repetition_penalty :
  • Modèle de la série Qwen3,5-Omni-Realtime : 1,0
  • Autres modèles : 1,05
Définissez repetition_penalty à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.
presence_penaltyFloatContrôle la répétition du contenu dans la sortie du modèle.Valeurs valides : [-2,0, 2,0]. Les valeurs positives réduisent la répétition ; les valeurs négatives l'augmentent.Valeurs par défaut de presence_penalty :
  • Modèle de la série Qwen3,5-Omni-Realtime : 1,5
  • Autres modèles : 0,0
Scénarios :Des valeurs plus élevées conviennent aux scénarios nécessitant de la diversité ou de la créativité, tels que l'écriture créative ou le brainstorming.Des valeurs plus faibles conviennent aux scénarios nécessitant de la cohérence ou de la précision technique, tels que les documents techniques.
Définissez presence_penalty à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.
seedIntegerRend la génération plus déterministe, garantissant des résultats cohérents d'une exécution à l'autre.L'utilisation de la même seed avec des paramètres identiques produit, autant que possible, le même résultat.Valeurs valides : 0 à 231−1. Valeur par défaut : -1.
Définissez seed à l'aide de la méthode parameters de l'instance OmniRealtimeConfig. L'utilisation est identique à celle d'instructions.

Référence de l’API

Classe OmniRealtimeConversation

Importez avec import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.
Signature de la méthodeÉvénement de réponse du serveur (envoyé via callback)Description
public void connect() throws NoApiKeyException, InterruptedException
Événements serveur
Session créée
session.updated
Configuration de la session mise à jour
Établit une connexion avec le serveur.
public void updateSession(OmniRealtimeConfig config)
session.updated
Configuration de la session mise à jour
Met à jour la configuration de la session. Pour plus de détails sur les paramètres, consultez la section Paramètres de requête.Après la connexion, le serveur renvoie les 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. Des paramètres invalides renvoient une erreur ; sinon, le serveur met à jour la configuration de la session.
public void appendAudio(String audioBase64)
AucunAjoute de l'audio encodé en Base64 au tampon d'entrée cloud. Le tampon est un stockage temporaire pouvant être écrit et validé ultérieurement.
  • Si « turn_detection » est activé, le tampon audio est utilisé pour détecter la parole et le serveur décide quand valider.
  • Si « turn_detection » est désactivé, le client peut envoyer jusqu'à 15 MiB d'audio par événement. Le streaming de blocs plus petits rend la VAD plus réactive.
public void appendVideo(String videoBase64)
AucunAjoute des données d'image encodées en Base64 au tampon vidéo cloud. Accepte des images locales ou des captures de flux vidéo en temps réel.Limites d'entrée d'image :
  • Le format d'image doit être JPG ou JPEG. La résolution d'image recommandée est 480p ou 720p, avec un maximum de 1080p.
  • Une seule image après encodage Base64 ne doit pas dépasser 256 Ko. Nous vous recommandons de maintenir la taille brute de l'image inférieure à 190 Ko avant l'encodage.
  • Les données d'image doivent être encodées en Base64.
  • Nous vous recommandons d'envoyer les images au serveur à une fréquence d'une image par seconde.
public void clearAppendedAudio()
input_audio_buffer.cleared
L'audio reçu par le serveur est effacé
Supprime l'audio présent dans le tampon cloud actuel.
public void commit()
input_audio_buffer.committed
Le 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.
  • Si « turn_detection » est activé, le client n'a pas besoin d'envoyer cet événement. Le serveur valide automatiquement le tampon audio.
  • Si « turn_detection » est désactivé, le client doit valider le tampon audio pour créer un élément de message utilisateur.
Remarque :
  1. Si input_audio_transcription est configuré pour la session, le système transcrit l'audio.
  2. La validation du tampon d'audio entrant ne crée pas de réponse du modèle.
public void createResponse(String instructions, List<OmniRealtimeModality> modalities)
Événements serveur
Le serveur commence à générer une réponse
response.output_item.added
Nouveau contenu de sortie disponible dans la réponse
Événements serveur
Un élément de conversation est créé
response.content_part.added
Nouveau contenu de sortie ajouté à l'élément de message de l'assistant
response.audio_transcript.delta
Texte transcrit généré de manière incrémentielle
response.audio.delta
Audio généré de manière incrémentielle par le modèle
response.audio_transcript.done
Transcription du texte terminée
response.audio.done
Génération audio terminée
response.content_part.done
Streaming du contenu textuel ou audio pour le message de l'assistant terminé
response.output_item.done
Streaming de l'élément de sortie entier pour le message de l'assistant terminé
response.done
Réponse terminée
Instruit le serveur de créer une réponse du modèle.Lorsque la session est configurée en mode « turn_detection », le serveur crée automatiquement une réponse du modèle.
public void cancelResponse()
AucunAnnule la réponse en cours. Si aucune réponse n'est disponible pour annulation, le serveur renvoie une erreur.
public void createItem(JsonObject item)
AucunEnvoie l'événement conversation.item.create au serveur. Dans un scénario d'appel d'outil, cette méthode est utilisée pour renvoyer le résultat de l'exécution de l'outil au serveur.Le paramètre item est un JsonObject et doit contenir les champs suivants :
  • type : la valeur est fixée à « function_call_output ».
  • call_id : correspond au call_id dans l'événement response.function_call_arguments.done.
  • output : une chaîne représentant le résultat de l'exécution de l'outil.
public void close()
AucunArrête la tâche et ferme la connexion.
public String getSessionId()
AucunRécupère l'ID de session de la tâche actuelle.
public String getResponseId()
AucunRécupère l'ID de réponse de la réponse la plus récente.

Interface de callback (OmniRealtimeCallback)

Le serveur renvoie les événements et les données de réponse via des callbacks. Implémentez les méthodes de callback pour traiter les réponses du serveur. Importez avec import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;.
MéthodeParamètreValeur de retourDescription
public void onOpen()
AucunAucunAppelé immédiatement après l'établissement d'une connexion avec le serveur.
public abstract void onEvent(JsonObject message)
message : l'événement de réponse du serveur.AucunContient les réponses aux appels d'interface ainsi que le texte et l'audio générés par le modèle. Consultez les événements serveur.
public abstract void onClose(int code, String reason)
code : le code d'état de fermeture du WebSocket.reason : la raison de la fermeture du WebSocket.AucunAppelé après la fermeture de la connexion avec le serveur.