Este tópico descreve os parâmetros e as interfaces do Python SDK para o modelo de reconhecimento de fala em tempo real Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime.
Pré-requisitos
Início rápido
A Recognition class fornece interfaces para chamadas sem streaming e com streaming bidirecional. Escolha o método de chamada adequado às suas necessidades:
- Chamada sem streaming: reconhece um arquivo local e retorna o resultado completo em uma única resposta. Ideal para processar áudio pré-gravado.
- Chamada com streaming bidirecional: 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 sincronamente ao passar um arquivo local.
Instancie a Recognition class, vincule os Request parameters e chame call para executar o reconhecimento ou tradução e obter o Recognition result (RecognitionResult) final.
Visualize o exemplo completo
Visualize o exemplo completo
Chamada com streaming bidirecional
Envie uma única tarefa de reconhecimento de fala em tempo real e transmita os resultados continuamente implementando a interface de callback.
-
Inicie o reconhecimento de fala em streaming.
Instancie a Recognition class, vincule os Request parameters e a Callback interface (RecognitionCallback) e chame o método
startpara iniciar o reconhecimento de fala em streaming. -
Transmita o áudio.
Chame o método
send_audio_frameda Recognition class em 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 microfone. Durante o envio do áudio, o servidor retorna resultados de reconhecimento ao cliente em tempo real por meio do métodoon_eventda Callback interface (RecognitionCallback). Envie cerca de 100 ms de áudio por quadro e mantenha cada quadro entre 1 KB e 16 KB. -
Encerre a tarefa.
Chame o método
stopda Recognition class para encerrar o reconhecimento de fala. Esse método bloqueia a thread atual até que o callbackon_completeouon_errorda Callback interface (RecognitionCallback) seja acionado.
Visualize o exemplo completo
Visualize o exemplo completo
Parâmetros da solicitação
Defina os parâmetros da solicitação por meio do construtor (init) da Recognition class.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| model | str | Sim | Nome do modelo. Há suporte para as séries Qwen-Audio-3.0-ASR-Flash-Streaming e Fun-ASR-Realtime. Para mais detalhes, consulte Supported models and regions. |
| sample_rate | int | Sim | Taxa de amostragem, em Hz.Valores válidos: modelos de 8 kHz aceitam apenas 8000 Hz; outros modelos aceitam qualquer taxa de amostragem. |
| format | str | Sim | Formato do áudio.Valores válidos:
|
| vocabulary_id | str | 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. |
| vocabulary | dict | 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: |
| semantic_punctuation_enabled | bool | Não | Define se a segmentação semântica deve ser ativada.Padrão: False.
|
| max_sentence_silence | int | 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. Quando semantic_punctuation_enabled é definido como true, este parâmetro não é 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_threshold_mode_enabled | bool | 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_enabled | bool | Não | Define se a pontuação deve ser adicionada automaticamente aos resultados de reconhecimento:
|
| heartbeat | bool | Não | Define se os pacotes de heartbeat devem ser ativados.Padrão: False.
|
| language_hints | list[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.Para a série de modelos Qwen-Audio-3.0-ASR-Flash-Streaming, você pode definir até 4 valores; se definir mais de 4, apenas os primeiros 4 terão efeito. Para a série de modelos Fun-ASR-Realtime, você pode definir apenas 1 valor; se definir vários, apenas o primeiro terá efeito.
Clique em para visualizar os códigos de idioma aceitos
|
| speech_noise_threshold | float | 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:
|
| special_word_filter | str | 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. |
| callback | RecognitionCallback | Não | Callback interface (RecognitionCallback). |
call ou start da instância Recognition.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| raw_input | dict | 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:
Este campo requer a versão 1.25.23 ou posterior do SDK.Passe raw_input para o método start ou call da instância Recognition: |
Interfaces principais
Classe Recognition
Importe Recognition com "from dashscope.audio.asr import *".
| Método membro | Assinatura do método | Descrição |
|---|---|---|
| call | Chamada sem streaming baseada em arquivo local. Este método bloqueia a thread atual até que todo o áudio seja lido e requer permissão de leitura no arquivo.O resultado do reconhecimento é retornado como um objeto RecognitionResult. | |
| start | Inicia o reconhecimento de fala.Reconhecimento em tempo real via streaming baseado em callback. Este método não bloqueia a thread atual. Use-o juntamente com send_audio_frame e stop. | |
| send_audio_frame | 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 através do método on_event da Callback interface (RecognitionCallback). | |
| stop | Interrompe o reconhecimento de fala. Bloqueia até que o servidor termine de reconhecer todo o áudio recebido e então encerra a tarefa. | |
| get_last_request_id | Obtém o request_id. Disponível após a chamada do construtor (criação do objeto). | |
| get_first_package_delay | Obtém o atraso do primeiro pacote: a latência desde o envio do primeiro pacote de áudio até o recebimento do primeiro resultado de reconhecimento. Use após a conclusão da tarefa. | |
| get_last_package_delay | Obtém o atraso do último pacote: o tempo desde o envio do comando stop até o recebimento do último resultado de reconhecimento. Use após a conclusão da tarefa. | |
| get_response | Obtém a última mensagem. Use para recuperar um erro de falha na tarefa. |
Interface de callback (RecognitionCallback)
Durante uma Bidirectional streaming call, o servidor retorna informações-chave de processo e dados ao cliente por meio de callbacks. Implemente os métodos de callback para lidar com as informações e dados retornados pelo servidor.
Visualize o exemplo
Visualize o exemplo
| Método | Parâmetro | Valor de retorno | Descrição |
|---|---|---|---|
| None | None | Chamado imediatamente após o estabelecimento da conexão com o servidor. | |
result: Recognition result (RecognitionResult) | None | Chamado quando o servidor envia uma resposta. | |
| None | None | Chamado após o retorno de todos os resultados de reconhecimento. | |
result: Recognition result (RecognitionResult) | None | Chamado quando ocorre um erro. | |
| None | None | Chamado após o servidor fechar a conexão. |
Resposta
Resultado de reconhecimento (RecognitionResult)
RecognitionResult representa o resultado de um único reconhecimento em tempo real em uma Bidirectional streaming call ou o resultado de uma Non-streaming call.
| Método membro | Assinatura do método | Descrição |
|---|---|---|
| get_sentence | Obtém a frase reconhecida atual e suas informações de timestamp. Um callback retorna uma única frase, portanto este método retorna Dict[str, Any].Para detalhes, consulte Sentence (Sentence). | |
| get_request_id | Obtém o request_id da solicitação. | |
| is_sentence_end | Determina se a frase fornecida terminou. Este método verifica se o campo end_time em sentence é None: um end_time diferente de None indica que a frase terminou. Chame-o como RecognitionResult.is_sentence_end(sentence), onde sentence é o dict de frase única retornado por get_sentence(), não um campo booleano em uma instância de Sentence. |
Informações da frase (Sentence)
Os membros da classe Sentence são os seguintes:
Parâmetro | Tipo | Descrição |
|---|---|---|
begin_time | int | Tempo de início da frase, em ms. |
end_time | int | Tempo de término da frase, em ms. |
text | str | Texto reconhecido. |
words | Uma 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âmetro | Tipo | Descrição |
|---|---|---|
begin_time | int | Tempo de início da palavra, em ms. |
end_time | int | Tempo de término da palavra, em ms. |
text | str | A palavra. |
punctuation | str | A pontuação. |
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.
FAQ
Recursos
P: Como mantenho a conexão ativa durante longos períodos de silêncio?
Defina o parâmetro de solicitação heartbeat como true e continue enviando áudio silencioso para o servidor.
Áudio silencioso é o conteúdo em um arquivo de áudio ou fluxo 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 converto áudio para um formato aceito?
Use o FFmpeg. Para mais usos, consulte o site oficial do FFmpeg.
P: Como reconheço um arquivo local (gravação)?
Existem duas maneiras de reconhecer um arquivo local:
-
Passe o caminho do arquivo local diretamente: esta forma retorna o resultado completo somente após o término do reconhecimento, portanto não é adequada para cenários que precisam de feedback imediato.
Consulte Non-streaming call e passe o caminho do arquivo para o método
callda Recognition class para reconhecer a gravação diretamente. -
Converta o arquivo local em um fluxo binário para reconhecimento: esta forma reconhece o arquivo enquanto transmite os resultados em fluxo, sendo adequada para cenários que precisam de feedback imediato.
Consulte Bidirectional streaming call e envie o fluxo binário para o servidor para reconhecimento através do método
send_audio_frameda Recognition class.
Solução de problemas
P: Por que a fala não é reconhecida (nenhum resultado de reconhecimento)?
-
Verifique se o formato de áudio (
format) e a taxa de amostragem (sampleRate/sample_rate) nos parâmetros da solicitação estão corretos e atendem às restrições de parâmetros. Erros comuns incluem:- O arquivo de áudio tem extensão .wav, mas na verdade está no formato MP3, enquanto o parâmetro de solicitação
formatestá definido como mp3 (configuração incorreta de parâmetro). - A taxa de amostragem do áudio é 3600 Hz, mas o parâmetro de solicitação
sampleRate/sample_rateestá definido como 48000 (configuração incorreta de parâmetro).
- O arquivo de áudio tem extensão .wav, mas na verdade está no formato MP3, enquanto o parâmetro de solicitação
- Se nenhuma das verificações acima revelar um problema, adicione palavras-chave personalizadas para melhorar o reconhecimento de termos específicos.