Tous les produits
Search
Centre de documentation

Alibaba Cloud Model Studio:SDK HarmonyOS de reconnaissance vocale non temps réel Qwen-Audio-ASR-Filetrans

Dernière mise à jour :Oct 29, 2026

Ce guide explique comment utiliser le SDK HarmonyOS de reconnaissance vocale non temps réel Qwen-Audio-ASR-Filetrans pour convertir la parole en texte.

Démarrage rapide

  1. Obtenir une clé API : Obtenir une clé API. Pour des raisons de sécurité, nous recommandons de configurer la clé API comme variable d'environnement.
  2. Télécharger le SDK et exécuter l'exemple de code :
    • Télécharger le dernier package SDK.
    • Extrayez le package TAR. Obtenez le SDK au format HAR depuis le répertoire neonui et ajoutez-le aux dépendances de votre projet. Pour l'intégration C++, obtenez les bibliothèques dynamiques et les fichiers d'en-tête depuis native/libs et native/include dans le package TAR.
    • Ouvrez le projet dans DevEco Studio. L'exemple de code se trouve dans DashFunAsrFileTranscriberPage.ets. Remplacez la clé API pour tester la fonctionnalité.

Étapes d'appel

Mode synchrone

  1. Initialiser le SDK.
  2. Configurez les paramètres en fonction de vos besoins métier.
  3. Appelez startFileTranscriber pour démarrer une tâche de reconnaissance avec async_request défini sur false.
  4. Dans l'interface onFileTransEventCallback, écoutez l'événement EVENT_FILE_TRANS_RESULT pour obtenir le résultat final de la reconnaissance.
  5. Appelez release pour libérer les ressources du SDK.

Mode asynchrone

  1. Initialiser le SDK.
  2. Configurez les paramètres en fonction de vos besoins métier.
  3. Appelez startFileTranscriber pour démarrer une tâche de reconnaissance avec async_request défini sur true.
  4. Appelez queryFileTranscriber pour interroger la progression ou le résultat de la reconnaissance.
  5. Dans l'interface onFileTransEventCallback, écoutez l'événement EVENT_FILE_TRANS_QUERY_RESULT pour obtenir le résultat de requête actuel.
  6. Dans l'interface onFileTransEventCallback, écoutez l'événement EVENT_FILE_TRANS_RESULT pour obtenir le résultat final de la reconnaissance.
  7. Appelez release pour libérer les ressources du SDK.

Paramètres de la requête

Paramètres de connexion et de contrôle

Passez une chaîne JSON au paramètre parameters de initializeFileTrans pour configurer les paramètres suivants.

Exemple

La chaîne JSON suivante est un exemple et n'inclut pas tous les paramètres. Ajoutez les paramètres selon vos besoins :

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Descriptions des paramètres

ParamètreTypeObligatoireDescription

url

string

Oui

Le point de terminaison. Celui-ci est fixé à wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription. Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.

apikey

string

Oui

La clé API. Nous recommandons d'utiliser une clé API temporaire plus sécurisée avec une courte période de validité afin de réduire le risque de fuite d'une clé à long terme.

service_mode

string

Oui

Le mode de fonctionnement. Pour la reconnaissance vocale non temps réel, cette valeur est fixée à "1".

device_id

string

Oui

Une chaîne unique identifiant l'utilisateur final. Vous pouvez la définir sur un ID utilisateur in-app ou un identifiant d'appareil unique généré par le client. Cet ID est principalement utilisé pour le suivi des journaux et le dépannage.

debug_path

string

Non

Le chemin de stockage des fichiers journaux. Ce paramètre prend effet uniquement si vous définissez save_log sur true lors de l'appel de initializeFileTrans. Dans ce cas, vous devez spécifier un chemin de fichier journal. Sinon, une erreur se produit. Un maximum de deux fichiers journaux sont conservés localement.

max_log_file_size

number

Non

