Skip to main content

SDK de Python de Qwen-Audio-ASR-Message

Este tema describe los parámetros e interfaces del SDK de Python para el modelo de reconocimiento de voz en tiempo real Qwen-Audio-3.1-ASR-Flash-Message.

Alibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:
  • China (Pekín): de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapur: de dashscope-intl.aliyuncs.com a {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Requisitos previos

Inicio rápido

El recurso principal (client.audio.asr) proporciona interfaces tanto para llamadas sin streaming como de transmisión bidireccional. Elija el método de llamada que se adapte a sus necesidades:
  • Llamada sin streaming (recognize_file): Reconoce un archivo local. El SDK envía automáticamente el audio en bloques y lleva la tarea hasta su finalización. Adecuado para procesar audio pregrabado.
  • Llamada de transmisión bidireccional (sesión recognize): Reconoce un flujo de audio directamente y genera resultados en tiempo real. El flujo de audio puede provenir de un dispositivo externo, como un micrófono, o leerse desde un archivo local. Adecuado para escenarios que requieren retroalimentación inmediata.
  • Llamada sin transmisión
  • Llamada de transmisión bidireccional
Envíe una única tarea de reconocimiento de voz en tiempo real y obtenga el resultado del reconocimiento de forma síncrona pasando un archivo local.Llame al método recognize_file del recurso principal (client.audio.asr) para vincular los parámetros de solicitud y pasar la ruta del archivo local, y recorra en iteración los eventos del servidor para obtener los resultados del reconocimiento.
import os
import dashscope

# Las API Key de las regiones de Singapur y Pekín son diferentes. Obtenga su API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# 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"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # La siguiente configuración corresponde a la región de Singapur (ap-southeast-1). Al llamar, sustituya "{WorkspaceId}" por el ID real de su espacio de trabajo. La configuración varía según la región.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Reconocimiento de un archivo de audio local: recognize_file envía automáticamente el audio en bloques y lleva la tarea hasta su finalización
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='qwen-audio-3.1-asr-flash-message',
        format='wav',
        sample_rate=16000):
    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'])

Parámetros de solicitud

Establezca los parámetros de solicitud a través de los métodos recognize/recognize_file del recurso principal (client.audio.asr): model, format, sample_rate y vocabulary_id son parámetros con nombre, y el resto de parámetros (como language_hints) se pasan a través del diccionario parameters.
ParámetroTipoObligatorioDescripción
modelstrSíEl nombre del modelo. Establézcalo en qwen-audio-3.1-asr-flash-message.
sample_rateintSí

La frecuencia de muestreo, en Hz.

Solo se admite 16000 Hz.
formatstrSí

El formato de audio.

Valores válidos:
  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr
opus/speex: Debe usar encapsulación Ogg.wav: Debe usar codificación PCM.amr: Solo se admite el tipo AMR-NB.
disfluency_removal_enabledboolNoIndica si se deben filtrar las muletillas y pulir la salida. El valor predeterminado es false. Establézcalo en true para habilitar esta función. Páselo como un argumento de palabra clave con el mismo nombre.
intermediate_result_enabledboolNoIndica si se deben devolver resultados intermedios de streaming. El valor predeterminado es false. Establézcalo en true para devolver resultados intermedios de streaming. Páselo como un argumento de palabra clave con el mismo nombre.
keep_dialectboolNoEl valor predeterminado es false, que transcribe dialectos al chino estándar. Establézcalo en true para conservar las expresiones dialectales. Páselo como un argumento de palabra clave con el mismo nombre. Consulte Eventos del cliente para obtener más detalles.Este parámetro solo se aplica a los resultados finales (sentence_end=true) y no es compatible con los resultados intermedios (sentence_end=false).
vad_modelstrNoEstablézcalo en near_meeting_16k (campo cercano) o far_field_meeting_16k (campo lejano, predeterminado). Páselo como un argumento de palabra clave con el mismo nombre. Consulte Eventos del cliente para obtener más detalles.
vocabulary_idstrNo

El ID de una lista de palabras clave precompilada.

