Python SDK - Alibaba Cloud Model Studio - Centre de documentation Alibaba Cloud

Cette rubrique décrit les paramètres et les interfaces du SDK Python pour le modèle de reconnaissance vocale en temps réel Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime.

ImportantAlibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions Chine (Pékin) et Singapour. Ces nouveaux domaines dédiés offrent de meilleures performances et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :

Chine (Pékin) : passez de dashscope.aliyuncs.com à {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapour : passez de dashscope-intl.aliyuncs.com à {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Remplacez {WorkspaceId} par votre ID d'espace de travail réel. Les domaines existants restent entièrement fonctionnels.

Guide d'utilisation : Pour obtenir des descriptions des modèles et des conseils de sélection, consultez la rubrique Reconnaissance vocale.

Prérequis

Le service est activé et vous avez obtenu une clé API. Pour éviter les risques de sécurité liés à la divulgation de code, configurez la clé API comme variable d'environnement au lieu de l'intégrer directement dans votre code.

Installez la dernière version du SDK DashScope.

Démarrage rapide

La classe Recognition fournit des interfaces pour les appels non diffusés (non-streaming) et les appels bidirectionnels en flux continu (streaming). Choisissez la méthode d'appel adaptée à vos besoins :

Appel non diffusé : reconnaît un fichier local et renvoie le résultat complet en une seule réponse. Cette méthode convient au traitement de fichiers audio préenregistrés.
Appel bidirectionnel en flux continu : reconnaît un flux audio directement et produit des 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 recommandée pour les scénarios nécessitant un retour immédiat.

Appel non diffusé

Soumettez une tâche unique de reconnaissance vocale en temps réel et obtenez le résultat de manière synchrone en transmettant un fichier local.

Instanciez une classe Recognition, associez les paramètres de requête et appelez la méthode call pour exécuter la reconnaissance ou la traduction, puis récupérez le résultat de reconnaissance (RecognitionResult) final.

Afficher l'exemple complet

from http import HTTPStatus
import dashscope
from dashscope.audio.asr import Recognition
import os

# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

recognition = Recognition(model='qwen-audio-3.0-asr-flash-streaming',
                          format='wav',
                          sample_rate=16000,
                          callback=None)
result = recognition.call('{YOUR_AUDIO_FILE}')
if result.status_code == HTTPStatus.OK:
    print('Recognition result:')
    print(result.get_sentence())
else:
    print('Error: ', result.message)

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.get_last_request_id(),
        recognition.get_first_package_delay(),
        recognition.get_last_package_delay(),
    ))

Appel bidirectionnel en flux continu

Soumettez une tâche unique de reconnaissance vocale en temps réel et diffusez les résultats en temps réel en implémentant l'interface de rappel (callback).

Démarrez la reconnaissance vocale en flux continu.

Instanciez une classe Recognition, associez les paramètres de requête ainsi que l'interface de rappel (RecognitionCallback), puis appelez la méthode start pour lancer la reconnaissance vocale en flux continu.
Diffusez l'audio.

Appelez la méthode send_audio_frame de la classe Recognition dans une boucle afin d'envoyer le flux audio binaire au serveur par segments. Le flux est lu depuis un fichier local ou un périphérique, tel qu'un microphone.

Pendant l'envoi de l'audio, le serveur renvoie les résultats de reconnaissance au client en temps réel via la méthode on_event de l'interface de rappel (RecognitionCallback).

Envoyez environ 100 ms d'audio par trame, en veillant à ce que chaque trame soit comprise entre 1 Ko et 16 Ko.
Terminez la tâche.

Appelez la méthode stop de la classe Recognition pour mettre fin à la reconnaissance vocale.

Cette méthode bloque le thread actuel jusqu'à ce que le rappel on_complete ou on_error de l'interface de rappel (RecognitionCallback) soit déclenché.

Afficher l'exemple complet

Reconnaître la parole du microphone

import os
import signal  # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys

import dashscope
import pyaudio
from dashscope.audio.asr import *

mic = None
stream = None

# Set recording parameters
sample_rate = 16000  # sampling rate (Hz)
channels = 1  # mono channel
dtype = 'int16'  # data type
format_pcm = 'pcm'  # the format of the audio data
block_size = 3200  # number of frames per buffer