Définit la taille maximale d'un fichier journal en octets. Ce paramètre prend effet uniquement si vous définissez save_log sur true lors de l'appel de initializeFileTrans. Valeur par défaut : 104857600 (100 * 1024 * 1024 octets, soit 100 Mio).

Paramètres d'effet de reconnaissance vocale

Configurez le paramètre nls_config en utilisant setParams, ou configurez tous les paramètres d'effet de reconnaissance vocale en utilisant startFileTranscriber.

Exemple

La chaîne JSON suivante est un exemple et n'inclut pas tous les paramètres. Ajoutez les paramètres selon vos besoins :

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false,
        "parameters": {
            "speech_noise_threshold": 0.0
        }
    }
}

Descriptions des paramètres

ParamètreTypeObligatoireDescription

file_urls

array[string]

Oui

Une liste d'URL pour les fichiers audio ou vidéo à transcrire. HTTP et HTTPS sont pris en charge. Une seule requête prend en charge uniquement 1 URL. Pour les exigences d'entrée telles que les formats audio pris en charge et les limites de taille et de durée des fichiers, voir Spécifications audio. Si un fichier audio est stocké dans Alibaba Cloud OSS, l'API RESTful prend en charge une URL temporaire avec le préfixe oss://, mais pas le SDK.

Important

  • Une URL temporaire est valide pendant 48 heures et ne peut plus être utilisée après son expiration. N'utilisez pas d'URL temporaires dans des environnements de production.

  • L'interface d'identifiants de téléchargement de fichiers est limitée à 100 QPS et ne peut pas être mise à l'échelle. Ne l'utilisez pas dans des environnements de production, des scénarios à haute concurrence ou des tests de charge.

  • Dans les environnements de production, utilisez un stockage stable tel que Alibaba Cloud OSS pour garantir la disponibilité à long terme des fichiers et éviter la limitation du débit.

- Si une URL publique OSS temporaire n'est pas accessible, définissez l'en-tête de requête X-DashScope-OssResourceResolve sur enable. Cette méthode n'est pas recommandée. Le SDK ne prend pas en charge la configuration des en-têtes de requête.

async_request

boolean

Non

Spécifie s'il faut utiliser une requête asynchrone. Valeur par défaut : false. Valeurs valides : - true : requête asynchrone - false : requête synchrone.

apikey

string

Non

Si apikey dans Paramètres de connexion et de contrôle est une clé API temporaire, mettez-la à jour ici avant qu'elle n'expire.

nls_config

object

Oui

L'objet de configuration principal de la reconnaissance vocale, qui contient les paramètres clés pour la sélection du modèle et le contrôle de l'effet de reconnaissance.

nls_config.model

string

Oui

Le nom du modèle.

nls_config.special_word_filter

object

Non

Spécifie les mots sensibles à traiter lors de la reconnaissance vocale et prend en charge différentes méthodes de traitement pour différents mots. Pour plus d'informations, voir Filtrage des mots sensibles.

nls_config.channel_id

array[integer]

Non

Spécifie les index des pistes audio à reconnaître dans un fichier audio multipiste. Les index commencent à 0. Par exemple, [0] reconnaît la première piste, et [0, 1] reconnaît les première et deuxième pistes. Si omis, la première piste est traitée.

ImportantChaque piste spécifiée est facturée séparément. Par exemple, [0, 1] pour un seul fichier entraîne deux frais distincts.

Valeur par défaut : [0].

nls_config.diarization_enabled

boolean

Non

Spécifie s'il faut activer la diarisation des locuteurs. Cette fonctionnalité est désactivée par défaut. Elle s'applique uniquement à l'audio mono. L'audio multicanal ne prend pas en charge la diarisation des locuteurs. Lorsqu'elle est activée, le résultat de reconnaissance contient speaker_id pour distinguer les locuteurs.

RemarqueSi la diarisation des locuteurs est activée, nous recommandons de limiter la durée audio à 2 heures pour éviter un échec de reconnaissance ou un délai d'expiration.

Valeur par défaut : false. Pour un exemple de speaker_id, voir Descriptions des résultats de reconnaissance.