Genere este ID con antelación llamando a la API de creación de lista de palabras clave. Pase el ID durante el reconocimiento para usar las palabras clave de la lista.Adecuado para escenarios donde el vocabulario es conocido y relativamente estable, y donde necesita reutilizar la misma lista de palabras en distintas solicitudes.Para obtener detalles sobre el uso, consulte Palabras clave precompiladas.
vocabularydictNo

Palabras clave instantáneas.

Se pasan como pares clave-valor, donde la clave es el texto de la palabra clave (string) y el valor es el peso de la palabra clave (integer). No es necesario crear una lista de palabras clave con antelación. El peso oscila entre [1, 5] o se establece en 50: un valor en [1, 5] hace que el modelo tenga más probabilidades de generar la palabra a medida que aumenta el valor; un valor de 50 designa una súper palabra clave, lo que mejora enormemente la recuperación, pero el número de súper palabras clave no puede exceder 50.Adecuado para la optimización temporal de palabras clave a nivel de sesión.Cuando las palabras clave instantáneas y precompiladas se configuran juntas, el sistema fusiona ambos conjuntos. Si el conjunto fusionado contiene más de 2000 palabras clave, el sistema selecciona aleatoriamente 2000 para usar. Para detalles de uso, consulte Palabras clave instantáneas.Ejemplo:
import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# Las palabras clave instantáneas se pasan a través de parameters
vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
language_hintslist[str]NoEl idioma del audio a reconocer. No hay valor predeterminado; si no se establece, el modelo detecta el idioma automáticamente.Puede configurar hasta 4 valores. Si configura más, solo los primeros 4 surten efecto.
  • zh: Chino
  • en: Inglés
  • ja: Japonés
  • ko: Coreano
  • vi: Vietnamita
  • th: Tailandés
  • id: Indonesio
  • ms: Malayo
  • tl: Filipino
  • hi: Hindi
  • ar: Árabe
  • fr: Francés
  • de: Alemán
  • es: Español
  • pt: Portugués
  • ru: Ruso
  • it: Italiano
  • nl: Neerlandés
  • sv: Sueco
  • da: Danés
  • fi: Finés
  • no: Noruego
  • el: Griego
  • pl: Polaco
  • cs: Checo
  • hu: Húngaro
  • ro: Rumano
  • bg: Búlgaro
  • hr: Croata
  • sk: Eslovaco
Páselo como un argumento de palabra clave con el mismo nombre.Este parámetro solo se aplica a los resultados finales (sentence_end=true) y no es compatible con los resultados intermedios (sentence_end=false).
max_sentence_silenceintNo

El umbral de silencio VAD para la segmentación, en ms. Cuando el silencio después de un segmento de voz supera este umbral, el sistema determina que la oración ha terminado.

Valor predeterminado: 800.Valores válidos: [200, 6000].
heartbeatboolNo

Si se deben habilitar los paquetes de latido.

Predeterminado: False.
  • True: Mantiene activa la conexión con el servidor mientras se envía audio silencioso continuamente.
  • False (predeterminado): Incluso cuando se envía audio silencioso de forma continua, la conexión expira y se cierra después de un período de tiempo.
El audio silencioso se refiere al contenido en un archivo de audio o flujo de datos que no contiene señal de sonido. Puede generar audio silencioso de varias maneras, como utilizando software de edición de audio como Audacity o Adobe Audition, o utilizando una herramienta de línea de comandos como FFmpeg.Este campo se introdujo en el SDK 1.23.1 y ya está incluido en la versión 2.0.1 y posteriores.
speech_noise_thresholdfloatNo

El umbral para distinguir el habla del ruido, utilizado para ajustar la sensibilidad de la Detección de Actividad de Voz (VAD).

Valores válidos: [-1.0, 1.0].Descripciones de valores:
  • Cuanto más cerca esté el valor de -1: El umbral de ruido disminuye, por lo que es más probable que el ruido se reconozca como habla, lo que puede causar que se transcriba más ruido.
  • Cuanto más cerca esté el valor de +1: El umbral de ruido aumenta, por lo que es más probable que el habla se juzgue erróneamente como ruido, lo que puede causar que se filtre parte del habla.
