Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Paraformer Real-time Speech Recognition Java SDK

Última atualização: Sep 09, 2026

Este tópico descreve os parâmetros e os detalhes da interface do Java SDK para reconhecimento de fala em tempo real Paraformer.

ImportanteO Alibaba Cloud Model Studio lançou um domínio específico de workspace para a região China (Beijing). O novo domínio dedicado oferece desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com.

Substitua {WorkspaceId} pelo seu Workspace ID real. O domínio existente permanece totalmente funcional.

ImportanteEste documento aplica-se apenas à região China (Beijing). Para usar modelos, utilize uma chave de API da região China (Beijing).

Guia do usuário: Para introdução aos modelos e recomendações de seleção, consulte Real-time speech recognition - Fun-ASR/Paraformer.

Pré-requisitos

Ative o service e Obtain an API key. Configure API key as an environment variable em vez de codificá-la diretamente no código para evitar riscos de segurança causados por vazamento de código.

ObservaçãoPara fornecer acesso temporário a aplicativos ou usuários terceiros, ou para controlar rigorosamente operações de alto risco, como acessar ou excluir dados sensíveis, recomendamos o uso de temporary authentication tokens.

Em comparação com chaves de API de longo prazo, os tokens de autenticação temporários possuem curto período de validade (60 segundos) e maior segurança. Isso os torna adequados para cenários de chamada temporária e reduz efetivamente o risco de vazamento da chave de API.

Uso: No seu código, substitua a chave de API originalmente usada para autenticação pelo token de autenticação temporário obtido.

Lista de modelos

paraformer-realtime-v2paraformer-realtime-8k-v2
Caso de uso

Transmissões ao vivo, reuniões e cenários similares

Reconhecimento de áudio de 8 kHz em cenários como atendimento telefônico e correio de voz

Taxa de amostragem

Qualquer

8kHz

Idioma

Chinês (incluindo mandarim e vários dialetos), inglês, japonês, coreano, alemão, francês, russo

Dialetos chineses suportados: Xangainês, Wu, Minnan, Nordestino, Gansu, Guizhou, Henan, Hubei, Hunan, Jiangxi, Ningxia, Shanxi, Shaanxi, Shandong, Sichuan, Tianjin, Yunnan, Cantonês

Chinês

Previsão de pontuação

Suportado por padrão, sem necessidade de configuração

Suportado por padrão, sem necessidade de configuração

Normalização inversa de texto (ITN)

Suportado por padrão, sem necessidade de configuração

Suportado por padrão, sem necessidade de configuração

Palavras-chave personalizadas

Consulte Custom hotwords

Consulte Custom hotwords

Especificar idioma de reconhecimento

Especifique por meio do parâmetro language_hints

Reconhecimento de sentimento

(Clique para visualizar o uso)

O reconhecimento de sentimento segue estas restrições:

  • Disponível apenas para o modelo paraformer-realtime-8k-v2.
  • A segmentação semântica deve estar desativada (controlada via Request parameters semantic_punctuation_enabled). A segmentação semântica é desativada por padrão.
  • Os resultados do reconhecimento de sentimento aparecem somente quando o método isSentenceEnd de Real-time recognition result (RecognitionResult) retorna true.

Como obter resultados de reconhecimento de sentimento: Chame os métodos getEmoTag e getEmoConfidence de Sentence information (Sentence) para obter, respectivamente, o sentimento e a confiança do sentimento da frase atual.

Início rápido

A Recognition class fornece interfaces de chamada não streaming e streaming bidirecional. Escolha o método de chamada apropriado conforme suas necessidades:

  • Chamada não streaming: Reconhece arquivos locais e retorna o resultado completo de uma só vez. Adequado para processamento de áudio pré-gravado.
  • Chamada streaming bidirecional: Reconhece fluxos de áudio diretamente e gera resultados em tempo real. O fluxo de áudio pode vir de dispositivos externos (como um microfone) ou ser lido de um arquivo local. Ideal para cenários que exigem feedback imediato.

Chamada não streaming

Envie uma única tarefa de conversão de fala em texto em tempo real e obtenha sincronamente o resultado da transcrição passando um arquivo local.

image

Instancie a Recognition class, chame o método call com Request parameters e o arquivo a ser reconhecido, execute o reconhecimento e obtenha o resultado.

Clique para visualizar o exemplo completo

import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.utils.Constants;

