本文介绍Paraformer非实时语音识别Java SDK的参数和接口细节。
前提条件
快速开始
核心类(Transcription)提供了异步提交任务、同步等待任务结束和异步查询任务执行结果的接口。可通过如下两种调用方式进行非实时语音识别:
- 异步提交任务+同步等待任务结束:提交任务后,阻塞当前线程直到任务结束并获取识别结果。
- 异步提交任务+异步查询任务执行结果:提交任务后,在需要的时候通过调用查询任务接口获取任务的执行结果。
异步提交任务+同步等待任务结束
- 配置请求参数。
- 实例化核心类(Transcription)。
-
调用核心类(Transcription)的
asyncCall方法异步提交任务。- 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内。任务开始处理后,语音识别将以数百倍加速完成。 - 每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。
- 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
-
调用核心类(Transcription)的
wait方法同步等待任务结束。 任务的状态包括PENDING、RUNNING、SUCCEEDED和FAILED。当任务处于PENDING或RUNNING状态时,wait接口将被阻塞。当任务处于SUCCEEDED或FAILED状态时,wait接口不再阻塞并返回任务的执行结果。wait返回任务执行结果(TranscriptionResult)。
点击查看完整示例
点击查看完整示例
异步提交任务+异步查询任务执行结果
- 配置请求参数。
- 实例化核心类(Transcription)。
-
调用核心类(Transcription)的
asyncCall方法异步提交任务。- 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内。任务开始处理后,语音识别将以数百倍加速完成。 - 每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。
- 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
-
循环调用核心类(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对应的热词信息。默认不启用。注:phraseId为v1版本模型热词方案,不支持v2及后续系列模型。支持该方式热词的模型列表请参考Paraformer语音识别热词定制与管理。 | |
| channelId | List<Integer> | [0] | 否 | 指定在多音轨音频文件中需要识别的音轨索引,索引从 0 开始。例如,[0] 表示识别第一个音轨,[0, 1] 表示同时识别第一和第二个音轨。如果省略此参数,则默认处理第一个音轨。 |
| disfluencyRemovalEnabled | Boolean | false | 否 | 过滤语气词,默认关闭。 |
| timestampAlignmentEnabled | Boolean | false | 否 | 是否启用时间戳校准功能,默认关闭。 |
| specialWordFilter | String | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。若未传入该参数,系统将启用系统内置的敏感词过滤逻辑,识别结果中与阿里云百炼敏感词表匹配的词语将被替换为等长的*。若传入该参数,则可实现以下敏感词处理策略:
| |
| language_hints | String[] | ["zh", "en"] | 否 | 指定待识别语音的语言代码。该参数仅适用于paraformer-v2模型。支持的语言代码:
language_hints需要通过TranscriptionParam实例的parameter方法或者parameters方法进行设置: |
| diarizationEnabled | Boolean | false | 否 | 自动说话人分离,默认关闭。仅适用于单声道音频,多声道音频不支持说话人分离。启用该功能后,识别结果中将显示speaker_id字段,用于区分不同说话人。如果启用说话人分离功能,建议音频时长不超过2小时,否则可能导致识别失败或超时。 speaker_id的示例,请参见识别结果说明。 |
| speakerCount | Integer | 否 | 说话人数量参考值。取值范围为2至100的整数(包含2和100)。开启说话人分离功能后(diarizationEnabled设置为true)生效。默认自动判断说话人数量,如果配置此项,只能辅助算法尽量输出指定人数,无法保证一定会输出此人数。 | |
| apiKey | String | 否 | 用户API Key。如已将API Key配置到环境变量,则无须在代码中设置。否则一定要在代码中进行设置。 |
响应结果
任务执行结果(TranscriptionResult)
TranscriptionResult封装了当前任务执行结果。
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | requestId | 获取requestId。 | |
| 无 | taskId | 获取taskId。 | |
| 无 | TaskStatus,任务状态 | 获取任务状态。TaskStatus为枚举类,只需关注PENDING、RUNNING、SUCCEEDED和FAILED这四个状态即可。当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为 SUCCEEDED,需通过subtask_status字段判断具体子任务结果。 | |
| 无 | 子任务执行结果(TranscriptionTaskResult) | 获取子任务执行结果(TranscriptionTaskResult)。每个任务对一个或多个音频文件进行识别,不同音频文件在不同的子任务中处理,因此每个任务对应一到多个子任务。 | |
| 无 | 任务执行结果,为JSON格式的数据 | 获取任务执行结果。该结果是一个JSON格式的数据,如果您想通过getOutput接口获取任务执行结果,请您在获取结果后自行解析。
点击查看JSON示例 |
子任务执行结果(TranscriptionTaskResult)
TranscriptionTaskResult封装了子任务执行结果。子任务对单个音频文件进行识别。
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 被识别的音频文件的链接 | 获取被识别音频文件的链接。 | |
| 无 | 识别结果对应的链接 | 获取识别结果对应的链接。该链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。识别结果保存为JSON文件,您可以通过上述链接下载该文件或直接通过HTTP请求读取该文件中的内容。JSON数据中各字段含义请参见识别结果说明。 | |
| 无 | TaskStatus,子任务状态 | 获取子任务状态。TaskStatus为枚举类,只需关注PENDING、RUNNING、SUCCEEDED和FAILED这四个状态即可。 | |
| 无 | 任务执行过程中关键信息,可能为空 | 获取任务执行过程中的关键信息。当任务失败时,可查看该内容分析原因。 |
识别结果说明
识别结果保存为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实例。
点击查看示例
点击查看示例
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| TranscriptionQueryParam实例 | 创建TranscriptionQueryParam实例。 |
核心类(Transcription)
Transcription可以通过“import com.alibaba.dashscope.audio.asr.transcription.*;”方式引入。它的关键接口如下:
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
param:语音识别相关参数,TranscriptionParam实例 | 任务执行结果(TranscriptionResult) | 异步提交语音识别任务。 | |
queryParam:TranscriptionQueryParam实例 | 任务执行结果(TranscriptionResult) | 阻塞当前线程直到异步任务结束(任务状态为SUCCEEDED或FAILED)。 | |
queryParam:TranscriptionQueryParam实例 | 任务执行结果(TranscriptionResult) | 异步查询当前任务执行结果。 |
其他接口:批量查询任务状态/取消任务
详情请参见管理异步任务:支持批量查询24小时内提交的非实时语音识别任务,同时支持取消PENDING(排队)状态的任务。
错误码
如遇报错问题,请参见错误码进行排查。
若问题仍未解决,请加入开发者群反馈遇到的问题,并提供Request ID,以便进一步排查问题。
当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为SUCCEEDED,需通过subtask_status字段判断具体子任务结果。
错误返回示例:
更多示例
更多示例,请参见GitHub。
常见问题
功能特性
Q:是否支持Base64编码方式的音频?
不支持Base64编码方式的音频。仅支持可通过公网访问的 URL 所指向的音频的识别,不支持识别二进制流,也不支持直接识别本地文件。
Q:如何将音频文件以公网可访问的URL形式提供?
通常遵循以下几个步骤(这里为您提供一种思路,具体情况因不同存储产品而异,推荐将音频上传至阿里云OSS):
1、选择存储和托管方式
1、选择存储和托管方式
-
对象存储服务(推荐):
- 使用云服务商的对象存储服务(如阿里云OSS),将音频文件上传到存储桶中,并设置为公开访问。
- 优点:高可用性、支持 CDN 加速、易于管理。
-
Web 服务器:
- 将音频文件放置在支持 HTTP/HTTPS 访问的 Web 服务器上(如 Nginx、Apache)。
- 优点:适合小型项目或本地测试。
-
内容分发网络(CDN):
- 将音频文件托管在 CDN 上,通过 CDN 提供的 URL 访问。
- 优点:加速文件传输,适合高并发场景。
2、上传音频文件
2、上传音频文件
-
对象存储服务:
- 登录云服务商的控制台,创建存储桶。
- 上传音频文件,并设置文件权限为“公共读”或生成临时访问链接。
-
Web 服务器:
- 将音频文件放置在服务器指定目录下(如
/var/www/html/audio/)。 - 确保文件可以通过 HTTP/HTTPS 访问。
- 将音频文件放置在服务器指定目录下(如
3、生成公网可访问的URL
3、生成公网可访问的URL
-
对象存储服务:
- 文件上传后,系统会自动生成一个公网访问 URL(通常格式为
https://<bucket-name>.<region>.aliyuncs.com/<file-name>)。 - 如果需要更友好的域名,可以绑定自定义域名并开启 HTTPS。
- 文件上传后,系统会自动生成一个公网访问 URL(通常格式为
-
Web 服务器:
- 文件的访问 URL 通常是服务器地址加上文件路径(如
https://your-domain.com/audio/file.mp3)。
- 文件的访问 URL 通常是服务器地址加上文件路径(如
-
CDN:
- 配置 CDN 加速后,使用 CDN 提供的 URL(如
https://cdn.your-domain.com/audio/file.mp3)。
- 配置 CDN 加速后,使用 CDN 提供的 URL(如
4、验证URL的可用性
4、验证URL的可用性
- 在浏览器中打开 URL,检查是否能播放音频文件。
- 使用工具(如
curl或 Postman)验证 URL 是否返回正确的 HTTP 响应(状态码 200)。
oss://为前缀的临时 URL。
使用RESTful API时,若录音文件存储在阿里云OSS,支持使用以 oss://为前缀的临时 URL:
Q:多久能获取识别结果?
任务提交后将进入排队(PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内,请耐心等待。并且音频时长越长,所需时间越久。
故障排查
如遇代码报错问题,请根据错误码中的信息进行排查。
Q:识别结果和语音播放不同步怎么办?
将请求参数timestampAlignmentEnabled设为true将启用时间戳校准功能,能够让识别结果和语音播放同步。
Q:一直轮询不到结果?
可能是限流原因,请耐心等待。若需扩容,请加入开发者群进行申请。
Q:无法识别语音(无识别结果)是什么原因?
- 请检查音频是否符合要求(格式、采样率)。
- 若是使用了
paraformer-v2模型,检查language_hints的设置是否正确。 - 以上都没问题,可通过定制热词,提升对特定词语的识别效果。