Skip to main content

SDK Android Qwen-Audio-Realtime

Utilisez le SDK Android de Qwen-Audio-Realtime pour les conversations vocales en temps réel, avec une entrée audio en temps réel et une sortie vocale ou textuelle.

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. Guide d'utilisation : Pour les présentations des modèles et les conseils de sélection, consultez Conversation vocale en temps réel.

Prérequis

  1. Obtenez et configurez une clé API. Ne codez pas en dur de clé API de longue durée dans votre application mobile. Nous vous recommandons de générer une clé API temporaire sur votre serveur d’application et de la transmettre au client.

Installer le SDK

  • Téléchargez le dernier package du SDK.
  • Extrayez le package ZIP. Obtenez le SDK AAR depuis app/libs et ajoutez-le aux dépendances de votre projet. Pour l'intégration C++ Android, utilisez android_libs et android_include dans le package ZIP pour obtenir les bibliothèques dynamiques et les fichiers d'en-tête.

Démarrage rapide

Ouvrez le projet dans Android Studio. Le code d'exemple se trouve dans DashQwenAudioChatActivity.java. 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 initialize pour définir les paramètres de connexion et de contrôle, et utilisez setParams pour définir les paramètres de conversation vocale.
  3. Appelez startDialog 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 des données d'enregistrement dans onNuiNeedAudioData, ou appelez updateAudio pour pousser 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 stopDialog 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 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 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. L’exemple utilise qwen-audio-3.1-realtime-plus. Pour utiliser un autre modèle, mettez à jour à la fois model dans l’URL et nls_config.model dans Paramètres de conversation vocale.
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}
Paramètres
ParamètreTypeObligatoireDescription
urlStringOuiPoint 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.
apikeyStringOuiClé API.
service_modeStringOuiMode d'exécution. Définissez ce paramètre sur "1" pour une conversation vocale en temps réel.
device_idStringOuiUne 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_manuallyStringNonIndique 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.
workspaceStringNonLe 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_pathStringNonLe chemin de stockage du fichier journal. Ce paramètre prend effet uniquement lorsque save_log est true dans initialize. Dans ce cas, le chemin est requis. Le SDK conserve au maximum deux fichiers journaux localement.
save_wavStringNonIndique 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_sizeintNonTaille 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_levelintNonLe 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 à 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.
aec_paramsobjectNonConfiguration AEC avancée sur l'appareil. Cet objet prend effet uniquement lorsque audio_update_manually est "true".
aec_params.enable_aecbooleanNonIndique s'il faut activer l'AEC sur l'appareil. Si audio_update_manually est "true" et que le SDK prend en charge l'AEC sur l'appareil, l'AEC est activé par défaut.
aec_params.save_audiobooleanNonIndique s'il faut enregistrer l'audio traité par le module AEC sur l'appareil. Si save_wav est "true" et que debug_path est défini, cette fonctionnalité est activée par défaut et l'audio est enregistré sous debug_path.
aec_params.enable_aec_data_callbackbooleanNonIndique s'il faut renvoyer l'audio traité par l'AEC via EVENT_AEC_DATA dans onNuiAssistEventCallback. Valeur par défaut : false.
vad_paramsobjectNonConfiguration VAD avancée sur l'appareil. Cet objet prend effet uniquement lorsque audio_update_manually est "true".
vad_params.enable_vadbooleanNonIndique s'il faut activer le VAD sur l'appareil. Si audio_update_manually est "true" et que le SDK prend en charge le VAD sur l'appareil, le VAD est activé par défaut.
vad_params.save_audiobooleanNonIndique s'il faut enregistrer l'audio traité par le module VAD sur l'appareil. Si save_wav est "true" et que debug_path est défini, cette fonctionnalité est activée par défaut et l'audio est enregistré sous debug_path.

Paramètres de conversation vocale

Transmettez une chaîne JSON dans l'argument params de setParams. 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_typeintOuiType de service vocal. Définissez ce paramètre sur 4 pour une conversation vocale en temps réel.
nls_configobjectOuiConfiguration principale de la conversation vocale, y compris la sélection du modèle et le comportement de la conversation.
nls_config.modelstringOuiNom 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_formatstringOuiFormat audio d'entrée. Seul pcm est pris en charge. Le format par défaut est 16 kHz, 16 bits, PCM mono.
nls_config.modalitiesstringNonUne 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.voicestringNonVoix 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_emotionbooleanNonIndique 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 : true. Valeurs valides : true et false.
nls_config.instructionsstringNonInstructions 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_turnsintNonNombre 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.toolsstringNonUne 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_detectionstringNonUne 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.typestringNonType 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.thresholdfloatNonSensibilité 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_msintNonDuré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_urlsstringNonUne 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.

Référence de l’API

NativeNui

initialize · Initialiser le SDK

Initialise une instance du SDK de conversation vocale. Le SDK est un singleton. Ne l'initialisez pas plus d'une fois avant d'appeler release. Cette méthode est bloquante, appelez-la donc sur un thread non UI. Signature de la méthode
public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
Paramètres

Paramètre

Type

Description

callback

INativeNuiCallback

L'implémentation de l'interface de rappel des événements et des données.

parameters

String

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

level

Constants.LogLevel

Contrôle le niveau d'impression des propres journaux du SDK.

save_log

boolean

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

setParams

Définit les paramètres de conversation vocale au format JSON. Appelez cette méthode avant startDialog. Signature de la méthode
public synchronized int setParams(String params)
Paramètres

Paramètre

Type

Description

params

String

Paramètres de conversation vocale.

startDialog

Démarre la conversation. Signature de la méthode
public synchronized int startDialog(VadMode vad_mode, String dialog_params)
Paramètres
ParamètreTypeDescription
vad_modeVadModeMode VAD. Fixé à VadMode.TYPE_P2T.
dialog_paramsStringSi 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-****"
}