import java.io.File;

public class Main {
    public static void main(String[] args) {
        // The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
        // Create a Recognition instance
        Recognition recognizer = new Recognition();
        // Create RecognitionParam
        RecognitionParam param =
                RecognitionParam.builder()
                        // If you have not configured the API Key as an environment variable, uncomment the following line and replace apiKey with your own API Key
                        // .apiKey("yourApikey")
                        .model("paraformer-realtime-v2")
                        .format("wav")
                        .sampleRate(16000)
                        // "language_hints" is only supported by the paraformer-realtime-v2 model
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .build();

        try {
            System.out.println("Recognition result: " + recognizer.call(param, new File("{YOUR_AUDIO_FILE}")));
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // Close the WebSocket connection after the task ends
            recognizer.getDuplexApi().close(1000, "bye");
        }
        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
        System.exit(0);
    }
}

Streaming bidirecional: baseado em callback

Envie uma única tarefa de conversão de fala em texto em tempo real e transmita os resultados de reconhecimento em tempo real pela interface de callback.

image
  1. Inicie o reconhecimento de fala streaming

    Instancie a Recognition class, chame o método call com Request parameters e Callback interface (ResultCallback) para iniciar o reconhecimento de fala streaming.

  2. Transmita dados de áudio

    Chame o método sendAudioFrame da Recognition class em um loop para enviar segmentos de fluxo de áudio binário lidos de um arquivo local ou dispositivo (como um microfone) para o servidor.

    Durante a transmissão dos dados de áudio, o servidor retorna resultados de reconhecimento ao cliente em tempo real pelo método onEvent da Callback interface (ResultCallback).

    Recomenda-se que cada segmento de áudio tenha duração aproximada de 100 milissegundos, com tamanho de dados entre 1 KB e 16 KB.

  3. Finalize o processamento

    Chame o método stop da Recognition class para encerrar o reconhecimento de fala.

    Este método bloqueia a thread atual até que o callback onComplete ou onError da Callback interface (ResultCallback) seja acionado.

Clique para visualizar o exemplo completo

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 javax.sound.sampled.AudioFormat;
import javax.sound.sampled.AudioSystem;
import javax.sound.sampled.TargetDataLine;

import java.nio.ByteBuffer;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

public class Main {
    public static void main(String[] args) throws InterruptedException {
        // The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
        ExecutorService executorService = Executors.newSingleThreadExecutor();
        executorService.submit(new RealtimeRecognitionTask());
        executorService.shutdown();
        executorService.awaitTermination(1, TimeUnit.MINUTES);
        System.exit(0);
    }
}

class RealtimeRecognitionTask implements Runnable {
    @Override
    public void run() {
        RecognitionParam param = RecognitionParam.builder()
                // If you have not configured the API Key as an environment variable, replace apiKey with your own API Key
                // .apiKey("yourApikey")
                .model("paraformer-realtime-v2")
                .format("wav")
                .sampleRate(16000)
                // "language_hints" is only supported by the paraformer-realtime-v2 model
                .parameter("language_hints", new String[]{"zh", "en"})
                .build();
        Recognition recognizer = new Recognition();

        ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
            @Override
            public void onEvent(RecognitionResult result) {
                if (result.isSentenceEnd()) {
                    System.out.println("Final Result: " + result.getSentence().getText());
                } else {
                    System.out.println("Intermediate Result: " + result.getSentence().getText());
                }
            }

            @Override
            public void onComplete() {
                System.out.println("Recognition complete");
            }

            @Override
            public void onError(Exception e) {
                System.out.println("RecognitionCallback error: " + e.getMessage());
            }
        };
        try {
            recognizer.call(param, callback);
            // Create audio format
            AudioFormat audioFormat = new AudioFormat(16000, 16, 1, true, false);
            // Match the default recording device based on the format
            TargetDataLine targetDataLine =
                    AudioSystem.getTargetDataLine(audioFormat);
            targetDataLine.open(audioFormat);
            // Start recording
            targetDataLine.start();
            ByteBuffer buffer = ByteBuffer.allocate(1024);
            long start = System.currentTimeMillis();
            // Record for 50s and perform real-time transcription
            while (System.currentTimeMillis() - start < 50000) {
                int read = targetDataLine.read(buffer.array(), 0, buffer.capacity());
                if (read > 0) {
                    buffer.limit(read);
                    // Send the recorded audio data to the streaming recognition service
                    recognizer.sendAudioFrame(buffer);
                    buffer = ByteBuffer.allocate(1024);
                    // Recording rate is limited, sleep briefly to prevent high CPU usage
                    Thread.sleep(20);
                }
            }
            recognizer.stop();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // Close the WebSocket connection after the task ends
            recognizer.getDuplexApi().close(1000, "bye");
        }

        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
    }
}
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 java.io.FileInputStream;
import java.nio.ByteBuffer;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

