Alibaba Cloud Model Studio:SDK Python

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 :

• Région de Singapour : wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime.
• Région de Pékin : wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime

Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.

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 :

• Série de modèles Qwen3.5-Omni : "Tina"
• qwen3-omni-flash-realtime-2025-09-15 : "Cherry"

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.

• True : obtenez une réponse conversationnelle.

• False : obtenez une réponse plus formelle, de style écrit.

  Notez que cela peut entraîner une qualité moindre si le contenu se prête mal à la lecture à haute voix.

• None : le modèle sélectionne automatiquement un style de réponse conversationnel ou formel.

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 :

• server_vad (par défaut) : détecte la fin de la parole de l'utilisateur en fonction des caractéristiques acoustiques.
• semantic_vad : détecte la fin de la parole de l'utilisateur en fonction de la validité sémantique. Ce mode permet de filtrer les paroles sans signification, telles que les mots de remplissage et les bruits de fond. Seule la série de modèles Qwen3.5-Omni-Realtime prend en charge ce mode.

turn_detection_threshold

float

Seuil de détection VAD. Augmentez cette valeur dans les environnements bruyants et diminuez-la dans les environnements calmes.

• Plus la valeur se rapproche de -1, plus le bruit risque d'être interprété comme de la parole.
• Plus la valeur se rapproche de 1, moins le bruit risque d'être interprété comme de la parole.

Valeur par défaut : 0,2. Valeurs valides : [-1,0, 1,0].

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

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]

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 :

• type (string, obligatoire) : doit être défini sur "function".

• function (dict, obligatoire) : définition de la fonction outil. Elle contient les champs suivants :

  • name (string, obligatoire) : nom personnalisé de la fonction outil. Nous vous recommandons d'utiliser un nom identique à celui de la fonction, par exemple get_current_weather ou get_current_time.

  • description (string, facultatif) : description de la fonction outil. Le modèle utilise cette description pour décider s'il doit appeler la fonction.

  • parameters (dict, facultatif) : descriptions des paramètres d'entrée. Le modèle les utilise pour extraire les paramètres. Si la fonction outil ne nécessite aucun paramètre d'entrée, ce champ n'est pas requis. Il contient les champs suivants :

    • type (string, obligatoire) : doit être défini sur "object".
    • properties (dict, 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 un dictionnaire contenant le type de données (type) ainsi que la description (description).
    • required (list, facultatif) : spécifie les paramètres d'entrée obligatoires.

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.

• Série de modèles Qwen3.5-Omni-Realtime : 0,7
• qwen3-omni-flash-realtime-2025-09-15 : 0,9

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 :

• Série de modèles Qwen3.5-Omni-Realtime : 0,8
• qwen3-omni-flash-realtime-2025-09-15 : 1,0

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 :

• Série de modèles Qwen3.5-Omni-Realtime : 20
• qwen3-omni-flash-realtime-2025-09-15 : 50

max_tokens

integer

Nombre maximal de tokens à retourner.

Le paramètre max_tokens n'affecte pas le processus de génération du LLM. Si le nombre de tokens 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 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 :

• Série de modèles Qwen3.5-Omni-Realtime : 1,0
• Autres modèles : 1,05

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 :

• Série de modèles Qwen3.5-Omni-Realtime : 1,5
• Autres modèles : 0,0

Cas d'usage :

Les valeurs élevées conviennent aux scénarios exigeant de la diversité ou de la créativité, tels que la rédaction créative ou le brainstorming.

Les valeurs faibles sont adaptées aux scénarios nécessitant de la cohérence ou une précision technique, comme la rédaction de documents techniques.

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 à 2³¹−1. Valeur par défaut : -1.

def connect(self,) -> None

Événement serveur

Session créée

session.updated

Configuration de session mise à jour

Établit une connexion avec le serveur.

def update_session(self,
                       output_modalities: list[MultiModality],
                       voice: str,
                       input_audio_format: AudioFormat = AudioFormat.
                       PCM_16000HZ_MONO_16BIT,
                       output_audio_format: AudioFormat = AudioFormat.
                       PCM_24000HZ_MONO_16BIT,
                       enable_input_audio_transcription: bool = True,
                       input_audio_transcription_model: str = None,
                       enable_turn_detection: bool = True,
                       turn_detection_type: str = 'server_vad',
                       prefix_padding_ms: int = 300,
                       turn_detection_threshold: float = 0.2,
                       turn_detection_silence_duration_ms: int = 800,
                       turn_detection_param: dict = None,
                       **kwargs) -> None

session.updated

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

def append_audio(self, audio_b64: str) -> None

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.

• Si « turn_detection » est activé, le tampon audio sert à la détection vocale et le serveur décide du moment de validation.
• Si « turn_detection » est désactivé, le client peut envoyer jusqu'à 15 Mio d'audio par événement. Le streaming de blocs plus petits rend le VAD plus réactif.

def append_video(self, video_b64: str) -> None

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 :

• Le format d'image doit être JPG ou JPEG. La résolution recommandée est 480p ou 720p, avec un maximum de 1080p.
• Une image unique après encodage Base64 ne doit pas dépasser 256 Ko. Nous recommandons de conserver la taille de l'image brute sous 190 Ko avant l'encodage.
• Les données d'image doivent être encodées en Base64.
• Nous recommandons d'envoyer des images au serveur à une fréquence de 1 image par seconde.

def clear_appended_audio(self, ) -> None

input_audio_buffer.cleared

Supprime l'audio reçu par le serveur

Supprime l'audio du tampon cloud actuel.

def commit(self, ) -> None

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 la transcription audio est configurée pour la session via input_audio_transcription, le système transcrit l'audio.
2. La validation du tampon audio d'entrée ne déclenche pas de réponse du modèle.

def create_response(self,
        instructions: str = None,
        output_modalities: list[MultiModality] = None) -> None

Événement serveur

Le serveur commence à générer une réponse

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

def cancel_response(self, ) -> None

Aucun

Annule la réponse en cours. S'il n'y a aucune réponse à annuler, le serveur répond par une erreur.

def create_item(self, item: dict) -> None

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 :

• type : Doit être « function_call_output ».
• call_id : Le call_id provenant de l'événement response.function_call_arguments.done.
• output : Une chaîne contenant le résultat d'exécution de l'outil.

def close(self, ) -> None

Aucun

Termine la tâche et ferme la connexion.

def get_session_id(self) -> str

Aucun

Récupère le session_id de la tâche actuelle.

def get_last_response_id(self) -> str

Aucun

Récupère le response_id de la dernière réponse.

def on_open(self) -> None

Aucun

Aucun

Appelée une fois la connexion au serveur établie.

def on_event(self, message: str) -> None

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.

def on_close(self, close_status_code, close_msg) -> None

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.