O service de reconhecimento de fala em tempo real recebe um fluxo de áudio e o transcreve em texto pontuado instantaneamente. Utilize este recurso para legendas ao vivo, reuniões online, chat de voz, assistentes inteligentes e cenários semelhantes.
Visão geral
Este service processa fluxos de áudio e retorna texto transcrito com baixa latência.
- Oferece alta precisão no reconhecimento de mandarim, além de cantonês, sichuanês e outros dialetos.
- Opera em ambientes acústicos complexos, com detecção automática de idioma e filtragem inteligente de sons que não são fala.
- Identifica diversos estados emocionais, incluindo surpresa, calma, felicidade, tristeza, repulsa, raiva e medo.
- Permite o uso de hotwords personalizadas para aumentar a precisão no reconhecimento de termos específicos.
- Oferece aprimoramento de contexto para melhorar a precisão do reconhecimento mediante o envio de histórico de conversas ou termos de domínio.
- Gera timestamps para produzir resultados de reconhecimento estruturados.
- Aceita taxas de amostragem flexíveis e múltiplos formatos de áudio para se adaptar a diferentes ambientes de gravação.
Pré-requisitos
- Uma chave de API foi Obtain an API key e set as an environment variable.
- Para chamar o service por meio do DashScope SDK, install the latest SDK.
Início rápido
Os exemplos a seguir demonstram como chamar o service de reconhecimento de fala em tempo real usando o DashScope SDK.
- Qwen-Audio-3.0-ASR-Flash-Streaming/ Fun-ASR -Realtime
- Qwen3-ASR-Flash-Realtime
- Paraformer
- Reconhecer fala a partir de um microfone
- Reconhecer um arquivo de áudio local
- Java
- Python
Configuração de reconhecimento
Modos de interação do Qwen3-ASR-Flash-Realtime
A API em tempo real do Qwen3-ASR-Flash-Realtime oferece dois modos de interação:
- Modo VAD (padrão): O servidor detecta automaticamente o início e o fim da fala (segmentação). Este modo é adequado para conversas em tempo real, anotações de reuniões e cenários semelhantes. Para ativá-lo, configure o parâmetro
session.turn_detection(ativado por padrão). - Modo manual: O cliente controla a segmentação enviando
input_audio_buffer.commit. Use este modo em cenários que exigem controle explícito sobre o envio de áudio, como o envio de mensagens de voz em aplicativos de chat. Para ativá-lo, definasession.turn_detectioncomo null.
- WebSocket: Defina o campo
turn_detectionem um eventosession.update.
- SDK Python: Configure o parâmetro
enable_turn_detectionno métodoupdate_session.
- SDK Java: Defina o parâmetro
enableTurnDetectionpor meio deOmniRealtimeConfig.builder().
Configuração de segmentação VAD
A Detecção de Atividade de Voz (VAD) determina quando um segmento contínuo de fala termina, o que aciona o evento de resultado final de reconhecimento. As três famílias de modelos habilitam o VAD no lado do servidor por padrão, mas seus nomes de parâmetros e granularidade de ajuste diferem:
- Qwen-Audio-3.0-ASR-Flash-Streaming / Fun-ASR-Realtime / Paraformer: Configurado via
max_sentence_silence(limiar de silêncio VAD para segmentação, em milissegundos). Quando o silêncio após um segmento de fala excede esse limiar, o sistema considera a frase concluída. - Qwen3-ASR-Flash-Realtime: Configurado por meio de
session.turn_detection, que incluisilence_duration_ms(limiar de duração do silêncio que encerra um turno quando excedido; padrão do servidor800, sendo400recomendado para cenários de conversa e chat que exigem segmentação rápida) ethreshold(sensibilidade de detecção VAD; padrão do servidor0.2). O Qwen3-ASR-Flash-Realtime também suporta o modo Manual, que desativa o VAD e utiliza confirmação no lado do cliente para segmentação. Para mais detalhes, consulte Qwen3-ASR-Flash-Realtime interaction modes acima.
max_sentence_silence no Qwen-Audio-3.0-ASR-Flash-Streaming / Fun-ASR-Realtime / Paraformer, e silence_duration_ms no Qwen3-ASR-Flash-Realtime. Para as definições completas dos campos, veja API reference.
Recursos avançados
Melhorar a precisão com palavras-chave
Utilize palavras-chave para aumentar a precisão do reconhecimento de termos específicos, como nomes de marcas, nomes próprios e terminologia técnica.
Para obter detalhes sobre a configuração e o uso de palavras-chave, consulte Improve recognition accuracy.
Aumentar a precisão com aprimoramento de contexto
O aprimoramento de contexto fornece histórico de conversas ou terminologia de domínio ao modelo ASR, melhorando significativamente a precisão da transcrição de termos específicos. Para instruções detalhadas e exemplos de resultados, veja Context enhancement.
Obter carimbos de data/hora
As famílias de modelos Qwen-Audio-3.0-ASR-Flash-Streaming, Fun-ASR-Realtime e Paraformer retornam carimbos de data/hora nos níveis de frase e de palavra por padrão. Isso permite alinhamento de legendas, destaque de palavras-chave, leitura acompanhada estilo karaokê e outros casos de uso. Atualmente, o Qwen3-ASR-Flash-Realtime (qwen3-asr-flash-realtime) não retorna carimbos de data/hora. Caso precise dessa funcionalidade, utilize Qwen-Audio-3.0-ASR-Flash-Streaming, Fun-ASR-Realtime ou Paraformer. Para transcrição de arquivos, o modelo de transcrição de gravações Qwen ASR qwen3-asr-flash-filetrans suporta carimbos de data/hora no nível de palavra. Para mais informações, consulte Non-real-time speech recognition.
Os carimbos de data/hora são retornados em milissegundos em dois níveis:
- Nível de frase:
payload.output.sentence.begin_timeepayload.output.sentence.end_timemarcam o início e o fim de uma frase completa no áudio. Em resultados intermediários,end_timepode sernulle recebe o valor definitivo quando a frase termina (sentence_end = true). - Nível de palavra: O array
payload.output.sentence.words, onde cada elemento contémbegin_time,end_time,text(texto da palavra ou caractere) epunctuation(pontuação seguinte à palavra, ou string vazia se não houver).
Reconhecimento de emoções
O Qwen3-ASR-Flash-Realtime e alguns modelos Paraformer podem incluir o estado emocional do falante no resultado da transcrição, porém diferem na granularidade da saída e na forma de ativação do recurso.
Qwen3-ASR-Flash-Realtime (qwen3-asr-flash-realtime): Sempre ativo, sem necessidade de configuração. A emoção é retornada por meio de um campo emotion de nível superior tanto nos eventos conversation.item.input_audio_transcription.text quanto conversation.item.input_audio_transcription.completed. O valor corresponde a uma das sete emoções detalhadas: surprised, neutral, happy, sad, disgusted, angry e fearful.
payload.output.sentence.emo_tag e payload.output.sentence.emo_confidence. O valor representa uma de três polaridades: positive (como feliz ou satisfeito), negative (como irritado ou abatido) e neutral (sem emoção clara). A confiança varia de 0,0 a 1,0.
O reconhecimento de emoções só é retornado quando todas as condições abaixo são atendidas:
- O modelo é
paraformer-realtime-8k-v2. - Segmentação semântica desativada:
semantic_punctuation_enabled = false(false é o padrão, portanto nenhuma configuração especial é necessária). - O resultado aparece apenas no evento de fim de frase, onde
sentence_end = true.
semantic_punctuation_enabled como true. Essa ação ativa a segmentação semântica e deixa de retornar os campos emo_tag e emo_confidence.
Os nomes de campo acima seguem os caminhos JSON do WebSocket. Diferentes SDKs expõem esses campos com suas próprias convenções de nomenclatura (chaves de dicionário, propriedades de objeto, métodos getter, etc.). Para o mapeamento completo de campos, consulte a referência da API de cada SDK.
Para definições completas dos campos, restrições de valores e exemplos, veja API reference.
Filtragem de palavras sensíveis
A filtragem de palavras sensíveis substitui ou remove termos sensíveis no resultado do reconhecimento. Aplique este recurso em inspeções de qualidade de call center, conformidade de conteúdo, revisão de legendas e situações afins.
Modelos suportados: Apenas Qwen-Audio-3.0-ASR-Flash-Streaming e Fun-ASR-Realtime.
Limite: É possível definir até 32 palavras sensíveis.
Comportamento padrão: Se o parâmetro special_word_filter não for enviado, nenhuma palavra sensível será filtrada.
Como configurar: special_word_filter é um objeto JSON com três subcampos:
filter_with_signed.word_list: Array de strings que lista as palavras sensíveis a serem substituídas por uma sequência de caracteres*de igual comprimento. Por exemplo, com["test"], "Help me test it" torna-se "Help me **** it".filter_with_empty.word_list: Array de strings que lista as palavras sensíveis a serem removidas completamente do resultado. Por exemplo, com["start"], "Is the game about to start" torna-se "Is the game about to".system_reserved_filter: Valor booleano cujo padrão éfalse. Determina se a filtragem de palavras sensíveis está ativada.
Chamar o protocolo WebSocket nativo
Os exemplos a seguir demonstram como se conectar diretamente ao servidor usando o protocolo WebSocket nativo, destinados a cenários que não utilizam o DashScope SDK. Cada exemplo consiste em uma implementação mínima e executável. Para obter detalhes sobre o protocolo WebSocket, consulte a API reference de cada modelo.
Clique para visualizar exemplos do protocolo WebSocket nativo
Clique para visualizar exemplos do protocolo WebSocket nativo
- Tab
- Qwen3-ASR-Flash-Realtime
- Paraformer
Python
Antes de executar o exemplo, instale as dependências com os seguintes comandos:websocket.py. Esse nome entra em conflito com a biblioteca websocket e causa o seguinte erro: AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?.Java
Antes de executar o exemplo, instale a dependência Java-WebSocket:Node.js
Instale as dependências necessárias:C#
O código do exemplo é o seguinte:PHP
O projeto de exemplo possui a seguinte estrutura de diretórios:my-php-project/├── composer.json├── vendor/└── index.phpO conteúdo do arquivo composer.json está abaixo. Ajuste as versões das dependências conforme necessário:Go
Aplicação em produção
Reutilização de conexões (WebSocket)
As conexões WebSocket para Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime e Paraformer permitem reutilização. Após a conclusão de uma tarefa de reconhecimento, é possível iniciar a próxima sem restabelecer a conexão.
Fluxo de reutilização: O cliente envia finish-task. Depois que o servidor retorna task-finished, o cliente pode enviar run-task novamente para começar uma nova tarefa.
O modelo Qwen3-ASR-Flash-Realtime opera com um modelo de sessão e não oferece suporte à reutilização de conexões. Feche a conexão sempre que uma sessão terminar.
Para consultar os eventos de cada modelo, acesse API reference.
Melhores práticas para alta concorrência
O DashScope SDK possui um mecanismo interno de pool que reutiliza conexões WebSocket e objetos de reconhecimento, evitando a sobrecarga causada pela criação e destruição frequentes de recursos.
Clique para visualizar as melhores práticas de alta concorrência
Clique para visualizar as melhores práticas de alta concorrência
Pré-requisitos
- Obtain an API key
- DashScope SDK instalado e compatível com a versão exigida. Recomendamos que você install the latest version: Java SDK versão 2.16.9 ou superior.
- Pool de conexões: O pool OkHttp3, integrado ao SDK, gerencia e reutiliza as conexões WebSocket subjacentes, reduzindo a sobrecarga de handshakes de rede. Esse recurso vem ativado por padrão.
- Pool de objetos: Construído sobre
commons-pool2, este pool mantém um conjunto de objetosRecognitioncom conexões já estabelecidas. Ao obter um objeto do pool, elimina-se a latência de configuração de conexão, reduzindo significativamente a latência do primeiro pacote.
Etapas de implementação
-
Adicione as dependências
Inclua dashscope-sdk-java e commons-pool2 no arquivo de configuração de dependências, conforme a ferramenta de build do seu projeto.
Os exemplos abaixo mostram a configuração para Maven e Gradle:
- Maven
- Gradle
- Abra o arquivo
pom.xmldo seu projeto Maven. - Insira as seguintes dependências dentro da tag
<dependencies>.
- Salve o arquivo
pom.xml. - Execute um comando Maven (como
mvn clean installoumvn compile) para atualizar as dependências do projeto.
-
Configure o pool de conexões
Defina os principais parâmetros do pool de conexões por meio de variáveis de ambiente:
Variável de ambiente
Descrição
DASHSCOPE_CONNECTION_POOL_SIZE
Tamanho do pool de conexões.
Valor recomendado: pelo menos o dobro da concorrência de pico.
Valor padrão: 32.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS
Número máximo de requisições assíncronas.
Valor recomendado: igual a
DASHSCOPE_CONNECTION_POOL_SIZE.Valor padrão: 32.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST
Limite de requisições assíncronas por host.
Valor recomendado: igual a
DASHSCOPE_CONNECTION_POOL_SIZE.Valor padrão: 32.
-
Configure o pool de objetos
Ajuste o tamanho do pool de objetos usando uma variável de ambiente:
Crie o pool de objetos com o código abaixo:Variável de ambiente
Descrição
RECOGNITION_OBJECTPOOL_SIZE
Capacidade do pool de objetos.
Valor recomendado: entre 1,5 e 2 vezes a concorrência de pico.
Valor padrão: 500.
-
Obtenha um objeto Recognition do pool
Se a quantidade de objetos não devolvidos exceder o limite do pool, o sistema criará novos objetos
Recognition. Esses novos objetos precisarão restabelecer a conexão WebSocket e não poderão ser reutilizados imediatamente.
-
Execute o reconhecimento de fala
Invoque o método call ou streamCall do objeto
Recognitionpara processar o áudio. - Devolva o objeto Recognition Ao concluir a tarefa de reconhecimento, devolva o objeto Recognition para permitir sua reutilização. Não devolva objetos associados a tarefas incompletas ou com falha.
Código completo
Configuração recomendada
As configurações a seguir baseiam-se em testes executados exclusivamente com o serviço de reconhecimento de fala em tempo real Paraformer, rodando em servidores Alibaba Cloud das especificações indicadas. A concorrência por máquina refere-se ao número de tarefas simultâneas de reconhecimento (ou seja, a quantidade de threads de trabalho).Especificação da máquina (Alibaba Cloud) | Concorrência máxima por máquina | Tamanho do pool de objetos | Tamanho do pool de conexões |
|---|---|---|---|
4 vCPUs, 8 GiB | 100 | 500 | 2000 |
8 vCPUs, 16 GiB | 200 | 500 | 2000 |
16 vCPUs, 32 GiB | 400 | 500 | 2000 |
Gestão de recursos e tratamento de erros
-
Sucesso na tarefa: Invoque
GenericObjectPool.returnObject()para devolver o objeto Recognition ao pool, permitindo seu reaproveitamento. -
Falha na tarefa: Se uma exceção lançada pelo SDK ou pela lógica de negócio interromper a execução, realize as duas ações abaixo:
- Feche ativamente a conexão WebSocket subjacente.
- Invalidade o objeto no pool para impedir que seja reutilizado.
- Caso o serviço retorne um erro TaskFailed, nenhuma ação adicional é necessária.
Warm-up e medição de latência
Ao avaliar métricas de desempenho como a latência de chamadas concorrentes no DashScope Java SDK, recomenda-se executar um aquecimento adequado antes dos testes oficiais.Mecanismo de reutilização de conexões
O DashScope Java SDK gerencia e reutiliza conexões WebSocket através de um pool global singleton. Esse mecanismo funciona da seguinte forma:- Criação sob demanda: O SDK não pré-cria conexões WebSocket na inicialização. Em vez disso, ele estabelece as conexões conforme necessário durante a primeira chamada.
-
Reutilização temporária: Após a conclusão de uma requisição, a conexão permanece disponível no pool por até 60 segundos.
- Se uma nova requisição chegar dentro desse período, o SDK aproveita a conexão existente, evitando a sobrecarga de um novo handshake.
- Conexões ociosas por mais de 60 segundos são fechadas automaticamente para liberar recursos.
Importância do warm-up
Nos cenários abaixo, o pool pode não ter conexões ativas disponíveis, obrigando a requisição a criar uma nova:- A aplicação acabou de iniciar e ainda não realizou chamadas.
- O serviço ficou inativo por mais de 60 segundos, causando o fechamento das conexões do pool por timeout.
Abordagem recomendada
Antes de iniciar testes de carga formais ou medir latência, siga estas etapas de aquecimento:- Simule o nível de concorrência do teste oficial enviando chamadas antecipadamente (por exemplo, durante 1 a 2 minutos) para preencher completamente o pool de conexões.
- Após confirmar que o pool estabeleceu e manteve conexões ativas suficientes, comece a coletar os dados de desempenho oficiais.
Melhoria da precisão do reconhecimento
- Escolha um modelo compatível com a taxa de amostragem: Para áudio telefônico de 8 kHz, utilize diretamente um modelo de 8 kHz. Isso previne a perda de informações causada pelo upsampling para 16 kHz.
- Otimize a qualidade do áudio de entrada: Utilize microfones de alta qualidade e grave em ambientes com boa relação sinal-ruído e ausência de eco. Na camada de aplicação, integre algoritmos de pré-processamento como redução de ruído (ex: RNNoise) e cancelamento de eco acústico (AEC).
Configuração de estratégia de tolerância a falhas
-
Reconexão no lado do cliente: Implemente reconexão automática no cliente para lidar com instabilidades de rede. Abaixo está uma implementação de referência para o Python SDK:
- Captura de exceções: Implemente o método
on_errorna classeCallback. O SDKdashscopeinvoca esse método ao detectar erros de rede ou outros problemas. - Sinalização de estado: Quando
on_errorfor acionado, defina um sinal de reconexão. Em Python, usethreading.Event, um sinalizador thread-safe. - Loop de reconexão: Envolva a lógica principal em um loop
for(por exemplo, tente 3 vezes). Ao detectar o sinal de reconexão, interrompa a rodada atual de reconhecimento, limpe os recursos e, após alguns segundos, reinicie o loop para estabelecer uma conexão totalmente nova.
- Captura de exceções: Implemente o método
-
Configure heartbeat para manter a conexão ativa: Para preservar conexões persistentes com o servidor, defina o parâmetro heartbeat como
true. Assim, a conexão permanecerá aberta mesmo durante longos períodos de silêncio no áudio. - Limites de taxa do modelo: Ao chamar a API do modelo, observe as regras de Rate limiting.
Modelos e regiões suportados
- Singapore
- China (Beijing)
- Qwen-Audio-3.0-ASR-Flash-Streaming: qwen-audio-3.0-asr-flash-streaming
- Fun-ASR-Realtime: fun-asr-realtime (versão estável, atualmente equivalente a fun-asr-realtime-2025-11-07), fun-asr-realtime-2025-11-07 (versão snapshot)
- Qwen3-ASR-Flash-Realtime: qwen3-asr-flash-realtime (versão estável, atualmente equivalente a qwen3-asr-flash-realtime-2025-10-27), qwen3-asr-flash-realtime-2026-02-10 (versão snapshot mais recente), qwen3-asr-flash-realtime-2025-10-27 (versão snapshot)
Referência da API
- Real-time speech recognition - Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime API reference
- Real-time speech recognition - Qwen3-ASR-Flash-Realtime API reference
- Real-time speech recognition - Paraformer API reference
- AOQ client SDK (para Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime)
FAQ
Quais formatos de áudio são suportados pelo reconhecimento de fala em tempo real?
Os modelos Qwen-Audio-3.0-ASR-Flash-Streaming, Fun-ASR-Realtime e Paraformer aceitam os formatos pcm, wav, mp3, opus, speex, aac e amr. Para o modelo Qwen3-ASR-Flash-Realtime, recomendamos os formatos pcm ou opus. Outros formatos (como wav, aac e amr) passam pela validação de session.update, mas podem falhar na decodificação do servidor. Certifique-se de que o fluxo de áudio utiliza um formato recomendado antes de enviá-lo.
Qual a diferença entre o SDK e a API WebSocket, e qual devo escolher?
O DashScope SDK abstrai detalhes como gerenciamento de conexões WebSocket, autenticação e reconexão, sendo ideal para integrações rápidas. Já a conexão direta via API WebSocket oferece controle mais granular, atendendo linguagens não cobertas pelo SDK ou cenários que exigem gestão personalizada de conexões. Recomendamos começar pelo SDK.
Como melhorar a precisão no reconhecimento de substantivos próprios?
Utilize hotwords ou aprimoramento de contexto. Para métodos detalhados de configuração e notas de uso, consulte Improve recognition accuracy.
O que fazer quando a conexão cai frequentemente?
Implemente reconexão no lado do cliente e ative o parâmetro heartbeat (heartbeat=true) para evitar quedas durante longos períodos sem áudio. Para estratégias detalhadas de tolerância a falhas, veja Apply in production.