SDK de Python

​

Requisitos previos

• Instale el SDK de DashScope más reciente.

​

Lista de modelos

​

Introducción

• Llamada sin transmisión (recognize_file): Reconoce un archivo local. El SDK envía automáticamente el audio en fragmentos y lleva la tarea hasta su finalización. 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

import os
import dashscope

# La siguiente configuración corresponde a la región de China (Pekín). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Reconocer un archivo de audio local: recognize_file envía automáticamente el audio en fragmentos y lleva la tarea hasta su finalización
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='paraformer-realtime-v2',
        format='wav',
        sample_rate=16000,
        # El parámetro "language_hints" solo es compatible con el modelo 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'])

​

Llamada de transmisión bidireccional

1. Iniciar reconocimiento de voz por transmisión Llame al método recognize del recurso principal (client.audio.asr) para crear una sesión de reconocimiento con los parámetros de solicitud. Entre en el contexto with (que llama automáticamente al método start para establecer la conexión y enviar la tarea) para iniciar el reconocimiento de voz por transmisión.
2. Transmisión Llame repetidamente al método send_audio_frame de la sesión de reconocimiento para enviar el flujo de audio binario leído de un archivo local o de un dispositivo (como un micrófono) al servidor en segmentos. El envío y la recepción deben realizarse de forma concurrente: el hilo receptor itera los eventos del servidor mediante la iteración de eventos (events()/results()) 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 sesión de reconocimiento para detener el reconocimiento de voz. Este método solo notifica al servidor que la entrada ha finalizado; el hilo receptor debe seguir consumiendo events() hasta el evento task-finished para obtener los resultados y estadísticas finales del reconocimiento. Los errores de la capa WebSocket se lanzan como excepciones DashScopeError, que pueden capturarse con try/except en los puntos de envío o recepción.

import os
import signal  # para el manejo de eventos de teclado (presione "Ctrl+C" para terminar la grabación)
import sys

import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor

# La siguiente configuración corresponde a la región de China (Pekín). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su 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

# Configurar los parámetros de grabación
sample_rate = 16000  # tasa de muestreo (Hz)
channels = 1  # canal mono
dtype = 'int16'  # tipo de datos
format_pcm = 'pcm'  # el formato de los datos de audio
block_size = 3200  # número de fotogramas por búfer

# Receptor de eventos de reconocimiento de voz en tiempo real
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 ...')
    # Detener el reconocimiento
    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,
        ))
    # Forzar la salida del programa
    sys.exit(0)

# función principal
if __name__ == '__main__':
    print('Initializing ...')

    signal.signal(signal.SIGINT, signal_handler)
    print("Press 'Ctrl+C' to stop recording and recognition...")

    # Llamar al servicio de reconocimiento; puede personalizar los parámetros de reconocimiento, como model, format,
    # sample_rate
    with client.audio.asr.recognize(
            model='paraformer-realtime-v2',
            format=format_pcm,
            # 'pcm', 'wav', 'opus', 'speex', 'aac' o 'amr'. Puede consultar los formatos compatibles en la documentación.
            sample_rate=sample_rate,
            # Se admiten 8000 o 16000.
            parameters={'semantic_punctuation_enabled': False},
    ) as recognition:
        # Abrir el micrófono
        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:
                # Enviar audio desde el micrófono hasta que se presione "Ctrl+C"
                while stream:
                    data = stream.read(3200, exception_on_overflow=False)
                    recognition.send_audio_frame(data)
                recognition.stop()
                receiver.result()
            finally:
                # close debe ejecutarse dentro del contexto del pool para desbloquear el receptor
                recognition.close()
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None

​

Llamadas concurrentes

​

Parámetros de solicitud

​

Interfaces clave

​

Recurso principal (client.audio.asr)

def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]

def start(self)

def send_audio_frame(self, buffer: bytes)

def stop(self)

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]

def close(self)

rec.request_id
rec.first_package_delay
rec.last_package_delay

​

Iteración de eventos (events()/results())

# Iterar eventos sin procesar: el texto reconocido se encuentra en 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'])


# O iterar únicamente los fotogramas de resultados de reconocimiento (devuelve RecognitionResult, fotogramas de latido filtrados)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognized text: ', sentence['text'])

event["header"]["event"] == "task-started"

def events(self) -> Iterator[Dict]

def results(self) -> Iterator[RecognitionResult]

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)

event["header"]["event"] == "task-finished"

​

Resultados de respuesta

​

Resultado de reconocimiento (RecognitionResult)

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

result.request_id

def is_sentence_end(self) -> bool

​

Oración (Sentence)

​

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

​

Códigos de error

​

Más ejemplos

​

FAQ

​

Funcionalidades

​

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

​

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

# 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?

​

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

• 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. Llame al método recognize_file del recurso principal (client.audio.asr) con la ruta del archivo para reconocer directamente el archivo de audio grabado. 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 sesión de reconocimiento 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?

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.
   Copy

   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.
   Copy

   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.