Este es un parámetro de configuración avanzada. Ajustarlo puede afectar significativamente los resultados del reconocimiento. Recomendaciones:
  • Pruebe y verifique exhaustivamente los resultados antes de ajustar.
  • Ajuste en incrementos pequeños según el entorno de audio real (se recomienda un paso de 0.1).
Pase los siguientes parámetros a través del argumento de palabra clave input de los métodos recognize/recognize_file.
ParámetroTipoObligatorioDescripción
inputdictNo

El objeto de entrada utilizado para pasar el contexto de la conversación. La mejora de contexto aumenta la precisión del reconocimiento de términos específicos del dominio. Para obtener información sobre su uso, consulte Inicio rápido.

El diccionario debe incluir una clave context cuyo valor sea una lista de mensajes (list[dict]). Cada mensaje contiene los siguientes campos:
  • role (str, obligatorio): El rol del mensaje. user representa los resultados de reconocimiento de turnos anteriores del usuario o una lista de palabras específica del dominio. assistant representa las respuestas del modelo de lenguaje grande de turnos anteriores.
  • content (list[dict], obligatorio): La lista del contenido del mensaje. Cada elemento contiene type (str; establecido en input_text cuando el rol es user, y text cuando el rol es assistant) y text (str, el contenido de texto).
Los mensajes de contexto de los tipos input_text y text están limitados a 5 mensajes cada uno. Cuando se supera el límite, solo se conservan los 5 mensajes más recientes. La longitud total del texto por turno de contexto no puede exceder los 400 caracteres, y cualquier exceso se trunca desde el final.
Cuando pasa contexto, los mensajes en context deben seguir un orden específico: los mensajes de contexto deben organizarse por turno de conversación y, dentro de cada turno, el mensaje user (tipo input_text) debe preceder a su mensaje assistant correspondiente (tipo text).
Este campo se introdujo en el SDK 1.25.23 y ya está incluido en la versión 2.0.1 y posteriores.
# Construya la entrada que se va a pasar
      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?"
                      }
                  ]
              }
          ]
      }

      # Pásela a través del parámetro input al crear la sesión de reconocimiento
      recognition = client.audio.asr.recognize(
          model='qwen-audio-3.1-asr-flash-message',
          format='wav',
          sample_rate=16000,
          input=input_context,
      )

Interfaces clave

Recurso principal (client.audio.asr)

La capacidad de reconocimiento de voz en tiempo real está montada en el recurso client.audio.asr: recognize crea una sesión de reconocimiento bidireccional en streaming (Recognition) y recognize_file realiza un reconocimiento único sobre un archivo local.
Método miembroFirma del métodoDescripción
recognize
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
Crea una sesión de reconocimiento bidireccional en streaming. Al entrar en el contexto with se llama automáticamente a start para establecer la conexión y enviar la tarea.El envío de audio y el consumo de eventos deben ejecutarse de forma concurrente (utilícelo junto con send_audio_frame, events()/results() y stop).
recognize_file
def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
Una llamada sin streaming basada en un archivo local: envía automáticamente el audio en bloques, lleva la tarea hasta su finalización y devuelve los eventos del servidor uno a uno. Este método requiere permiso de lectura en el archivo.
start
def start(self)
Inicia el reconocimiento de voz: establece la conexión, envía la tarea y espera el evento task-started. Se llama automáticamente al entrar en el contexto with, y el audio solo se puede enviar después de que tenga éxito.
send_audio_frame
def send_audio_frame(self, buffer: bytes)
Envía audio. Mantenga cada cuadro de audio enviado ni demasiado grande ni demasiado pequeño: aproximadamente 100 ms por cuadro, entre 1 KB y 16 KB.Los resultados del reconocimiento se obtienen a través de la iteración de eventos (events()/results()).
stop
def stop(self)
Detiene el reconocimiento de voz: solo notifica al servidor que la entrada ha terminado; el hilo receptor debe seguir consumiendo events() hasta el evento task-finished.
events / results
def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
Recorre en iteración los eventos del servidor: events() devuelve eventos dict sin procesar (el texto reconocido está en payload.output.sentence); results() devuelve solo los fotogramas de resultados de reconocimiento y retorna objetos tipados Resultado del reconocimiento (RecognitionResult) (los fotogramas de latido se filtran).
close
def close(self)
Cierra la sesión de reconocimiento. Se llama automáticamente al salir del contexto with.
request_id / first_package_delay / last_package_delay / last_response
rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.last_response
Obtiene el request_id, el retraso del primer paquete (la latencia desde el envío del primer paquete de audio hasta la recepción del primer resultado de reconocimiento) y el retraso del último paquete (el tiempo desde el envío del comando stop hasta la llegada del último resultado de reconocimiento). Úselos después de que la tarea se complete. last_response es el último mensaje sin procesar leído correctamente, que puede usar para recuperar un error de tarea fallida. Siguen siendo legibles después de cerrar la sesión.

