Alibaba Cloud Model Studio:SDK de Python

Los parámetros e interfaces del SDK de Python para reconocimiento de voz en tiempo real de Paraformer.

Guía del usuario: Para introducción al modelo y recomendaciones de selección, consulte Reconocimiento de voz en tiempo real - Fun-ASR/Paraformer.

Requisitos previos

Ha activado el servicio y ha seguido los pasos para Obtener una clave de API. Por favor, Configure la clave de API como una variable de entorno en lugar de codificarla directamente en su código para prevenir riesgos de seguridad causados por fugas de código.

• Instale el SDK de DashScope más reciente.

Lista de modelos

Introducción

La clase Recognition proporciona métodos para llamadas sin transmisión y de transmisión bidireccional. Puede seleccionar el método apropiado según sus necesidades:

• Llamada sin transmisión: Reconoce un archivo local y devuelve el resultado completo de una sola vez. Es adecuada para procesar audio pregrabado.
• Llamada de transmisión bidireccional: Reconoce un flujo de audio y genera los resultados en tiempo real. El flujo de audio puede provenir de un dispositivo externo, como un micrófono, o leerse desde un archivo local. Es adecuada para escenarios que requieren retroalimentación inmediata.

Llamada sin streaming

Este método envía una tarea de conversión de voz a texto en tiempo real para un archivo local. El proceso se bloquea hasta que se devuelve el resultado completo de la transcripción.

Instancie la clase Recognition, configure los parámetros de solicitud y llame al método call para realizar el reconocimiento o la traducción y obtener el RecognitionResult.

from http import HTTPStatus
from dashscope.audio.asr import Recognition
# China (Beijing): Replace {WorkspaceId} with your actual workspace ID. The configuration varies by region.
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"

# If you have not configured the API key in the environment variable, uncomment the following line of code and replace apiKey with your API key.
# import dashscope
# dashscope.api_key = "apiKey"

recognition = Recognition(model='paraformer-realtime-v2',
                          format='wav',
                          sample_rate=16000,
                          # The "language_hints" parameter is supported only by the paraformer-realtime-v2 model.
                          language_hints=['zh', 'en'],
                          callback=None)
result = recognition.call('{YOUR_AUDIO_FILE}')
if result.status_code == HTTPStatus.OK:
    sentences = result.get_sentence()
    for sentence in sentences:
        print(sentence['text'])
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(),
    ))

Llamada de transmisión bidireccional

Este método envía una tarea de conversión de voz a texto en tiempo real y devuelve los resultados de reconocimiento en tiempo real a través de una interfaz de callback.

1. Iniciar reconocimiento de voz por transmisión

   Instancie la clase Recognition, vincule los parámetros de solicitud y la interfaz de callback (RecognitionCallback), y llame al método start para iniciar el reconocimiento de voz por transmisión.

2. Transmisión

   Llame repetidamente al método send_audio_frame de la clase Recognition para enviar el flujo de audio binario desde un archivo local o un dispositivo (como un micrófono) al servidor en segmentos.

   A medida que se envían los datos de audio, el servidor utiliza el método on_event de la interfaz de callback RecognitionCallback para devolver los resultados de reconocimiento al cliente en tiempo real.

   Se recomienda que la duración de cada segmento de audio enviado sea de aproximadamente 100 milisegundos y que el tamaño de los datos esté entre 1 KB y 16 KB.

3. Finalizar procesamiento

   Llame al método stop de la clase Recognition para detener el reconocimiento de voz.

   Este método bloquea el hilo actual hasta que se active el callback on_complete o on_error de la interfaz de callback (RecognitionCallback).

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 *
# China (Beijing): Replace {WorkspaceId} with your actual workspace ID. The configuration varies by region.
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"

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