stopDialog

Met fin à la conversation. Après avoir appelé cette méthode, le serveur renvoie le résultat final de la conversation et met fin à la tâche. Signature de la méthode
public synchronized int stopDialog();

cancelDialog

Met fin à la conversation immédiatement. Après avoir appelé cette méthode, la tâche se termine aussitôt sans attendre que le serveur renvoie le résultat final de la conversation. Signature de la méthode
public synchronized int cancelDialog();

updateAction

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
public synchronized int updateAction(String params);
Paramètres
ParamètreTypeDescription
paramsStringUne chaîne JSON utilisée pour mettre à jour le comportement d'exécution, tel que le contexte de conversation.
params.typeStringDéfinir sur "action".
params.commandStringCommande 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.contextStringMise à jour de la requête d'appel de fonction. Utilisé lorsque command est "function_call".
params.context.typeStringType 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.itemobjectObligatoire lorsque params.context.type est conversation.item.create. L'élément de conversation à créer.
params.context.responseobjectFacultatif 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
idStringIdentifiant 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à.
typeStringType 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.
roleStringObligatoire pour message. Valeurs valides : system, user et assistant.
contentarrayObligatoire 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_idStringObligatoire pour function_call et function_call_output. L'identifiant unique qui associe une requête d'appel de fonction à son résultat.
nameStringObligatoire pour function_call. Le nom de la fonction à appeler.
argumentsStringObligatoire pour function_call. Arguments de la fonction sous forme de chaîne JSON.
outputStringObligatoire 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
modalitiesarrayModalités de sortie. ["text"] renvoie uniquement du texte. ["audio", "text"] (par défaut) renvoie à la fois de l'audio et du texte.
voicestringRemplace 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"
  }
}

updateAudio

Lorsque audio_update_manually est défini sur "true", appelez cette méthode pour pousser activement les données d'enregistrement au lieu de fournir les données via onNuiNeedAudioData. Signature de la méthode
public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);
Paramètres

Paramètre

Type

Description

data

byte[]

Les données audio à transmettre.

len

int

Le nombre d'octets de données audio à transmettre.

first_pack

boolean

Ignorer ce paramètre.

updateRefAudio

Lorsque audio_update_manually est défini sur "true" et que l'AEC sur l'appareil est activé, appelez cette méthode pour pousser l'audio lu par le lecteur en tant que signal de référence. Signature de la méthode
public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);
Paramètres

Paramètre

Type

Description

data

byte[]

Les données audio à transmettre.

len

int

Le nombre d'octets de données audio à transmettre.

first_pack

boolean

Ignorer ce paramètre.

release · Libérer les ressources du SDK

Libère toutes les ressources internes du SDK. Après avoir appelé cette méthode, l'instance du SDK devient indisponible. Pour l'utiliser à nouveau, vous devez la réinitialiser en appelant initialize. Signature de la méthode
public synchronized int release();

GetVersion

Obtient les informations de version actuelles du SDK. Signature de la méthode
public synchronized String GetVersion();
Valeur de retour Les informations de version actuelles du SDK.

INativeNuiCallback : rappels de l'écouteur

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

Signature de la méthode
void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);
Paramètres

Paramètre

Type

Description

event

NuiEvent

L'événement de rappel.

resultCode

int

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

arg2

int

Un paramètre réservé.

asrResult

AsrResult

Le résultat de la reconnaissance vocale.

kwsResult

KwsResult

La fonctionnalité de réveil vocal. Vous n'avez pas besoin d'utiliser ce paramètre.

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(AudioState state);
États AudioState

État

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(byte[] buffer, int len);
Paramètres

Paramètre

Type

Description

buffer

byte[]

Les données audio à remplir.

len

int

Le nombre d'octets de données audio à remplir.

Valeur de retour Le nombre d'octets réellement remplis.

onNuiAssistEventCallback : recevoir les événements et données auxiliaires

Ce rappel reçoit les événements auxiliaires et les données associées du SDK. Signature de la méthode
void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);
Paramètres

Paramètre

Type

Description

event

int

Un événement NuiEvent.

info

String

Ignorer ce paramètre.

info_len

int

Ignorer ce paramètre.

data

byte[]

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

onNuiLogTrackCallback : écouter les journaux de trace

Ce rappel reçoit les journaux internes détaillés du SDK pour aider au dépannage et au débogage.
default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

NuiEvent : types d'événements

ÉvénementDescription
EVENT_TRANSCRIBER_STARTEDLa tâche a démarré avec succès.
EVENT_VAD_STARTDé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_ENDLa fin de la parole a été détectée.
EVENT_ASR_PARTIAL_RESULTUn résultat intermédiaire de reconnaissance vocale.
EVENT_ASR_ERRORUne erreur s'est produite pendant la conversation vocale.
EVENT_MIC_ERRORDéclenché lorsqu'aucune donnée audio n'est reçue pendant deux secondes consécutives.
EVENT_SENTENCE_ENDLa fin d'une phrase a été détectée et un résultat de reconnaissance complet a été renvoyé.
EVENT_TRANSCRIBER_COMPLETELa 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_COMPLETEDLa transcription de la sortie audio est terminée.
EVENT_OTHER_RESULTAutres informations d'événement, telles qu'un résultat de Function Calling.
EVENT_ASR_TTS_STARTLe modèle a commencé à renvoyer l'audio TTS.
EVENT_ASR_TTS_DATAAudio TTS renvoyé par le modèle.
EVENT_ASR_TTS_COMPLETELe modèle a terminé de renvoyer l'audio TTS.
EVENT_AEC_DATADonnées audio traitées par l'AEC.