class TimeUtils {
    private static final DateTimeFormatter formatter =
            DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");

    public static String getTimestamp() {
        return LocalDateTime.now().format(formatter);
    }
}

public class Main {
    public static void main(String[] args) throws InterruptedException {
        // The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
        ExecutorService executorService = Executors.newSingleThreadExecutor();
        executorService.submit(new RealtimeRecognitionTask(Paths.get(System.getProperty("user.dir"), "{YOUR_AUDIO_FILE}")));
        executorService.shutdown();

        // wait for all tasks to complete
        executorService.awaitTermination(1, TimeUnit.MINUTES);
        System.exit(0);
    }
}

class RealtimeRecognitionTask implements Runnable {
    private Path filepath;

    public RealtimeRecognitionTask(Path filepath) {
        this.filepath = filepath;
    }

    @Override
    public void run() {
        RecognitionParam param = RecognitionParam.builder()
                // If you have not configured the API Key as an environment variable, replace apiKey with your own API Key
                // .apiKey("yourApikey")
                .model("paraformer-realtime-v2")
                .format("wav")
                .sampleRate(16000)
                // "language_hints" is only supported by the paraformer-realtime-v2 model
                .parameter("language_hints", new String[]{"zh", "en"})
                .build();
        Recognition recognizer = new Recognition();

        String threadName = Thread.currentThread().getName();

        ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
            @Override
            public void onEvent(RecognitionResult message) {
                if (message.isSentenceEnd()) {

                    System.out.println(TimeUtils.getTimestamp()+" "+
                            "[process " + threadName + "] Final Result:" + message.getSentence().getText());
                } else {
                    System.out.println(TimeUtils.getTimestamp()+" "+
                            "[process " + threadName + "] Intermediate Result: " + message.getSentence().getText());
                }
            }

            @Override
            public void onComplete() {
                System.out.println(TimeUtils.getTimestamp()+" "+"[" + threadName + "] Recognition complete");
            }

            @Override
            public void onError(Exception e) {
                System.out.println(TimeUtils.getTimestamp()+" "+
                        "[" + threadName + "] RecognitionCallback error: " + e.getMessage());
            }
        };

        try {
            recognizer.call(param, callback);
            // Please replace the path with your audio file path
            System.out.println(TimeUtils.getTimestamp()+" "+"[" + threadName + "] Input file_path is: " + this.filepath);
            // Read file and send audio by chunks
            FileInputStream fis = new FileInputStream(this.filepath.toFile());
            // chunk size set to 1 seconds for 16KHz sample rate
            byte[] buffer = new byte[3200];
            int bytesRead;
            // Loop to read chunks of the file
            while ((bytesRead = fis.read(buffer)) != -1) {
                ByteBuffer byteBuffer;
                // Handle the last chunk which might be smaller than the buffer size
                System.out.println(TimeUtils.getTimestamp()+" "+"[" + threadName + "] bytesRead: " + bytesRead);
                if (bytesRead < buffer.length) {
                    byteBuffer = ByteBuffer.wrap(buffer, 0, bytesRead);
                } else {
                    byteBuffer = ByteBuffer.wrap(buffer);
                }

                recognizer.sendAudioFrame(byteBuffer);
                buffer = new byte[3200];
                Thread.sleep(100);
            }
            System.out.println(TimeUtils.getTimestamp()+" "+LocalDateTime.now());
            recognizer.stop();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // Close the WebSocket connection after the task ends
            recognizer.getDuplexApi().close(1000, "bye");
        }

        System.out.println(
                "["
                        + threadName
                        + "][Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
    }
}

Streaming bidirecional: baseado em Flowable

Envie uma única tarefa de conversão de fala em texto em tempo real e transmita os resultados de reconhecimento em tempo real por um fluxo de trabalho Flowable.

Flowable é um framework de código aberto para gerenciamento de fluxo de trabalho e processos de negócios, lançado sob a licença Apache 2.0. Para mais informações sobre o Flowable, consulte a documentação da API Flowable.

