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
-
Obtenir une clé API : Obtenir et configurer une clé API.
-
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.xcframeworksur 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
- Initialiser le SDK.
- Définissez les paramètres pour votre cas d'utilisation. Utilisez l'argument
parametersde 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. - Appelez nui_dialog_start pour démarrer la conversation.
- Dans onNuiAudioStateChanged, démarrez le périphérique d'enregistrement en fonction de l'état audio.
- Fournissez en continu les données d'enregistrement dans onNuiNeedAudioData, ou appelez nui_update_audio_data pour envoyer activement les données d'enregistrement.
- Recevez en continu l'audio renvoyé par le modèle dans onNuiAssistEventCallback.
- Écoutez les événements et obtenez les informations d'événement dans onNuiEventCallback.
- Appelez nui_dialog_cancel pour arrêter la conversation, et écoutez
EVENT_TRANSCRIBER_COMPLETEpour confirmer qu'elle est terminée. - 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ètre | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Point de terminaison du service :
{WorkspaceId} par votre véritable ID d'espace de travail. |
|
| Oui | Clé API. |
|
| Oui | Mode d'exécution. Définissez ce paramètre sur |
|
| 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. |
|
| Non | Indique s'il faut pousser activement les données audio. Valeur par défaut : |
|
| Non | Le chemin de stockage des fichiers de ressources sur l'appareil. Ce paramètre est requis lorsque |
|
| Non | Le chemin de stockage du fichier journal. Ce paramètre prend effet uniquement lorsque |
|
| Non | Indique s'il faut enregistrer l'audio de débogage sous |
|
| Non | Taille maximale du fichier journal en octets. Ce paramètre prend effet uniquement lorsque |
|
| Non | Le niveau de filtrage pour les journaux envoyés via |
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érieur | Type | Obligatoire | Description |
|---|---|---|---|
|
| Oui | Type de service vocal. Définissez ce paramètre sur |
|
| Oui | Configuration principale de la conversation vocale, y compris la sélection du modèle et le comportement de la conversation. |
|
| Oui | Nom du modèle. Prend en charge les séries de modèles |
|
| Oui | Format audio d'entrée. Seul |
|
| Non | Une chaîne contenant un tableau de modalités de sortie. Valeurs valides :
|
|
| Non | Voix TTS. La valeur par défaut est 3.1 Plus prend également en charge |
|
| 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 : |
|
| 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. |
|
| Non | Nombre maximal de tours de questions-réponses historiques autorisés dans une requête. Valeurs valides : 1 à 50. Valeur par défaut : |
|
| 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 |
|
| 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é. |
|
| Non | Type de VAD. |
|
| Non | Sensibilité du VAD. Ce paramètre s'applique uniquement à |
|
| 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 à |
|
| 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 à |
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 |
|---|---|---|
|
| 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. |
|
| Niveau d'impression pour les propres journaux du SDK. |
| BOOL | Indique s'il faut enregistrer les journaux localement. Si défini sur |
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 |
|---|---|---|
|
|
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ètre | Type | Description |
|---|---|---|
|
| Mode VAD. Fixé à |
|
| Si |
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 |
|---|---|---|
|
| Indique s'il faut forcer la fin et ignorer le résultat final.
|
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ètre | Type | Description |
|---|---|---|
|
| Une chaîne JSON utilisée pour mettre à jour le comportement d'exécution, tel que le contexte de conversation. |
|
| Définir sur |
|
| Commande d'exécution. Valeurs valides :
|
|
| Mise à jour de la requête d'appel de fonction. Utilisé lorsque |
|
| Type d'événement. Ce paramètre est requis lorsque |
|
| Obligatoire lorsque |
|
| Facultatif lorsque |
Paramètres de context.item :
| Paramètre | Type | Description |
|---|---|---|
|
| 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 d'élément requis. Valeurs valides :
|
|
| Obligatoire pour |
|
| Obligatoire pour |
|
| Obligatoire pour |
|
| Obligatoire pour |
|
| Obligatoire pour |
|
| Obligatoire pour |
Paramètres de context.response :
| Paramètre | Type | Description |
|---|---|---|
|
| Modalités de sortie. |
|
| 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.
-(NuiResultCode) nui_update_audio_data:(const char *)data
Len:(int)length
FirstPack:(BOOL)first_pack;
Descriptions des paramètres
Paramètre | Type | Description |
|---|---|---|
|
| Les données audio à transmettre. |
|
| La longueur des données audio, en octets. |
|
| 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.
-(NuiResultCode) nui_push_reference_data:(const char *)data
Len:(int)length
FirstPack:(BOOL)first_pack;
Descriptions des paramètres
Paramètre | Type | Description |
|---|---|---|
|
| Les données audio à transmettre. |
|
| La longueur des données audio, en octets. |
|
| 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.
-(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 |
|---|---|---|
| Événement de rappel. | |
|
| ID de session. Vous n'avez pas besoin d'utiliser ce paramètre. |
|
| Réveil vocal. Vous n'avez pas besoin d'utiliser ce paramètre. |
|
| Résultat de la reconnaissance vocale. |
|
| Indique si le tour de reconnaissance actuel est terminé. |
|
| Valide uniquement lorsque l’événement |
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 |
|---|---|
| L'interaction a démarré. Vous pouvez ouvrir le périphérique d'enregistrement et commencer l'enregistrement. |
| L'interaction s'est arrêtée. Vous pouvez arrêter l'enregistrement. |
| 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".
-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;
Descriptions des paramètres
Paramètre | Type | Description |
|---|---|---|
|
| Les données audio à fournir. |
|
| 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 |
|---|---|---|
|
| L'événement de rappel. |
|
| Vous n'avez pas besoin d'utiliser ce paramètre. |
|
| Vous n'avez pas besoin d'utiliser ce paramètre. |
|
| Données auxiliaires, telles que l'audio TTS renvoyé par le modèle. |
|
| 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énement | Description |
|---|---|
| La tâche a démarré avec succès. |
| 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é. |
| La fin de la parole a été détectée. |
| Un résultat intermédiaire de reconnaissance vocale. |
| Une erreur s'est produite pendant la conversation vocale. |
| Déclenché lorsqu'aucune donnée audio n'est reçue pendant deux secondes consécutives. |
| La fin d'une phrase a été détectée et un résultat de reconnaissance complet a été renvoyé. |
| La conversation vocale est terminée. |
| Événement de transcription textuelle incrémentielle pour la sortie audio. Les segments de transcription sont renvoyés en mode streaming. |
| La transcription de la sortie audio est terminée. |
| Autres informations d'événement, telles qu'un résultat de Function Calling. |
| Le modèle a commencé à renvoyer l'audio TTS. |
| Audio TTS renvoyé par le modèle. |
| Le modèle a terminé de renvoyer l'audio TTS. |
| Données audio traitées par l'AEC. |