Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Qwen-Audio-ASR / Fun-ASR Python SDK

Última atualização: Nov 19, 2026

Pré-requisitos

Ative o service e Obtain an API key. Para evitar riscos de segurança causados por vazamento de código, Configure API key as an environment variable em vez de codificá-la diretamente no código.

Início rápido

Use os mesmos exemplos para os modelos abaixo. Substitua o ID do modelo conforme a tabela.

ModeloID do modelo no exemplo
Qwen-Audio-ASR-Streamingqwen-audio-3.0-asr-flash-streaming
Qwen-Audio-ASR-Messageqwen-audio-3.1-asr-flash-message
Oferece suporte apenas à taxa de amostragem de 16000 Hz.
Fun-ASR-Realtimefun-asr-realtime

O recurso principal (client.audio.asr) fornece interfaces para chamadas sem streaming e com streaming bidirecional. Escolha o método de chamada adequado às suas necessidades:

  • Chamada sem streaming (recognize_file): reconhece um arquivo local; o SDK envia o áudio automaticamente em blocos e conduz a tarefa até o fim. Ideal para processar áudio pré-gravado.
  • Chamada com streaming bidirecional (sessão recognize): reconhece um fluxo de áudio diretamente e gera resultados em tempo real. O fluxo pode vir de um dispositivo externo, como microfone, ou ser lido de um arquivo local. Recomendado 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 de forma síncrona e bloqueante ao passar um arquivo local.

Chame o método recognize_file do recurso principal (client.audio.asr) para vincular os parâmetros da solicitação e passar o caminho do arquivo local, e itere os eventos do servidor para obter os resultados do reconhecimento.

import os
import dashscope

# A API Key da região Singapura é diferente da da região Pequim. Obtenha uma API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Reconhece um arquivo de áudio local: recognize_file envia o áudio automaticamente em blocos e conduz a tarefa até o fim
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='qwen-audio-3.0-asr-flash-streaming',
        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('Resultado do reconhecimento:', sentence['text'])

Chamada com streaming bidirecional

Envie uma única tarefa de reconhecimento de fala em tempo real e transmita os resultados continuamente por meio da iteração de eventos.

  1. Inicie o reconhecimento de fala em streaming.

    Chame o método recognize do recurso principal (client.audio.asr) para criar a sessão de reconhecimento e vincular os parâmetros da solicitação; entrar no contexto with (que chama automaticamente o método start para estabelecer a conexão e enviar a tarefa) inicia o reconhecimento de fala em streaming.

  2. Transmita o áudio.

    Chame o método send_audio_frame da sessão em loop para enviar ao servidor, em segmentos, o fluxo de áudio binário lido de um arquivo local ou de um dispositivo, como microfone.

    O envio e o recebimento devem ocorrer de forma concorrente: a thread de recepção itera os eventos do servidor por meio do método events() da sessão, retornando os resultados de reconhecimento ao cliente em tempo real.

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

  3. Encerre a tarefa.

    Chame o método stop da sessão para encerrar o reconhecimento de fala.

    Esse método apenas notifica o servidor de que a entrada terminou; a thread de recepção deve continuar consumindo events() até o evento task-finished para obter os últimos resultados de reconhecimento e as estatísticas. Erros da camada ws são lançados como exceções DashScopeError e podem ser capturados com try/except no envio/recebimento.

import os
import signal  # para tratamento de eventos de teclado (pressione "Ctrl+C" para encerrar a gravação)
import sys

import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor

mic = None
stream = None

# Define os parâmetros de gravação
sample_rate = 16000  # Use a mesma taxa de amostragem para a captura e o reconhecimento. O Qwen-Audio-ASR-Message aceita apenas 16000 Hz.
channels = 1  # canal mono
dtype = 'int16'  # tipo de dados
format_pcm = 'pcm'  # o formato dos dados de áudio
block_size = 3200  # número de frames por buffer

# Receptor de eventos de reconhecimento de fala em tempo 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('Texto reconhecido: ', sentence['text'])
            if sentence.get('sentence_end'):
                print(
                    'Fim da frase do reconhecimento, request_id:%s, usage:%s'
                    % (rec.request_id, rec.usage))

def signal_handler(sig, frame):
    print('Ctrl+C pressionado, interrompendo o reconhecimento...')
    # Interrompe o reconhecimento
    recognition.stop()
    print('Reconhecimento interrompido.')
    print(
        '[Métrica] requestId: {}, atraso do primeiro pacote (ms): {}, atraso do último pacote (ms): {}'
        .format(
            recognition.request_id,
            recognition.first_package_delay,
            recognition.last_package_delay,
        ))
    # Encerra o programa de forma forçada
    sys.exit(0)

