Tous les produits
Search
Centre de documentation

Alibaba Cloud Model Studio:SDK iOS de conversation vocale en temps réel Qwen-Audio-3.0-Realtime

Dernière mise à jour :Oct 11, 2026

Utilisez le SDK iOS pour Qwen-Audio-3.0-Realtime afin de créer des conversations vocales en temps réel avec une entrée audio et une sortie audio ou texte.

Guide d'utilisation : Pour les présentations des modèles et les conseils de sélection, consultez Conversation vocale en temps réel.

Démarrage rapide

  1. Obtenir une clé API : Obtenir et configurer une clé API.

  2. Téléchargez le SDK et exécutez l'exemple de code :
    • Téléchargez le dernier package du SDK.
    • Extrayez le package ZIP et ajoutez nuisdk.xcframework à votre projet.
    • Dans Build Phases > Link Binary With Libraries, ajoutez nuisdk.xcframework.
    • Dans General > Frameworks, Libraries, and Embedded Content, définissez nuisdk.xcframework sur Embed & Sign.
    • Ouvrez le projet dans Xcode. Le code d'exemple se trouve dans DashQwenAudioChatViewController.m. Remplacez la clé API pour tester la fonctionnalité.

Procédure d'appel

  1. Initialiser le SDK.
  2. Définissez les paramètres pour votre cas d'utilisation. Utilisez l'argument parameters de nui_initialize pour définir les paramètres de connexion et de contrôle, et utilisez nui_set_params pour définir les paramètres de conversation vocale.
  3. Appelez nui_dialog_start pour démarrer la conversation.
  4. Dans onNuiAudioStateChanged, démarrez le périphérique d'enregistrement en fonction de l'état audio.
  5. Fournissez en continu les données d'enregistrement dans onNuiNeedAudioData, ou appelez nui_update_audio_data pour envoyer activement les données d'enregistrement.
  6. Recevez en continu l'audio renvoyé par le modèle dans onNuiAssistEventCallback.
  7. Écoutez les événements et obtenez les informations d'événement dans onNuiEventCallback.
  8. Appelez nui_dialog_cancel pour arrêter la conversation, et écoutez EVENT_TRANSCRIBER_COMPLETE pour confirmer qu'elle est terminée.
  9. Lorsque la fonctionnalité de conversation n'est plus nécessaire, appelez nui_release pour libérer les ressources du SDK.

Paramètres de requête

Paramètres de connexion et de contrôle

Transmettez une chaîne JSON dans l'argument parameters de nui_initialize.

Exemple : La chaîne JSON suivante ne répertorie pas tous les paramètres. Ajoutez les paramètres nécessaires pour votre cas d'utilisation.

{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}
Paramètres
ParamètreTypeObligatoireDescription

url

String

Oui

Point de terminaison du service :

  • wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Chine (Pékin) : wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Singapour : wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.

apikey

String

Oui

Clé API.

service_mode

String

Oui

Mode d'exécution. Définissez ce paramètre sur "1" pour une conversation vocale en temps réel.

device_id

String

Oui

Une chaîne unique qui identifie l'utilisateur final. Vous pouvez utiliser un identifiant d'utilisateur dans l'application ou un identifiant d'appareil généré par le client. Cet identifiant est principalement utilisé pour le suivi des journaux et le dépannage.

audio_update_manually

String

Non

Indique s'il faut pousser activement les données audio. Valeur par défaut : "false". Si défini sur "true" et que le SDK prend en charge les capacités audio sur l'appareil telles que l'AEC et le VAD, ces capacités sont activées par défaut.

workspace

String

Non

Le chemin de stockage des fichiers de ressources sur l'appareil. Ce paramètre est requis lorsque audio_update_manually est "true" et qu'une capacité audio sur l'appareil telle que l'AEC ou le VAD est activée.

debug_path

String

Non

Le chemin de stockage du fichier journal. Ce paramètre prend effet uniquement lorsque save_log est true dans nui_initialize. Dans ce cas, le chemin est requis. Le SDK conserve au maximum deux fichiers journaux localement.

save_wav

String

Non

Indique s'il faut enregistrer l'audio de débogage sous debug_path. Valeur par défaut : "false". Les valeurs valides sont "true" et "false". Ce paramètre prend effet uniquement lorsque save_log est true, et debug_path doit également être défini.

max_log_file_size

