Prepare o áudio, reutilize conexões, gerencie a concorrência Java e tarefas assíncronas e trate erros em aplicações de reconhecimento de fala.
Preparar o áudio de entrada
Verifique o formato, a taxa de amostragem, os canais e a duração da entrada conforme as especificações de áudio do modelo de destino.
- Priorize a qualidade da captura e reduza ruído e eco. Antes de ativar supressão de ruído ou AEC, compare os resultados antes e depois do processamento no mesmo conjunto representativo de áudio com transcrição manual.
- Para áudio telefônico de 8 kHz, escolha um modelo e uma taxa de amostragem compatíveis.
- Escolha um modelo compatível com o idioma e o dialeto do áudio.
- Se houver imprecisão no reconhecimento de termos especializados, configure palavras-chave ou aprimoramento de contexto conforme Melhorar a precisão do reconhecimento.
Verificar e processar o áudio
Verificar e processar o áudio
- Verificar o formato do áudio
- Converter a codificação e a taxa de amostragem
- Recortar o áudio
- Extrair o áudio de um vídeo
Use o FFprobe para verificar o contêiner, o codec, a taxa de amostragem e os canais:
Escolher um método de entrada de arquivo
Os métodos de entrada de arquivo dependem da API. Por exemplo, o Qwen-Audio-ASR-Flash aceita URLs de arquivos de áudio e URIs de dados Base64. Codifique o áudio local como uma URI de dados Base64 para enviá-lo diretamente. Para exemplos de codificação e chamada, consulte API HTTP Flash.
Ao enviar um arquivo por URL, garanta que o serviço possa baixar o áudio durante o processamento. Verifique permissões, validade da URL e acesso pela rede pública.
Em produção, hospede os arquivos em armazenamento estável, como o OSS, e envie suas URLs. Reutilize arquivos já carregados no processamento em lote para reduzir uploads repetidos. Antes de usar o upload de arquivos locais de um SDK, verifique os limites da interface. O mecanismo de arquivos temporários e suas condições estão em Obter uma URL de arquivo temporário.
Gerenciar tarefas e conexões em tempo real
O protocolo run-task / finish-task de Qwen-Audio-ASR-Message, Qwen-Audio-ASR-Streaming, Fun-ASR-Realtime e Paraformer permite reutilizar conexões sequencialmente:
- Envie
run-taskcom umtask_idexclusivo. Aguardetask-startedantes de enviar áudio. - Após enviar o áudio, envie
finish-taskcom o mesmotask_id. - Aguarde o evento
task-finisheddo servidor para confirmar a conclusão. - Inicie a próxima tarefa na mesma conexão com um novo
task_id. Não execute tarefas simultâneas em uma conexão.
Tratar conexões ociosas ou com falha
- A conexão é fechada automaticamente se nenhuma nova tarefa começar por aproximadamente 60 segundos após a conclusão. Estabeleça uma nova conexão após um período ocioso prolongado.
- Após falha na tarefa, interrupção da rede ou erro de protocolo, feche a conexão anterior e crie um novo objeto. Invalide os objetos do pool em vez de devolvê-los como disponíveis.
- Feche o pool e suas conexões quando a aplicação encerrar ou parar de fornecer reconhecimento.
Tratar silêncios prolongados durante uma tarefa
Se uma tarefa em execução precisar receber áudio silencioso contínuo, configure heartbeat=true conforme a API e continue enviando silêncio na codificação exigida. Após a conclusão, gerencie as conexões ociosas conforme a seção anterior. Consulte as referências a seguir para os parâmetros dos modelos.
Eventos do cliente Message | Eventos do cliente Streaming | Eventos do cliente Fun-ASR | Eventos do cliente Paraformer
Configurar a concorrência Java
Reserve um objeto Recognition para cada tarefa em execução e devolva-o somente após a conclusão bem-sucedida. O exemplo a seguir gerencia objetos com Commons Pool 2. Crie o pool uma vez e reutilize-o entre chamadas.
Adicionar dependências
Conclua primeiro Obter uma chave de API e Instalar um SDK. O exemplo completo desta seção requer DashScope Java SDK 2.18.0 ou posterior. Estas configurações usam DashScope Java SDK 2.23.2 e Commons Pool 2.12.0:
- Maven
- Gradle
Distinguir capacidades de conexões, objetos e requisições
O SDK lê as três variáveis de ambiente DASHSCOPE_ abaixo. Defina-as antes de iniciar o processo. O código deste exemplo lê RECOGNITION_OBJECTPOOL_SIZE.
| Variável de ambiente | Padrão | Função |
|---|---|---|
DASHSCOPE_CONNECTION_POOL_SIZE | 32 | Conexões HTTP ociosas mantidas pelo cliente OkHttp compartilhado do SDK. |
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS | 32 | Capacidade de agendamento concorrente das requisições assíncronas do SDK. As requisições excedentes aguardam. |
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST | 32 | Capacidade de agendamento de requisições assíncronas por host. |
RECOGNITION_OBJECTPOOL_SIZE | 500 | Total de objetos permitido neste exemplo, controlado pelo maxTotal do Commons Pool. |
Concorrência é o número de tarefas executadas ao mesmo tempo; RPS é o número de requisições por segundo. Configure os threads de trabalho e a capacidade do pool conforme a concorrência da aplicação e controle a frequência de início das tarefas segundo os Limites de taxa do modelo.
Referência de configuração do Paraformer
Referência de configuração do Paraformer
Os valores abaixo são referências de planejamento de capacidade para aplicações Paraformer em tempo real. A concorrência por servidor corresponde às tarefas em execução simultânea. O servidor executa apenas essa aplicação de reconhecimento.
- Para conexões HTTP ociosas, comece com uma capacidade de pelo menos duas vezes a concorrência de pico e ajuste.
- Inicialmente, defina as capacidades de agendamento assíncrono total e por host iguais à capacidade de conexões, ajustando depois conforme as filas observadas.
- Para o pool de objetos de reconhecimento, comece com 1,5 a 2 vezes a concorrência de pico. O padrão de 500 é uma configuração da aplicação de exemplo.
| Servidor Alibaba Cloud | Concorrência de referência | Capacidade do pool | Conexões HTTP ociosas |
|---|---|---|---|
| 4 vCPUs, 8 GiB | 100 | 500 | 2000 |
| 8 vCPUs, 16 GiB | 200 | 500 | 2000 |
| 16 vCPUs, 32 GiB | 400 | 500 | 2000 |
Estas configurações se aplicam a um servidor dedicado à aplicação de reconhecimento em tempo real Paraformer. Ajuste a capacidade conforme a taxa de envio de áudio, os recursos do cliente e a carga da aplicação. Para os limites das APIs dos modelos, consulte Limites de taxa.
Implementar um pool de objetos de reconhecimento
Use o ciclo de vida abaixo. Quando maxTotal é atingido e não há objetos ociosos, o borrowObject deste exemplo aguarda a devolução de um objeto. Os objetos são criados sob demanda e as conexões WebSocket são estabelecidas ao iniciar as requisições de reconhecimento.
- Obtenha um objeto
Recognitiondo pool, inicie o reconhecimento e envie áudio. - Envie o comando de encerramento e aguarde a confirmação. Em chamadas assíncronas, verifique também o callback de erro.
- Após sucesso, chame
returnObjectpara permitir a reutilização. - Em caso de falha ou interrupção, chame
invalidateObject. O métododestroyObjectda fábrica fecha a conexão. - Depois que todas as tarefas terminarem, feche o pool para liberar as conexões dos objetos ociosos.
RecognitionPoolExample.java. Prepare asr-example.pcm em PCM mono, 16 kHz, 16 bits, defina DASHSCOPE_API_KEY e substitua o workspace e o endereço pela configuração da região desejada (consulte Endpoints). O exemplo usa três threads de trabalho para processar nove tarefas.
Aquecer conexões e medir a latência
Faça o aquecimento enviando requisições reais de reconhecimento para estabelecer conexões WebSocket reutilizáveis pelas tarefas seguintes.
- Antes das medições, envie requisições com a concorrência prevista para produção. Um a dois minutos é uma referência inicial, ajustável à carga.
- Confirme a existência de conexões reutilizáveis antes de medir o estado estável. Separe os dados de inicialização a frio dos de operação estável.
- Conexões podem ser fechadas durante períodos ociosos, exigindo nova conexão. Repita o aquecimento quando necessário antes de novas medições.
Gerenciar trabalhos de transcrição assíncronos
Para transcrição em lote com alta concorrência, prefira callbacks de conclusão de tarefas para reduzir as consultas periódicas. Para configuração e formato dos eventos, consulte Configurar callbacks de tarefas assíncronas.
Ao receber uma notificação de conclusão, identifique a tarefa de negócio com data.task_id e verifique data.task_status. Se a tarefa tiver sido concluída com sucesso, mas a notificação não contiver o resultado necessário, consulte a API HTTP do modelo e baixe e salve os arquivos de transcrição.
Controlar as taxas de envio, consulta e upload
- Envio de tarefas: controle a frequência de envio conforme os Limites de taxa do modelo de destino.
- Consultas de status: a API de consulta tem limite padrão de 20 QPS, que pode ser aumentado para até 100 QPS (entre em contato com seu gerente de conta Alibaba Cloud para solicitar um aumento), por conta principal Alibaba Cloud, incluindo seus usuários RAM. Para consultas periódicas, comece com um intervalo de 2 a 5 segundos e ajuste-o à quantidade de tarefas para manter a taxa total dentro do limite. Para consultas, consultas em lote e cancelamento, consulte Gerenciar tarefas assíncronas.
- Upload de arquivos temporários: a API de credenciais de upload tem limite de 100 QPS por conta principal Alibaba Cloud e por modelo. Esse limite não pode ser aumentado. Use armazenamento estável, como OSS, em produção e em cargas com alta concorrência. Para procedimentos e limites de upload temporário, consulte Obter uma URL de arquivo temporário.
Salvar prontamente os resultados
Baixe e salve os arquivos assim que a tarefa for concluída com sucesso. Por exemplo, o campo transcription_url de API HTTP do Qwen-Audio-ASR-Filetrans é válido por 24 horas. Baixe e armazene os resultados de forma persistente antes da expiração.
- Se a resposta contiver um array
results, verifique cadasubtask_statusantes de baixar o JSON de transcrição dos arquivos processados com sucesso. Salve os timestamps, as informações dos falantes e os demais campos necessários à aplicação. - Mantenha a relação entre tarefas e arquivos e o status final. Se o download falhar, preserve o registro e tente novamente durante a validade da URL.
Tratar erros e novas tentativas
Decida se deve tentar novamente conforme o tipo de erro. Registre o ID da requisição, o ID da tarefa, o modelo, a região e a etapa da falha para distinguir problemas de entrada ou permissão de falhas temporárias.
| Problema | Ação |
|---|---|
| Arquivo de entrada ou parâmetros inválidos | Verifique URL, codificação, taxa de amostragem, canais e intervalos dos parâmetros. Corrija antes de reenviar. |
| Autenticação ou endpoint incorreto | Verifique a chave de API, o workspace e a região do endpoint e corrija conforme a mensagem de erro. |
| Limitação de taxa | Reduza a frequência das requisições ou de início das tarefas e siga Limites de taxa. Evite ciclos de repetição imediata. |
| Timeout de rede, interrupção ou erro temporário do servidor (5xx) | Para falhas em consultas ou downloads, use novas tentativas com espera progressiva, limitando as tentativas e o tempo total de espera. Se o envio assíncrono atingir o tempo limite, consulte a tarefa caso um task_id tenha sido recebido. Caso contrário, decida se deve reenviar conforme a tolerância da aplicação a processamento e cobranças duplicados. |
| Falha no processamento de tarefa ou arquivo | Preserve os erros no nível da tarefa e do arquivo, identifique a causa e decida entre corrigir a entrada ou reenviar. |
Documentação relacionada
- Integração básica: Reconhecimento de fala em tempo real e Reconhecimento de fala não em tempo real.
- Qualidade do reconhecimento: Melhorar a precisão do reconhecimento.
- Tarefas assíncronas: Configurar callbacks de tarefas assíncronas e Gerenciar tarefas assíncronas.