# função principal
if __name__ == '__main__':
    # A API Key da região Singapura é diferente da da região Pequim. Obtenha uma API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
    client = dashscope.Client(
        api_key=os.environ.get('DASHSCOPE_API_KEY'),
        # A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
    )

    # Chama o serviço de reconhecimento; você pode personalizar os parâmetros de reconhecimento, como model, format
    # e sample_rate
    with client.audio.asr.recognize(
            model='qwen-audio-3.0-asr-flash-streaming',
            format=format_pcm,
            # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr'; consulte os formatos compatíveis na documentação
            sample_rate=sample_rate,
    ) as recognition:
        # Abre o microfone
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=sample_rate,
                          input=True)
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, recognition)
            try:
                # Envia o áudio do microfone até que "Ctrl+C" seja pressionado
                while stream:
                    data = stream.read(3200, exception_on_overflow=False)
                    recognition.send_audio_frame(data)
                recognition.stop()
                receiver.result()
            finally:
                # close deve ser executado dentro do contexto do pool para desbloquear o receptor
                recognition.close()
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None
import os
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor

# A API Key da região Singapura é diferente da da região Pequim. Obtenha uma API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

from datetime import datetime

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

# Receptor de eventos de reconhecimento de fala em tempo 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(get_timestamp() + ' Texto reconhecido: ', sentence['text'])
        if sentence.get('sentence_end'):
            print(get_timestamp() +
                  'Fim da frase do reconhecimento, request_id:%s, usage:%s'
                  % (rec.request_id, rec.usage))

with client.audio.asr.recognize(
        model='qwen-audio-3.0-asr-flash-streaming',
        format='wav',
        sample_rate=16000,
) as recognition:
    with ThreadPoolExecutor(max_workers=1) as pool:
        receiver = pool.submit(receive_events, recognition)
        try:
            audio_data: bytes = None
            f = open("{YOUR_AUDIO_FILE}", 'rb')
            if os.path.getsize("{YOUR_AUDIO_FILE}"):
                # Lê todos os dados do arquivo para o buffer de uma só vez
                file_buffer = f.read()
                f.close()
                print("Iniciando o reconhecimento")

                # Envia do buffer blocos de 3200 bytes por vez
                buffer_size = len(file_buffer)
                offset = 0
                chunk_size = 3200

                while offset < buffer_size:
                    # Calcula o tamanho do bloco de dados a enviar nesta iteração
                    remaining_bytes = buffer_size - offset
                    current_chunk_size = min(chunk_size, remaining_bytes)

                    # Extrai o bloco de dados atual do buffer
                    audio_data = file_buffer[offset:offset + current_chunk_size]

                    # Envia o frame de dados de áudio
                    recognition.send_audio_frame(audio_data)
                    # Atualiza o deslocamento
                    offset += current_chunk_size

                    # Adiciona um atraso para simular a transmissão em tempo real
                    time.sleep(0.1)

                recognition.stop()
                receiver.result()
            else:
                raise Exception(
                    'O arquivo fornecido estava vazio (zero bytes)')
        finally:
            # close deve ser executado dentro do contexto do pool para desbloquear o receptor
            recognition.close()

print(
    '[Métrica] requestId: {}, atraso do primeiro pacote (ms): {}, atraso do último pacote (ms): {}'
    .format(
        recognition.request_id,
        recognition.first_package_delay,
        recognition.last_package_delay,
    ))

Parâmetros da solicitação

Qwen-Audio-ASR-Streaming

Referência comum

Consulte a referência atual de Qwen-Audio-ASR-Streaming Python SDK.

Defina os parâmetros da solicitação por meio dos métodos recognize/recognize_file do recurso principal (client.audio.asr): model, format, sample_rate e vocabulary_id são argumentos nomeados. Passe language_hints no dicionário parameters.

ParâmetroTipoObrigatórioDescrição
modelstr

Sim

O nome do modelo.
sample_rateint

Sim

A taxa de amostragem em Hz. Qualquer taxa é compatível.

formatstr

Sim

Formato do áudio.

Valores válidos:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

Importanteopus/speex: devem usar encapsulamento Ogg.

wav: deve usar codificação PCM.

amr: apenas o tipo AMR-NB é aceito.

keep_dialectbool

Não

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash-streaming.

Padrão: false, que transcreve dialetos em chinês padrão. Defina como true para preservar expressões dialetais. Passe este campo no dicionário parameters.

vad_modelstr

Não

ObservaçãoAplica-se apenas a qwen-audio-3.1-asr-flash-streaming.

Modelo VAD: near_meeting_16k (campo próximo) ou far_field_meeting_16k (campo distante, padrão). Passe este campo no dicionário parameters.

vocabulary_idstr

Não

ID de uma lista de palavras-chave pré-compilada.

Gere esse ID antecipadamente chamando a API de criação de lista de palavras-chave. Passe o ID durante o reconhecimento para usar as palavras-chave da lista.

Indicado para cenários em que o vocabulário é conhecido e relativamente estável e quando você precisa reutilizar a mesma lista de palavras entre solicitações.