# Real-time speech recognition callback
class Callback(RecognitionCallback):
    def on_open(self) -> None:
        global mic
        global stream
        print('RecognitionCallback open.')
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)

    def on_close(self) -> None:
        global mic
        global stream
        print('RecognitionCallback close.')
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None

    def on_complete(self) -> None:
        print('RecognitionCallback completed.')  # recognition completed

    def on_error(self, message) -> None:
        print('RecognitionCallback task_id: ', message.request_id)
        print('RecognitionCallback error: ', message.message)
        # Stop and close the audio stream if it is running
        if 'stream' in globals() and stream.active:
            stream.stop()
            stream.close()
        # Forcefully exit the program
        sys.exit(1)

    def on_event(self, result: RecognitionResult) -> None:
        sentence = result.get_sentence()
        if 'text' in sentence:
            print('RecognitionCallback text: ', sentence['text'])
            if RecognitionResult.is_sentence_end(sentence):
                print(
                    'RecognitionCallback sentence end, request_id:%s, usage:%s'
                    % (result.get_request_id(), result.get_usage(sentence)))

def signal_handler(sig, frame):
    print('Ctrl+C pressed, stop recognition ...')
    # Stop recognition
    recognition.stop()
    print('Recognition stopped.')
    print(
        '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
        .format(
            recognition.get_last_request_id(),
            recognition.get_first_package_delay(),
            recognition.get_last_package_delay(),
        ))
    # Forcefully exit the program
    sys.exit(0)

# main function
if __name__ == '__main__':
    # The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # If you have not configured the environment variable, replace the following line with your Model Studio API Key: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

    # The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
    dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

    # Create the recognition callback
    callback = Callback()

    # Call recognition service by async mode, you can customize the recognition parameters, like model, format,
    # sample_rate
    recognition = Recognition(
        model='qwen-audio-3.0-asr-flash-streaming',
        format=format_pcm,
        # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr', you can check the supported formats in the document
        sample_rate=sample_rate,
        # support 8000, 16000
        semantic_punctuation_enabled=False,
        callback=callback)

    # Start recognition
    recognition.start()

    signal.signal(signal.SIGINT, signal_handler)
    print("Press 'Ctrl+C' to stop recording and recognition...")
    # Create a keyboard listener until "Ctrl+C" is pressed

    while True:
        if stream:
            data = stream.read(3200, exception_on_overflow=False)
            recognition.send_audio_frame(data)
        else:
            break

    recognition.stop()

Reconnaître un fichier audio local

import os
import time
import dashscope
from dashscope.audio.asr import *

# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

class Callback(RecognitionCallback):
    def on_complete(self) -> None:
        print(get_timestamp() + ' Recognition completed')  # recognition complete

    def on_error(self, result: RecognitionResult) -> None:
        print('Recognition task_id: ', result.request_id)
        print('Recognition error: ', result.message)
        exit(0)

    def on_event(self, result: RecognitionResult) -> None:
        sentence = result.get_sentence()
        if 'text' in sentence:
            print(get_timestamp() + ' RecognitionCallback text: ', sentence['text'])
        if RecognitionResult.is_sentence_end(sentence):
            print(get_timestamp() +
                  'RecognitionCallback sentence end, request_id:%s, usage:%s'
                  % (result.get_request_id(), result.get_usage(sentence)))

callback = Callback()

recognition = Recognition(model='qwen-audio-3.0-asr-flash-streaming',
                          format='wav',
                          sample_rate=16000,
                          callback=callback)

try:
    audio_data: bytes = None
    f = open("{YOUR_AUDIO_FILE}", 'rb')
    if os.path.getsize("{YOUR_AUDIO_FILE}"):
        # Read all the file data into the buffer at once
        file_buffer = f.read()
        f.close()
        print("Start Recognition")
        recognition.start()

        # Send 3200 bytes from the buffer at a time
        buffer_size = len(file_buffer)
        offset = 0
        chunk_size = 3200

        while offset < buffer_size:
            # Calculate the size of the data chunk to send this time
            remaining_bytes = buffer_size - offset
            current_chunk_size = min(chunk_size, remaining_bytes)

            # Extract the current data chunk from the buffer
            audio_data = file_buffer[offset:offset + current_chunk_size]

            # Send the audio data frame
            recognition.send_audio_frame(audio_data)
            # Update the offset
            offset += current_chunk_size

            # Add a delay to simulate real-time transmission
            time.sleep(0.1)

        recognition.stop()
    else:
        raise Exception(
            'The supplied file was empty (zero bytes long)')