int

Non

Taille maximale du fichier journal en octets. Ce paramètre prend effet uniquement lorsque save_log est true. Valeur par défaut : 104857600 (100 × 1024 × 1024 octets, soit 100 Mio).

log_track_level

int

Non

Le niveau de filtrage pour les journaux envoyés via onNuiLogTrackCallback. Valeur par défaut : 2. Valeurs valides : 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR) et 5 (NONE). Un journal n'est renvoyé que lorsque son niveau est supérieur ou égal à la fois à log_track_level et au level transmis à nui_initialize. Par exemple, si log_track_level est 2 (INFO) et que level est 3 (WARNING), seuls les journaux de niveau WARNING et supérieur (valeurs supérieures ou égales à 3) sont renvoyés.

Paramètres de conversation vocale

Transmettez une chaîne JSON dans l'argument params de nui_set_params.

Exemple : La chaîne JSON suivante ne répertorie pas tous les paramètres. Ajoutez les paramètres nécessaires pour votre cas d'utilisation.

{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}
Paramètres
Paramètre de niveau supérieurTypeObligatoireDescription

service_type

int

Oui

Type de service vocal. Définissez ce paramètre sur 4 pour une conversation vocale en temps réel.

nls_config

object

Oui

Configuration principale de la conversation vocale, y compris la sélection du modèle et le comportement de la conversation.

nls_config.model

string

Oui

Nom du modèle. Prend en charge les séries de modèles qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus et qwen-audio-3.0-realtime-flash.

nls_config.sr_format

string

Oui

Format audio d'entrée. Seul pcm est pris en charge. Le format par défaut est 16 kHz, 16 bits, PCM mono.

nls_config.modalities

string

Non

Une chaîne contenant un tableau de modalités de sortie. Valeurs valides :

  • ["text"] : renvoie uniquement du texte.
  • ["audio", "text"] (par défaut) : renvoie à la fois l'audio et le texte.

nls_config.voice

string

Non

Voix TTS. La valeur par défaut est longanqian_v3.1 pour 3.1 Plus et longanqian pour 3.0 Plus/Flash. Ce paramètre ne peut être défini que dans le premier session.update ; les valeurs ultérieures sont ignorées. Voix système : longanqian, longanlingxin, longanlingxi, longanxiaoxin et longanlufeng. Vous pouvez également spécifier un voice_id cloné créé via l'API de clonage vocal. Consultez Configuration de la voix.

3.1 Plus prend également en charge longanqian_v3.1, longanhuan_v3.1, longanlingxin_v3.1, longanfengyue_v3.1, xunanchuan_v3.1, beth_v3.1, betty_v3.1 et cally_v3.1.

nls_config.enable_speech_emotion

BOOL

Non

Indique s'il faut activer l'expression émotionnelle améliorée. Lorsqu'elle est activée, la voix de réponse présente des variations émotionnelles plus perceptibles. Valeur par défaut : YES. Valeurs valides : YES et NO.

nls_config.instructions

string

Non

Instructions système qui définissent le rôle du modèle, le style de réponse et les préférences comportementales pour l'ensemble de la session.

nls_config.max_history_turns

int

Non

Nombre maximal de tours de questions-réponses historiques autorisés dans une requête. Valeurs valides : 1 à 50. Valeur par défaut : 20.

nls_config.tools

string

Non

Une chaîne contenant un tableau de définitions d'outils d'appel de fonction. Après avoir configuré ce paramètre, le modèle décide s'il doit appeler un outil en fonction de l'entrée de l'utilisateur. Chaque définition utilise type (requis et fixé à function) et un objet function contenant name (requis), description (facultatif) et parameters (facultatif). Si une fonction n'a pas d'arguments, omettez parameters.
Exemple :

[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Queries weather information for a specified city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  }
]

nls_config.turn_detection

string

Non

Une chaîne contenant un objet JSON pour la détection des tours de parole. S'il est omis, la session utilise le mode push-to-talk, dans lequel l'audio est validé et l'inférence est déclenchée manuellement. S'il est défini, le mode de conversation duplex est activé.

nls_config.turn_detection.type

string

Non

Type de VAD. server_vad (par défaut) détecte les limites de la parole à partir des caractéristiques acoustiques et déclenche automatiquement l'inférence. smart_turn combine les signaux acoustiques et sémantiques ; les sons sans contenu sémantique, tels que les tics de langage, ne démarrent pas un tour de parole et n'interrompent pas la lecture du modèle.