Para detalhes de uso, consulte Precompiled hotwords.

vocabularydict

Não

Palavras-chave instantâneas.

Passadas como pares chave-valor, em que a chave é o texto da palavra-chave (string) e o valor é o peso da palavra-chave (integer). Não é necessário criar uma lista de palavras-chave antecipadamente. O peso varia de [1, 5] ou é definido como 50: um valor em [1, 5] aumenta a probabilidade de o modelo gerar a palavra conforme o valor cresce; um valor de 50 designa uma super palavra-chave, que melhora significativamente o recall, mas o número de super palavras-chave não pode exceder 50.

Adequado para otimização temporária de palavras-chave no nível da sessão.

Quando configurado junto com palavras-chave pré-compiladas, apenas as palavras-chave instantâneas têm efeito. Para detalhes de uso, consulte Instant hotwords.

Exemplo:

import os
import dashscope

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

# As palavras-chave instantâneas são passadas por meio de parameters
vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.0-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
max_sentence_silenceint

Não

Limiar de silêncio VAD para segmentação, em ms. Quando o silêncio após um segmento de fala excede esse limiar, o sistema determina que a frase terminou.

Valor padrão: 800.

Valores válidos: [200, 6000].

multi_threshold_mode_enabledbool

Não

Define se o modo de múltiplos limiares deve ser ativado. Quando ativado, impede que a segmentação VAD produza segmentos excessivamente longos.

Padrão: False.

punctuation_prediction_enabledbool

Não

Define se a pontuação deve ser adicionada automaticamente aos resultados de reconhecimento:

  • True (padrão): sim. Este valor não pode ser alterado.
heartbeatbool

Não

Define se os pacotes de heartbeat devem ser ativados.

Padrão: False.

  • True: mantém a conexão com o servidor ativa enquanto áudio silencioso é enviado continuamente.
  • False (padrão): mesmo quando áudio silencioso é enviado continuamente, a conexão expira e fecha após um período de tempo.

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

O uso deste campo requer o SDK 2.0.1 ou posterior.

language_hintslist[str]

Não

Idioma do áudio a ser reconhecido. Não há valor padrão; se não definido, o modelo detecta o idioma automaticamente.

Você pode definir até 4 valores. Se definir mais, somente os 4 primeiros terão efeito.

Clique em para visualizar os códigos de idioma aceitos

  • 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: Tcheco
  • hu: Húngaro
  • ro: Romeno
  • bg: Búlgaro
  • hr: Croata
  • sk: Eslovaco
speech_noise_thresholdfloat

Não

Limiar 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].

Descrições dos valores:

  • Quanto mais próximo de -1: o limiar de ruído diminui, tornando mais provável que ruído seja reconhecido como fala, o que pode causar a transcrição de mais ruído.
  • Quanto mais próximo de +1: o limiar de ruído aumenta, tornando mais provável que fala seja erroneamente julgada como ruído, o que pode filtrar parte da fala.

Este é um parâmetro de configuração avançada. Ajustá-lo pode afetar significativamente os resultados de reconhecimento. Recomendações:

  • Teste e verifique minuciosamente os resultados antes de ajustar.
  • Ajuste em pequenos incrementos com base no ambiente de áudio real (recomenda-se um passo de 0.1).
special_word_filterstr

Não

Especifica as palavras sensíveis a serem processadas durante o reconhecimento de fala e permite definir diferentes métodos de processamento para cada uma. Para detalhes, consulte Sensitive word filtering.

Passe o contexto em input ao criar a sessão com recognize.

ParâmetroTipoObrigatórioDescrição
inputdict

Não

Objeto de entrada usado para passar o contexto da conversa. O aprimoramento de contexto melhora a precisão do reconhecimento para termos específicos de domínio. Para uso, consulte Quick start.

O dict deve incluir uma chave context cujo valor é uma lista de mensagens (list[dict]). Cada mensagem contém os seguintes campos:

  • role (str, obrigatório): a função da mensagem. user representa os resultados de reconhecimento de turnos anteriores do usuário ou uma lista de palavras específicas de domínio. assistant representa as respostas do modelo de linguagem grande de turnos anteriores.
  • content (list[dict], obrigatório): a lista de conteúdo da mensagem. Cada elemento contém type (str; definido como input_text quando role é user, e text quando role é assistant) e text (str, o conteúdo de texto).

ImportanteLimites: mensagens de contexto dos tipos input_text e text são limitadas a 5 mensagens cada. Quando o limite é excedido, apenas as 5 mensagens mais recentes são retidas. O comprimento total do texto por turno de contexto não pode exceder 400 caracteres, e qualquer excesso é truncado a partir do final.

ImportanteAo passar 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, a mensagem user (tipo input_text) deve preceder sua mensagem assistant correspondente (tipo text).

ObservaçãoO uso deste campo requer o SDK 2.0.1 ou posterior.

Passe input para o método recognize do recurso principal (client.audio.asr):