except Exception as e:
    raise e

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.get_last_request_id(),
        recognition.get_first_package_delay(),
        recognition.get_last_package_delay(),
    ))

Paramètres de requête

Définissez les paramètres de requête via le constructeur (init) de la classe Recognition.

Paramètre	Type	Obligatoire	Description
model	str	Oui	Le nom du modèle. Les séries de modèles Qwen-Audio-3.0-ASR-Flash-Streaming et Fun-ASR-Realtime sont prises en charge. Pour plus de détails, consultez la rubrique Modèles et régions pris en charge.
sample_rate	int	Oui	La fréquence d'échantillonnage, en Hz. Valeurs valides : les modèles 8 kHz prennent uniquement en charge 8 000 Hz ; les autres modèles acceptent n'importe quelle fréquence d'échantillonnage.
format	str	Oui	Le format audio. Valeurs valides : `pcm` `wav` `mp3` `opus` `speex` `aac` `amr` Importantopus/speex : doit utiliser l'encapsulation Ogg. wav : doit utiliser l'encodage PCM. amr : seul le type AMR-NB est pris en charge.
vocabulary_id	str	Non	L'ID d'une liste de mots clés précompilée. Générez cet ID à l'avance en appelant l'API de création de liste de mots clés. Transmettez l'ID lors de la reconnaissance pour utiliser les mots clés de la liste. Convient aux scénarios où le vocabulaire est connu et relativement stable, et où vous devez réutiliser la même liste de mots entre plusieurs requêtes. Pour plus de détails sur l'utilisation, consultez la rubrique Mots clés précompilés.
vocabulary	dict	Non	Mots clés instantanés. Transmis sous forme de paires clé-valeur, où la clé correspond au texte du mot clé (`string`) et la valeur au poids du mot clé (`integer`). Aucune liste de mots clés ne doit être créée à l'avance. Le poids varie de [1, 5] ou est défini sur 50 : une valeur comprise entre [1, 5] augmente la probabilité que le modèle génère le mot à mesure que la valeur augmente ; une valeur de 50 désigne un super mot clé, ce qui améliore considérablement le rappel, mais le nombre de super mots clés ne peut pas dépasser 50. Adapté à l'optimisation temporaire des mots clés au niveau de la session. Lorsqu'ils sont configurés conjointement avec des mots clés précompilés, seuls les mots clés instantanés prennent effet. Pour plus de détails sur l'utilisation, consultez la rubrique Mots clés instantanés. ImportantSeuls les modèles `qwen-audio-3.0-asr-flash-streaming` prennent en charge les mots clés instantanés. Exemple : `from dashscope.audio.asr import Recognition vocab = {"John Smith": 5, "Jane Doe": 5} recognition = Recognition( model='qwen-audio-3.0-asr-flash-streaming', format='wav', sample_rate=16000, vocabulary=vocab, callback=None)`
semantic_punctuation_enabled	bool	Non	Indique s'il faut activer la segmentation sémantique. Par défaut : False. True : active la segmentation sémantique et désactive la segmentation VAD. False (par défaut) : 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 (Voice Activity Detection) présente une latence plus faible et est adaptée aux scénarios interactifs.
max_sentence_silence	int	Non	Le seuil de silence VAD pour la segmentation, en ms. Lorsque le silence après un segment de parole dépasse ce seuil, le système considère que la phrase est terminée. Lorsque `semantic_punctuation_enabled` est défini sur true, ce paramètre n'est pas utilisé comme critère pour renvoyer `sentence_end`, mais une valeur trop basse peut affecter les performances de reconnaissance. Valeur par défaut : 1300. Valeurs valides : [200, 6000].
multi_threshold_mode_enabled	bool	Non	ImportantPrend effet uniquement lorsque `semantic_punctuation_enabled` est défini sur false. Indique s'il faut activer le mode multi-seuil. Lorsqu'il est activé, ce mode empêche la segmentation VAD de produire des segments trop longs. Par défaut : False.
punctuation_prediction_enabled	bool	Non	Indique s'il faut ajouter automatiquement la ponctuation aux résultats de reconnaissance : True (par défaut) : Oui. Cette valeur ne peut pas être modifiée.
heartbeat	bool	Non	Indique s'il faut activer les paquets de maintien de connexion (heartbeat). Par défaut : False. True : maintient la connexion au serveur active pendant l'envoi continu d'audio silencieux. False (par défaut) : même lorsque de l'audio silencieux est envoyé en continu, la connexion expire et se ferme après un certain temps. L'audio silencieux désigne le contenu d'un fichier audio ou d'un flux de données ne contenant aucun signal sonore. Vous pouvez générer de l'audio silencieux de plusieurs manières, par exemple en utilisant des logiciels de montage audio tels qu'Audacity ou Adobe Audition, ou des outils en ligne de commande comme FFmpeg. Ce champ nécessite la version 1.23.1 ou ultérieure du SDK.
language_hints	list[str]	Non	La langue de l'audio à reconnaître. Il n'y a pas de valeur par défaut ; si ce paramètre n'est pas défini, le modèle détecte automatiquement la langue. Pour la série de modèles Qwen-Audio-3.0-ASR-Flash-Streaming, vous pouvez définir jusqu'à 4 valeurs ; si vous en définissez davantage, seules les 4 premières prendront effet. Pour la série de modèles Fun-ASR-Realtime, vous ne pouvez définir qu'une seule valeur ; si vous en définissez plusieurs, seule la première sera prise en compte. Cliquez pour afficher les codes de langue pris en charge qwen-audio-3.0-asr-flash-streaming, fun-asr-realtime, fun-asr-realtime-2025-11-07 : 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 fun-asr-realtime-2026-02-28 : zh : chinois en : anglais ja : japonais fun-asr-realtime-2025-09-15 : zh : chinois en : anglais fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28 : zh : chinois
speech_noise_threshold	float	Non	Le seuil permettant de distinguer la parole du bruit, utilisé pour ajuster la sensibilité de la détection d'activité vocale (VAD). Valeurs valides : [-1,0, 1,0]. Descriptions des valeurs : Plus la valeur se rapproche de -1 : le seuil de bruit diminue, ce qui rend le bruit plus susceptible d'être reconnu comme de la parole, pouvant entraîner la transcription de davantage de bruit. Plus la valeur se rapproche de +1 : le seuil de bruit augmente, ce qui rend la parole plus susceptible d'être identifiée à tort comme du bruit, pouvant entraîner le filtrage de certaines parties de la parole. Il s'agit d'un paramètre de configuration avancé. Son ajustement peut affecter significativement les résultats de reconnaissance. Recommandations : Testez et vérifiez minutieusement les résultats avant tout ajustement. Ajustez par petits incréments en fonction de l'environnement audio réel (un pas de 0,1 est recommandé).
special_word_filter	str	Non	Spécifie les mots sensibles à traiter lors de la reconnaissance vocale et permet de définir différentes méthodes de traitement pour différents mots sensibles. Pour plus de détails, consultez la rubrique Filtrage des mots sensibles.
callback	RecognitionCallback	Non	Interface de rappel (RecognitionCallback).

