Qwen-Audio-3.x-ASR-Flash-Streaming/Fun-ASR-Realtime SDK Python

Este tópico descreve os parâmetros e interfaces do Python SDK para o Qwen-Audio-3.x-ASR-Flash-Streaming/Fun-ASR-Realtime modelo de reconhecimento de fala em tempo real.

Guia do usuário: Para descrições de modelos e orientações de seleção, consulte Fala para texto.

Pré-requisitos

• O serviço está ativado e você obteve uma chave API. Para se proteger contra riscos de segurança causados por vazamentos de código, configure a chave de API como uma variável de ambiente, em vez de codificá-lo em seu código.
• Instale o SDK DashScope mais recente.

Início rápido

A classe de reconhecimento fornece interfaces para chamadas de streaming bidirecionais e sem streaming. Escolha o método de chamada que atenda às suas necessidades:

• Chamada sem streaming: Reconhece um arquivo local e retorna o resultado completo em uma única resposta. Adequado para processar áudio pré-gravado.
• Chamada de streaming bidirecional: Reconhece um fluxo de áudio diretamente e gera resultados em tempo real. O fluxo de áudio pode vir de um dispositivo externo, como um microfone, ou ser lido de um arquivo local. Adequado para cenários que exigem feedback imediato.

Chamada sem streaming

Envie uma única tarefa de reconhecimento de fala em tempo real e obtenha o resultado do reconhecimento de forma síncrona, passando um arquivo local.

Instancie uma classe de reconhecimento, vincular parâmetros de solicitação e ligue call para executar o reconhecimento ou tradução e obter o resultado do reconhecimento (RecognitionResult).

Veja o exemplo completo.

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

# If you have not configured the environment variable, replace the following line with your API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

recognition = Recognition(model='qwen-audio-3.1-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(),
  ))

Chamada de streaming bidirecional

Envie uma única tarefa de reconhecimento de fala em tempo real e transmita os resultados do reconhecimento em tempo real implementando a interface de retorno de chamada.

Comece a transmitir reconhecimento de fala.

