Skip to main content

Práticas recomendadas de reconhecimento de fala

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 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:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.mp3

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:
  1. Envie run-task com um task_id exclusivo. Aguarde task-started antes de enviar áudio.
  2. Após enviar o áudio, envie finish-task com o mesmo task_id.
  3. Aguarde o evento task-finished do servidor para confirmar a conclusão.
  4. Inicie a próxima tarefa na mesma conexão com um novo task_id. Não execute tarefas simultâneas em uma conexão.
O Qwen3-ASR-Realtime usa um protocolo de sessão. Feche explicitamente a conexão após o encerramento da sessão. Para conexão e encerramento, consulte Fluxo de interação do Qwen3-ASR-Realtime.

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
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>2.23.2</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-pool2</artifactId>
    <version>2.12.0</version>
</dependency>

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 ambientePadrãoFunção
DASHSCOPE_CONNECTION_POOL_SIZE32Conexões HTTP ociosas mantidas pelo cliente OkHttp compartilhado do SDK.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS32Capacidade de agendamento concorrente das requisições assíncronas do SDK. As requisições excedentes aguardam.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST32Capacidade de agendamento de requisições assíncronas por host.
RECOGNITION_OBJECTPOOL_SIZE500Total 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.
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 CloudConcorrência de referênciaCapacidade do poolConexões HTTP ociosas
4 vCPUs, 8 GiB1005002000
8 vCPUs, 16 GiB2005002000
16 vCPUs, 32 GiB4005002000
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.
  1. Obtenha um objeto Recognition do pool, inicie o reconhecimento e envie áudio.
  2. Envie o comando de encerramento e aguarde a confirmação. Em chamadas assíncronas, verifique também o callback de erro.
  3. Após sucesso, chame returnObject para permitir a reutilização.
  4. Em caso de falha ou interrupção, chame invalidateObject. O método destroyObject da fábrica fecha a conexão.
  5. Depois que todas as tarefas terminarem, feche o pool para liberar as conexões dos objetos ociosos.
Salve o código como 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.
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionResult;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import org.apache.commons.pool2.BasePooledObjectFactory;
import org.apache.commons.pool2.PooledObject;
import org.apache.commons.pool2.impl.DefaultPooledObject;
import org.apache.commons.pool2.impl.GenericObjectPool;
import org.apache.commons.pool2.impl.GenericObjectPoolConfig;

import java.io.InputStream;
import java.nio.ByteBuffer;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import java.util.concurrent.atomic.AtomicReference;

public class RecognitionPoolExample {
    private static final int WORKERS = 3;
    private static final int TASKS = 9;
    private static final int COMPLETION_TIMEOUT_SECONDS = 60;

    public static void main(String[] args) {
        int exitCode = 0;
        try {
            run(args);
        } catch (Exception e) {
            e.printStackTrace();
            exitCode = 1;
        }
        // Exit this standalone example after all owned resources are closed.
        System.exit(exitCode);
    }

    private static void run(String[] args) throws Exception {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            throw new IllegalArgumentException("Set DASHSCOPE_API_KEY first");
        }
        // Replace {WorkspaceId} with the workspace ID for the endpoint region.
        Constants.baseWebsocketApiUrl =
                "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
        Path audio = Paths.get(args.length == 0 ? "asr-example.pcm" : args[0]);
        if (!Files.isReadable(audio)) {
            throw new IllegalArgumentException("Audio file is not readable: " + audio);
        }
        int capacity = Integer.parseInt(System.getenv().getOrDefault(
                "RECOGNITION_OBJECTPOOL_SIZE", "500"));
        if (capacity <= 0) {
            throw new IllegalArgumentException("Pool size must be positive");
        }
        GenericObjectPoolConfig<Recognition> config = new GenericObjectPoolConfig<>();
        config.setMaxTotal(capacity);
        config.setMaxIdle(capacity);
        config.setBlockWhenExhausted(true);
        config.setMinIdle(0);