# Constrói a entrada a ser passada
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?"
                }
            ]
        }
    ]
}

# Passa por meio do argumento input ao criar a sessão de reconhecimento
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.0-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Qwen-Audio-ASR-Message

Referência comum

Consulte a referência atual de Qwen-Audio-ASR-Message Python SDK.

Defina os parâmetros da solicitação por meio dos métodos recognize/recognize_file do recurso principal (client.audio.asr): model, format, sample_rate e vocabulary_id são argumentos nomeados. Passe language_hints no dicionário parameters.

ParâmetroTipoObrigatórioDescrição
modelstr

Sim

O nome do modelo.
sample_rateint

Sim

A taxa de amostragem em Hz. Apenas 16000 é compatível.

formatstr

Sim

Formato do áudio.

Valores válidos:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

Importanteopus/speex: devem usar encapsulamento Ogg.

wav: deve usar codificação PCM.

amr: apenas o tipo AMR-NB é aceito.

keep_dialectbool

Não

Padrão: false, que transcreve dialetos em chinês padrão. Defina como true para preservar expressões dialetais. Passe este campo no dicionário parameters.

Este parâmetro se aplica somente aos resultados finais (sentence_end=true) e não é compatível com resultados intermediários (sentence_end=false).

vad_modelstr

Não

Modelo VAD: near_meeting_16k (campo próximo) ou far_field_meeting_16k (campo distante, padrão). Passe este campo no dicionário parameters.

disfluency_removal_enabledbool

Não

Indica se palavras de preenchimento devem ser removidas e o texto aprimorado. Padrão: false. Defina como true para ativar. Passe como argumento nomeado com o mesmo nome.

intermediate_result_enabledbool

Não

Indica se resultados intermediários de streaming devem ser retornados. Padrão: false. Defina como true para recebê-los. Passe este campo no dicionário parameters.

vocabulary_idstr

Não

ID de uma lista de palavras-chave pré-compilada.

Gere esse ID antecipadamente chamando a API de criação de lista de palavras-chave. Passe o ID durante o reconhecimento para usar as palavras-chave da lista.

Indicado para cenários em que o vocabulário é conhecido e relativamente estável e quando você precisa reutilizar a mesma lista de palavras entre solicitações.

Para detalhes de uso, consulte Precompiled hotwords.

vocabularydict

Não

Palavras-chave instantâneas.

Passadas como pares chave-valor, em que a chave é o texto da palavra-chave (string) e o valor é o peso da palavra-chave (integer). Não é necessário criar uma lista de palavras-chave antecipadamente. O peso varia de [1, 5] ou é definido como 50: um valor em [1, 5] aumenta a probabilidade de o modelo gerar a palavra conforme o valor cresce; um valor de 50 designa uma super palavra-chave, que melhora significativamente o recall, mas o número de super palavras-chave não pode exceder 50.

Adequado para otimização temporária de palavras-chave no nível da sessão.

Quando configurado junto com palavras-chave pré-compiladas, apenas as palavras-chave instantâneas têm efeito. Para detalhes de uso, consulte Instant hotwords.

ImportanteApenas qwen-audio-3.1-asr-flash-message aceita palavras-chave instantâneas.

Exemplo:

import os
import dashscope

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

# As palavras-chave instantâneas são passadas por meio 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]

Não

Idioma do áudio a ser reconhecido. Não há valor padrão; se não definido, o modelo detecta o idioma automaticamente.

Você pode definir até 4 valores. Se definir mais, somente os 4 primeiros terão efeito.

Clique em para visualizar os códigos de idioma aceitos

  • 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: Tcheco
  • hu: Húngaro
  • ro: Romeno
  • bg: Búlgaro
  • hr: Croata
  • sk: Eslovaco

Passe este campo no dicionário parameters, por exemplo parameters={"language_hints": ["zh"]}.

Este parâmetro se aplica somente aos resultados finais (sentence_end=true) e não é compatível com resultados intermediários (sentence_end=false).

max_sentence_silenceint

Não

Limite de silêncio do VAD para segmentação, em milissegundos. A frase termina quando o silêncio após a fala ultrapassa esse limite. Padrão: 800. Intervalo válido: [200, 6000].

heartbeatbool

Não

Define se os pacotes de heartbeat devem ser ativados.

Padrão: False.

  • True: mantém a conexão com o servidor ativa enquanto áudio silencioso é enviado continuamente.
  • False (padrão): mesmo quando áudio silencioso é enviado continuamente, a conexão expira e fecha após um período de tempo.

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

Este campo foi introduzido no SDK 1.23.1 e já está incluído na versão 2.0.1 ou posterior.

speech_noise_thresholdfloat

Não

Limiar 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].

