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

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

ImportantAlibaba Cloud Model Studio a introduit un domaine spécifique à l'espace de travail pour la région Chine (Pékin). Ce domaine offre des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer de dashscope.aliyuncs.com vers {WorkspaceId}.cn-beijing.maas.aliyuncs.com.

Remplacez {WorkspaceId} par votre véritable ID d'espace de travail. Le domaine existant reste disponible.

Guide d'utilisation : Pour les présentations des modèles et les recommandations de sélection, consultez Reconnaissance vocale en temps réel - Fun-ASR et Paraformer.

Expérience en ligne : Seuls paraformer-realtime-v2, paraformer-realtime-8k-v2 prennent en charge l'expérience en ligne.

Démarrage rapide

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

RemarquePour accorder un accès temporaire à des applications tierces ou à des utilisateurs, ou pour contrôler strictement des 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é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 DashParaformerSpeechTranscriberPage.ets. Remplacez la clé API pour tester la fonctionnalité.

Étapes d'appel

Initialiser le SDK.
Configurez les paramètres en fonction de vos besoins métier : Utilisez le paramètre parameters de initialize pour définir les paramètres de connexion et de contrôle, et utilisez setParams pour définir les paramètres d'effet de reconnaissance vocale.
Appelez startDialog pour démarrer la reconnaissance.
Dans le rappel onNuiAudioStateChanged, démarrez le périphérique d'enregistrement en fonction de l'état audio.
Dans le rappel onNuiNeedAudioData, fournir continuellement des données audio enregistrées.
Dans le rappel onNuiEventCallback, écouter les événements et obtenir les résultats de reconnaissance vocale.
Appelez stopDialog pour arrêter la reconnaissance, et écoutez l'événement EVENT_TRANSCRIBER_COMPLETE pour confirmer que la reconnaissance est terminée.
Lorsque la reconnaissance vocale n'est plus nécessaire, appeler release pour libérer les ressources du SDK.

Paramètres de la requête

Paramètres de connexion et de contrôle

Transmettez une chaîne JSON au paramètre parameters de initialize 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-ws/v1/inference",
    "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. Celui-ci est fixé à `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference`. 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 en temps réel, ceci est fixé à `"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 initialize. 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.