        GenericObjectPool<Recognition> pool =
                new GenericObjectPool<>(new RecognitionFactory(), config);
        ExecutorService executor = Executors.newFixedThreadPool(WORKERS);
        ExecutorService completionExecutor = Executors.newFixedThreadPool(WORKERS);
        try {
            List<Callable<Void>> tasks = new ArrayList<>();
            for (int i = 0; i < TASKS; i++) {
                tasks.add(() -> {
                    recognize(pool, audio, apiKey, completionExecutor);
                    return null;
                });
            }
            // Wait for every task, then propagate any task failure.
            List<Future<Void>> results = executor.invokeAll(tasks);
            for (Future<Void> result : results) {
                result.get();
            }
        } finally {
            executor.shutdown();
            completionExecutor.shutdownNow();
            try {
                if (!executor.awaitTermination(1, TimeUnit.MINUTES)) {
                    executor.shutdownNow();
                }
                if (!completionExecutor.awaitTermination(1, TimeUnit.MINUTES)) {
                    completionExecutor.shutdownNow();
                }
            } finally {
                pool.close();
                System.out.printf("Pool closed: created=%d, destroyed=%d, active=%d, idle=%d%n",
                        pool.getCreatedCount(), pool.getDestroyedCount(),
                        pool.getNumActive(), pool.getNumIdle());
            }
        }
    }

    private static void recognize(GenericObjectPool<Recognition> pool,
                                  Path audio, String apiKey,
                                  ExecutorService completionExecutor) throws Exception {
        // Example timeout; adjust it to the application's queueing policy.
        Recognition recognizer = pool.borrowObject(Duration.ofSeconds(30));
        boolean reusable = false;
        AtomicReference<Exception> failure = new AtomicReference<>();
        CountDownLatch completed = new CountDownLatch(1);
        try (InputStream input = Files.newInputStream(audio)) {
            RecognitionParam param = RecognitionParam.builder()
                    .model("qwen-audio-3.1-asr-flash-streaming")
                    .apiKey(apiKey).format("pcm").sampleRate(16000).build();
            ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
                @Override
                public void onEvent(RecognitionResult result) {
                    if (result.isSentenceEnd() && result.getSentence() != null) {
                        System.out.println(result.getSentence().getText());
                    }
                }

                @Override
                public void onComplete() {
                    completed.countDown();
                }

                @Override
                public void onError(Exception error) {
                    failure.set(error);
                    completed.countDown();
                }
            };
            recognizer.call(param, callback);
            // 100 ms of PCM16 mono audio at 16 kHz is 3,200 bytes.
            byte[] buffer = new byte[3200];
            int count;
            while ((count = input.read(buffer)) != -1) {
                if (failure.get() != null) {
                    throw failure.get();
                }
                recognizer.sendAudioFrame(ByteBuffer.wrap(buffer, 0, count));
                Thread.sleep(100);
                buffer = new byte[3200];
            }
            // stop() blocks in the SDK, so apply the deadline to the stop call itself.
            long deadline = System.nanoTime()
                    + TimeUnit.SECONDS.toNanos(COMPLETION_TIMEOUT_SECONDS);
            Future<?> stopTask = completionExecutor.submit(recognizer::stop);
            try {
                stopTask.get(Math.max(0, deadline - System.nanoTime()), TimeUnit.NANOSECONDS);
                long remaining = Math.max(0, deadline - System.nanoTime());
                if (!completed.await(remaining, TimeUnit.NANOSECONDS)) {
                    throw new TimeoutException("Timed out waiting for task completion");
                }
            } finally {
                stopTask.cancel(true);
            }
            if (failure.get() != null) {
                throw failure.get();
            }
            reusable = true;
            System.out.printf("Completed: request_id=%s, first_packet_ms=%d, last_packet_ms=%d%n",
                    recognizer.getLastRequestId(), recognizer.getFirstPackageDelay(),
                    recognizer.getLastPackageDelay());
        } finally {
            if (reusable) {
                pool.returnObject(recognizer);
            } else {
                // destroyObject closes the connection before discarding the object.
                pool.invalidateObject(recognizer);
            }
        }
    }

    private static class RecognitionFactory extends BasePooledObjectFactory<Recognition> {
        @Override
        public Recognition create() {
            return new Recognition();
        }

        @Override
        public PooledObject<Recognition> wrap(Recognition recognizer) {
            return new DefaultPooledObject<>(recognizer);
        }

        @Override
        public void destroyObject(PooledObject<Recognition> object) {
            if (object.getObject().getDuplexApi() != null) {
                object.getObject().getDuplexApi().close(1000, "pool cleanup");
            }
        }
    }
}
O exemplo define 30 segundos para a espera de empréstimo de objetos e 60 segundos para a conclusão de tarefas. Ambos são ajustáveis. Para captura ao vivo, ajuste a espera à latência de inicialização permitida e limite a quantidade de tarefas na fila. Ao trocar a fonte de áudio, mantenha a confirmação de conclusão, a invalidação após falhas e a liberação de recursos.

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.
  1. 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.
  2. 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.
  3. Conexões podem ser fechadas durante períodos ociosos, exigindo nova conexão. Repita o aquecimento quando necessário antes de novas medições.
Registre as latências do primeiro e do último pacote fornecidas pelo SDK, além da latência de ponta a ponta da aplicação. Defina o início e o fim de cada métrica. Filas, estabelecimento de conexões, envio de áudio e processamento do serviço afetam métricas diferentes e devem ser observados separadamente.

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 cada subtask_status antes 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.
ProblemaAção
Arquivo de entrada ou parâmetros inválidosVerifique URL, codificação, taxa de amostragem, canais e intervalos dos parâmetros. Corrija antes de reenviar.
Autenticação ou endpoint incorretoVerifique a chave de API, o workspace e a região do endpoint e corrija conforme a mensagem de erro.
Limitação de taxaReduza 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 arquivoPreserve os erros no nível da tarefa e do arquivo, identifique a causa e decida entre corrigir a entrada ou reenviar.
Use espera exponencial com variação aleatória e limite o número de tentativas e o tempo total de espera. Por exemplo, permita no máximo três tentativas e ajuste os limites ao orçamento de latência da aplicação. Após uma desconexão em tempo real, feche a conexão antiga e inicie uma tarefa com um novo ID. Registre a posição do áudio a partir do último resultado final confirmado. Reenvie o áudio não confirmado do buffer da aplicação conforme necessário e combine e remova duplicatas dos resultados pelas posições no áudio original.

Documentação relacionada