Clique para visualizar o exemplo completo

Chame diretamente o método streamCall da Recognition class para iniciar o reconhecimento.

O método streamCall retorna uma instância Flowable<RecognitionResult>. Você pode chamar métodos como blockingForEach e subscribe da instância Flowable para processar os resultados do reconhecimento. Os resultados são encapsulados em RecognitionResult.

O método streamCall requer dois parâmetros:

  • Instância RecognitionParam (Request parameters): Use-a para definir parâmetros como modelo, taxa de amostragem e formato de áudio para o reconhecimento de fala.
  • Instância Flowable<ByteBuffer>: Crie uma instância do tipo Flowable<ByteBuffer> e implemente o método de análise do fluxo de áudio dentro dela.
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.BackpressureStrategy;
import io.reactivex.Flowable;

import javax.sound.sampled.AudioFormat;
import javax.sound.sampled.AudioSystem;
import javax.sound.sampled.TargetDataLine;
import java.nio.ByteBuffer;

public class Main {
    public static void main(String[] args) throws NoApiKeyException {
        // The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
        // Create a Flowable<ByteBuffer>
        Flowable<ByteBuffer> audioSource =
                Flowable.create(
                        emitter -> {
                            new Thread(
                                    () -> {
                                        try {
                                            // Create audio format
                                            AudioFormat audioFormat = new AudioFormat(16000, 16, 1, true, false);
                                            // Match the default recording device based on the format
                                            TargetDataLine targetDataLine =
                                                    AudioSystem.getTargetDataLine(audioFormat);
                                            targetDataLine.open(audioFormat);
                                            // Start recording
                                            targetDataLine.start();
                                            ByteBuffer buffer = ByteBuffer.allocate(1024);
                                            long start = System.currentTimeMillis();
                                            // Record for 50s and perform real-time transcription
                                            while (System.currentTimeMillis() - start < 50000) {
                                                int read = targetDataLine.read(buffer.array(), 0, buffer.capacity());
                                                if (read > 0) {
                                                    buffer.limit(read);
                                                    // Send the recorded audio data to the streaming recognition service
                                                    emitter.onNext(buffer);
                                                    buffer = ByteBuffer.allocate(1024);
                                                    // Recording rate is limited, sleep briefly to prevent high CPU usage
                                                    Thread.sleep(20);
                                                }
                                            }
                                            // Notify the end of transcription
                                            emitter.onComplete();
                                        } catch (Exception e) {
                                            emitter.onError(e);
                                        }
                                    })
                                    .start();
                        },
                        BackpressureStrategy.BUFFER);

        // Create Recognizer
        Recognition recognizer = new Recognition();
        // Create RecognitionParam, pass the Flowable<ByteBuffer> created above to the audioFrames parameter
        RecognitionParam param = RecognitionParam.builder()
                // If you have not configured the API Key as an environment variable, replace apiKey with your own API Key
                // .apiKey("yourApikey")
                .model("paraformer-realtime-v2")
                .format("pcm")
                .sampleRate(16000)
                // "language_hints" is only supported by the paraformer-realtime-v2 model
                .parameter("language_hints", new String[]{"zh", "en"})
                .build();

        // Streaming call interface
        recognizer
                .streamCall(param, audioSource)
                .blockingForEach(
                        result -> {
                            // Subscribe to the output result
                            if (result.isSentenceEnd()) {
                                System.out.println("Final Result: " + result.getSentence().getText());
                            } else {
                                System.out.println("Intermediate Result: " + result.getSentence().getText());
                            }
                        });
        // Close the WebSocket connection after the task ends
        recognizer.getDuplexApi().close(1000, "bye");
        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
        System.exit(0);
    }
}

Chamadas de alta concorrência

O DashScope Java SDK utiliza pool de conexões OkHttp3 para reduzir a sobrecarga de estabelecimento repetido de conexões. Para mais informações, consulte Optimize Paraformer real-time speech recognition for high concurrency.

Parâmetros de solicitação

Configure parâmetros como modelo, taxa de amostragem e formato de áudio pelos métodos encadeados de RecognitionParam. Passe o objeto de parâmetro configurado para o método call/streamCall da Recognition class.

Clique para visualizar o exemplo

