Paramètres et interfaces du SDK Python de reconnaissance vocale en temps réel Paraformer.
ImportantCe document s'applique uniquement à la région Chine continentale (Pékin). Pour utiliser les modèles, vous devez disposer d'une clé API provenant de la région Chine continentale (Pékin).
ImportantAlibaba Cloud Model Studio a publié un domaine spécifique aux espaces de travail pour la région Chine (Pékin). Ce nouveau domaine dédié 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 pleinement fonctionnel.
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.
Prérequis
Vous avez activé le service et obtenu une clé API. Veuillez configurer la clé API comme variable d'environnement plutôt que de la coder en dur dans votre code afin d'éviter les risques de sécurité liés à une fuite de code.
RemarqueLorsque 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, russe Dialectes 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é | ||
| Spécifier la langue de reconnaissance | Spécifiez la langue à l'aide du paramètre | 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 :
Pour obtenir les résultats de détection des émotions, récupérez respectivement l'émotion et le niveau de confiance de l'émotion de la phrase actuelle depuis les champs |
Démarrage rapide
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é.
Appelez la méthode 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
import os
import dashscope
# Voici la configuration de la région de la Chine (Pékin). Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
# Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
# Reconnaître un fichier audio local : recognize_file envoie automatiquement l'audio par segments et conduit la tâche jusqu'à son terme
for event in client.audio.asr.recognize_file(
'{YOUR_AUDIO_FILE}',
model='paraformer-realtime-v2',
format='wav',
sample_rate=16000,
# Le paramètre « language_hints » est pris en charge uniquement par le modèle paraformer-realtime-v2.
parameters={'language_hints': ['zh', 'en']}):
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('Recognition result: ', sentence['text'])
Remarquerecognize_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 à consommer
events()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
import os
import signal # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys
import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor
# Voici la configuration de la région de la Chine (Pékin). Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
# Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
mic = None
stream = None
# Définir les paramètres d'enregistrement
sample_rate = 16000 # fréquence d'échantillonnage (Hz)
channels = 1 # canal mono
dtype = 'int16' # type de données
format_pcm = 'pcm' # le format des données audio
block_size = 3200 # nombre de trames par tampon
# Récepteur d'événements de reconnaissance vocale en temps réel
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('Recognition text: ', sentence['text'])
if sentence.get('sentence_end'):
print(
'Recognition sentence end, request_id:%s, usage:%s'
% (rec.request_id, rec.usage))
def signal_handler(sig, frame):
print('Ctrl+C pressed, stop recognition ...')
# Arrêter la reconnaissance
recognition.stop()
print('Recognition stopped.')
print(
'[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
.format(
recognition.request_id,
recognition.first_package_delay,
recognition.last_package_delay,
))
# Forcer la sortie du programme
sys.exit(0)
# fonction principale
if __name__ == '__main__':
print('Initializing ...')
signal.signal(signal.SIGINT, signal_handler)
print("Press 'Ctrl+C' to stop recording and recognition...")
# Appelez le service de reconnaissance ; vous pouvez personnaliser les paramètres de reconnaissance, comme model, format,
# sample_rate
with client.audio.asr.recognize(
model='paraformer-realtime-v2',
format=format_pcm,
# 'pcm', 'wav', 'opus', 'speex', 'aac' ou 'amr'. Consultez les formats pris en charge dans la documentation.
sample_rate=sample_rate,
# 8000 ou 16000 sont pris en charge.
parameters={'semantic_punctuation_enabled': False},
) as recognition:
# Ouvrir le microphone
mic = pyaudio.PyAudio()
stream = mic.open(format=pyaudio.paInt16,
channels=1,
rate=16000,
input=True)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, recognition)
try:
# Envoyer l'audio du microphone jusqu'à l'appui sur "Ctrl+C"
while stream:
data = stream.read(3200, exception_on_overflow=False)
recognition.send_audio_frame(data)
recognition.stop()
receiver.result()
finally:
# close doit être exécuté dans le contexte du pool pour débloquer le récepteur
recognition.close()
stream.stop_stream()
stream.close()
mic.terminate()
stream = None
mic = None
import os
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor
# Voici la configuration de la région de la Chine (Pékin). Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
# Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
from datetime import datetime
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# Récepteur d'événements de reconnaissance vocale en temps réel
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print(get_timestamp() + ' Recognition text: ', sentence['text'])
if sentence.get('sentence_end'):
print(get_timestamp() +
'Recognition sentence end, request_id:%s, usage:%s'
% (rec.request_id, rec.usage))
with client.audio.asr.recognize(
model='paraformer-realtime-v2',
format='wav',
sample_rate=16000,
# Le paramètre « language_hints » est pris en charge uniquement par le modèle paraformer-realtime-v2.
parameters={'language_hints': ['zh', 'en']},
) as recognition:
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, recognition)
try:
audio_data: bytes = None
f = open("{YOUR_AUDIO_FILE}", 'rb')
if os.path.getsize("{YOUR_AUDIO_FILE}"):
while True:
audio_data = f.read(3200)
if not audio_data:
break
else:
recognition.send_audio_frame(audio_data)
time.sleep(0.1)
else:
raise Exception(
'The supplied file was empty (zero bytes long)')
f.close()
recognition.stop()
receiver.result()
finally:
# close doit être exécuté dans le contexte du pool pour débloquer le récepteur
recognition.close()
print(
'[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
.format(
recognition.request_id,
recognition.first_package_delay,
recognition.last_package_delay,
))
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. Importantopus/speex : Doit utiliser l'encapsulation Ogg. wav : Doit être encodé en PCM. amr : Seul le type AMR-NB est pris en charge. | |
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 :
Ce paramètre s'applique uniquement aux modèles multilingues. Pour plus d'informations, voir Liste des modèles. |
semantic_punctuation_enabled | bool | False | Non | Définissez s'il faut activer la segmentation sémantique. Désactivée par défaut.
La segmentation sémantique offre une précision supérieure et convient aux scénarios de transcription de réunions. La segmentation VAD (Voice Activity Detection) présente une latence plus faible et convient aux scénarios interactifs. En ajustant le paramètre 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 |
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 |
punctuation_prediction_enabled | bool | True | Non | Définissez s'il faut ajouter automatiquement la ponctuation dans les résultats de reconnaissance :
Ce paramètre ne prend effet que lorsque le modèle est v2 ou ultérieur. |
heartbeat | bool | False | Non | Lorsque vous devez maintenir une connexion longue avec le serveur, utilisez ce commutateur pour contrôler le comportement :
Ce paramètre ne prend effet que lorsque le modèle est v2 ou ultérieur. Lors de l'utilisation de ce champ, la version du SDK doit être 1.23.1 ou ultérieure. |
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. |
Référence de l’API
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 |
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 |
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
# Itérer sur les événements bruts : le texte reconnu se trouve dans payload.output.sentence
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('Recognized text: ', sentence['text'])
# Ou itérer uniquement sur les trames de résultats de reconnaissance (renvoie RecognitionResult, les trames de heartbeat sont filtrées)
def receive_results(rec):
for result in rec.results():
sentence = result.get_sentence()
if sentence and 'text' in sentence:
print('Recognized text: ', sentence['text'])
| É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 :
La reconnaissance des émotions est soumise aux contraintes suivantes :
|
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. |
Autres exemples
Pour plus d'exemples, voir GitHub.
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.