nls_config.turn_detection.threshold

float

Non

Sensibilité du VAD. Ce paramètre s'applique uniquement à server_vad et n'a aucun effet sur smart_turn. Des valeurs plus basses rendent le VAD plus sensible aux sons faibles et au bruit de fond ; des valeurs plus élevées nécessitent une parole plus claire et plus forte. Plage valide : [-1.0, 1.0]. Valeur par défaut : 0.5.

nls_config.turn_detection.silence_duration_ms

int

Non

Durée minimale de silence après la parole, en millisecondes, avant que la réponse du modèle ne soit déclenchée. Ce paramètre s'applique uniquement à server_vad et n'a aucun effet sur smart_turn. Des valeurs plus basses réduisent la latence mais peuvent se déclencher lors de brèves pauses. Plage valide : [200, 6000]. Valeur par défaut : 800. Recommandé pour la conversation : 400 à 800.

nls_config.turn_detection.voiceprint_audio_urls

string

Non

Une chaîne contenant un tableau d'URL d'audio préenregistré accessibles au public pour le locuteur cible. Ce paramètre s'applique uniquement à smart_turn. Dans les conversations duplex, il aide le modèle à se concentrer sur le locuteur cible et à ignorer les autres locuteurs et le bruit de fond. Jusqu'à cinq URL sont prises en charge. L'audio doit être au format PCM ou WAV à 16 kHz.

API clés

NeoNui

nui_initialize

Initialise l'instance du SDK de conversation vocale. Le SDK est un singleton. Ne l'initialisez pas à nouveau avant d'appeler nui_release.

Signature de la méthode
-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;
Descriptions des paramètres

Paramètre

Type

Description

parameters

char*

Une chaîne JSON contenant les paramètres d'authentification, de connexion et de débogage. Voir Paramètres de connexion et de contrôle.

level

NuiSdkLogLevel

Niveau d'impression pour les propres journaux du SDK.

save_log

BOOL

Indique s'il faut enregistrer les journaux localement. Si défini sur YES, spécifiez un chemin avec debug_path dans les Paramètres de connexion et de contrôle, et définissez éventuellement la taille du fichier avec max_log_file_size.

nui_set_params

Définit les Paramètres de conversation vocale au format JSON. Appelez cette méthode avant nui_dialog_start.

Signature de la méthode
-(NuiResultCode) nui_set_params:(const char *)params;
Descriptions des paramètres

Paramètre

Type

Description

params

char*

Paramètres de conversation vocale.

nui_dialog_start

Démarre la conversation.

Signature de la méthode
-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;
Paramètres
ParamètreTypeDescription

vad_mode

NuiVadMode

Mode VAD. Fixé à MODE_P2T.

dialog_params

char*

Si apikey dans les paramètres de connexion et de contrôle est une clé API temporaire, mettez-la à jour ici après son expiration.
Format JSON :

{
  "apikey": "st-****"
}

nui_dialog_cancel

Met fin à la conversation ou annule immédiatement l'interaction en cours.

Signature de la méthode
-(NuiResultCode) nui_dialog_cancel:(BOOL)force;
Descriptions des paramètres

Paramètre

Type

Description

force

BOOL

Indique s'il faut forcer la fin et ignorer le résultat final.

  • YES : Met fin immédiatement à la tâche sans attendre que le serveur renvoie le résultat final de la conversation.

  • NO : Met fin à la tâche, mais attend le retour du résultat complet.

nui_dialog_action

Envoie une commande d'action de conversation pendant une interaction pour mettre à jour le comportement d'exécution, tel que le contexte de la conversation.

Signature de la méthode
- (NuiResultCode) nui_dialog_action:(const char *)params;
Paramètres
ParamètreTypeDescription

params

char*

Une chaîne JSON utilisée pour mettre à jour le comportement d'exécution, tel que le contexte de conversation.

params.type

String

Définir sur "action".

params.command

String

Commande d'exécution. Valeurs valides :

  • function_call : met à jour une requête d'appel de fonction.
  • play_start : lorsque l'AEC sur l'appareil est utilisé, notifie au SDK que la lecture audio a démarré.
  • play_over : lorsque l'AEC sur l'appareil est utilisé, notifie au SDK que la lecture audio est terminée.