`save_wav`	`string`	Non	Spécifie s'il faut enregistrer des fichiers audio pour le débogage. Les fichiers audio sont enregistrés sous `debug_path`. Valeur par défaut : `"false"`. Valeurs valides : - `"true"` : oui - `"false"` : non. Ce paramètre prend effet uniquement si vous définissez `save_log` sur true lors de l'appel de initialize. Vous devez également définir `debug_path`.
`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 initialize. Valeur par défaut : 104857600 (100 * 1024 * 1024 octets, soit 100 Mio).
`log_track_level`	`number`	Non	Contrôle le niveau de filtrage du contenu des journaux envoyé à l'extérieur via le rappel `onNuiLogTrackCallback`. Valeur par défaut : 2. Valeurs valides : - 0 : LOG_LEVEL_VERBOSE - 1 : LOG_LEVEL_DEBUG - 2 : LOG_LEVEL_INFO - 3 : LOG_LEVEL_WARNING - 4 : LOG_LEVEL_ERROR - 5 : LOG_LEVEL_NONE (désactive cette fonctionnalité). Remarque : `log_track_level` et `level`, qui est défini via initialize, déterminent ensemble quels journaux sont envoyés au rappel. Un niveau de journal doit être supérieur ou égal à la fois à `log_track_level` et à `level` pour déclencher le rappel. Par exemple, si `log_track_level` est 2 (INFO) et que `level` est 3 (WARNING), seuls les journaux au niveau WARNING ou supérieur (valeur >=3) déclenchent le rappel.

Paramètres d'effet de reconnaissance vocale

Transmettez une chaîne JSON au paramètre params de setParams 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 :

{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

Descriptions des paramètres

Paramètre de niveau 1	Type	Obligatoire	Description
`service_type`	`int`	Oui	Le type de service vocal. Pour la reconnaissance vocale en temps réel, ceci est fixé à `4`.
`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.sr_format`	`string`	Oui	Le format de l'audio à reconnaître. Formats pris en charge : pcm, wav et opus. Important opus : L'audio source doit être encodé en PCM. Le SDK l'encode en OPUS. wav/pcm : L'audio doit être encodé en PCM.
`nls_config.sample_rate`	`int`	Oui	La fréquence d'échantillonnage de l'audio à reconnaître, en Hz. Elle varie selon le modèle : - paraformer-realtime-v2 prend en charge n'importe quelle fréquence d'échantillonnage. - paraformer-realtime-8k-v2 prend en charge uniquement 8000 Hz.
`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.
`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. Codes de langue pris en charge : - zh : Chinois - en : Anglais - ja : Japonais - yue : Cantonais - ko : Coréen - de : Allemand - fr : Français - ru : Russe. Ce paramètre prend effet uniquement pour les modèles qui prennent en charge plusieurs langues.
`nls_config.semantic_punctuation_enabled`	`boolean`	Non	Spécifie le mode de segmentation des phrases. Valeur par défaut : false. Valeurs valides : - true : Active la segmentation sémantique et désactive la segmentation VAD. - false : Active la segmentation VAD et désactive la segmentation sémantique. La segmentation sémantique est plus précise et convient à la transcription de réunions. La segmentation VAD (détection d'activité vocale) a une latence plus faible et convient à l'interaction en temps réel. Ce paramètre prend effet uniquement pour les modèles v2 et ultérieurs.
`nls_config.max_sentence_silence`	`int`	Non	Le seuil de silence pour la segmentation des phrases par VAD (détection d'activité vocale), en millisecondes. Valeur par défaut : 800. Plage valide : `[200, 6000]`. Lorsque le silence après un segment dépasse ce seuil, le système détermine que la phrase est terminée. Ce paramètre prend effet uniquement lorsque `semantic_punctuation_enabled` est false et que le modèle est v2 ou ultérieur.
`nls_config.multi_threshold_mode_enabled`	`boolean`	Non	Spécifie s'il faut activer le mode de prévention des segments trop longs. Ce mode empêche les segments VAD de devenir trop longs. Valeur par défaut : false (désactivé). Valeurs valides : - true : active le mode - false : désactive le mode. Ce paramètre prend effet uniquement lorsque `semantic_punctuation_enabled` est false et que le modèle est v2 ou ultérieur.
`nls_config.punctuation_prediction_enabled`	`boolean`	Non	Spécifie s'il faut ajouter automatiquement la ponctuation aux résultats de reconnaissance. Valeur par défaut : true. Valeurs valides : - true : oui - false : non. Ce paramètre prend effet uniquement pour les modèles v2 et ultérieurs.
`nls_config.heartbeat`	`boolean`	Non	Spécifie s'il faut maintenir une connexion persistante au serveur. Valeur par défaut : false. Valeurs valides : - true : La connexion reste active tant que de l'audio silencieux est envoyé en continu. - false : Même si de l'audio silencieux est envoyé en continu, la connexion expire après un certain temps. Le délai d'expiration est une valeur par défaut côté serveur et ne peut pas être configuré sur le client. Ce paramètre prend effet uniquement pour les modèles v2 et ultérieurs.
`nls_config.inverse_text_normalization_enabled`	`boolean`	Non	Spécifie s'il faut activer la normalisation inverse du texte (ITN). Lorsqu'elle est activée, les chiffres chinois sont convertis en chiffres arabes. Valeur par défaut : true (activée). Valeurs valides : - true : activée - false : désactivée. Ce paramètre prend effet uniquement pour les modèles v2 et ultérieurs.
`nls_config.vocabulary_id`	`string`	Non	L'ID du vocabulaire de mots clés, qui améliore la précision de reconnaissance de mots spécifiques. Ce paramètre s'applique aux modèles v2 et ultérieurs. Pour plus d'informations, consultez Mots clés personnalisés.

Interfaces clés

NativeNui

initialize

Initialise une instance du SDK de reconnaissance vocale. N'initialisez pas l'instance à nouveau avant d'avoir appelé release.

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

Signature de la méthode

public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number

Descriptions des paramètres

Paramètre	Type	Description
`callback`	`INativeNuiCallback`	Une implémentation de l'interface de rappel d'événements et de données.
`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.

Valeur de retour

setParams

Définit les paramètres d'effet de reconnaissance vocale au format JSON. Appelez cette interface avant startDialog.

Signature de la méthode

public setParams(params: string): number

Descriptions des paramètres

Paramètre	Type	Description
`params`	`string`	Les paramètres d'effet de reconnaissance vocale.

Valeur de retour

startDialog

Démarre la reconnaissance.

Signature de la méthode

public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number

Descriptions des paramètres

Paramètre	Type	Description
`vad_mode`	`Constants.VadMode`	Le mode VAD. Ceci est fixé à `Constants.VadMode.TYPE_P2T`.
`dialog_params`	`string`	Si la clé API temporaire spécifiée par `apikey` dans Paramètres de connexion et de contrôle a expiré, mettez-la à jour ici. La valeur est au format JSON : `typescript { "apikey": "st-****" }`

Valeur de retour

stopDialog

Arrête la reconnaissance. Après l'appel de cette interface, le serveur renvoie le résultat final de la reconnaissance et termine la tâche.

Signature de la méthode

public stopDialog(): number

Valeur de retour

cancelDialog

Arrête immédiatement la reconnaissance sans attendre que le serveur retourne le résultat final de reconnaissance.

Signature de la méthode

public cancelDialog(): number

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 initialize afin de 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 actuelle du SDK.

INativeNuiCallback