RecognitionParam param = RecognitionParam.builder()
  .model("paraformer-realtime-v2")
  .format("pcm")
  .sampleRate(16000)
  // "language_hints" is only supported by the paraformer-realtime-v2 model
  .parameter("language_hints", new String[]{"zh", "en"})
  .build();
ParâmetroTipoPadrãoObrigatórioDescrição

model

String

Sim

Modelo para reconhecimento de fala em tempo real. Para mais informações, consulte Model list.

sampleRate

Integer

Sim

Define a taxa de amostragem (em Hz) do áudio a ser reconhecido.

Varia conforme o modelo:

  • paraformer-realtime-v2 suporta qualquer taxa de amostragem.
  • paraformer-realtime-8k-v2 suporta apenas taxa de amostragem de 8000 Hz.

format

String

Sim

Define o formato de áudio a ser reconhecido.

Formatos de áudio suportados: pcm, wav, mp3, opus, speex, aac, amr.

Importanteopus/speex: Devem usar encapsulamento Ogg.

wav: Deve ser codificado em PCM.

amr: Apenas o tipo AMR-NB é suportado.

vocabularyId

String

Não

Define o ID das palavras-chave. Se não definido, as palavras-chave não terão efeito. Use este campo para definir o ID das palavras-chave para modelos v2 e posteriores.

Na sessão atual de reconhecimento de fala, as informações de palavras-chave correspondentes a este ID serão aplicadas. Para uso detalhado, consulte Custom hotwords.

disfluencyRemovalEnabled

boolean

false

Não

Define se deve filtrar palavras de preenchimento:

  • true: Filtra palavras de preenchimento
  • false (padrão): Não filtra palavras de preenchimento

language_hints

String[]

["zh", "en"]

Não

Define os códigos de idioma para reconhecimento. Se não for possível determinar o idioma antecipadamente, deixe este campo indefinido e o modelo detectará o idioma automaticamente.

Códigos de idioma suportados atualmente:

  • zh: Chinês
  • en: Inglês
  • ja: Japonês
  • yue: Cantonês
  • ko: Coreano
  • de: Alemão
  • fr: Francês
  • ru: Russo

Este parâmetro só tem efeito para modelos que suportam múltiplos idiomas (consulte Model list).

Observaçãolanguage_hints deve ser definido pelo método parameter ou parameters da instância RecognitionParam:

RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("language_hints", new String[]{"zh", "en"})
 .build();
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("language_hints", new String[]{"zh", "en"}))
 .build();

semantic_punctuation_enabled

boolean

false

Não

Define se deve ativar a segmentação semântica. Desativado por padrão.

  • true: Ativa a segmentação semântica e desativa a segmentação VAD (Detecção de Atividade de Voz).
  • false (padrão): Ativa a segmentação VAD (Detecção de Atividade de Voz) e desativa a segmentação semântica.

A segmentação semântica oferece maior precisão e é adequada para cenários de transcrição de reuniões. A segmentação VAD (Detecção de Atividade de Voz) possui menor latência e é adequada para cenários interativos.

Ao ajustar o parâmetro semantic_punctuation_enabled, você pode alternar flexivelmente o método de segmentação de reconhecimento de fala para adequar-se a diferentes cenários.

Este parâmetro só tem efeito quando o modelo é v2 ou posterior.

Observaçãosemantic_punctuation_enabled deve ser definido pelo método parameter ou parameters da instância RecognitionParam:

RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("semantic_punctuation_enabled", true)
 .build();
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("semantic_punctuation_enabled", true))
 .build();

max_sentence_silence

Integer

800

Não

Define o limiar de duração de silêncio (em ms) para segmentação VAD (Detecção de Atividade de Voz).

Quando a duração do silêncio após um segmento de fala excede este limiar, o sistema determina que a frase terminou.

O intervalo do parâmetro é de 200 ms a 6000 ms, com valor padrão de 800 ms.

Este parâmetro só tem efeito quando o parâmetro semantic_punctuation_enabled é false (segmentação VAD) e o modelo é v2 ou posterior.

Observaçãomax_sentence_silence deve ser definido pelo método parameter ou parameters da instância RecognitionParam:

RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("max_sentence_silence", 800)
 .build();
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("max_sentence_silence", 800))
 .build();

multi_threshold_mode_enabled

boolean

false

Não

Quando esta opção está ativada (true), ela impede que a segmentação VAD corte frases excessivamente longas. Desativado por padrão.