Instancie uma [classe de reconhecimento](#recognition-class), vincular [parâmetros de solicitação](#request-parameters) e uma [interface de retorno de chamada (RecognitionCallback)](#callback-interface-recognitioncallback) e ligue para o `start` método para iniciar o streaming de reconhecimento de fala.

Stream the audio

Ligue para o `send_audio_frame` método da [classe de reconhecimento](#recognition-class) em um loop para enviar o fluxo de áudio binário ao servidor em segmentos. O fluxo é lido de um arquivo local ou de um dispositivo, como um microfone.

Enquanto o áudio está sendo enviado, o servidor retorna os resultados do reconhecimento ao cliente em tempo real através do `on_event` método da [interface de retorno de chamada (RecognitionCallback)](#callback-interface-recognitioncallback).

Envie cerca de 100 ms de áudio por quadro e mantenha cada quadro entre 1 KB e 16 KB.

End the task

Ligue para o `stop` método da [classe de reconhecimento](#recognition-class) para encerrar o reconhecimento de fala.

Este método bloqueia o thread atual até que o `on_complete` ou `on_error` retorno de chamada da [interface de retorno de chamada (RecognitionCallback)](#callback-interface-recognitioncallback) é acionado.

Veja o exemplo completo.

Recognize microphone speech

  ```python
  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__':
    # If you have not configured the environment variable, replace the following line with your API Key: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

    # 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()
  ```

Recognize a local audio file

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

  # If you have not configured the environment variable, replace the following line with your API Key: dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

  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, message: str) -> None:
      print('Error occurred: ', message)
      print('Error details: ', 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.1-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(),
    ))
  ```

Parâmetros de solicitação

Defina parâmetros de solicitação por meio do construtor (__init__) da classe de reconhecimento.

opus/speex: Deve usar encapsulamento Ogg. wav: Deve usar codificação PCM. amr: Somente o tipo AMR-NB é suportado. | | manter_dialeto | bool | Não | Apoiado por qwen-audio-3.1-asr-flash-streaming apenas. O padrão é false, que transcreve dialetos para o chinês padrão. Definir como true para preservar expressões dialetais. Passe como um argumento de palavra-chave com o mesmo nome. Consulte referência da API para obter detalhes. | | vad_modelo | | Não | Apoiado por qwen-audio-3.1-asr-flash-streaming apenas. Definir como near_meeting_16k (campo próximo) ou far_field_meeting_16k (campo distante, padrão). Passe como um argumento de palavra-chave com o mesmo nome. Consulte referência da API para obter detalhes. | | vocabulário_id | | Não | O ID de uma lista de hot word pré-compilada. Gere esse ID antecipadamente chamando a API de criação de lista de palavras quentes. Passe o ID durante o reconhecimento para usar as palavras quentes da lista. Adequado para cenários onde o vocabulário é conhecido e relativamente estável, e onde é necessário reutilizar a mesma lista de palavras em solicitações. Para obter detalhes de uso, consulte Hotwords pré-compiladas. | | vocabulário | ditado | Não | Palavras quentes instantâneas. Passados como pares de valores-chave, onde a chave é o texto da palavra quente (string) e o valor é o peso da palavra quente (integer). Nenhuma lista de palavras quentes precisa ser criada com antecedência. O peso varia de [1, 5] ou é definido como 50: um valor em [1, 5] aumenta a probabilidade de o modelo gerar a palavra à medida que o valor aumenta; um valor de 50 designa uma palavra superquente, o que melhora muito a recuperação, mas o número de palavras superquentes não pode exceder 50. Adequado para otimização de palavra quente temporária em nível de sessão. Quando hotwords instantâneas e pré-compiladas são configuradas juntas, o sistema mescla os dois conjuntos. Se o conjunto mesclado contiver mais de 2.000 hotwords, o sistema selecionará aleatoriamente 2.000 para usar. Para obter detalhes de uso, consulte Hotwords instantâneas. Somente qwen-audio-3.1-asr-flash-streaming e qwen-audio-3.0-asr-flash-streaming suporta palavras quentes instantâneas. Exemplo:

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) | | semântica_pontuação_habilitada | bool | Não | Seja para ativar a segmentação semântica. Padrão: Falso. <ul><li>Verdadeiro: ativa a segmentação semântica e desativa a segmentação VAD.</li><li>Falso (padrão): habilita a segmentação VAD e desabilita a segmentação semântica.</li></ul> A segmentação semântica é mais precisa e adequada à transcrição de reuniões. A segmentação VAD (Voice Activity Detection) tem menor latência e se adapta a cenários interativos. | | max_frase_silêncio | interno | Não | O limite de silêncio do VAD para segmentação, em ms. Quando o silêncio após um segmento de fala ultrapassa esse limite, o sistema determina que a frase terminou. Quando semantic_punctuation_enabled estiver definido como verdadeiro, este parâmetro não será usado como critério para retornar sentence_end, mas defini-lo muito baixo pode afetar o desempenho do reconhecimento. Valor padrão: 1300. Valores válidos: [200, 6000]. | | multi_limite_modo_enabled | bool | Não | Só entra em vigor quando semantic_punctuation_enabled é falso. Se deve ativar o modo multi-limite. Quando ativado, evita que a segmentação VAD produza segmentos muito longos. Padrão: Falso. | | pontuação_predição_habilitado | bool | Não | Se a pontuação será adicionada automaticamente aos resultados de reconhecimento: <ul><li>Verdadeiro (padrão): Sim. Este valor não pode ser alterado.</li></ul> | | batimento cardíaco | bool | Não | Se deve ativar pacotes de pulsação. Padrão: Falso. <ul><li>Verdadeiro: mantém a conexão com o servidor ativa enquanto o áudio silencioso é enviado continuamente.</li><li>Falso (padrão): Mesmo quando o áudio silencioso é enviado continuamente, a conexão atinge o tempo limite e fecha após um período de tempo.</li></ul> Áudio silencioso refere-se ao conteúdo de um arquivo de áudio ou fluxo de dados que não contém sinal sonoro. Você pode gerar áudio silencioso de várias maneiras, como usando software de edição de áudio como Audacity ou Adobe Audition, ou usando uma ferramenta de linha de comando como FFmpeg. Este campo requer o SDK versão 1.23.1 ou posterior. | | idioma_dicas | lista[str] | Não | O idioma do áudio a ser reconhecido. Não há valor padrão; se não for definido, o modelo detectará o idioma automaticamente. Para o Qwen-Audio-3.x-ASR-Flash-Streaming série de modelos, você pode definir até 4 valores; se você definir mais de 4, apenas os 4 primeiros terão efeito. Para o Fun-ASR-Realtime série de modelos, você pode definir apenas 1 valor; se você definir vários valores, apenas o primeiro terá efeito. Códigos suportados: <ul><li>qwen-audio-3.1-asr-flash-streaming, qwen-audio-3.0-asr-flash-streaming, fun-asr-realtime: zh (chinês), en (inglês), ja (japonês), ko (coreano), vi (vietnamita), th (tailandês), id (indonésio), ms (malaio), tl (filipino), hi (hindi), ar (árabe), fr (francês), de (alemão), es (espanhol), pt (português), ru (russo), it (italiano), nl (holandês), sv (sueco), da (dinamarquês), fi (finlandês), no (norueguês), el (grego), pl (polonês), cs (checo), hu (húngaro), ro (romeno), bg (búlgaro), hr (croata), sk (eslovaco)</li></ul> | | fala_ruído_limiar | flutuar | Não | O limite para distinguir fala de ruído, usado para ajustar a sensibilidade da Detecção de Atividade de Voz (VAD). Valores válidos: [-1,0, 1,0]. <ul><li>Quanto mais próximo o valor estiver de -1: o limite de ruído diminui, então é mais provável que o ruído seja reconhecido como fala, o que pode fazer com que mais ruído seja transcrito.</li><li>Quanto mais próximo o valor estiver de +1: O limite de ruído aumenta, então é mais provável que a fala seja mal avaliada como ruído, o que pode fazer com que parte da fala seja filtrada.</li></ul> Este é um parâmetro de configuração avançado. Ajustá-lo pode afetar significativamente os resultados do reconhecimento. Recomendações: testar e verificar minuciosamente os resultados antes de ajustar; ajuste em pequenos incrementos com base no ambiente de áudio real (recomenda-se um passo de 0,1). | | especial_palavra_filtro | | Não | Especifica as palavras sensíveis a serem processadas durante o reconhecimento de fala e suporta a configuração de diferentes métodos de processamento para diferentes palavras sensíveis. Para obter detalhes, consulte Filtragem de palavras sensíveis. | | retorno de chamada | ReconhecimentoCallback | Não | Interface de retorno de chamada (RecognitionCallback). |

Parâmetros do método

Passe os seguintes parâmetros como argumentos de palavra-chave para o call ou start método do Recognition instância.

Quando você passa o contexto, as mensagens em context devem seguir uma ordem específica: as mensagens de contexto devem ser organizadas por turno de conversa e, dentro de cada turno, o user mensagem (input_text tipo) deve preceder seu correspondente assistant mensagem (text tipo).

Este campo requer a versão 1.25.23 ou posterior do SDK. Passe raw_input para o start ou call método do Recognition instância. |

Exemplo:

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

Recognition aula

Importar Recognition com from dashscope.audio.asr import *.

Interface de retorno de chamada (RecognitionCallback)

Durante uma chamada de streaming bidirecional, o servidor retorna informações e dados importantes do processo ao cliente por meio de retornos de chamada. Implemente os métodos de retorno de chamada para lidar com as informações e dados retornados pelo servidor.

Veja o exemplo.

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

  def on_event(self, result: RecognitionResult) -> None:
    sentence = result.get_sentence()
    if 'text' in sentence:
      print('RecognitionCallback text: ', sentence['text'])

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

  def on_error(self, message: str) -> None:
    print('An error occurred:', message)

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

callback = Callback()

Resposta

Resultado do reconhecimento (RecognitionResult)

RecognitionResult representa o resultado de um único reconhecimento em tempo real em uma chamada de streaming bidirecional ou o resultado de uma chamada sem streaming.

Informações da frase (Sentence)

Os membros da classe Sentença são os seguintes:

Informações de carimbo de data/hora em nível de palavra (Word)

Os membros da classe Word são os seguintes:

Códigos de erro

Se você encontrar erros, consulte Códigos de erro para solução de problemas.

Se o problema persistir, junte-se à comunidade de desenvolvedores para relatar seu problema e fornecer o ID da solicitação para investigação adicional.

Perguntas frequentes

Recursos

P: Como mantenho a conexão ativa durante longos períodos de silêncio?

Defina o heartbeat request parâmetro como true e continue enviando áudio silencioso para o servidor.

Áudio silencioso é o conteúdo de um arquivo ou fluxo de áudio que não contém sinal sonoro. Você pode gerar áudio silencioso de várias maneiras, como usando software de edição de áudio como Audacity ou Adobe Audition, ou ferramentas de linha de comando como FFmpeg.

P: Como faço para converter áudio para um formato compatível?

Utilize FFmpeg. Para mais uso, consulte o site oficial do 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

P: Como reconheço um arquivo local (gravação)?

Existem duas maneiras de reconhecer um arquivo local:

• Passar o caminho do arquivo local diretamente: Desta forma retorna o resultado completo somente após o término do reconhecimento, portanto não é adequado para cenários que necessitam de feedback imediato. Consulte Chamada sem streaming e passe o caminho do arquivo para o call método da classe de reconhecimento para reconhecer a gravação diretamente.
• Converter o arquivo local em um fluxo binário para reconhecimento: Desta forma, reconhece o arquivo durante o streaming dos resultados, adequando-se a cenários que precisam de feedback imediato. Consulte Chamada de streaming bidirecional e envia o fluxo binário ao servidor para reconhecimento por meio do send_audio_frame método da classe de reconhecimento.

Solução de problemas

P: Por que a fala não pode ser reconhecida (sem resultado de reconhecimento)?

1. Verifique se o formato de áudio (format) e taxa de amostragem (sampleRate/sample_rate) nos parâmetros da solicitação estão corretos e atendem às restrições de parâmetro. Erros comuns incluem:

   • O arquivo de áudio tem extensão .wav, mas na verdade está no formato MP3, enquanto o format parâmetro de solicitação está definido como mp3 (configuração de parâmetro incorreta).
   • A taxa de amostragem de áudio é de 3600 Hz, mas o sampleRate/sample_rate parâmetro de solicitação está definido como 48000 (configuração de parâmetro incorreta).

   Use o ffprobe ferramenta para obter o contêiner, codec, taxa de amostragem, canais e outras informações do áudio:

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

2. Se nenhuma das verificações acima revelar um problema, adicione hotwords personalizados para melhorar o reconhecimento de termos específicos.