params.context

String

Mise à jour de la requête d'appel de fonction. Utilisé lorsque command est "function_call".

params.context.type

String

Type d'événement. Ce paramètre est requis lorsque command est "function_call". conversation.item.create insère un élément de conversation pour le contexte historique, le texte supplémentaire ou le résultat d'un outil. Après avoir envoyé conversation.item.create, utilisez response.create pour déclencher une autre inférence.

params.context.item

object

Obligatoire lorsque params.context.type est conversation.item.create. L'élément de conversation à créer.

params.context.response

object

Facultatif lorsque params.context.type est response.create. Remplace les valeurs par défaut de la session pour cette inférence. S'il est omis, la configuration de session actuelle est utilisée.

Paramètres de context.item :

ParamètreTypeDescription

id

String

Identifiant unique facultatif de l'élément de conversation. S'il est omis, le serveur en génère un. Une erreur est renvoyée si l'identifiant spécifié existe déjà.

type

String

Type d'élément requis. Valeurs valides :

  • message : un message standard.
  • function_call : une requête d'appel de fonction. Ce type est généralement généré par le serveur. Le client peut également l'utiliser pour ajouter un contexte historique.
  • function_call_output : un résultat d'exécution d'outil. Après avoir reçu un function_call, le client exécute l'outil et utilise ce type pour renvoyer le résultat.

role

String

Obligatoire pour message. Valeurs valides : system, user et assistant.

content

array

Obligatoire pour message. Chaque élément contient un type et le champ de données associé. system prend en charge input_text avec text ; user prend en charge input_text avec text et input_audio avec audio encodé en Base64 ; assistant prend en charge output_text avec text.

call_id

String

Obligatoire pour function_call et function_call_output. L'identifiant unique qui associe une requête d'appel de fonction à son résultat.

name

String

Obligatoire pour function_call. Le nom de la fonction à appeler.

arguments

String

Obligatoire pour function_call. Arguments de la fonction sous forme de chaîne JSON.

output

String

Obligatoire pour function_call_output. Résultat de l'exécution de l'outil sous forme de chaîne JSON.

Paramètres de context.response :

ParamètreTypeDescription

modalities

array

Modalités de sortie. ["text"] renvoie uniquement du texte. ["audio", "text"] (par défaut) renvoie à la fois de l'audio et du texte.

voice

string

Remplace la voix TTS pour cette inférence.

Exemple :

{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"Hangzhou\",\"condition\":\"sunny\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": ["text", "audio"]
    },
    "type": "response.create"
  }
}

nui_update_audio_data

Lorsque audio_update_manually est défini sur "true", les données d'enregistrement ne sont plus fournies via onNuiNeedAudioData. Utilisez plutôt cette méthode pour les envoyer activement.