Este parâmetro só tem efeito quando o parâmetro semantic_punctuation_enabled é false (segmentação VAD) e o modelo é v2 ou posterior.

Observaçãomulti_threshold_mode_enabled deve ser definido pelo método parameter ou parameters da instância RecognitionParam:

RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("multi_threshold_mode_enabled", true)
 .build();
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("multi_threshold_mode_enabled", true))
 .build();

punctuation_prediction_enabled

boolean

true

Não

Define se deve adicionar pontuação automaticamente nos resultados de reconhecimento:

  • true (padrão): Sim
  • false: Não

Este parâmetro só tem efeito quando o modelo é v2 ou posterior.

Observaçãopunctuation_prediction_enabled deve ser definido pelo método parameter ou parameters da instância RecognitionParam:

RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("punctuation_prediction_enabled", false)
 .build();
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("punctuation_prediction_enabled", false))
 .build();

heartbeat

boolean

false

Não

Para manter uma conexão longa com o servidor, use esta opção para controlar o comportamento:

  • true: A conexão com o servidor pode ser mantida sem interrupção ao enviar continuamente áudio silencioso.

  • false (padrão): Mesmo ao enviar continuamente áudio silencioso, a conexão será desconectada após 60 segundos devido a timeout.

    Áudio silencioso refere-se a arquivos de áudio ou fluxos de dados que não contêm sinal sonoro. Áudio silencioso pode ser gerado por vários métodos, como usar software de edição de áudio como Audacity ou Adobe Audition, ou por ferramentas de linha de comando como FFmpeg.

Este parâmetro só tem efeito quando o modelo é v2 ou posterior.

ObservaçãoA versão do SDK deve ser 2.19.1 ou posterior para usar este campo.

heartbeat deve ser definido pelo método parameter ou parameters da instância RecognitionParam:

RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("heartbeat", true)
 .build();
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("heartbeat", true))
 .build();

inverse_text_normalization_enabled

boolean

true

Não

Define se deve ativar ITN (Normalização Inversa de Texto).

Ativado por padrão (true). Quando ativado, numerais chineses são convertidos para numerais arábicos.

Este parâmetro só tem efeito quando o modelo é v2 ou posterior.

Observaçãoinverse_text_normalization_enabled deve ser definido pelo método parameter ou parameters da instância RecognitionParam:

RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("inverse_text_normalization_enabled", false)
 .build();
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("inverse_text_normalization_enabled", false))
 .build();

apiKey

String

Não

Chave de API do usuário.

Interfaces principais

Classe Recognition

A classe Recognition é importada via "import com.alibaba.dashscope.audio.asr.recognition.Recognition;". Suas interfaces principais são as seguintes:

Interface/MétodoParâmetroValor de retornoDescrição
public void call(RecognitionParam param, final ResultCallback<RecognitionResult> callback)

Nenhum

Reconhecimento em tempo real streaming baseado em callback. Este método não bloqueia a thread atual.

public String call(RecognitionParam param, File file)

Resultado do reconhecimento

Chamada não streaming baseada em arquivo local. Este método bloqueia a thread atual até que todo o áudio seja lido. O arquivo a ser reconhecido deve ter permissões de leitura.

public Flowable<RecognitionResult> streamCall(RecognitionParam param, Flowable<ByteBuffer> audioFrame)

Flowable<RecognitionResult>

Reconhecimento em tempo real streaming baseado em Flowable.

public void sendAudioFrame(ByteBuffer audioFrame)
  • audioFrame: Fluxo de áudio binário do tipo ByteBuffer

Nenhum

Envia dados de áudio. Cada pacote de áudio não deve ser muito grande nem muito pequeno. Recomenda-se que cada pacote tenha duração aproximada de 100 ms, com tamanho entre 1 KB e 16 KB.

Os resultados de reconhecimento são obtidos pelo método onEvent da Callback interface (ResultCallback).

public void stop()

Nenhum

Nenhum

Interrompe o reconhecimento em tempo real.

Este método bloqueia a thread atual até que o método onComplete ou onError da instância ResultCallback seja chamado.

recognizer.getDuplexApi().close(int code, String reason)

code: Código de fechamento WebSocket

reason: Motivo do fechamento

Estes dois parâmetros podem ser configurados de acordo com a documentação The WebSocket Protocol.

true

