Pré-requisitos
Início rápido
Use os mesmos exemplos para os modelos abaixo. Substitua o ID do modelo conforme a tabela.
| Modelo | ID do modelo no exemplo |
|---|---|
| Qwen-Audio-ASR-Streaming | qwen-audio-3.0-asr-flash-streaming |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-messageOferece suporte apenas à taxa de amostragem de 16000 Hz. |
| Fun-ASR-Realtime | fun-asr-realtime |
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
- Chamada com streaming bidirecional
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.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 parâmetros nomeados, e os demais parâmetros (como language_hints) são passados por meio do dicionário parameters.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | O nome do modelo. |
sample_rate | int | Sim | A taxa de amostragem em Hz. Qualquer taxa é compatível. |
format | str | Sim | Formato do áudio.Valores válidos:
|
keep_dialect | bool | Não | Aplica-se apenas a qwen-audio-3.1-asr-flash-streaming.false, que transcreve dialetos em chinês padrão. Defina como true para preservar expressões dialetais. Passe como argumento nomeado com o mesmo nome. |
vad_model | str | Não | Aplica-se apenas a qwen-audio-3.1-asr-flash-streaming.near_meeting_16k (campo próximo) ou far_field_meeting_16k (campo distante, padrão). Passe como argumento nomeado com o mesmo nome. |
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: |
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.Valor padrão: 800.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.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
|
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. |
input dos métodos recognize/recognize_file.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
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:
O uso deste campo requer o SDK 2.0.1 ou posterior. input para o método recognize/recognize_file do recurso principal (client.audio.asr): |
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 parâmetros nomeados, e os demais parâmetros (como language_hints) são passados por meio do dicionário parameters.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | O nome do modelo. |
sample_rate | int | Sim | A taxa de amostragem em Hz. Apenas 16000 é compatível. |
format | str | Sim | Formato do áudio.Valores válidos:
|
keep_dialect | bool | Não | Padrão: false, que transcreve dialetos em chinês padrão. Defina como true para preservar expressões dialetais. Passe como argumento nomeado com o mesmo nome.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_model | str | Não | Modelo VAD: near_meeting_16k (campo próximo) ou far_field_meeting_16k (campo distante, padrão). Passe como argumento nomeado com o mesmo nome. |
disfluency_removal_enabled | bool | 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_enabled | bool | Não | Indica se resultados intermediários de streaming devem ser retornados. Padrão: false. Defina como true para recebê-los. Passe como argumento nomeado com o mesmo nome. |
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: |
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.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
sentence_end=true) e não é compatível com resultados intermediários (sentence_end=false). |
max_sentence_silence | int | 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]. |
heartbeat | bool | Não | Define se os pacotes de heartbeat devem ser ativados.Padrão: False.
|
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:
|
input dos métodos recognize/recognize_file.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
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 foi introduzido no SDK 1.25.23 e já está incluído na versão 2.0.1 ou posterior. input para o método recognize/recognize_file do recurso principal (client.audio.asr): |
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 parâmetros nomeados; os demais parâmetros (como max_sentence_silence e language_hints) são passados por meio do dicionário parameters.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | O nome do modelo. |
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. |
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.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.Você pode definir 1 valor. Se definir mais, somente 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. |
input dos métodos recognize/recognize_file.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
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 Melhorar a precisão do reconhecimento.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 2.0.1 ou posterior do SDK. input ao criar a sessão de reconhecimento: |
Referência da API
Interfaces comuns
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. |
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 membro | Assinatura do método | Descrição |
|---|---|---|
recognize | 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 | 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 | 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 | 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 | 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 | 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 | Fecha a sessão de reconhecimento. Chamado automaticamente ao sair do contexto with. | |
request_id / first_package_delay / last_package_delay / 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.
| Método/evento | Conteúdo produzido | Valor de retorno | Descrição |
|---|---|---|---|
Evento task-started | Nenhum | Lido internamente por start(); a resposta de inicialização é salva em last_response e não é produzida novamente por events(). | |
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. | |
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. | |
Exceção DashScopeError | Nenhum | Lançada na thread de envio/recepção quando ocorre um erro; pode ser capturada com try/except. | |
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 membro | Assinatura do método | Descrição |
|---|---|---|
get_sentence | 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 | O request_id da solicitação correspondente ao evento atual. | |
is_sentence_end | 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
- Resultado de reconhecimento (RecognitionResult)
- Informações da frase (
Sentence) - Informações de timestamp no nível da palavra (Word)
Qwen-Audio-ASR-Message
Interfaces principais
Resposta
- Resultado de reconhecimento (RecognitionResult)
- Informações da frase (
Sentence) - Informações de timestamp no nível da palavra (Word)
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 membro | Assinatura do método | Descrição |
|---|---|---|
| recognize | 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 | 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 | 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 | 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 | 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 | 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 | Fecha a sessão de reconhecimento. É chamado automaticamente na saída do contexto with. | |
| request_id / first_package_delay / last_package_delay / 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.
| Evento/método de iteração | Conteúdo produzido | Valor de retorno | Descrição |
|---|---|---|---|
Evento task-started | Nenhum | Lido internamente por start() e salvo em last_response no retorno do início; não é produzido novamente por events(). | |
event: evento dict do servidor | Iterador | Produz 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. | |
result: resultado de reconhecimento (RecognitionResult) | Iterador | Produz apenas frames de resultado de reconhecimento (frames de heartbeat filtrados); a iteração termina após o retorno de todos os resultados de reconhecimento. | |
Exceção DashScopeError | Nenhum | Lançada na thread de envio/recebimento quando ocorre um erro; pode ser capturada com try/except. | |
Evento task-finished | Nenhum | Produzido 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 membro | Assinatura do método | Descrição |
|---|---|---|
get_sentence | 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 | O request_id da solicitação correspondente ao evento atual. | |
is_sentence_end | 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. |