nls_config.speaker_count

integer

Non

ImportantCe paramètre prend effet uniquement lorsque la diarisation des locuteurs est activée en définissant diarization_enabled sur true.

Il fournit une valeur de référence pour le nombre de locuteurs. Les valeurs valides sont des entiers de 2 à 100. Par défaut, le nombre de locuteurs est déterminé automatiquement. Si ce paramètre est défini, il guide uniquement l'algorithme pour produire le nombre spécifié et ne garantit pas ce nombre. Aucune valeur par défaut.

nls_config.vocabulary_id

string

Non

L'ID de la liste de mots clés précompilés. Créez d'abord une liste de mots clés et transmettez son ID lors de la reconnaissance pour utiliser les mots clés de la liste. Cela convient lorsque le vocabulaire est connu et relativement stable et que le même vocabulaire doit être réutilisé entre les requêtes. Pour plus d'informations, voir Mots clés précompilés.

nls_config.language_hints

array[string]

Non

Spécifie les codes de langue pour l'audio à reconnaître. Si la langue ne peut pas être déterminée à l'avance, omettez ce paramètre et le modèle détecte automatiquement la langue. Vous pouvez définir jusqu’à 4 valeurs. Au-delà, seules les 4 premières sont prises en compte.

Cliquez pour afficher les codes de langue pris en charge

  • zh : Chinois
  • en : Anglais
  • ja : Japonais
  • ko : Coréen
  • vi : Vietnamien
  • th : Thaï
  • id : Indonésien
  • ms : Malais
  • tl : Philippin
  • hi : Hindi
  • ar : Arabe
  • fr : Français
  • de : Allemand
  • es : Espagnol
  • pt : Portugais
  • ru : Russe
  • it : Italien
  • nl : Néerlandais
  • sv : Suédois
  • da : Danois
  • fi : Finnois
  • no : Norvégien
  • el : Grec
  • pl : Polonais
  • cs : Tchèque
  • hu : Hongrois
  • ro : Roumain
  • bg : Bulgare
  • hr : Croate
  • sk : Slovaque

nls_config.parameters

object

Non

Configure des paramètres supplémentaires sous forme d'objet JSON.

Interfaces clés

NativeNui

initializeFileTrans

Initialise une instance SDK de transcription vocale. Ne réinitialisez pas l'instance avant d'avoir appelé release.

RemarqueContrairement à la reconnaissance vocale en temps réel, la transcription de fichiers audio non temps réel doit utiliser initializeFileTrans et passer un rappel INativeFileTransCallback au lieu d'utiliser initialize.

Cette interface bloque le thread appelant. Appelez-la depuis un thread non UI.

Signature de la méthode

public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number

Descriptions des paramètres

ParamètreTypeDescription

callback

INativeFileTransCallback

Une implémentation de l'interface de rappel d'événements et de données de transcription de fichiers.

parameters

string

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

level

number

Contrôle le niveau de journalisation du SDK. Les valeurs valides sont définies par l'énumération Constants.LogLevel.

save_log

boolean

Spécifie s'il faut enregistrer les journaux locaux. Si ce paramètre est true, utilisez debug_path dans Paramètres de connexion et de contrôle pour spécifier un chemin. Vous pouvez également utiliser max_log_file_size pour définir la taille du fichier.

setParams

Définit ou met à jour uniquement le paramètre nls_config. Si tous les paramètres sont fournis dans startFileTranscriber, vous n'avez pas besoin d'appeler cette méthode.

Signature de la méthode

public setParams(params: string): number

Descriptions des paramètres

ParamètreTypeDescription

params

string