Descrições dos valores:

  • Quanto mais próximo de -1: o limiar de ruído diminui, tornando mais provável que ruído seja reconhecido como fala, o que pode causar a transcrição de mais ruído.
  • Quanto mais próximo de +1: o limiar de ruído aumenta, tornando mais provável que fala seja erroneamente julgada como ruído, o que pode filtrar parte da fala.

Este é um parâmetro de configuração avançada. Ajustá-lo pode afetar significativamente os resultados de reconhecimento. Recomendações:

  • Teste e verifique minuciosamente os resultados antes de ajustar.
  • Ajuste em pequenos incrementos com base no ambiente de áudio real (recomenda-se um passo de 0.1).

Passe o contexto em input ao criar a sessão com recognize.

ParâmetroTipoObrigatórioDescrição
inputdict

Não

Objeto de entrada usado para passar o contexto da conversa. O aprimoramento de contexto melhora a precisão do reconhecimento para termos específicos de domínio. Para uso, consulte Quick start.

ImportanteOs modelos qwen-audio-3.1-asr-flash-message aceitam o parâmetro de contexto.

O dict deve incluir uma chave context cujo valor é uma lista de mensagens (list[dict]). Cada mensagem contém os seguintes campos:

  • role (str, obrigatório): a função da mensagem. user representa os resultados de reconhecimento de turnos anteriores do usuário ou uma lista de palavras específicas de domínio. assistant representa as respostas do modelo de linguagem grande de turnos anteriores.
  • content (list[dict], obrigatório): a lista de conteúdo da mensagem. Cada elemento contém type (str; definido como input_text quando role é user, e text quando role é assistant) e text (str, o conteúdo de texto).

ImportanteLimites: mensagens de contexto dos tipos input_text e text são limitadas a 5 mensagens cada. Quando o limite é excedido, apenas as 5 mensagens mais recentes são retidas. O comprimento total do texto por turno de contexto não pode exceder 400 caracteres, e qualquer excesso é truncado a partir do final.

ImportanteAo passar 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, a mensagem user (tipo input_text) deve preceder sua mensagem assistant correspondente (tipo text).

ObservaçãoEste campo foi introduzido no SDK 1.25.23 e já está incluído na versão 2.0.1 ou posterior.

Passe input para o método recognize do recurso principal (client.audio.asr):

# Constrói a entrada a ser passada
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?"
                }
            ]
        }
    ]
}

# Passa por meio do argumento input ao criar a sessão de reconhecimento
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Fun-ASR-Realtime

Referência comum

Consulte a referência atual de Fun-ASR-Realtime Python SDK.

Defina os parâmetros da solicitação por meio dos métodos recognize/recognize_file do recurso principal (client.audio.asr): model, format, sample_rate e vocabulary_id são argumentos nomeados. Passe max_sentence_silence e language_hints no dicionário parameters.

ParâmetroTipoObrigatórioDescrição
modelstr

Sim

O nome do modelo.
sample_rateint

Sim

Taxa de amostragem, em Hz.

Valores válidos: modelos de 8 kHz aceitam apenas 8000 Hz; outros modelos aceitam qualquer taxa de amostragem.

formatstr

Sim

Formato do áudio.

Valores válidos:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

Importanteopus/speex: devem usar encapsulamento Ogg.

wav: deve usar codificação PCM.

amr: apenas o tipo AMR-NB é aceito.

vocabulary_idstr

Não

ID de uma lista de palavras-chave pré-compilada.

Gere esse ID antecipadamente chamando a API de criação de lista de palavras-chave. Passe o ID durante o reconhecimento para usar as palavras-chave da lista.

Indicado para cenários em que o vocabulário é conhecido e relativamente estável e quando você precisa reutilizar a mesma lista de palavras entre solicitações.

Para detalhes de uso, consulte Precompiled hotwords.

max_sentence_silenceint

Não

Limiar de silêncio VAD para segmentação, em ms. Quando o silêncio após um segmento de fala excede esse limiar, o sistema determina que a frase terminou.

Valor padrão: 1300.

Valores válidos: [200, 6000].

multi_threshold_mode_enabledbool

Não

Define se o modo de múltiplos limiares deve ser ativado. Quando ativado, impede que a segmentação VAD produza segmentos excessivamente longos.

Padrão: False.

punctuation_prediction_enabledbool

Não

Define se a pontuação deve ser adicionada automaticamente aos resultados de reconhecimento:

  • True (padrão): sim. Este valor não pode ser alterado.
heartbeatbool

Não

Define se os pacotes de heartbeat devem ser ativados.

Padrão: False.

  • True: mantém a conexão com o servidor ativa enquanto áudio silencioso é enviado continuamente.
  • False (padrão): mesmo quando áudio silencioso é enviado continuamente, a conexão expira e fecha após um período de tempo.

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

Este campo requer a versão 2.0.1 ou posterior do SDK.

language_hintslist[str]

Não

Idioma do áudio a ser reconhecido. Não há valor padrão; se não definido, o modelo detecta o idioma automaticamente.

