本文介绍Paraformer实时语音识别Java API的使用。
前提条件
已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
模型列表
模型名 | 模型简介 |
paraformer-realtime-v2 | 推荐使用。Paraformer最新多语种实时语音识别模型。
|
paraformer-realtime-8k-v2 | 推荐使用。Paraformer最新8k中文实时语音识别模型,模型结构升级,具有更快的推理速度和更好的识别效果。
|
paraformer-realtime-v1 | Paraformer中文实时语音识别模型。
|
paraformer-realtime-8k-v1 | Paraformer中文实时语音识别模型。
|
调用模式
核心类(Recognition)提供了同步调用和流式调用等接口。请根据实际需求选择合适的调用模式:
同步调用:对本地文件进行识别,并一次性输出完整结果。
流式调用:直接对音频流(无论是从外部设备如麦克风获取的音频流,还是从本地文件读取的音频流)进行识别,并流式输出结果。
同步调用
提交单个语音实时转写任务,通过传入本地文件的方式同步阻塞地拿到转写结果。
配置请求参数。
RecognitionParam param = RecognitionParam.builder() .model("paraformer-realtime-v2") .format("wav") .sampleRate(16000) // “language_hints”只支持paraformer-realtime-v2模型 .parameter("language_hints", new String[]{"zh", "en"}) .build();
实例化核心类(Recognition)。
Recognition recognizer = new Recognition();
同步调用。
调用核心类(Recognition)的
call
方法进行识别。// 调用call方法开始识别并获取识别结果 String result = recognizer.call(param, new File("asr_example.wav"));
流式调用:基于回调
提交单个语音实时转写任务,通过实现回调接口的方式流式输出实时识别结果。
配置请求参数。
RecognitionParam param = RecognitionParam.builder() .model("paraformer-realtime-v2") .format("wav") .sampleRate(16000) // “language_hints”只支持paraformer-realtime-v2模型 .parameter("language_hints", new String[]{"zh", "en"}) .build();
实例化核心类(Recognition)。
Recognition recognizer = new Recognition();
调用核心类(Recognition)的
call
方法开启任务。// 调用call方法开始任务 recognizer.call(param, callback);
分段发送二进制音频。
您需要调用核心类(Recognition)的
sendAudioFrame
方法,将从本地文件或设备(如麦克风)读取的二进制音频流分段发送给服务端。每次发送的音频时长建议为100ms左右,数据大小建议在1KB到16KB之间。在发送音频数据的同时,服务端会回调ResultCallback
实例的方法将识别结果返回给客户端。try (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 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); } } catch (Exception e) { e.printStackTrace(); }
结束任务:调用核心类(Recognition)的
stop
方法请不要遗漏该步骤。
stop
会阻塞当前线程,直到ResultCallback
的onComplete
或者onError
方法被回调才会解除对当前线程的阻塞。recognizer.stop();
流式调用:基于Flowable
提交单个语音实时转写任务,通过实现工作流(Flowable)的方式流式输出实时识别结果。
Flowable 是一个用于工作流和业务流程管理的开源框架,它基于 Apache 2.0 许可证发布。关于Flowable的使用,请参见Flowable API详情。
高并发调用
在DashScope Java SDK中,采用了OkHttp3的连接池技术,以减少重复建立连接的开销。详情请参见实时语音识别高并发场景。
请求参数
请求参数通过RecognitionParam
的链式方法进行配置。
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | String | - | 是 | 用于实时语音识别的模型。详情请参见模型列表。 |
sampleRate | Integer | - | 是 | 待识别音频采样率。 因模型而异:
|
format | String | - | 是 | 待识别音频格式。 支持的音频格式:'pcm'、'wav'、'mp3'、'opus'、'speex'、'aac'、'amr'。 |
vocabularyId | String | - | 否 | 最新热词ID,支持最新v2系列模型并配置语种信息,此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词。 |
phraseId | String | - | 否 | 热词ID,此次语音识别中生效此热词ID对应的热词信息。默认不启用。 注: |
disfluencyRemovalEnabled | boolean | false | 否 | 过滤语气词,默认关闭。 |
language_hints | String[] | ["zh", "en"] | 否 | 指定识别语音中语言的代码列表。 该参数仅适用于paraformer-realtime-v2模型。 支持的语言代码:
仅对支持多语言的模型生效。如果不填写则模型会自动识别语种。 说明
通过parameter设置
通过parameters设置
|
semantic_punctuation_enabled | boolean | true | 否 | 是否开启语义断句,服务默认开启语义断句,如果关闭则使用VAD (Voice Activity Detection)断句。一般而言,VAD断句延迟低适用于交互场景,语义断句准确适用于会议转写场景。 此功能只有v2系列模型支持。 说明
|
max_sentence_silence | Integer | 800 | 否 | 语音断句检测阈值,如果一段语音后的静音时长超过该阈值,会被认为一个句子已经结束,参数范围200ms~6000ms,默认值800ms。 此功能只有v2系列模型支持。 说明
|
inverse_text_normalization_enabled | Boolean | true | 否 | 是否开启ITN(逆文本,Inverse Text Normalization),开启后(设置为true)中文数字会转换为阿拉伯数字。 此功能只有v2系列模型支持。 说明
通过parameter设置
通过parameters设置
|
apiKey | String | - | 否 | 用户API Key。如已将API Key配置到环境变量,则无须在代码中设置。 |
响应结果
实时识别结果(RecognitionResult
)
RecognitionResult
代表一次实时识别的结果。
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | requestId | 获取requestId。 |
| 无 | 是否是完整句子,即产生断句 | 判断给定句子是否已经结束。 |
| 无 |
| 获取单句信息,包括时间戳和文本信息等。详情请参见单句信息(Sentence)。 |
单句信息(Sentence
)
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | 句子开始时间,单位为ms | 返回句子开始时间。 |
| 无 | 句子结束时间,单位为ms | 返回句子结束时间。 |
| 无 | 识别文本 | 返回识别文本。 |
| 无 | 字时间戳信息: | 返回字时间戳信息。详情请参见字时间戳信息(Word)。 |
| 无 | 当前句子的情感 | 返回当前句子的情感:
仅在关闭语义断句( 仅paraformer-realtime-8k-v2模型支持情感识别。 |
| 无 | 当前句子识别情感的置信度 | 返回当前句子识别情感的置信度,取值范围:[0.0,1.0]。值越大表示置信度越高。 仅paraformer-realtime-8k-v2模型支持情感识别。 |
字时间戳信息(Word
)
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | 字开始时间,单位为ms | 返回字开始时间。 |
| 无 | 字结束时间,单位为ms | 返回字结束时间。 |
| 无 | 字 | 返回识别的字。 |
| 无 | 标点 | 返回标点。 |
关键接口
核心类(Recognition
)
Recognition
可以通过“import com.alibaba.dashscope.audio.asr.recognition.Recognition;
”方式引入。它的关键接口如下:
接口/方法 | 参数 | 返回值 | 描述 |
|
| 无 | 基于回调形式的流式实时识别,该方法不会阻塞当前线程。 |
|
| 识别结果 | 基于本地文件的同步调用,该方法会阻塞当前线程直到全部音频读完,该方法要求所识别文件具有可读权限。 |
|
|
| 基于Flowable的流式实时识别。 |
|
| 无 | 推送音频,每次推送的音频流不宜过大或过小,建议每包音频时长为100ms左右,大小在1KB~16KB之间。 识别结果通过回调接口(ResultCallback)的onEvent方法获取。 |
| 无 | 无 | 停止实时识别。 该方法会阻塞当前线程,直到回调实例 |
| 无 | requestId | 获取当前任务的requestId,在调用 说明 该方法自2.18.0版本及以后的SDK中才开始提供。 |
| 无 | 首包延迟 | 获取首包延迟,从发送第一包音频到收到首包识别结果延迟,在任务完成后使用。 说明 该方法自2.18.0版本及以后的SDK中才开始提供。 |
| 无 | 尾包延迟 | 获得尾包延迟,发送 说明 该方法自2.18.0版本及以后的SDK中才开始提供。 |
回调接口(ResultCallback
)
流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
回调方法的实现,通过继承抽象类ResultCallback
完成,继承该抽象类时,您可以指定泛型为RecognitionResult
。RecognitionResult
封装了服务器返回的数据结构。
由于Java支持连接复用,因此没有onClose
和onOpen
。
接口/方法 | 参数 | 返回值 | 描述 |
|
| 无 | 当服务有回复时会被回调。 |
| 无 | 无 | 任务完成后该接口被回调。 |
|
| 无 | 发生异常时该接口被回调。 |
错误码
在使用API过程中,如果调用失败并返回错误信息,请参见错误信息进行解决。
更多示例
更多示例,请参见GitHub。
常见问题
请参见GitHub QA。