Paraformer reconnaissance vocale non en temps réel HarmonyOS SDK_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

Ce guide explique comment utiliser le SDK HarmonyOS de reconnaissance vocale non en temps réel Paraformer pour convertir la parole en texte.

Guide d'utilisation : Reconnaissance vocale non temps réel

Démarrage rapide

Obtenir une clé API : Obtenir et configurer une clé API. Pour des raisons de sécurité, nous recommandons de configurer la clé API en tant que variable d'environnement.

RemarquePour accorder un accès temporaire à des applications ou des utilisateurs tiers, ou pour contrôler strictement les opérations à haut risque telles que l'accès ou la suppression de données sensibles, utilisez une clé API temporaire. Une clé API temporaire est valide pendant 60 secondes par défaut. Obtenez-en une nouvelle après son expiration.
Téléchargez le SDK et exécutez l'exemple de code :
- Téléchargez le dernier package du 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. Le code d'exemple se trouve dans DashParaformerFileTranscriberPage.ets. Remplacez la clé API pour tester la fonctionnalité.

Étapes d'appel

Mode synchrone

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

Mode asynchrone

Initialiser le SDK.
Configurez les paramètres en fonction de vos besoins métier.
Appelez startFileTranscriber pour démarrer une tâche de reconnaissance avec async_request défini sur true.
Appelez queryFileTranscriber pour interroger la progression ou le résultat de la reconnaissance.
Dans l'interface onFileTransEventCallback, écoutez l'événement EVENT_FILE_TRANS_QUERY_RESULT pour obtenir le résultat de la requête en cours.
Dans l'interface onFileTransEventCallback, écoutez l'événement EVENT_FILE_TRANS_RESULT pour obtenir le résultat final de la reconnaissance.
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 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 des 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ètre	Type	Obligatoire	Description
`url`	`string`	Oui	Le point de terminaison. Ceci 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é pour 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, ceci est fixé à `"1"`.
`device_id`	`string`	Oui	Une chaîne unique qui identifie l'utilisateur final. Vous pouvez la définir sur un ID d'utilisateur dans l'application 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 lorsque vous appelez 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 des paramètres selon vos besoins :

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"paraformer-v2",
        "disfluency_removal_enabled":false,
        "timestamp_alignment_enabled": false
    }
}

Descriptions des paramètres

Paramètre	Type	Obligatoire	Description
`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. Si un fichier audio est stocké dans Alibaba Cloud OSS, le SDK ne prend pas en charge une URL temporaire qui utilise le préfixe `oss://`. - Formats audio : `aac`, `amr`, `avi`, `flac`, `flv`, `m4a`, `mkv`, `mov`, `mp3`, `mp4`, `mpeg`, `ogg`, `opus`, `wav`, `webm`, `wma` et `wmv`. ImportantÉtant donné que les formats audio et vidéo comportent de nombreuses variantes, il est techniquement impossible de tous les tester. L'API ne peut pas garantir que chaque format sera correctement reconnu. Testez votre fichier pour vérifier qu'il produit un résultat de reconnaissance valide. - Les taux d'échantillonnage audio varient selon le modèle : - paraformer-v2 prend en charge n'importe quel taux d'échantillonnage. - paraformer-8k-v2 prend en charge uniquement 8 kHz. - Taille et durée du fichier audio : Le fichier ne peut pas dépasser 2 Go, et sa durée ne peut pas dépasser 12 heures. Pour traiter un fichier qui dépasse ces limites, prétraitez-le pour réduire sa taille. Pour les bonnes pratiques, consultez Prétraiter les fichiers vidéo pour améliorer l'efficacité de la transcription pour la reconnaissance de fichiers audio.
`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 les Paramètres de connexion et de contrôle est une clé API temporaire, mettez-la à jour ici avant son expiration.
`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 modèle de reconnaissance vocale.
`nls_config.language_hints`	`array[string]`	Non	Spécifie les codes de langue pour l'audio à reconnaître. Ce paramètre s'applique uniquement à paraformer-v2. Valeur par défaut : `["zh", "en"]`. Codes de langue pris en charge : - zh : chinois - en : anglais - ja : japonais - yue : cantonais - ko : coréen - de : allemand - fr : français - ru : russe.
`nls_config.disfluency_removal_enabled`	`boolean`	Non	Spécifie s'il faut supprimer les disfluences telles que les mots de remplissage. Valeur par défaut : false. Valeurs valides : - true : supprime les disfluences - false : conserve les disfluences.
`nls_config.timestamp_alignment_enabled`	`boolean`	Non	Spécifie s'il faut activer l'alignement des horodatages. Valeur par défaut : false. Valeurs valides : - true : activé - false : désactivé.
`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. Si ce paramètre est omis, la logique de filtrage des mots sensibles intégrée est activée. Les mots qui correspondent à la liste des mots sensibles d'Alibaba Cloud Model Studio sont remplacés par le même nombre de caractères ``. Si ce paramètre est spécifié, les mots correspondants peuvent être remplacés par des caractères `` ou supprimés. La valeur est un objet JSON au format suivant : `{ "filter_with_signed": { "word_list": ["测试"] }, "filter_with_empty": { "word_list": ["开始", "发生"] }, "system_reserved_filter": true }`. Descriptions des champs JSON : - `filter_with_signed` : Un objet facultatif qui spécifie les mots à remplacer par le même nombre de caractères ``. Dans l'exemple précédent, le résultat pour « 帮我测试一下这段代码 » est « 帮我``一下这段代码 ». Son champ `word_list` est un tableau de chaînes à remplacer. - `filter_with_empty` : Un objet facultatif qui spécifie les mots à supprimer du résultat. Dans l'exemple précédent, le résultat pour « 比赛这就要开始了吗？ » est « 比赛这就要了吗 ». Son champ `word_list` est un tableau de chaînes à supprimer. - `system_reserved_filter` : Un booléen facultatif. Valeur par défaut : true. Spécifie s'il faut activer les règles de mots sensibles intégrées. Si défini sur `true`, les mots correspondant à la liste des mots sensibles d'Alibaba Cloud Model Studio sont remplacés par le même nombre de caractères ``.
`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 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 du locuteur. 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 du locuteur. Lorsqu'elle est activée, le résultat de la reconnaissance contient `speaker_id` pour distinguer les locuteurs. RemarqueSi la diarisation du locuteur est activée, nous recommandons de limiter la durée de l'audio à 2 heures pour éviter un échec de reconnaissance ou un délai d'attente. Pour un exemple de `speaker_id`, consultez les Descriptions des résultats de reconnaissance.
`nls_config.speaker_count`	`integer`	Non	Une valeur de référence pour le nombre de locuteurs. Pour utiliser cette fonctionnalité, définissez `diarization_enabled` sur `true`. 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. Plage valide : `[2, 100]`. Le minimum est 2 car cette fonctionnalité distingue plusieurs locuteurs.
`nls_config.vocabulary_id`	`string`	Non	L'ID de vocabulaire des mots-clés, qui améliore la précision de la reconnaissance de mots spécifiques. Ce paramètre s'applique aux modèles v2 et ultérieurs. Pour plus d'informations, consultez les Mots-clés personnalisés.