Transmettez les paramètres suivants en tant qu'arguments nommés aux méthodes call ou start de l'instance Recognition.

Paramètre Type Obligatoire Description

Paramètre	Type	Obligatoire	Description
raw_input	dict	Non	L'objet d'entrée utilisé pour transmettre le contexte de conversation. L'amélioration contextuelle améliore la précision de la reconnaissance pour les termes spécifiques à un domaine. Pour l'utilisation, consultez le guide de démarrage rapide. ImportantLe paramètre de contexte est pris en charge uniquement par les modèles `qwen-audio-3.0-asr-flash-streaming`, `fun-asr-realtime` et `fun-asr-realtime-2025-11-07`. Le dictionnaire doit inclure une clé `context` dont la valeur est une liste de messages (list[dict]). Chaque message contient les champs suivants : `role` (str, obligatoire) : le rôle du message. `user` représente les résultats de reconnaissance des tours précédents de l'utilisateur ou une liste de mots spécifiques à un domaine. `assistant` représente les réponses du grand modèle de langage des tours précédents. `content` (list[dict], obligatoire) : la liste du contenu du message. Chaque élément contient `type` (str ; défini sur `input_text` lorsque le rôle est user, et sur `text` lorsque le rôle est assistant) et `text` (str, le contenu textuel). ImportantLimites : les messages de contexte de type `input_text` et `text` sont chacun limités à 5 messages. Lorsque la limite est dépassée, seuls les 5 messages les plus récents sont conservés. La longueur totale du texte par tour de contexte ne peut pas dépasser 400 caractères, tout excédent étant tronqué à la fin. ImportantLorsque vous transmettez un contexte, les messages dans `context` doivent respecter un ordre spécifique : les messages de contexte doivent être organisés par tour de conversation, et au sein de chaque tour, le message `user` (type `input_text`) doit précéder son message `assistant` correspondant (type `text`). RemarqueCe champ nécessite la version 1.25.23 ou ultérieure du SDK. Transmettez `raw_input` à la méthode `start` ou `call` de l'instance `Recognition` : `# Build the input to pass in input_context = { "context": [ { "role": "user", "content": [ { "type": "input_text", "text": "Hello there" } ] }, { "role": "assistant", "content": [ { "type": "text", "text": "Hello, I am Qwen. How can I help you?" } ] } ] } # Pass it in through the raw_input parameter recognition.start(raw_input=input_context) # Or recognition.call(raw_input=input_context)`