Actualizar contexto de conversación

Llame a update_context para actualizar el contexto de la conversación mientras se ejecuta una tarea de reconocimiento. El contexto se utiliza para ayudar al reconocimiento del audio subsiguiente. Este método requiere el SDK de Python de DashScope 2.0.1 o posterior.
def update_context(self, context: dict)
  • Cuándo llamar: Después de entrar en el contexto with (que llama automáticamente a start) para iniciar el reconocimiento por streaming, y antes de llamar a stop.
  • Parámetro: context es un diccionario que contiene el objeto payload.input de un evento continue-task, incluyendo el campo context. No agregue un contenedor payload o input adicional.
  • Modelos compatibles y restricciones de parámetros: Consulte continue-task.
El siguiente ejemplo utiliza una instancia de recognition existente e iniciada.
payload_input = {
    "context": [
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "Hello"}]
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "Hello, I am Qwen. How can I help you?"}]
        }
    ]
}
recognition.update_context(context=payload_input)

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

Durante una Llamada de streaming bidireccional, el servidor devuelve información clave del proceso y datos al cliente a través de eventos. En el hilo receptor, recorra en iteración los events() de la sesión (eventos dict sin procesar) o results() (fotogramas de resultados de reconocimiento tipados) para manejar la información y los datos devueltos por el servidor.
# Recorra en iteración los eventos sin procesar: el texto reconocido está 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 recorra solo los fotogramas de resultados de reconocimiento (devuelve RecognitionResult, los fotogramas de latido se filtran)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognized text: ', sentence['text'])
Método de evento/iteraciónSalidaValor de retornoDescripción
event["header"]["event"] == "task-started"
evento task-startedNoneLo lee internamente start() y lo almacena en last_response cuando retorna; events() no lo vuelve a devolver.
def events(self) -> Iterator[Dict]
event: un dict de evento del servidorIteradorDevuelve eventos cuando el servidor responde. Los resultados del reconocimiento están en payload.output.sentence y pueden ser eventos de latido o de texto vacío, que las aplicaciones pueden ignorar según sea necesario. Consúmalo con un único hilo receptor; no cree varios lectores concurrentes.
def results(self) -> Iterator[RecognitionResult]
result: Resultado del reconocimiento (RecognitionResult)IteradorDevuelve solo los fotogramas de resultados de reconocimiento (los fotogramas de latido se filtran) y la iteración termina después de que se devuelvan todos los resultados del reconocimiento.
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
excepción DashScopeErrorNoneSe lanza en el hilo de envío/recepción cuando ocurre un error; captúrelo con try/except.
event["header"]["event"] == "task-finished"
evento task-finishedNoneLo devuelve events() después de que el servidor completa todo el reconocimiento, tras lo cual la iteración termina; aún debe leer este evento después de llamar a stop().

Respuesta

Resultado del reconocimiento (RecognitionResult)

RecognitionResult representa un único fotograma de resultado de reconocimiento devuelto por la iteración results() de la sesión (utilizable tanto en Llamadas de streaming bidireccional como en Llamadas sin streaming; events() devuelve eventos dict sin procesar; use results() si necesita esta vista tipada).
Método miembroFirma del métodoDescripción
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

Obtiene la oración reconocida actual y su información de marca de tiempo. Este método devuelve Dict[str, Any] (una sola oración).