Interfaces clés

NativeNui

initializeFileTrans

Initialise une instance du SDK de transcription vocale. N'initialisez pas l'instance à nouveau avant d'appeler release.

RemarqueContrairement à la reconnaissance vocale en temps réel, la transcription de fichiers audio non temps réel doit utiliser initializeFileTrans et transmettre 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ètre	Type	Description
`callback`	`INativeFileTransCallback`	Une implémentation de l'interface de rappel des événements et des données de transcription de fichiers.
`parameters`	`string`	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`	`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 les 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.

Valeur de retour

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ètre	Type	Description
`params`	`string`	Le paramètre `nls_config` dans les 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":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } }`

Valeur de retour

startFileTranscriber

Démarre la reconnaissance.

Signature de la méthode

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

Descriptions des paramètres

Paramètre	Type	Description
`params`	`string`	Les paramètres d'effet de reconnaissance vocale. Exemple : `{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"paraformer-v2", "disfluency_removal_enabled":false, "timestamp_alignment_enabled": false } }`
`task_id`	`ArrayBuffer`	Le tampon de l'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 mesurer au moins 33 octets. L'exemple utilise `new ArrayBuffer(64)`. Après un appel réussi, décodez le tampon pour obtenir l'`task_id` de la tâche.

Valeur de retour

queryFileTranscriber

Interroge l'état actuel et le résultat d'une tâche asynchrone. Après un appel réussi, le résultat est renvoyé 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ètre	Type	Description
`task_id`	`string`	L'ID de la tâche à interroger, obtenu à partir du tampon écrit par `startFileTranscriber`.

Valeur de retour

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ètre	Type	Description
`task_id`	`string`	L'ID de la tâche à annuler.

Valeur de retour

release

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

Signature de la méthode

public release(): number

Valeur de retour

GetVersion

Obtient les informations de version actuelles du SDK.

Signature de la méthode

public GetVersion(): string

Valeur de retour

Les informations de version actuelles 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ètre	Type	Description
`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énement	Description
`EVENT_FILE_TRANS_CONNECTED`	Le service est connecté.
`EVENT_FILE_TRANS_UPLOADED`	Le fichier audio à reconnaître est téléversé.
`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 se produit lors de la reconnaissance vocale.

Types auxiliaires

Constants.LogLevel

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

Valeur	Description
`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'erreur.
`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 renvoyé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.