raw_input

dict

Non

L'objet d'entrée utilisé pour transmettre le contexte de conversation. L'amélioration contextuelle améliore la précision de la reconnaissance pour les termes spécifiques à un domaine. Pour l'utilisation, consultez le guide de démarrage rapide.

ImportantLe paramètre de contexte est pris en charge uniquement par les modèles qwen-audio-3.0-asr-flash-streaming, fun-asr-realtime et fun-asr-realtime-2025-11-07.

Le dictionnaire doit inclure une clé context dont la valeur est une liste de messages (list[dict]). Chaque message contient les champs suivants :

role (str, obligatoire) : le rôle du message. user représente les résultats de reconnaissance des tours précédents de l'utilisateur ou une liste de mots spécifiques à un domaine. assistant représente les réponses du grand modèle de langage des tours précédents.
content (list[dict], obligatoire) : la liste du contenu du message. Chaque élément contient type (str ; défini sur input_text lorsque le rôle est user, et sur text lorsque le rôle est assistant) et text (str, le contenu textuel).

ImportantLimites : les messages de contexte de type input_text et text sont chacun limités à 5 messages. Lorsque la limite est dépassée, seuls les 5 messages les plus récents sont conservés. La longueur totale du texte par tour de contexte ne peut pas dépasser 400 caractères, tout excédent étant tronqué à la fin.

ImportantLorsque vous transmettez un contexte, les messages dans context doivent respecter un ordre spécifique : les messages de contexte doivent être organisés par tour de conversation, et au sein de chaque tour, le message user (type input_text) doit précéder son message assistant correspondant (type text).

RemarqueCe champ nécessite la version 1.25.23 ou ultérieure du SDK.

Transmettez raw_input à la méthode start ou call de l'instance Recognition :

# Build the input to pass in
          input_context = {
              "context": [
                  {
                      "role": "user",
                      "content": [
                          {
                              "type": "input_text",
                              "text": "Hello there"
                          }
                      ]
                  },
                  {
                      "role": "assistant",
                      "content": [
                          {
                              "type": "text",
                              "text": "Hello, I am Qwen. How can I help you?"
                          }
                      ]
                  }
              ]
          }

          # Pass it in through the raw_input parameter
          recognition.start(raw_input=input_context)
          # Or
          recognition.call(raw_input=input_context)

Interfaces principales

Classe `Recognition`

Importez Recognition avec « from dashscope.audio.asr import * ».

