Utilisez le SDK Android 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 textuelle.
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
-
Téléchargez le SDK et exécutez l'exemple de code :
- Téléchargez le dernier package du SDK.
- Extrayez le package ZIP. Obtenez le SDK AAR depuis
app/libset ajoutez-le aux dépendances de votre projet. Pour l'intégration C++ Android, utilisezandroid_libsetandroid_includedans le package ZIP pour obtenir les bibliothèques dynamiques et les fichiers d'en-tête. - 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
- Initialiser le SDK.
- Définissez les paramètres pour votre cas d'utilisation. Utilisez l'argument
parametersde 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. - Appelez startDialog pour démarrer la conversation.
- Dans onNuiAudioStateChanged, démarrez le périphérique d'enregistrement en fonction de l'état audio.
- Fournissez en continu des données d'enregistrement dans onNuiNeedAudioData, ou appelez updateAudio pour pousser 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 stopDialog 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 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.
{
"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 |
|
| Non | Configuration AEC avancée sur l'appareil. Cet objet prend effet uniquement lorsque |
|
| Non | Indique s'il faut activer l'AEC sur l'appareil. Si |
|
| Non | Indique s'il faut enregistrer l'audio traité par le module AEC sur l'appareil. Si |
|
| Non | Indique s'il faut renvoyer l'audio traité par l'AEC via |
|
| Non | Configuration VAD avancée sur l'appareil. Cet objet prend effet uniquement lorsque |
|
| Non | Indique s'il faut activer le VAD sur l'appareil. Si |
|
| Non | Indique s'il faut enregistrer l'audio traité par le module VAD sur l'appareil. Si |
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é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
NativeNui
initialize
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éthodepublic synchronized int initialize(final INativeNuiCallback callback,
String parameters,
final Constants.LogLevel level,
final boolean save_log)
Paramètres
Paramètre | Type | Description |
|---|---|---|
| L'implémentation de l'interface de rappel des événements et des données. | |
|
| 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. |
|
| Contrôle le niveau d'impression des propres journaux du SDK. |
|
| Indique s'il faut enregistrer les journaux locaux. Si défini sur |
setParams
Définit les paramètres de conversation vocale au format JSON. Appelez cette méthode avant startDialog.
Signature de la méthodepublic synchronized int setParams(String params)
Paramètres
Paramètre | Type | Description |
|---|---|---|
|
|
startDialog
Démarre la conversation.
Signature de la méthodepublic synchronized int startDialog(VadMode vad_mode, String dialog_params)
Paramètres
| Paramètre | Type | Description |
|---|---|---|
|
| Mode VAD. Fixé à |
|
| Si |
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éthodepublic 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éthodepublic 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éthodepublic synchronized int updateAction(String 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"
}
}
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.
public synchronized int updateAudio(byte[] data, int len,
boolean first_pack);
Paramètres
Paramètre | Type | Description |
|---|---|---|
|
| Les données audio à transmettre. |
|
| Le nombre d'octets de données audio à transmettre. |
|
| 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.
public synchronized int updateRefAudio(byte[] data, int len,
boolean first_pack);
Paramètres
Paramètre | Type | Description |
|---|---|---|
|
| Les données audio à transmettre. |
|
| Le nombre d'octets de données audio à transmettre. |
|
| Ignorer ce paramètre. |
release
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éthodepublic synchronized int release();
GetVersion
Obtient les informations de version actuelles du SDK.
Signature de la méthodepublic 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éthodevoid onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);
Paramètres
Paramètre | Type | Description |
|---|---|---|
| L'événement de rappel. | |
|
| Valide uniquement lorsque l’événement |
|
| Un paramètre réservé. |
|
| Le résultat de la reconnaissance vocale. |
|
| 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éthodevoid onNuiAudioStateChanged(AudioState state);
États AudioState
État | 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(byte[] buffer, int len);
Paramètres
Paramètre | Type | Description |
|---|---|---|
|
| Les données audio à remplir. |
|
| Le nombre d'octets de données audio à remplir. |
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éthodevoid onNuiAssistEventCallback_(int event, byte[] info, int info_len,
byte[] data);
Paramètres
Paramètre | Type | Description |
|---|---|---|
|
| Un événement |
|
| Ignorer ce paramètre. |
|
| Ignorer ce paramètre. |
|
| 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é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. |