Você pode definir 1 valor. Se definir mais, somente o primeiro terá efeito.

Clique em para visualizar os códigos de idioma aceitos

  • 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: Tcheco
    • hu: Húngaro
    • ro: Romeno
    • bg: Búlgaro
    • hr: Croata
    • sk: Eslovaco
  • fun-asr-realtime-2026-02-28:

    • zh: Chinês
    • en: Inglês
    • ja: Japonês
  • fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28:

    • zh: Chinês
speech_noise_thresholdfloat

Não

Limiar 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].

Descrições dos valores:

  • Quanto mais próximo de -1: o limiar de ruído diminui, tornando mais provável que ruído seja reconhecido como fala, o que pode causar a transcrição de mais ruído.
  • Quanto mais próximo de +1: o limiar de ruído aumenta, tornando mais provável que fala seja erroneamente julgada como ruído, o que pode filtrar parte da fala.

Este é um parâmetro de configuração avançada. Ajustá-lo pode afetar significativamente os resultados de reconhecimento. Recomendações:

  • Teste e verifique minuciosamente os resultados antes de ajustar.
  • Ajuste em pequenos incrementos com base no ambiente de áudio real (recomenda-se um passo de 0.1).
special_word_filterstr

Não

Especifica as palavras sensíveis a serem processadas durante o reconhecimento de fala e permite definir diferentes métodos de processamento para cada uma. Para detalhes, consulte Sensitive word filtering.

Passe o contexto em input ao criar a sessão com recognize.

ParâmetroTipoObrigatórioDescrição
inputdict

Não

Objeto de entrada usado para passar o contexto da conversa. O aprimoramento de contexto melhora a precisão do reconhecimento para termos específicos de domínio. Para uso, consulte Melhorar a precisão do reconhecimento.

ImportanteOs modelos fun-asr-realtime aceitam o parâmetro de contexto.

O dict deve incluir uma chave context cujo valor é uma lista de mensagens (list[dict]). Cada mensagem contém os seguintes campos:

  • role (str, obrigatório): a função da mensagem. user representa os resultados de reconhecimento de turnos anteriores do usuário ou uma lista de palavras específicas de domínio. assistant representa as respostas do modelo de linguagem grande de turnos anteriores.
  • content (list[dict], obrigatório): a lista de conteúdo da mensagem. Cada elemento contém type (str; definido como input_text quando role é user, e text quando role é assistant) e text (str, o conteúdo de texto).

ImportanteLimites: mensagens de contexto dos tipos input_text e text são limitadas a 5 mensagens cada. Quando o limite é excedido, apenas as 5 mensagens mais recentes são retidas. O comprimento total do texto por turno de contexto não pode exceder 400 caracteres, e qualquer excesso é truncado a partir do final.

ImportanteAo passar 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, a mensagem user (tipo input_text) deve preceder sua mensagem assistant correspondente (tipo text).

ObservaçãoEste campo requer a versão 2.0.1 ou posterior do SDK.

Passe-o por meio do parâmetro input ao criar a sessão de reconhecimento:

# Construa o input a ser passado
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?"
                }
            ]
        }
    ]
}