Após o término da tarefa, feche a conexão WebSocket independentemente de ter ocorrido uma exceção, para evitar vazamentos de conexão. Para informações sobre como reutilizar conexões para melhorar a eficiência, consulte Optimize Paraformer real-time speech recognition for high concurrency.

public String getLastRequestId()

Nenhum

requestId

Obtém o requestId da tarefa atual. Disponível após iniciar uma nova tarefa com call ou streamingCall.

ObservaçãoEste método está disponível a partir da versão 2.18.0 do SDK.

public long getFirstPackageDelay()

Nenhum

Atraso do primeiro pacote

Obtém o atraso do primeiro pacote, que é 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.

ObservaçãoEste método está disponível a partir da versão 2.18.0 do SDK.

public long getLastPackageDelay()

Nenhum

Atraso do último pacote

Obtém o atraso do último pacote, que é a latência desde o envio do comando stop até o recebimento do último resultado de reconhecimento. Use após a conclusão da tarefa.

ObservaçãoEste método está disponível a partir da versão 2.18.0 do SDK.

Interface de callback (ResultCallback)

Durante bidirectional streaming calls, o servidor retorna informações e dados importantes do processo ao cliente por callbacks. Implemente os métodos de callback para lidar com as informações ou dados retornados pelo servidor.

Os métodos de callback são implementados estendendo a classe abstrata ResultCallback. Ao estender esta classe abstrata, especifique o tipo genérico como RecognitionResult. RecognitionResult encapsula a estrutura de dados retornada pelo servidor.

Como o Java suporta reutilização de conexão, não existem callbacks onClose ou onOpen.

Exemplo

ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
    @Override
    public void onEvent(RecognitionResult result) {
        System.out.println("RequestId: " + result.getRequestId());
        // Implement your logic to process speech recognition results here
    }

    @Override
    public void onComplete() {
        System.out.println("Task completed");
    }

    @Override
    public void onError(Exception e) {
        System.out.println("Task failed: " + e.getMessage());
    }
};
Interface/MétodoParâmetroValor de retornoDescrição
public void onEvent(RecognitionResult result)

result: Real-time recognition result (RecognitionResult)

Nenhum

Chamado quando o servidor envia uma resposta.

public void onComplete()

Nenhum

Nenhum

Chamado quando a tarefa é concluída.

public void onError(Exception e)

e: Informações da exceção

Nenhum

Chamado quando ocorre uma exceção.

Resposta

Resultado de reconhecimento em tempo real (RecognitionResult)

RecognitionResult representa o resultado de uma sessão de reconhecimento em tempo real.

Interface/MétodoParâmetroValor de retornoDescrição
public String getRequestId()

Nenhum

requestId

Obtém o requestId.

public boolean isSentenceEnd()

Nenhum

Se é uma frase completa, ou seja, se um limite de frase foi atingido

Determina se a frase fornecida terminou.

public Sentence getSentence()

Nenhum

Sentence information (Sentence)

Obtém informações da frase, incluindo timestamps e texto.

Informações da frase (Sentence)

Interface/MétodoParâmetroValor de retornoDescrição
public Long getBeginTime()

Nenhum

Tempo de início da frase em ms

Retorna o tempo de início da frase.

public Long getEndTime()

Nenhum

Tempo de término da frase em ms

Retorna o tempo de término da frase.

public String getText()

Nenhum

Texto reconhecido

Retorna o texto reconhecido.

public List<Word> getWords()

Nenhum

Lista de Word timestamp information (Word)

Retorna informações de timestamp no nível de palavra.

public String getEmoTag()

Nenhum

Sentimento da frase atual

Retorna o sentimento da frase atual:

  • positive: Sentimento positivo, como feliz ou satisfeito
  • negative: Sentimento negativo, como irritado ou triste
  • neutral: Sem sentimento evidente

O reconhecimento de sentimento segue estas restrições:

  • Disponível apenas para o modelo paraformer-realtime-8k-v2.
  • A segmentação semântica deve estar desativada (controlada via Request parameters semantic_punctuation_enabled). A segmentação semântica é desativada por padrão.
  • Os resultados do reconhecimento de sentimento aparecem somente quando o método isSentenceEnd de Real-time recognition result (RecognitionResult) retorna true.
public Double getEmoConfidence()

Nenhum

Confiança do sentimento da frase atual

Retorna a confiança do sentimento da frase atual. Intervalo de valores: [0,0, 1,0]. Um valor maior indica maior confiança.