Méthode membre	Signature de la méthode	Description
call	`def call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult`	Un appel non diffusé basé sur un fichier local. Cette méthode bloque le thread actuel jusqu'à ce que tout l'audio soit lu et nécessite une autorisation de lecture sur le fichier. Le résultat de reconnaissance est renvoyé sous forme d'objet `RecognitionResult`.
start	`def start(self, phrase_id: str = None, **kwargs)`	Démarre la reconnaissance vocale. Une reconnaissance en temps réel en flux continu basée sur des rappels. Cette méthode ne bloque pas le thread actuel. Utilisez-la conjointement avec les méthodes `send_audio_frame` et `stop`.
send_audio_frame	`def send_audio_frame(self, buffer: bytes)`	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 sont obtenus via la méthode on_event de l'interface de rappel (RecognitionCallback).
stop	`def stop(self)`	Arrête la reconnaissance vocale. Bloque l'exécution jusqu'à ce que le serveur ait terminé de reconnaître tout l'audio reçu, puis met fin à la tâche.
get_last_request_id	`def get_last_request_id(self)`	Récupère le request_id. Disponible après l'appel du constructeur (création de l'objet).
get_first_package_delay	`def get_first_package_delay(self)`	Récupère la latence du premier paquet : le délai entre l'envoi du premier paquet audio et la réception du premier résultat de reconnaissance. À utiliser après la fin de la tâche.
get_last_package_delay	`def get_last_package_delay(self)`	Récupère la latence du dernier paquet : le temps écoulé entre l'envoi de la commande `stop` et la réception du dernier résultat de reconnaissance. À utiliser après la fin de la tâche.
get_response	`def get_response(self)`	Récupère le dernier message. Utilisez cette méthode pour récupérer une erreur en cas d'échec de la tâche.

Interface de rappel (`RecognitionCallback`)

Lors d'un appel bidirectionnel en flux continu, le serveur renvoie des informations clés sur le processus et les données au client via des rappels. Implémentez les méthodes de rappel pour gérer les informations et les données renvoyées par le serveur.

Afficher l'exemple

class Callback(RecognitionCallback):
    def on_open(self) -> None:
        print('Connection established')

    def on_event(self, result: RecognitionResult) -> None:
        # Implement the logic to receive recognition results
        pass

    def on_complete(self) -> None:
        print('Task completed')

    def on_error(self, result: RecognitionResult) -> None:
        print('An error occurred:', result)

    def on_close(self) -> None:
        print('Connection closed')

callback = Callback()

Méthode	Paramètre	Valeur de retour	Description
`def on_open(self) -> None`	None	None	Appelée immédiatement après l'établissement de la connexion au serveur.
`def on_event(self, result: RecognitionResult) -> None`	`result` : Résultat de reconnaissance (RecognitionResult)	None	Appelée lorsque le serveur envoie une réponse.
`def on_complete(self) -> None`	None	None	Appelée après le renvoi de tous les résultats de reconnaissance.
`def on_error(self, result: RecognitionResult) -> None`	`result` : Résultat de reconnaissance (RecognitionResult)	None	Appelée lorsqu'une erreur se produit.
`def on_close(self) -> None`	None	None	Appelée après la fermeture de la connexion par le serveur.

Réponse

Résultat de reconnaissance (RecognitionResult)

RecognitionResult représente le résultat d'une reconnaissance en temps réel unique lors d'un appel bidirectionnel en flux continu, ou le résultat d'un appel non diffusé.

Méthode membre Signature de la méthode Description

Méthode membre	Signature de la méthode	Description
get_sentence	`def get_sentence(self) -> Union[Dict[str, Any], List[Any]]`	Récupère la phrase reconnue actuelle et ses informations d'horodatage. Un rappel renvoie une seule phrase, donc cette méthode retourne Dict[str, Any]. Pour plus de détails, consultez la rubrique Phrase (Sentence).
get_request_id	`def get_request_id(self) -> str`	Récupère le request_id de la requête.
is_sentence_end	`@staticmethod def is_sentence_end(sentence: Dict[str, Any]) -> bool`	Détermine si la phrase donnée est terminée. Cette méthode vérifie si le champ `end_time` dans `sentence` est `None` : une valeur `end_time` différente de `None` indique que la phrase est terminée. Appelez-la sous la forme `RecognitionResult.is_sentence_end(sentence)`, où `sentence` est le dictionnaire de phrase unique renvoyé par `get_sentence()`, et non un champ booléen sur une instance `Sentence`.

get_sentence

def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

Récupère la phrase reconnue actuelle et ses informations d'horodatage. Un rappel renvoie une seule phrase, donc cette méthode retourne Dict[str, Any].