Para más detalles, consulte Oración (Sentence).
request_id
result.request_id
El request_id del evento actual.
is_sentence_end
def is_sentence_end(self) -> bool
Determina si la oración actual ha terminado. Este método verifica si el campo end_time en el dict de oración única devuelto por get_sentence() es None: un valor end_time distinto de None indica que la oración ha terminado.

Información de la oración (Sentence)

Los miembros de la clase Sentence son los siguientes:
ParámetroTipoDescripción
begin_timeintTiempo de inicio de la oración, en ms.
end_timeintTiempo de fin de la oración, en ms.
textstrTexto reconocido.
wordsUna lista de Información de marcas de tiempo a nivel de palabra (Word)Información de marcas de tiempo a nivel de palabra.

Información de marcas de tiempo a nivel de palabra (Word)

Los miembros de la clase Word son los siguientes:
ParámetroTipoDescripción
begin_timeintTiempo de inicio de la palabra, en ms.
end_timeintTiempo de fin de la palabra, en ms.
textstrLa palabra.
punctuationstrLa puntuación.

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 que aparece en el repositorio de muestras del SDK de voz para informar su problema y proporcionar el ID de solicitud para una investigación más detallada.

FAQ

Funcionalidades

P: ¿Cómo mantengo activa la conexión durante largos períodos de silencio?

Establezca el parámetro de solicitud heartbeat en true y continúe enviando audio silencioso al servidor. El audio silencioso es contenido en un archivo o flujo de audio que no contiene ninguna señal de sonido. Puede generar audio silencioso de varias maneras, por ejemplo, utilizando software de edición de audio como Audacity o Adobe Audition, o herramientas de línea de comandos como FFmpeg.

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

Utilice FFmpeg. Para más usos, consulte el sitio web oficial 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: sample rate; set to 16000 for this model
# -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 -ar 16000 -ac 1 output.mp3
# For example: MP3 to WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 16000 -ac 1 output.wav
# For example: M4A to AAC (extract or convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac  # Only if the source is already 16000 Hz mono AAC
ffmpeg -i input.m4a -c:a aac -b:a 64k -ar 16000 -ac 1 output.aac  # Re-encode as 16000 Hz mono audio
# For example: FLAC lossless to Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on -ar 16000 -ac 1 output.opus

P: ¿Cómo reconozco un archivo local (grabación)?

Hay dos formas de reconocer un archivo local:
  • Pasar la ruta del archivo local directamente: De esta manera se devuelve el resultado completo solo después de que finaliza el reconocimiento, por lo que no es adecuado para escenarios que necesitan retroalimentación inmediata. Consulte Llamada sin streaming y llame al método recognize_file del recurso principal (client.audio.asr) para reconocer la grabación directamente.
  • Convertir el archivo local a un flujo binario para el reconocimiento: De esta manera se reconoce el archivo mientras se transmiten los resultados, por lo que es adecuado para escenarios que necesitan retroalimentación inmediata. Consulte Llamada de streaming bidireccional y envíe el flujo binario al servidor para su reconocimiento a través del método send_audio_frame de la sesión de reconocimiento.

Solución de problemas

P: ¿Por qué no se puede reconocer el habla (sin resultado de reconocimiento)?

  1. Verifique que el formato de audio (format) y la tasa de muestreo (sampleRate/sample_rate) en los parámetros de solicitud sean correctos y cumplan con las restricciones de parámetros. Los errores comunes incluyen:
    • El archivo de audio tiene una extensión .wav pero en realidad está en formato MP3, mientras que el parámetro de solicitud format está establecido en wav (configuración de parámetro incorrecta).
    • La tasa de muestreo del audio es de 3600 Hz, pero el parámetro de solicitud sampleRate/sample_rate está establecido en 48000 (configuración de parámetro incorrecta).
    Utilice la herramienta ffprobe para obtener el contenedor, códec, tasa de muestreo, canales y otra información 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. Si none de las verificaciones anteriores revela un problema, agregue palabras clave personalizadas para mejorar el reconocimiento de términos específicos.