O reconhecimento de sentimento segue estas restrições:

  • Disponível apenas para o modelo paraformer-realtime-8k-v2.
  • A segmentação semântica deve estar desativada (controlada via Request parameters semantic_punctuation_enabled). A segmentação semântica é desativada por padrão.
  • Os resultados do reconhecimento de sentimento aparecem somente quando o método isSentenceEnd de Real-time recognition result (RecognitionResult) retorna true.

Informações de timestamp de palavra (Word)

Interface/MétodoParâmetroValor de retornoDescrição
public long getBeginTime()

Nenhum

Tempo de início da palavra em ms

Retorna o tempo de início da palavra.

public long getEndTime()

Nenhum

Tempo de término da palavra em ms

Retorna o tempo de término da palavra.

public String getText()

Nenhum

Palavra

Retorna a palavra reconhecida.

public String getPunctuation()

Nenhum

Pontuação

Retorna 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.

Mais exemplos

Para mais exemplos, consulte o GitHub.

FAQ

Perguntas sobre recursos

P: Como manter uma conexão longa com o servidor durante silêncio prolongado?

Defina o parâmetro de solicitação heartbeat como true e envie continuamente áudio silencioso para o servidor.

Áudio silencioso refere-se a arquivos de áudio ou fluxos de dados que não contêm sinal sonoro. Áudio silencioso pode ser gerado por vários métodos, como usar software de edição de áudio como Audacity ou Adobe Audition, ou por ferramentas de linha de comando como FFmpeg.

P: Como converter áudio para um formato suportado?

Utilize a ferramenta FFmpeg. Para mais usos, consulte o site oficial do FFmpeg.

# Basic conversion command (universal template)
# -i: Input file path. Example: audio.wav
# -c:a: Audio codec. Example: aac, libmp3lame, pcm_s16le
# -b:a: Bitrate (quality control). Example: 192k, 320k
# -ar: Sample rate. Example: 44100 (CD), 48000, 16000
# -ac: Number of channels. Example: 1 (mono), 2 (stereo)
# -y: Overwrite existing file (no value needed)
ffmpeg -i input_audio.ext -c:a codec_name -b:a bitrate -ar sample_rate -ac channels output.ext

# Example: WAV -> MP3 (preserve original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# Example: MP3 -> WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# Example: M4A -> AAC (extract/convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac  # Direct extraction without re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # Re-encode for higher quality
# Example: FLAC lossless -> Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

P: É possível visualizar o intervalo de tempo de cada frase?

Sim. Os resultados do reconhecimento de fala incluem os timestamps de início e fim de cada frase, que podem ser usados para determinar o intervalo de tempo de cada frase.

P: Como reconhecer um arquivo local (áudio gravado)?

Existem duas maneiras de reconhecer arquivos locais:

  • Passar o caminho do arquivo local diretamente: Este método obtém o resultado completo do reconhecimento apenas após todo o reconhecimento terminar, não sendo adequado para cenários que exigem feedback imediato.

    Consulte Non-streaming call. Passe o caminho do arquivo para o método call da Recognition class para reconhecer diretamente o arquivo gravado.

  • Converter o arquivo local em um fluxo binário para reconhecimento: Este método reconhece o arquivo enquanto transmite os resultados de reconhecimento, adequado para cenários que exigem feedback imediato.

Solução de problemas

P: O que causa falha no reconhecimento de fala (sem resultados de reconhecimento)?

  1. Verifique se o formato de áudio (format) e a taxa de amostragem (sampleRate/sample_rate) nos parâmetros de solicitação estão definidos corretamente e cumprem as restrições de parâmetros. A seguir estão exemplos comuns de erros:

    • A extensão do arquivo de áudio é .wav, mas o formato real é MP3, e o parâmetro de solicitação format está 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_rate está definido como 48000 (configuração incorreta de parâmetro).

    Use a ferramenta ffprobe para obter informações sobre container, codec, taxa de amostragem, canal e outros dados do áudio:

ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
  1. Ao usar o modelo paraformer-realtime-v2, verifique se o idioma definido em language_hints corresponde ao idioma real do áudio.

    Por exemplo: O áudio está realmente em chinês, mas language_hints está definido como en (inglês).

  2. Se todas as verificações acima forem aprovadas, utilize palavras-chave personalizadas para melhorar a precisão do reconhecimento de palavras específicas.