Paramètres et interfaces du SDK Python de reconnaissance vocale en temps réel Paraformer.
Consultez la documentation Paraformer Python SDK actuelle.
Guide d'utilisation : Pour une présentation des modèles et des recommandations de sélection, consultez Reconnaissance vocale en temps réel - Fun-ASR/Paraformer.
La ressource principale (
Cette méthode soumet une tâche de transcription vocale en temps réel pour un fichier local. Le processus est bloquant jusqu'à ce que le résultat complet de la transcription soit retourné.
Appelez la méthode
Cette méthode soumet une tâche de transcription vocale en temps réel et retourne les résultats de reconnaissance en temps réel via l'itération d'événements.
En Python, en raison du Global Interpreter Lock (GIL), un seul thread peut exécuter du code Python à la fois (bien que certaines bibliothèques orientées performances puissent lever cette limitation). Pour mieux exploiter les ressources de calcul d'un ordinateur multicœur, nous vous recommandons d'utiliser multiprocessing ou concurrent.futures.ProcessPoolExecutor. Le multithreading peut augmenter considérablement la latence des appels SDK sous une forte concurrence.
Les paramètres de requête se définissent via les méthodes
La reconnaissance vocale en temps réel est montée sur la ressource
Lors d'un appel streaming bidirectionnel, le serveur renvoie les informations clés du processus et les données au client via des événements. Dans un thread récepteur, itérez sur les
Les membres de la classe Sentence sont les suivants :
Les membres de la classe Word sont les suivants :
Si vous rencontrez des erreurs, consultez Codes d'erreur pour le dépannage.
Si le problème persiste, rejoignez la communauté des développeurs pour signaler votre problème et fournir l'ID de requête pour une investigation plus approfondie.
Pour plus d'exemples, voir GitHub.
Définissez le paramètre de requête
Vous pouvez utiliser l'outil FFmpeg. Pour plus d'informations sur son utilisation, reportez-vous au site officiel de FFmpeg.
Oui. Les résultats de la reconnaissance vocale incluent les horodatages de début et de fin pour chaque phrase, ce qui permet de déterminer la plage temporelle de chacune.
Il existe deux façons de reconnaître un fichier local :
Prérequis
Lorsque vous devez accorder un accès temporaire à des applications ou utilisateurs tiers, ou lorsque vous souhaitez contrôler strictement des opérations sensibles telles que l'accès ou la suppression de données confidentielles, nous vous recommandons d'utiliser des jetons d'authentification temporaires.Contrairement aux clés API permanentes, les jetons d'authentification temporaires ont une durée de validité courte (60 secondes) et offrent une sécurité renforcée. Ils conviennent aux scénarios d'appels temporaires et réduisent efficacement le risque de fuite de clé API.Utilisation : Dans votre code, remplacez la clé API initialement utilisée pour l'authentification par le jeton d'authentification temporaire obtenu.
Liste des modèles
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| Scénarios | Diffusion en direct, réunions et scénarios similaires | Reconnaissance audio 8 kHz dans des scénarios tels que le service client téléphonique et la messagerie vocale |
| Taux d'échantillonnage | Quelconque | 8kHz |
| Langue | Chinois (y compris le mandarin et divers dialectes), anglais, japonais, coréen, allemand, français, russeDialectes chinois pris en charge : shanghaïen, wu, minnan, nord-est, gansu, guizhou, henan, hubei, hunan, jiangxi, ningxia, shanxi, shaanxi, shandong, sichuan, tianjin, yunnan, cantonais | Chinois |
| Prédiction de la ponctuation | Pris en charge par défaut. Aucune configuration requise. | Pris en charge par défaut. Aucune configuration requise. |
| Normalisation inverse du texte (ITN) | Pris en charge par défaut. Aucune configuration requise. | Pris en charge par défaut. Aucune configuration requise. |
| Vocabulaire personnalisé | Voir Personnaliser les mots-clés | Voir Personnaliser les mots-clés |
| Spécifier la langue de reconnaissance | Spécifiez la langue à l'aide du paramètre language_hints. | Non pris en charge |
| Reconnaissance des émotions | Non pris en charge |
Cliquez pour voir l'utilisation La reconnaissance des émotions est soumise aux contraintes suivantes :
emo_tag et emo_confidence des informations de phrase unique (Sentence). |
Premiers pas
La ressource principale (client.audio.asr) fournit des méthodes pour les appels non streaming et streaming bidirectionnel. Choisissez la méthode appropriée selon vos besoins :
- Appel non streaming (
recognize_file) : Reconnaît un fichier local. Le SDK envoie automatiquement l'audio par segments et conduit la tâche jusqu'à son terme. Cette méthode convient au traitement d'audio préenregistré. - Appel streaming bidirectionnel : Reconnaît un flux audio et produit les résultats en temps réel. Le flux audio peut provenir d'un périphérique externe, tel qu'un microphone, ou être lu depuis un fichier local. Cette approche est idéale pour les scénarios nécessitant un retour immédiat.
Appel non streaming
Cette méthode soumet une tâche de transcription vocale en temps réel pour un fichier local. Le processus est bloquant jusqu'à ce que le résultat complet de la transcription soit retourné.
recognize_file de la ressource principale (client.audio.asr) avec les paramètres de requête et un chemin de fichier local, puis itérez sur les événements du serveur pour obtenir le RecognitionResult.
Cliquez pour voir l'exemple complet
Cliquez pour voir l'exemple complet
recognize_file renvoie les événements du serveur un par un (Dict[str, Any]) : le type d'événement se trouve dans event['header']['event'] et le texte reconnu dans event['payload']['output']['sentence'] (sentence_end à true indique que la phrase est terminée ; begin_time / end_time sont des horodatages, words contient les horodatages par mot, et les autres champs sont décrits dans Sentence). Les événements de heartbeat et de texte vide sont également renvoyés et peuvent être ignorés selon les besoins.Dans une session bidirectionnelle en flux continu, en plus de events(), vous pouvez utiliser results() pour itérer uniquement sur les trames de résultats de reconnaissance, qui renvoient des objets RecognitionResult typés avec filtrage des trames de heartbeat. Pour plus de détails, consultez la méthode get_sentence.Appel streaming bidirectionnel
Cette méthode soumet une tâche de transcription vocale en temps réel et retourne les résultats de reconnaissance en temps réel via l'itération d'événements.
-
Démarrer la reconnaissance vocale en streaming
Appelez la méthode
recognizede la ressource principale (client.audio.asr) pour créer une session de reconnaissance avec les paramètres de requête. Entrez dans le contextewith(qui appelle automatiquement la méthodestartpour établir la connexion et envoyer la tâche) pour lancer la reconnaissance vocale en streaming. -
Streaming
Appelez de manière répétée la méthode
send_audio_framede la session de reconnaissance pour envoyer le flux audio binaire lu depuis un fichier local ou un périphérique (tel qu'un microphone) au serveur par segments. L'envoi et la réception doivent s'exécuter de manière concurrente : le thread récepteur itère sur les événements du serveur via l'itération d'événements (events()/results()) pour retourner les résultats de reconnaissance au client en temps réel. Nous recommandons que la durée de chaque segment audio envoyé soit d'environ 100 millisecondes, avec une taille de données comprise entre 1 Ko et 16 Ko. -
Terminer le traitement
Appelez la méthode
stopde la session de reconnaissance pour arrêter la reconnaissance vocale. Cette méthode notifie seulement le serveur que la saisie est terminée ; le thread récepteur doit continuer à consommerevents()jusqu'à l'événementtask-finishedpour obtenir les résultats et statistiques finaux de la reconnaissance. Les erreurs de la couche WebSocket sont levées sous forme d'exceptionsDashScopeError, que vous pouvez capturer par try/except côté envoi ou réception.
Cliquez pour voir l'exemple complet
Cliquez pour voir l'exemple complet
Appels simultanés
En Python, en raison du Global Interpreter Lock (GIL), un seul thread peut exécuter du code Python à la fois (bien que certaines bibliothèques orientées performances puissent lever cette limitation). Pour mieux exploiter les ressources de calcul d'un ordinateur multicœur, nous vous recommandons d'utiliser multiprocessing ou concurrent.futures.ProcessPoolExecutor. Le multithreading peut augmenter considérablement la latence des appels SDK sous une forte concurrence.
Paramètres de requête
Les paramètres de requête se définissent via les méthodes recognize/recognize_file de la ressource principale (client.audio.asr) : model, format, sample_rate, vocabulary_id et disfluency_removal_enabled sont des paramètres nommés, et les autres paramètres (comme language_hints et semantic_punctuation_enabled) se transmettent via le dictionnaire parameters.
| Paramètre | Type | Valeur par défaut | Obligatoire | Description |
|---|---|---|---|---|
| model | str | Oui | Modèle utilisé pour la reconnaissance vocale en temps réel. Pour plus d'informations, voir Liste des modèles. | |
| sample_rate | int | Oui | Définissez le taux d'échantillonnage (en Hz) de l'audio à reconnaître.Varie selon le modèle :
| |
| format | str | Oui | Définissez le format audio à reconnaître.Formats audio pris en charge : pcm, wav, mp3, opus, speex, aac, amr. | |
| vocabulary_id | str | Non | Définissez l'ID du mot-clé. S'il n'est pas défini, les mots-clés ne seront pas pris en compte. Utilisez ce champ pour définir l'ID du mot-clé pour les modèles v2 et ultérieurs.Lors de la session de reconnaissance vocale en cours, les informations de mot-clé correspondant à cet ID seront appliquées. Pour une utilisation détaillée, voir Personnaliser les mots-clés. | |
| disfluency_removal_enabled | bool | False | Non | Définissez s'il faut filtrer les mots de remplissage :
|
| language_hints | list[str] | ["zh", "en"] | Non | Définissez les codes de langue pour la reconnaissance. Si vous ne pouvez pas déterminer la langue à l'avance, vous pouvez laisser ce champ vide et le modèle détectera automatiquement la langue.Codes de langue actuellement pris en charge :
|
| semantic_punctuation_enabled | bool | False | Non | Définissez s'il faut activer la segmentation sémantique. Désactivée par défaut.
semantic_punctuation_enabled, vous pouvez modifier la méthode de segmentation de la reconnaissance vocale pour l'adapter à différents scénarios.Ce paramètre ne prend effet que lorsque le modèle est v2 ou ultérieur. |
| max_sentence_silence | int | 800 | Non | Définissez le seuil de durée de silence (en ms) pour la segmentation VAD (Voice Activity Detection).Lorsque la durée de silence après un segment vocal dépasse ce seuil, le système considère que la phrase est terminée.La plage de paramètres s'étend de 200 ms à 6000 ms, avec une valeur par défaut de 800 ms.Ce paramètre ne prend effet que lorsque le paramètre semantic_punctuation_enabled est false (segmentation VAD) et que le modèle est v2 ou ultérieur. |
| multi_threshold_mode_enabled | bool | False | Non | Lorsque ce commutateur est activé (true), il empêche la segmentation VAD de couper des phrases trop longues. Désactivé par défaut.Ce paramètre ne prend effet que lorsque le paramètre semantic_punctuation_enabled est false (segmentation VAD) et que le modèle est v2 ou ultérieur. |
| punctuation_prediction_enabled | bool | True | Non | Définissez s'il faut ajouter automatiquement la ponctuation dans les résultats de reconnaissance :
|
| heartbeat | bool | False | Non | Lorsque vous devez maintenir une connexion longue avec le serveur, utilisez ce commutateur pour contrôler le comportement :
|
| inverse_text_normalization_enabled | bool | True | Non | Définissez s'il faut activer l'ITN (Normalisation inverse du texte).Activé par défaut (true). Lorsqu'elle est activée, les chiffres chinois sont convertis en chiffres arabes.Ce paramètre ne prend effet que lorsque le modèle est v2 ou ultérieur. |
Interfaces clés
Ressource principale (client.audio.asr)
La reconnaissance vocale en temps réel est montée sur la ressource client.audio.asr : recognize crée une session de reconnaissance bidirectionnelle en flux continu (Recognition) et recognize_file reconnaît un fichier local en un seul appel.
| Méthode membre | Signature de la méthode | Description |
|---|---|---|
| recognize | Crée une session de reconnaissance bidirectionnelle en flux continu. L'entrée dans le contexte with appelle automatiquement start pour établir la connexion et envoyer la tâche.L'envoi d'audio et la consommation d'événements doivent s'exécuter de manière concurrente (à utiliser avec send_audio_frame, events()/results() et stop). | |
| recognize_file | Un appel non diffusé basé sur un fichier local : envoie automatiquement l'audio par segments et conduit la tâche jusqu'à son terme, en délivrant les événements du serveur un par un. Cette méthode nécessite une autorisation de lecture sur le fichier. | |
| start | Démarre la reconnaissance vocale : établit la connexion, envoie la tâche et attend task-started. Appelée automatiquement à l'entrée dans le contexte with. L'audio ne peut être envoyé qu'après un démarrage réussi. | |
| send_audio_frame | Envoie l'audio. Veillez à ce que chaque trame audio envoyée ne soit ni trop grande ni trop petite : environ 100 ms par trame, entre 1 Ko et 16 Ko.Les résultats de reconnaissance s'obtiennent en itérant sur events()/results(). | |
| stop | Arrête la reconnaissance vocale : notifie seulement le serveur que la saisie est terminée. Le thread récepteur doit continuer à consommer events() jusqu'à l'événement task-finished. | |
| events / results | Itère sur les événements du serveur : events() délivre des dict d'événements bruts (le texte reconnu se trouve dans payload.output.sentence) ; results() ne délivre que les trames de résultats de reconnaissance, en renvoyant des objets typés Résultat de reconnaissance (RecognitionResult) (les trames de heartbeat sont filtrées). | |
| close | Ferme la session de reconnaissance. Appelée automatiquement à la sortie du contexte with. | |
| request_id / first_package_delay / last_package_delay / last_response | Récupère le request_id, la latence du premier paquet (délai entre l'envoi du premier paquet audio et la réception du premier résultat de reconnaissance) et la latence du dernier paquet (temps écoulé entre l'envoi de la commande stop et le dernier résultat de reconnaissance). À utiliser après la fin de la tâche. last_response est le dernier message brut lu correctement, utile pour récupérer les erreurs d'une tâche échouée. Restent lisibles après la fermeture de la session. |
Itération d'événements (events()/results())
Lors d'un appel streaming bidirectionnel, le serveur renvoie les informations clés du processus et les données au client via des événements. Dans un thread récepteur, itérez sur les events() de la session (dict d'événements bruts) ou results() (trames typées de résultats de reconnaissance) pour traiter les informations et données renvoyées par le serveur.
Cliquez pour voir l'exemple
Cliquez pour voir l'exemple
| Événement/méthode d'itération | Sortie | Valeur de retour | Description |
|---|---|---|---|
Événement task-started | None | Lu en interne par start() et enregistré dans last_response au retour du démarrage. N'est pas redélivré par events(). | |
event : dict d'événement du serveur | Itérateur | Délivre des événements lors des réponses du serveur. Le résultat de reconnaissance se trouve dans payload.output.sentence, qui peut être un événement de heartbeat ou de texte vide que les applications peuvent ignorer selon les besoins. Consommez-le depuis un unique thread récepteur et ne créez pas plusieurs lecteurs concurrents. | |
result : résultat de reconnaissance (RecognitionResult) | Itérateur | Ne délivre que les trames de résultats de reconnaissance (les trames de heartbeat sont filtrées). L'itération se termine après le renvoi de tous les résultats de reconnaissance. | |
Exception DashScopeError | None | Levée dans le thread d'envoi/réception en cas d'erreur. Vous pouvez la capturer par try/except. | |
Événement task-finished | None | Délivré par events() lorsque le serveur a terminé toute la reconnaissance, après quoi l'itération se termine. Vous devez continuer à lire cet événement après l'appel de stop(). |
Résultats de réponse
Résultat de reconnaissance (RecognitionResult)
RecognitionResult représente une trame de résultat de reconnaissance unique délivrée lors de l'itération sur les results() de la session (utilisable aussi bien dans un appel streaming bidirectionnel que dans un appel non streaming ; events() délivre des dict d'événements bruts ; utilisez results() si vous avez besoin de cette vue typée).
| Méthode membre | Signature de la méthode | Description |
|---|---|---|
| get_sentence | Obtient la phrase reconnue actuelle et ses informations d'horodatage. Cette méthode renvoie Dict[str, Any] (informations d'une seule phrase).Pour plus d'informations, voir Sentence. | |
| request_id | Le request_id correspondant à l'événement courant. | |
| is_sentence_end | Détermine si la phrase courante est terminée. Cette méthode vérifie si le champ end_time dans les informations de phrase unique renvoyées par get_sentence() est None : une valeur end_time différente de None indique que la phrase est terminée. |
Sentence (Sentence)
Les membres de la classe Sentence sont les suivants :
| Paramètre | Type | Description |
|---|---|---|
| begin_time | int | Heure de début de la phrase, en ms. |
| end_time | int | Heure de fin de la phrase, en ms. |
| text | str | Texte reconnu. |
| words | Une liste d'informations d'horodatage des mots (Word) | Informations d'horodatage des mots. |
| emo_tag | str | Émotion de la phrase actuelle :
|
| emo_confidence | float | Niveau de confiance de l'émotion reconnue pour la phrase actuelle. La valeur est comprise entre 0,0 et 1,0. Une valeur plus élevée indique un niveau de confiance supérieur.La reconnaissance des émotions est soumise aux contraintes suivantes :
|
Informations d'horodatage des mots (Word)
Les membres de la classe Word sont les suivants :
Paramètre | Type | Description |
|---|---|---|
begin_time | int | Heure de début du mot, en ms. |
end_time | int | Heure de fin du mot, en ms. |
text | str | Le mot. |
punctuation | str | La ponctuation. |
Codes d'erreur
Si vous rencontrez des erreurs, consultez Codes d'erreur pour le dépannage.
Si le problème persiste, rejoignez la communauté des développeurs pour signaler votre problème et fournir l'ID de requête pour une investigation plus approfondie.
Plus d'exemples
Pour plus d'exemples, voir GitHub.
FAQ
Fonctionnalités
Q : Comment maintenir une connexion longue avec le serveur lors d'un silence prolongé ?
Définissez le paramètre de requête heartbeat sur true et envoyez continuellement de l'audio silencieux au serveur.
L'audio silencieux désigne des fichiers audio ou des flux de données ne contenant aucun signal sonore. L'audio silencieux peut être généré par diverses méthodes, par exemple en utilisant des logiciels d'édition audio comme Audacity ou Adobe Audition, ou via des outils en ligne de commande comme FFmpeg.
Q : Comment convertir l'audio vers un format pris en charge ?
Vous pouvez utiliser l'outil FFmpeg. Pour plus d'informations sur son utilisation, reportez-vous au site officiel de FFmpeg.
Q : Est-il possible de consulter la plage temporelle de chaque phrase ?
Oui. Les résultats de la reconnaissance vocale incluent les horodatages de début et de fin pour chaque phrase, ce qui permet de déterminer la plage temporelle de chacune.
Q : Comment reconnaître un fichier local (fichier audio enregistré) ?
Il existe deux façons de reconnaître un fichier local :
-
Transmettre directement le chemin du fichier local : Cette méthode retourne le résultat complet de la reconnaissance une fois le fichier entièrement traité. Elle ne convient pas aux scénarios nécessitant un retour immédiat.
Transmettez le chemin du fichier à la méthode
recognize_filede la ressource principale (client.audio.asr) pour reconnaître directement le fichier audio. Pour plus d'informations, voir Appel non streaming. -
Convertir le fichier local en flux binaire pour la reconnaissance : Cette méthode retourne les résultats de reconnaissance sous forme de flux pendant le traitement du fichier. Elle convient aux scénarios nécessitant un retour immédiat.
Vous pouvez utiliser la méthode
send_audio_framede la session de reconnaissance pour envoyer un flux binaire au serveur pour reconnaissance. Pour plus d'informations, voir appel streaming bidirectionnel.
Dépannage
Q : Qu'est-ce qui cause l'échec de la reconnaissance vocale (aucun résultat de reconnaissance) ?
-
Vérifiez si le format audio (
format) et le taux d'échantillonnage (sampleRate/sample_rate) dans les paramètres de requête sont correctement définis et respectent les contraintes des paramètres. Voici des exemples d'erreurs courantes :- L'extension du fichier audio est .wav, mais le format réel est MP3, et le paramètre de requête
formatest défini surwav(paramétrage incorrect). - Le taux d'échantillonnage audio est de 3600 Hz, mais le paramètre de requête
sampleRate/sample_rateest défini sur 48000 (paramétrage incorrect).
- L'extension du fichier audio est .wav, mais le format réel est MP3, et le paramètre de requête
-
Lors de l'utilisation du modèle
paraformer-realtime-v2, vérifiez si la langue définie danslanguage_hintscorrespond à la langue réelle de l'audio. Par exemple : L'audio est en réalité en chinois, maislanguage_hintsest défini suren(anglais). - Si toutes les vérifications ci-dessus sont concluantes, vous pouvez utiliser des mots-clés personnalisés pour améliorer la précision de la reconnaissance pour des termes spécifiques.
Q : Comment corriger l'absence de résultats de reconnaissance due à un paramètre de format audio incorrect ?
format est obligatoire et doit correspondre au format réel de l'audio. Par exemple, pour un fichier audio au format MP3 portant l'extension .wav, définissez format='mp3'.
-
Vérifiez le format réel de l'audio : Utilisez
ffprobepour consulter le conteneur, le codec, le taux d'échantillonnage et les canaux de l'audio. -
Définissez les paramètres de requête : Définissez
formatsur le format réel de l'audio. Définissezsample_ratesur le taux d'échantillonnage réel et vérifiez qu'il respecte les exigences du modèle utilisé. -
Convertissez le format audio si nécessaire : Si vous avez besoin d'un fichier WAV, utilisez la commande suivante pour générer un fichier WAV encodé en PCM, à 16 kHz et mono.
Après la conversion, définissez
format='wav'etsample_rate=16000.