Pour plus de détails, consultez la rubrique Phrase (Sentence).

get_request_id

def get_request_id(self) -> str

Récupère le request_id de la requête.

is_sentence_end

@staticmethod
def is_sentence_end(sentence: Dict[str, Any]) -> bool

Détermine si la phrase donnée est terminée. Cette méthode vérifie si le champ end_time dans sentence est None : une valeur end_time différente de None indique que la phrase est terminée. Appelez-la sous la forme RecognitionResult.is_sentence_end(sentence), où sentence est le dictionnaire de phrase unique renvoyé par get_sentence(), et non un champ booléen sur une instance Sentence.

Informations sur la phrase (`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 au niveau des mots (Word)	Informations d'horodatage au niveau des mots.

Informations d'horodatage au niveau 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 la rubrique 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 afin de poursuivre l'investigation.

FAQ

Fonctionnalités

Q : Comment maintenir la connexion active pendant de longues périodes de silence ?

Définissez le paramètre de requête heartbeat sur true et continuez d'envoyer de l'audio silencieux au serveur.

L'audio silencieux désigne le contenu d'un fichier audio ou d'un flux ne contenant aucun signal sonore. Vous pouvez générer de l'audio silencieux de plusieurs manières, par exemple en utilisant des logiciels de montage audio tels qu'Audacity ou Adobe Audition, ou des outils en ligne de commande comme FFmpeg.

Q : Comment convertir l'audio dans un format pris en charge ?

Utilisez FFmpeg. Pour plus d'informations sur l'utilisation, consultez le site officiel de FFmpeg.

# Basic conversion command (all-purpose template)
# -i, purpose: input file path, example value: audio.wav
# -c:a, purpose: audio codec, example values: aac, libmp3lame, pcm_s16le
# -b:a, purpose: bitrate (audio quality control), example values: 192k, 320k
# -ar, purpose: sample rate, example values: 44100 (CD), 48000, 16000
# -ac, purpose: number of channels, example values: 1 (mono), 2 (stereo)
# -y, purpose: overwrite an existing file (no value needed)
ffmpeg -i input_audio.ext -c:a codec_name -b:a bitrate -ar sample_rate -ac channels output.ext

# For example: WAV to MP3 (keep the original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# For example: MP3 to WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# For example: M4A to AAC (extract or convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac  # Extract directly without re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # Re-encode to improve quality
# For example: FLAC lossless to Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

Q : Comment reconnaître un fichier local (enregistrement) ?

Il existe deux façons de reconnaître un fichier local :

Transmettez directement le chemin du fichier local : cette méthode renvoie le résultat complet uniquement après la fin de la reconnaissance, elle n'est donc pas adaptée aux scénarios nécessitant un retour immédiat.

Consultez la section Appel non diffusé et transmettez le chemin du fichier à la méthode call de la classe Recognition pour reconnaître l'enregistrement directement.
Convertissez le fichier local en flux binaire pour la reconnaissance : cette méthode reconnaît le fichier tout en diffusant les résultats, elle convient donc aux scénarios nécessitant un retour immédiat.

Consultez la section Appel bidirectionnel en flux continu et envoyez le flux binaire au serveur pour reconnaissance via la méthode send_audio_frame de la classe Recognition.

Dépannage

Q : Pourquoi la parole n'est-elle pas reconnue (aucun résultat de reconnaissance) ?

Vérifiez que le format audio (format) et la fréquence d'échantillonnage (sampleRate/sample_rate) dans les paramètres de requête sont corrects et respectent les contraintes des paramètres. Les erreurs courantes incluent :
- Le fichier audio possède l'extension .wav mais est réellement au format MP3, tandis que le paramètre de requête format est défini sur mp3 (paramètre incorrect).
- La fréquence d'échantillonnage audio est de 3 600 Hz, mais le paramètre de requête sampleRate/sample_rate est défini sur 48 000 (paramètre incorrect).
Utilisez l'outil ffprobe pour obtenir le conteneur, le codec, la fréquence d'échantillonnage, les canaux et d'autres informations de l'audio :
```
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
```
Si aucune des vérifications ci-dessus ne révèle de problème, ajoutez des mots clés personnalisés pour améliorer la reconnaissance de termes spécifiques.