Le paramètre nls_config dans Paramètres d'effet de reconnaissance vocale. Les paramètres en dehors de nls_config ne peuvent pas être définis à l'aide de cette méthode. Exemple : { "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }

startFileTranscriber

Démarre la reconnaissance.

Signature de la méthode

public startFileTranscriber(params: string, task_id: ArrayBuffer): number

Descriptions des paramètres

ParamètreTypeDescription

params

string

Les paramètres d'effet de reconnaissance vocale. Exemple : { "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }

task_id

ArrayBuffer

Le tampon d'ID de tâche. Le SDK écrit une chaîne d'ID de tâche aléatoire générée en interne dans ce tampon. Le tampon doit avoir une longueur d'au moins 33 octets. L'exemple utilise new ArrayBuffer(64). Après un appel réussi, décodez le tampon pour obtenir le task_id de la tâche.

queryFileTranscriber

Interroge l'état actuel et le résultat d'une tâche asynchrone. Après un appel réussi, le résultat est retourné par l'événement EVENT_FILE_TRANS_QUERY_RESULT dans le rappel onFileTransEventCallback.

Signature de la méthode

public queryFileTranscriber(task_id: string): number

Descriptions des paramètres

ParamètreTypeDescription

task_id

string

L'ID de la tâche à interroger, obtenu à partir du tampon écrit par startFileTranscriber.

cancelFileTranscriber

Annule immédiatement la tâche en cours.

Signature de la méthode

public cancelFileTranscriber(task_id: string): number

Descriptions des paramètres

ParamètreTypeDescription

task_id

string

L'ID de la tâche à annuler.

release

Libère toutes les ressources internes du SDK. Après l'appel de cette méthode, l'instance SDK devient indisponible. Pour la réutiliser, appelez initializeFileTrans pour la réinitialiser.

Signature de la méthode

public release(): number

GetVersion

Obtient les informations de version actuelles du SDK.

Signature de la méthode

public GetVersion(): string

Valeur de retour

Les informations de version actuelle du SDK.

INativeFileTransCallback

Définit les rappels pour les événements de transcription de fichiers et les résultats de reconnaissance.

onFileTransEventCallback

Écoute les événements de transcription de fichiers et obtient les résultats de reconnaissance vocale.

Signature de la méthode

onFileTransEventCallback: (event: Constants.NuiEvent, resultCode: number, finish: number,
                           asrResult: AsrResult, taskId: string) => void;

Descriptions des paramètres

ParamètreTypeDescription

event

Constants.NuiEvent

L'événement de rappel.

resultCode

number

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

finish

number

Indique si la tâche est terminée.

asrResult

AsrResult

Le résultat de la reconnaissance vocale.

taskId

string

L'ID de la tâche.

Constants.NuiEvent

Les types d'événements du SDK HarmonyOS sont définis par l'énumération Constants.NuiEvent. Les événements suivants s'appliquent à la transcription de fichiers audio :

ÉvénementDescription

EVENT_FILE_TRANS_CONNECTED

Le service est connecté.

EVENT_FILE_TRANS_UPLOADED

Le fichier audio à reconnaître est téléchargé.

EVENT_FILE_TRANS_QUERY_RESULT

Le résultat de la requête de tâche.

EVENT_FILE_TRANS_RESULT

Le résultat final de la reconnaissance.

EVENT_ASR_ERROR

Une erreur s'est produite lors de la reconnaissance vocale.

Types auxiliaires

Constants.LogLevel

Les valeurs d'énumération pour le paramètre level sont les suivantes :

ValeurDescription

LOG_LEVEL_VERBOSE

Les journaux les plus détaillés.

LOG_LEVEL_DEBUG

Journaux de débogage.

LOG_LEVEL_INFO

Journaux d'information (par défaut).

LOG_LEVEL_WARNING

Journaux d'avertissement.

LOG_LEVEL_ERROR

Journaux d'erreurs.

LOG_LEVEL_NONE

Désactive la journalisation.

Télécharger le résultat

Les résultats de la reconnaissance vocale non temps réel sont générés de manière asynchrone. La réponse retournée par l'événement EVENT_FILE_TRANS_RESULT contient transcription_url. Téléchargez le texte de reconnaissance au format JSON depuis cette URL. L'URL a une période de validité. Téléchargez le résultat rapidement.