Alibaba Cloud Model Studio:SDK Java

model

String

Le modèle Qwen-Omni à utiliser. Consultez la liste des modèles.

url

String

L'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.

modalities

List<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.

voice

String

La 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 »

inputAudioFormat

OmniRealtimeAudioFormat

Le 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.

outputAudioFormat

OmniRealtimeAudioFormat

Le 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.

instructions

String

Un 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. »

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_output

Boolean

Ce 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.

enableInputAudioTranscription

Boolean

Active la reconnaissance vocale pour l'audio entrant.

InputAudioTranscription

String

Modè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.

enableTurnDetection

Boolean

Active 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.

turnDetectionType

String

Le 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.

turnDetectionThreshold

Float

Seuil 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].

turnDetectionSilenceDurationMs

Integer

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. Par défaut : 800. Valeurs valides : [200, 6000].

turnDetectionParam

Map

Paramè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_search

Boolean

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_options

Object

Paramè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.

tools

List<Map<String, Object>>

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.

temperature

Float

Tempé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_p

Float

Seuil 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_k

Integer

Taille 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_tokens

Integer

Nombre 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_penalty

Float

Contrô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_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 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.

seed

Integer

Rend 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 à 2³¹−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.

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)

Aucun

Ajoute 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)

Aucun

Ajoute 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.

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()

Aucun

Annule la réponse en cours. Si aucune réponse n'est disponible pour annulation, le serveur renvoie une erreur.

public void createItem(JsonObject item)

Aucun

Envoie 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()

Aucun

Arrête la tâche et ferme la connexion.

public String getSessionId()

Aucun

Récupère l'ID de session de la tâche actuelle.

public String getResponseId()

Aucun

Récupère l'ID de réponse de la réponse la plus récente.

public void onOpen()

Aucun

Aucun

Appelé 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.

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 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.

Aucun

Appelé après la fermeture de la connexion avec le serveur.