本文介绍Paraformer非实时语音识别Java SDK的参数和接口细节。
阿里云百炼为华北2(北京)地域推出了业务空间专属域名,能够为推理请求提供卓越的性能和更高的稳定性,建议从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。
{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。
用户指南:非实时语音识别
前提条件
-
已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
说明当您需要为第三方应用或用户提供临时访问权限,或者希望严格控制敏感数据访问、删除等高风险操作时,建议使用临时鉴权Token。
与长期有效的 API Key 相比,临时鉴权 Token 具备时效性短(60秒)、安全性高的特点,适用于临时调用场景,能有效降低API Key泄露的风险。
使用方式:在代码中,将原本用于鉴权的 API Key 替换为获取到的临时鉴权 Token 即可。
快速开始
核心类(Transcription)提供了异步提交任务、同步等待任务结束和异步查询任务执行结果的接口。可通过如下两种调用方式进行非实时语音识别:
-
异步提交任务+同步等待任务结束:提交任务后,阻塞当前线程直到任务结束并获取识别结果。
-
异步提交任务+异步查询任务执行结果:提交任务后,在需要的时候通过调用查询任务接口获取任务的执行结果。
异步提交任务+同步等待任务结束
-
配置请求参数。
-
调用核心类(Transcription)的
asyncCall方法异步提交任务。说明-
文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内。任务开始处理后,语音识别将以数百倍加速完成。 -
每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。
-
-
调用核心类(Transcription)的
wait方法同步等待任务结束。任务的状态包括
PENDING、RUNNING、SUCCEEDED和FAILED。当任务处于PENDING或RUNNING状态时,wait接口将被阻塞。当任务处于SUCCEEDED或FAILED状态时,wait接口不再阻塞并返回任务的执行结果。wait返回任务执行结果(TranscriptionResult)。
异步提交任务+异步查询任务执行结果
-
配置请求参数。
-
调用核心类(Transcription)的
asyncCall方法异步提交任务。说明-
文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内。任务开始处理后,语音识别将以数百倍加速完成。 -
每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。
-
-
循环调用核心类(Transcription)的
fetch方法直到获取最终的任务结果。当任务状态为
SUCCEEDED或FAILED时,停止轮询并处理结果。fetch返回任务执行结果(TranscriptionResult)。
请求参数
请求参数通过TranscriptionParam的链式方法进行配置。
|
参数 |
类型 |
默认值 |
是否必须 |
说明 |
|
model |
String |
- |
是 |
指定用于音视频文件转写的Paraformer模型名。参见支持的模型。 |
|
fileUrls |
List<String> |
- |
是 |
音视频文件转写的URL列表,支持HTTP / HTTPS协议,单次请求仅支持1个URL。 若录音文件存储在阿里云OSS,使用SDK方式不支持使用以 oss://为前缀的临时 URL。 |
|
vocabularyId |
String |
- |
否 |
最新热词ID,支持最新v2系列模型并配置语种信息,此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词。 |
|
phraseId |
String |
- |
否 |
热词ID,此次语音识别中生效此热词ID对应的热词信息。默认不启用。 注: |
|
channelId |
List<Integer> |
[0] |
否 |
指定在多音轨音频文件中需要识别的音轨索引,索引从 0 开始。例如,[0] 表示识别第一个音轨,[0, 1] 表示同时识别第一和第二个音轨。如果省略此参数,则默认处理第一个音轨。 重要
指定的每一个音轨都将独立计费。例如,为单个文件请求 [0, 1] 会产生两笔独立的费用。 |
|
disfluencyRemovalEnabled |
Boolean |
false |
否 |
过滤语气词,默认关闭。 |
|
timestampAlignmentEnabled |
Boolean |
false |
否 |
是否启用时间戳校准功能,默认关闭。 |
|
specialWordFilter |
String |
- |
否 |
指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。 若未传入该参数,系统将启用系统内置的敏感词过滤逻辑,识别结果中与阿里云百炼敏感词表匹配的词语将被替换为等长的 若传入该参数,则可实现以下敏感词处理策略:
该参数的值应为一个 JSON 字符串,其结构如下所示:
JSON字段说明:
|
|
language_hints |
String[] |
["zh", "en"] |
否 |
指定待识别语音的语言代码。 该参数仅适用于paraformer-v2模型。 支持的语言代码:
说明
通过parameter设置
通过parameters设置
|
|
diarizationEnabled |
Boolean |
false |
否 |
自动说话人分离,默认关闭。 仅适用于单声道音频,多声道音频不支持说话人分离。 启用该功能后,识别结果中将显示 说明
如果启用说话人分离功能,建议音频时长不超过2小时,否则可能导致识别失败或超时。 有关 |
|
speakerCount |
Integer |
- |
否 |
说话人数量参考值。取值范围为2至100的整数(包含2和100)。 开启说话人分离功能后( 默认自动判断说话人数量,如果配置此项,只能辅助算法尽量输出指定人数,无法保证一定会输出此人数。 |
|
apiKey |
String |
- |
否 |
用户API Key。如已将API Key配置到环境变量,则无须在代码中设置。否则一定要在代码中进行设置。 |
响应结果
任务执行结果(TranscriptionResult)
TranscriptionResult封装了当前任务执行结果。
|
接口/方法 |
参数 |
返回值 |
描述 |
|
无 |
requestId |
获取requestId。 |
|
无 |
taskId |
获取taskId。 |
|
无 |
|
获取任务状态。
说明
当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为 |
|
无 |
获取子任务执行结果(TranscriptionTaskResult)。 每个任务对一个或多个音频文件进行识别,不同音频文件在不同的子任务中处理,因此每个任务对应一到多个子任务。 |
|
|
无 |
任务执行结果,为JSON格式的数据 |
获取任务执行结果。 该结果是一个JSON格式的数据,如果您想通过 |
子任务执行结果(TranscriptionTaskResult)
TranscriptionTaskResult封装了子任务执行结果。子任务对单个音频文件进行识别。
|
接口/方法 |
参数 |
返回值 |
描述 |
|
无 |
被识别的音频文件的链接 |
获取被识别音频文件的链接。 |
|
无 |
识别结果对应的链接 |
获取识别结果对应的链接。该链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。 识别结果保存为JSON文件,您可以通过上述链接下载该文件或直接通过HTTP请求读取该文件中的内容。 JSON数据中各字段含义请参见识别结果说明。 |
|
无 |
|
获取子任务状态。
|
|
无 |
任务执行过程中关键信息,可能为空 |
获取任务执行过程中的关键信息。 当任务失败时,可查看该内容分析原因。 |
识别结果说明
识别结果保存为JSON文件。
需要关注的参数如下:
|
参数 |
类型 |
说明 |
|
audio_format |
string |
源文件中音频的格式。 |
|
channels |
array[integer] |
源文件中音频的音轨索引信息,对单轨音频返回[0],对双轨音频返回[0, 1],以此类推。 |
|
original_sampling_rate |
integer |
源文件中音频的采样率(Hz)。 |
|
original_duration |
integer |
源文件中的原始音频时长(ms)。 |
|
channel_id |
integer |
转写结果的音轨索引,以0为起始。 |
|
content_duration |
integer |
音轨中被判定为语音内容的时长(ms)。 重要
Paraformer语音识别模型服务仅对音轨中被判定为语音内容的时长进行语音转写,并据此进行计量计费,非语音内容不计量、不计费。通常情况下语音内容时长会短于原始音频时长。由于对是否存在语音内容的判定是由AI模型给出的,可能与实际情况存在一定误差。 |
|
transcript |
string |
段落级别的语音转写结果。 |
|
sentences |
array |
句子级别的语音转写结果。 |
|
words |
array |
词级别的语音转写结果。 |
|
begin_time |
integer |
开始时间戳(ms)。 |
|
end_time |
integer |
结束时间戳(ms)。 |
|
text |
string |
语音转写结果。 |
|
speaker_id |
integer |
当前说话人的索引,以0为起始,用于区分不同的说话人。 仅在启用说话人分离功能时,该字段才会显示于识别结果中。 |
|
punctuation |
string |
预测出的词之后的标点符号(如有)。 |
关键接口
任务查询参数配置类(TranscriptionQueryParam)
TranscriptionQueryParam在等待任务完成(调用Transcription的wait方法)或查询任务执行结果(调用Transcription的fetch方法)时用到。
通过静态方法FromTranscriptionParam创建TranscriptionQueryParam实例。
|
接口/方法 |
参数 |
返回值 |
描述 |
|
|
|
创建 |
核心类(Transcription)
Transcription可以通过“import com.alibaba.dashscope.audio.asr.transcription.*;”方式引入。它的关键接口如下:
|
接口/方法 |
参数 |
返回值 |
描述 |
|
|
异步提交语音识别任务。 |
|
|
|
阻塞当前线程直到异步任务结束(任务状态为 |
|
|
|
异步查询当前任务执行结果。 |
其他接口:批量查询任务状态/取消任务
详情请参见管理异步任务:支持批量查询24小时内提交的非实时语音识别任务,同时支持取消PENDING(排队)状态的任务。
错误码
如遇报错问题,请参见错误码进行排查。
若问题仍未解决,请加入开发者群反馈遇到的问题,并提供Request ID,以便进一步排查问题。
当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为SUCCEEDED,需通过subtask_status字段判断具体子任务结果。
错误返回示例:
{
"task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2024-12-16 16:30:59.170",
"scheduled_time": "2024-12-16 16:30:59.204",
"end_time": "2024-12-16 16:31:02.375",
"results": [
{
"file_url": "{YOUR_AUDIO_URL}",
"code": "InvalidFile.DownloadFailed",
"message": "The audio file cannot be downloaded.",
"subtask_status": "FAILED"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 0,
"FAILED": 1
}
}
更多示例
更多示例,请参见GitHub。
常见问题
功能特性
Q:是否支持Base64编码方式的音频?
不支持Base64编码方式的音频。仅支持可通过公网访问的 URL 所指向的音频的识别,不支持识别二进制流,也不支持直接识别本地文件。
Q:如何将音频文件以公网可访问的URL形式提供?
通常遵循以下几个步骤(这里为您提供一种思路,具体情况因不同存储产品而异,推荐将音频上传至阿里云OSS):
使用SDK时,若录音文件存储在阿里云OSS,不支持使用以 oss://为前缀的临时 URL。
使用RESTful API时,若录音文件存储在阿里云OSS,支持使用以 oss://为前缀的临时 URL:
临时 URL 有效期48小时,过期后无法使用,请勿用于生产环境。
文件上传凭证接口限流为 100 QPS 且不支持扩容,请勿用于生产环境、高并发及压测场景。
生产环境建议使用阿里云OSS 等稳定存储,确保文件长期可用并规避限流问题。
Q:多久能获取识别结果?
任务提交后将进入排队(PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内,请耐心等待。并且音频时长越长,所需时间越久。
故障排查
如遇代码报错问题,请根据错误码中的信息进行排查。
Q:识别结果和语音播放不同步怎么办?
将请求参数timestampAlignmentEnabled设为true将启用时间戳校准功能,能够让识别结果和语音播放同步。
Q:一直轮询不到结果?
可能是限流原因,请耐心等待。若需扩容,请加入开发者群进行申请。
Q:无法识别语音(无识别结果)是什么原因?
-
请检查音频是否符合要求(格式、采样率)。
-
若是使用了
paraformer-v2模型,检查language_hints的设置是否正确。 -
以上都没问题,可通过定制热词,提升对特定词语的识别效果。
更多问题
请参见GitHub QA。