Écoute les événements, les états audio, les changements de volume et les journaux pendant la reconnaissance vocale en temps réel.

onNuiEventCallback

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

Signature de la méthode

onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => 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.
`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.
`arg2`	`number`	Un paramètre réservé.

onNuiAudioStateChanged

Le SDK utilise ce rappel pour indiquer quand l'enregistrement doit commencer ou s'arrêter.

Signature de la méthode

onNuiAudioStateChanged: (state: Constants.AudioState) => void

Descriptions AudioState

État	Description
`STATE_OPEN`	L'interaction commence. Vous pouvez démarrer le périphérique d'enregistrement.
`STATE_PAUSE`	L'interaction est en pause. Vous pouvez mettre l'enregistrement en pause.
`STATE_CLOSE`	L'interaction s'arrête. Vous pouvez arrêter complètement le périphérique d'enregistrement.

onNuiAudioRMSChanged

Surveille le volume des données audio enregistrées pour l'affichage de l'interface utilisateur.

Signature de la méthode

onNuiAudioRMSChanged: (val: number) => number

Descriptions des paramètres

Paramètre	Type	Description
`val`	`number`	Le volume des données audio enregistrées. La plage de sortie est généralement `[-160, 0]`.

onNuiNeedAudioData

Une fois la reconnaissance démarrée, ce rappel est déclenché en continu. Fournissez les données audio à reconnaître dans le rappel.

Signature de la méthode

onNuiNeedAudioData: (buffer: ArrayBuffer) => number

Descriptions des paramètres

Paramètre	Type	Description
`buffer`	`ArrayBuffer`	Les données audio à fournir. Le SDK utilise `buffer.byteLength` comme nombre d'octets demandé.

Valeur de retour

Le nombre réel d'octets fournis. Une valeur de retour de <=0 indique une erreur ou une absence de données.

onNuiLogTrackCallback

Ce callback reçoit les journaux internes détaillés du SDK pour le dépannage et le débogage.

onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

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 reconnaissance vocale en temps réel :

Événement	Description
`EVENT_TRANSCRIBER_STARTED`	La tâche démarre avec succès.
`EVENT_VAD_START`	Cet événement est déclenché immédiatement après le démarrage de la tâche. Il n'indique pas que le début de la parole a été détecté.
`EVENT_VAD_END`	La fin de la parole est détectée.
`EVENT_ASR_PARTIAL_RESULT`	Un résultat intermédiaire de reconnaissance vocale.
`EVENT_ASR_RESULT`	Un résultat de reconnaissance vocale complet.
`EVENT_ASR_ERROR`	Une erreur s'est produite lors de la reconnaissance vocale.
`EVENT_MIC_ERROR`	Cet événement est déclenché lorsqu'aucune donnée audio n'est reçue pendant 2 secondes consécutives.
`EVENT_SENTENCE_START`	Le début d'une phrase est détecté.
`EVENT_SENTENCE_END`	La fin d'une phrase est détectée et un résultat de reconnaissance complet est retourné.
`EVENT_TRANSCRIBER_COMPLETE`	La reconnaissance vocale se termine.

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'erreurs.
`LOG_LEVEL_NONE`	Désactive la journalisation.

Gestion des périphériques audio

Contrairement à Android, qui utilise AudioRecord, HarmonyOS utilise AudioCapturer de @kit.AudioKit pour capturer l'audio. L'exemple de produit encapsule cette logique dans la classe utilitaire AudioRecorder.ets, que vous pouvez réutiliser directement.

Création : audio.createAudioCapturer(capturerOptions) crée de manière asynchrone le capteur avec une fréquence d'échantillonnage fixe de 16 kHz, une profondeur de 16 bits et un canal (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW).
Événement de données : capturer.on('readData', (buffer: ArrayBuffer) => void) obtient en continu les données audio enregistrées. Mettez les données en mémoire tampon dans une file d'attente afin que le rappel onNuiNeedAudioData puisse les récupérer selon les besoins.
Événement d'état : capturer.on('stateChange', (state: audio.AudioState) => void). STATE_RUNNING indique que l'enregistrement a commencé, et STATE_STOPPED indique que l'enregistrement s'est arrêté.
Contrôle : start() démarre, stop() arrête et release() libère le capteur.

RemarqueHarmonyOS crée AudioCapturer de manière asynchrone. Appelez start() uniquement après la fin de la création. Par conséquent, ne créez pas et ne démarrez pas immédiatement un enregistreur lorsque STATE_OPEN se produit. Créez-le d'abord, puis appelez start() dans le rappel STATE_OPEN. L'exemple crée l'enregistreur pendant doInit et le démarre pendant onNuiAudioStateChanged. Lorsque STATE_CLOSE se produit, arrêtez l'enregistreur mais conservez l'instance pour la réutiliser. Libérez-la dans release.

Déclaration d'autorisation

Déclarer l'autorisation du microphone dans module.json5 pour utiliser l'enregistrement :

{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}