# Passe-o por meio do parâmetro input ao criar a sessão de reconhecimento
recognition = client.audio.asr.recognize(
    model='fun-asr-realtime',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Referência da API

Interfaces comuns

Informações da frase (Sentence)

Os membros da classe Sentence são os seguintes:

ParâmetroTipoDescrição
begin_timeintTempo de início da frase, em ms.
end_timeintTempo de término da frase, em ms.
textstrTexto reconhecido.
wordsUma lista de Word-level timestamp information (Word)Informações de timestamp no nível da palavra.

Informações de timestamp no nível da palavra (Word)

Os membros da classe Word são os seguintes:

ParâmetroTipoDescrição
begin_timeintTempo de início da palavra, em ms.
end_timeintTempo de término da palavra, em ms.
textstrA palavra.
punctuationstrA pontuação.

Qwen-Audio-ASR-Streaming / Qwen-Audio-ASR-Message

Recurso principal (client.audio.asr)

A capacidade de reconhecimento de fala em tempo real está montada no recurso client.audio.asr: recognize cria a sessão de reconhecimento com streaming bidirecional (Recognition) e recognize_file realiza o reconhecimento único de um arquivo local.

Método membroAssinatura do métodoDescrição
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

Cria a sessão de reconhecimento com streaming bidirecional; ao entrar no contexto with, o método start é chamado automaticamente para estabelecer a conexão e enviar a tarefa.

O envio de áudio e o consumo de eventos devem ocorrer de forma concorrente (use em conjunto com send_audio_frame, events()/results() e stop).

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

Chamada sem streaming baseada em arquivo local: envia o áudio automaticamente em blocos, conduz a tarefa até o fim e produz os eventos do servidor um a um. Este método requer permissão de leitura no arquivo reconhecido.

start
def start(self)

Inicia o reconhecimento de fala: estabelece a conexão, envia a tarefa e aguarda task-started. É chamado automaticamente ao entrar no contexto with; o áudio só pode ser enviado após o sucesso da inicialização.

send_audio_frame
def send_audio_frame(self, buffer: bytes)

Envia áudio. Mantenha cada quadro de áudio enviado nem muito grande nem muito pequeno: cerca de 100 ms por quadro, entre 1 KB e 16 KB.

Os resultados de reconhecimento são obtidos por meio da iteração de eventos (events()/results()).

stop
def stop(self)

Interrompe o reconhecimento de fala: apenas notifica o servidor de que a entrada terminou; a thread de recepção deve continuar consumindo events() até o evento task-finished.

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

Itera os eventos do servidor: events() produz eventos dict brutos (o texto reconhecido está em payload.output.sentence); results() produz apenas frames de resultado de reconhecimento, retornando objetos tipados Resultado de reconhecimento (RecognitionResult) (frames de heartbeat já filtrados).

close
def close(self)

Fecha a sessão de reconhecimento. Chamado automaticamente ao sair do 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

Obtém o request_id, o atraso do primeiro pacote (latência desde o envio do primeiro pacote de áudio até o recebimento do primeiro resultado de reconhecimento) e o atraso do último pacote (tempo desde o envio do comando stop até o recebimento do último resultado de reconhecimento); use após a conclusão da tarefa. last_response é a última mensagem bruta lida com sucesso e pode ser usada para recuperar erros de task-failed. Ainda podem ser lidos após o fechamento da sessão.

Iteração de eventos (events()/results())

Durante uma chamada com streaming bidirecional, o servidor retorna informações-chave de processo e dados ao cliente por meio de eventos. Você precisa iterar, na thread de recepção, os events() da sessão (eventos dict brutos) ou os results() (frames tipados de resultado de reconhecimento) para processar as informações ou os dados retornados pelo servidor.

# Itera os eventos brutos: o texto reconhecido está em 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('Texto reconhecido:', sentence['text'])


# Ou itera apenas os frames de resultado de reconhecimento (retorna RecognitionResult, frames de heartbeat já filtrados)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Texto reconhecido:', sentence['text'])
Método/eventoConteúdo produzidoValor de retornoDescrição
event["header"]["event"] == "task-started"

Evento task-started

Nenhum

Lido internamente por start(); a resposta de inicialização é salva em last_response e não é produzida novamente por events().

def events(self) -> Iterator[Dict]

event: evento dict do servidor

Iterador

Produz um evento quando o servidor responde. O resultado do reconhecimento está em payload.output.sentence; pode haver eventos de heartbeat ou de texto vazio, que podem ser ignorados conforme necessário. Deve ser consumido continuamente por uma única thread de recepção; não crie vários leitores em paralelo.

def results(self) -> Iterator[RecognitionResult]

result: Resultado de reconhecimento (RecognitionResult)

Iterador

Produz apenas frames de resultado de reconhecimento (frames de heartbeat já filtrados); a iteração termina após o retorno de todos os resultados.

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

Exceção DashScopeError

Nenhum

Lançada na thread de envio/recepção quando ocorre um erro; pode ser capturada com try/except.

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

Evento task-finished

Nenhum

Produzido por events() quando o servidor conclui todo o reconhecimento; a iteração termina em seguida. Esse evento ainda deve ser lido após o envio de stop().

Resultado de reconhecimento (RecognitionResult)

RecognitionResult representa um frame de resultado de reconhecimento produzido pela iteração results() da sessão (utilizável tanto na chamada com streaming bidirecional quanto na chamada sem streaming; events() produz eventos dict brutos — use results() caso precise dessa visualização tipada).

Método membroAssinatura do métodoDescrição
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

Obtém a frase reconhecida atual e suas informações de timestamp; retorna Dict[str, Any] (informação de uma única frase).

Para detalhes, consulte Informações da frase (Sentence).

request_id
result.request_id

O request_id da solicitação correspondente ao evento atual.

is_sentence_end
def is_sentence_end(self) -> bool

Determina se a frase atual terminou. Este método verifica se o campo end_time na informação de frase única retornada por get_sentence() é None: um end_time diferente de None indica que a frase terminou.

Qwen-Audio-ASR-Streaming

Interfaces principais

Resposta

Qwen-Audio-ASR-Message

Interfaces principais

Resposta

Fun-ASR-Realtime

Interfaces principais

Recurso principal (client.audio.asr)

O reconhecimento de fala em tempo real é montado no recurso client.audio.asr: recognize cria uma sessão de reconhecimento com streaming bidirecional (Recognition) e recognize_file faz o reconhecimento de um arquivo local em uma única chamada.

Método membroAssinatura do métodoDescrição

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
Cria uma sessão de reconhecimento com streaming bidirecional. A entrada no contexto with chama automaticamente start para estabelecer a conexão e enviar a tarefa.

O envio de áudio e o consumo de eventos devem ocorrer de forma concorrente (use em conjunto com send_audio_frame, events()/results() e stop).

recognize_file

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
Chamada sem streaming baseada em arquivo local: envia o áudio automaticamente em blocos e conduz a tarefa até o fim, produzindo os eventos do servidor um a um. Este método requer permissão de leitura no arquivo.

start

def start(self)
Inicia o reconhecimento de fala: estabelece a conexão, envia a tarefa e aguarda task-started. É chamado automaticamente na entrada do contexto with; o áudio só pode ser enviado após um início bem-sucedido.

send_audio_frame

def send_audio_frame(self, buffer: bytes)
Envia áudio. Mantenha cada quadro de áudio enviado nem muito grande nem muito pequeno: cerca de 100 ms por quadro, entre 1 KB e 16 KB.

Os resultados de reconhecimento são obtidos iterando events()/results().

stop

def stop(self)
Interrompe o reconhecimento de fala: apenas notifica o servidor de que a entrada terminou. A thread receptora deve continuar consumindo events() até o evento task-finished.

events / results

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
Itera os eventos do servidor: events() produz eventos dict brutos (o texto reconhecido está em payload.output.sentence); results() produz apenas os frames de resultado de reconhecimento, retornando objetos tipados Resultado de reconhecimento (RecognitionResult) (frames de heartbeat já filtrados).

close

def close(self)
Fecha a sessão de reconhecimento. É chamado automaticamente na saída do 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
Obtém o request_id, o atraso do primeiro pacote (a latência desde o envio do primeiro pacote de áudio até o recebimento do primeiro resultado de reconhecimento) e o atraso do último pacote (o tempo desde o envio do comando stop até o recebimento do último resultado de reconhecimento), usados após a conclusão da tarefa; last_response é a última mensagem bruta lida com sucesso, útil para recuperar erros de task-failed. Continuam legíveis após o fechamento da sessão.
Iteração de eventos (events()/results())

Durante uma chamada com streaming bidirecional, o servidor retorna informações-chave de processo e dados ao cliente por meio de eventos. Itere os events() da sessão (eventos dict brutos) ou results() (frames tipados de resultado de reconhecimento) na thread receptora, para lidar com as informações e dados retornados pelo servidor.

# Itere os eventos brutos: o texto reconhecido está em 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('Texto reconhecido: ', sentence['text'])


# Ou itere apenas os frames de resultado de reconhecimento (retorna RecognitionResult, frames de heartbeat filtrados)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Texto reconhecido: ', sentence['text'])
Evento/método de iteraçãoConteúdo produzidoValor de retornoDescrição
event["header"]["event"] == "task-started"
Evento task-startedNenhumLido internamente por start() e salvo em last_response no retorno do início; não é produzido novamente por events().
def events(self) -> Iterator[Dict]
event: evento dict do servidorIteradorProduz eventos quando o servidor responde. O resultado do reconhecimento está em payload.output.sentence, que pode ser um evento de heartbeat ou de texto vazio, que o aplicativo pode ignorar conforme necessário. Consuma em uma única thread receptora; não crie múltiplos leitores concorrentes.
def results(self) -> Iterator[RecognitionResult]
result: resultado de reconhecimento (RecognitionResult)IteradorProduz apenas frames de resultado de reconhecimento (frames de heartbeat filtrados); a iteração termina após o retorno de todos os resultados de reconhecimento.
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
Exceção DashScopeErrorNenhumLançada na thread de envio/recebimento quando ocorre um erro; pode ser capturada com try/except.
event["header"]["event"] == "task-finished"
Evento task-finishedNenhumProduzido por events() quando o servidor conclui todo o reconhecimento; a iteração termina em seguida. Este evento deve continuar sendo lido após o envio de stop().

Resposta

Resultado de reconhecimento (RecognitionResult)

RecognitionResult representa um frame de resultado de reconhecimento produzido pela iteração de results() da sessão (utilizável tanto em chamadas com streaming bidirecional quanto sem streaming; events() produz eventos dict brutos — use results() se precisar dessa visão tipada).

Método membroAssinatura do métodoDescrição
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

Obtém a frase reconhecida atual e suas informações de timestamp. Este método retorna Dict[str, Any] (informações de uma única frase).

Para detalhes, consulte Sentence (Sentence).

request_id
result.request_id

O request_id da solicitação correspondente ao evento atual.

is_sentence_end
def is_sentence_end(self) -> bool

Determina se a frase atual terminou. Este método verifica se o campo end_time nas informações de frase única retornadas por get_sentence() é None: um end_time diferente de None indica que a frase terminou.

Códigos de erro

Se encontrar erros, consulte Error codes para solução de problemas.

Se o problema persistir, junte-se à comunidade de desenvolvedores para relatar seu problema e forneça o Request ID para investigação adicional.