Signature de la méthode
-(NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;
Descriptions des paramètres

Paramètre

Type

Description

data

const char *

Les données audio à transmettre.

length

int

La longueur des données audio, en octets.

first_pack

BOOL

Vous n'avez pas besoin d'utiliser ce paramètre.

nui_push_reference_data

Lorsque audio_update_manually est défini sur "true" et que l'annulation d'écho acoustique (AEC) sur l'appareil est activée, utilisez cette méthode pour envoyer l'audio lu par le lecteur en tant que signal de référence.

Signature de la méthode
-(NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;
Descriptions des paramètres

Paramètre

Type

Description

data

const char *

Les données audio à transmettre.

length

int

La longueur des données audio, en octets.

first_pack

BOOL

Vous n'avez pas besoin d'utiliser ce paramètre.

nui_release

Libère toutes les ressources internes du SDK et termine de force toutes les tâches en cours d'exécution. Après avoir appelé cette méthode, l'instance du SDK devient indisponible. Pour la réutiliser, vous devez appeler nui_initialize pour l'initialiser à nouveau.

Signature de la méthode
-(NuiResultCode) nui_release;

nui_get_version

Obtient la version actuelle du SDK. Cette méthode ne renvoie une valeur qu'après l'appel de nui_initialize.

Signature de la méthode
-(const char*) nui_get_version;
Valeur de retour

La version actuelle du SDK.

nui_get_all_response

Obtient les informations complètes pour le rappel d'événement actuel.

Signature de la méthode
-(const char*) nui_get_all_response;
Valeur de retour

Les informations complètes de l'événement sous forme de chaîne JSON.

NeoNuiSdkDelegate : écouteurs de rappel

onNuiEventCallback : écouter les informations d'événement

Signature de la méthode
-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;
Descriptions des paramètres

Paramètre

Type

Description

nuiEvent

NuiCallbackEvent

Événement de rappel.

dialog

long

ID de session. Vous n'avez pas besoin d'utiliser ce paramètre.

wuw

char*

Réveil vocal. Vous n'avez pas besoin d'utiliser ce paramètre.

asr_result

char*

Résultat de la reconnaissance vocale.

finish

BOOL

Indique si le tour de reconnaissance actuel est terminé.

code

int

Valide uniquement lorsque l’événement EVENT_ASR_ERROR se produit.

onNuiAudioStateChanged : écouter l'état audio

Le SDK utilise ce rappel pour vous notifier quand démarrer ou arrêter l'enregistrement.

Signature de la méthode
-(void) onNuiAudioStateChanged:(NuiAudioState)state;
États NuiAudioState

Paramètre

Description

STATE_OPEN

L'interaction a démarré. Vous pouvez ouvrir le périphérique d'enregistrement et commencer l'enregistrement.

STATE_PAUSE

L'interaction s'est arrêtée. Vous pouvez arrêter l'enregistrement.

STATE_CLOSE

L'instance du SDK a été libérée. Vous pouvez fermer complètement le périphérique d'enregistrement.

onNuiNeedAudioData : fournir des données audio

Une fois la conversation démarrée, ce rappel est déclenché en continu. Fournissez les données audio dans ce rappel. Vous n'avez pas besoin d'utiliser ce rappel lorsque audio_update_manually est défini sur "true".

Signature de la méthode
-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;
Descriptions des paramètres

Paramètre

Type

Description

audioData

char *

Les données audio à fournir.

len

int

La taille des données audio fournies, en octets.

onNuiAssistEventCallback : recevoir des données et des informations auxiliaires

Reçoit les événements auxiliaires et les données associées du SDK.

Signature de la méthode
-(void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;
Descriptions des paramètres

Paramètre

Type

Description

nuiEvent

NuiCallbackEvent

L'événement de rappel.

info

char *

Vous n'avez pas besoin d'utiliser ce paramètre.

info_len

int

Vous n'avez pas besoin d'utiliser ce paramètre.

buffer

char *

Données auxiliaires, telles que l'audio TTS renvoyé par le modèle.

len

int

La longueur des données auxiliaires, en octets.

onNuiLogTrackCallback : écouter les journaux de suivi

Ce rappel reçoit les journaux internes détaillés du SDK pour vous aider à localiser et déboguer les problèmes.

-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent : types d'événements

ÉvénementDescription

EVENT_TRANSCRIBER_STARTED

La tâche a démarré avec succès.

EVENT_VAD_START

Déclenché immédiatement après le démarrage de la tâche. Cela ne signifie pas que le début de la parole a été détecté.

EVENT_VAD_END

La fin de la parole a été détectée.

EVENT_ASR_PARTIAL_RESULT

Un résultat intermédiaire de reconnaissance vocale.

EVENT_ASR_ERROR

Une erreur s'est produite pendant la conversation vocale.

EVENT_MIC_ERROR

Déclenché lorsqu'aucune donnée audio n'est reçue pendant deux secondes consécutives.

EVENT_SENTENCE_END

La fin d'une phrase a été détectée et un résultat de reconnaissance complet a été renvoyé.

EVENT_TRANSCRIBER_COMPLETE

La conversation vocale est terminée.

EVENT_AUDIO_TRANSCRIPTION

Événement de transcription textuelle incrémentielle pour la sortie audio. Les segments de transcription sont renvoyés en mode streaming.

EVENT_AUDIO_TRANSCRIPTION_COMPLETED

La transcription de la sortie audio est terminée.

EVENT_OTHER_RESULT

Autres informations d'événement, telles qu'un résultat de Function Calling.

EVENT_ASR_TTS_START

Le modèle a commencé à renvoyer l'audio TTS.

EVENT_ASR_TTS_DATA

Audio TTS renvoyé par le modèle.

EVENT_ASR_TTS_COMPLETE

Le modèle a terminé de renvoyer l'audio TTS.

EVENT_AEC_DATA

Données audio traitées par l'AEC.