def init_dashscope_api_key():
    """
        Set your DashScope API-key. More information:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # load API-key from environment variable DASHSCOPE_API_KEY
    else:
        dashscope.api_key = '<your-dashscope-api-key>'  # set API-key manually

# 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__':
    init_dashscope_api_key()
    print('Initializing ...')

    # 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='paraformer-realtime-v2',
        format=format_pcm,
        # 'pcm', 'wav', 'opus', 'speex', 'aac', or 'amr'. You can check the supported formats in the document.
        sample_rate=sample_rate,
        # 8000 or 16000 is supported.
        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()

import os
import time
from dashscope.audio.asr import *
# China (Beijing): Replace {WorkspaceId} with your actual workspace ID. The configuration varies by region.
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"

# If you have not configured the API key in the environment variable, uncomment the following line of code and replace apiKey with your API key.
# import dashscope
# dashscope.api_key = "apiKey"

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='paraformer-realtime-v2',
                          format='wav',
                          sample_rate=16000,
                          # The "language_hints" parameter is supported only by the paraformer-realtime-v2 model.
                          language_hints=['zh', 'en'],
                          callback=callback)

recognition.start()

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()
except Exception as e:
    raise e

recognition.stop()

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(),
    ))

Llamadas concurrentes

En Python, debido al Bloqueo Global del Intérprete (GIL), solo un hilo puede ejecutar código Python a la vez (aunque algunas bibliotecas orientadas al rendimiento pueden eliminar esta limitación). Si want aprovechar mejor los recursos informáticos de una computadora multinúcleo, le recomendamos utilizar multiprocessing o concurrent.futures.ProcessPoolExecutor. El uso de subprocesos múltiples puede aumentar significativamente la latencia de llamadas del SDK bajo alta concurrencia.

Parámetros de solicitud

Los parámetros de solicitud se configuran en el constructor (init) de la clase Recognition.

Interfaces clave

Clase Recognition

La clase Recognition se importa mediante from dashscope.audio.asr import *.

def call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult

def start(self, phrase_id: str = None, **kwargs)

def send_audio_frame(self, buffer: bytes)

def stop(self)

def get_last_request_id(self)

def get_first_package_delay(self)

def get_last_package_delay(self)

Interfaz de callback (RecognitionCallback)

Durante una llamada de transmisión bidireccional, el servidor utiliza callbacks para devolver información clave del proceso y datos al cliente. Debe implementar un método de callback para procesar la información y los datos devueltos.

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

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

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

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

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

callback = Callback()

def on_open(self) -> None

def on_event(self, result: RecognitionResult) -> None

def on_complete(self) -> None

def on_error(self, result: RecognitionResult) -> None

def on_close(self) -> None

Resultados de respuesta

Resultado de reconocimiento (RecognitionResult)

RecognitionResult representa el resultado de reconocimiento de un único reconocimiento en tiempo real en una llamada de transmisión bidireccional o en una llamada sin transmisión.

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

def get_request_id(self) -> str

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

Oración (Sentence)

Los miembros de la clase Sentence son los siguientes:

Información de marcas de tiempo de palabras (Word)

Los miembros de la clase Word son los siguientes:

Códigos de error

Si encuentra errores, consulte Códigos de error para solucionar problemas.

Si el problema persiste, únase a la comunidad de desarrolladores para reportar su incidencia y proporcione el ID de solicitud para una investigación más detallada.

Más ejemplos

Para más ejemplos, consulte GitHub.

FAQ

Funcionalidades

P: ¿Cómo mantener una conexión prolongada con el servidor durante un silencio prolongado?

Establezca el parámetro de solicitud heartbeat en true y envíe continuamente audio silencioso al servidor.

El audio silencioso se refiere a archivos de audio o flujos de datos que no contienen señal de sonido. El audio silencioso se puede generar mediante varios métodos, como usar software de edición de audio como Audacity o Adobe Audition, o a través de herramientas de línea de comandos como FFmpeg.

P: ¿Cómo convertir audio a un formato compatible?

Puede usar la herramienta FFmpeg. Para más usos, consulte el sitio web oficial de FFmpeg.

# Basic conversion command (universal template)
# -i: Input file path. Example: audio.wav
# -c:a: Audio codec. Example: aac, libmp3lame, pcm_s16le
# -b:a: Bitrate (quality control). Example: 192k, 320k
# -ar: Sample rate. Example: 44100 (CD), 48000, 16000
# -ac: Number of channels. Example: 1 (mono), 2 (stereo)
# -y: Overwrite existing file (no value needed)
ffmpeg -i input_audio.ext -c:a codec_name -b:a bitrate -ar sample_rate -ac channels output.ext

# Example: WAV -> MP3 (preserve original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# Example: MP3 -> WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# Example: M4A -> AAC (extract/convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac  # Direct extraction without re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # Re-encode for higher quality
# Example: FLAC lossless -> Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

P: ¿Admite ver el rango de tiempo para cada oración?

Sí. Los resultados del reconocimiento de voz incluyen las marcas de tiempo de inicio y fin para cada oración, las cuales se pueden utilizar para determinar el rango de tiempo de cada oración.

P: ¿Cómo reconozco un archivo local (archivo de audio grabado)?

Hay dos formas de reconocer un archivo local:

• Pasar directamente la ruta del archivo local: Este método devuelve el resultado completo del reconocimiento después de procesar totalmente el archivo. No es adecuado para escenarios que requieren retroalimentación inmediata.

  Pase la ruta del archivo al método call de la clase Recognition para reconocer directamente el archivo de audio. Para obtener más información, consulte Llamada sin transmisión.

• Convertir el archivo local en un flujo binario para su reconocimiento: Este método devuelve los resultados de reconocimiento como un flujo mientras se procesa el archivo. Es adecuado para escenarios que requieren retroalimentación inmediata.

  Puede utilizar el método send_audio_frame de la clase Recognition para enviar un flujo binario al servidor para su reconocimiento. Para obtener más información, consulte llamada de transmisión bidireccional.

Solución de problemas

P: ¿Qué causa el fallo al reconocer el habla (sin resultados de reconocimiento)?

1. Verifique si el formato de audio (format) y la frecuencia de muestreo (sampleRate/sample_rate) en los parámetros de solicitud están configurados correctamente y cumplen con las restricciones de parámetros. Los siguientes son ejemplos comunes de errores:

   • La extensión del archivo de audio es .wav, pero el formato real es MP3, y el parámetro de solicitud format está configurado como wav (configuración de parámetro incorrecta).
   • La frecuencia de muestreo del audio es de 3600 Hz, pero el parámetro de solicitud sampleRate/sample_rate está configurado en 48000 (configuración de parámetro incorrecta).

   Puede utilizar la herramienta ffprobe para obtener información sobre el contenedor, códec, frecuencia de muestreo, canales y otros detalles del audio:

ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx

2. Al utilizar el modelo paraformer-realtime-v2, verifique si el idioma configurado en language_hints coincide con el idioma real del audio.

   Por ejemplo: El audio está realmente en chino, pero language_hints está configurado como en (inglés).

3. Si todas las comprobaciones anteriores son correctas, puede usar palabras clave personalizadas para mejorar la precisión del reconocimiento de palabras específicas.

P: ¿Cómo soluciono la falta de resultados de reconocimiento causada por un parámetro de formato de audio incorrecto?

format es obligatorio y debe coincidir con el formato de audio real. Por ejemplo, para un archivo de audio MP3 con extensión .wav, configure format='mp3'.

1. Verifique el formato de audio real: Utilice ffprobe para inspeccionar el contenedor de audio, el códec, la frecuencia de muestreo y los canales.

   ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 your_audio_file
   

2. Configure los parámetros de solicitud: Establezca format en el formato de audio real. Configure sample_rate en la frecuencia de muestreo real y asegúrese de que cumpla con los requisitos del modelo que utiliza.

3. Convierta el formato de audio si es necesario: Si necesita audio WAV, utilice el siguiente comando para generar un archivo WAV monoaural codificado en PCM de 16 kHz.

   ffmpeg -i input_file -c:a pcm_s16le -ar 16000 -ac 1 output.wav
   

   Después de la conversión, configure format='wav' y sample_rate=16000.