调用UploadAudioData上传音频质检。最佳实践场景:与自有呼叫中心系统对接,呼叫中心每产生一条录音,就调用该API将录音推送至SCA进行分析。

流程说明

API调用上传音频质检 => 录音文件转文本 => 根据指定的分轨方式对文本进行角色分离(区分客服、客户) => 使用质检规则进行分析 => 质检完成。

录音文件URL要求

  • 持单轨/双轨的wav格式、mp3格式的录音文件,文件大小需要控制在512M以下
  • URL必须是基于HTTP可访问的URL地址,不支持提交本地文件;录音文件访问权限需要为公开。
  • URL中只能使用域名,不能使用IP地址,URL中不可包含空格,请尽量避免使用中文。
  • 系统在录音转文本后,会将下载的录音文件删除,不会保存录音副本
  • 若您的录音url是存在访问有效期的,例如录音存储在阿里云OSS,通过OSS生成录音url时指定了有效期,建议有效期至少为12小时,如果条件允许,最好设置为24小时。这样做是因为文件转写需要一定的时间,并且偶尔会产生排队等待,若排队时间较长,开始转写时才会下载录音,避免下载录音时录音url已失效的情况发生。
  • 质检分析完成后,在控制台复核文件时,播放录音使用的仍然是您提供的URL,所以需要保证URL长期可用,否则将无法播放录音。

角色分离说明

录音转文本后,系统会自动将文本分为两个对话角色,但是系统无法判断哪个角色是客服、哪个是客户。所以需要您来根据某些规则进行角色分离。角色分离的准确性非常重要,因为我们进行质检分析时所用的规则,很多时候都有检测角色的限制(即一个规则只检测客服或者客户),如果角色分离错误,那么将对质检结果的准确性产生极大影响。

录音文件通常分为 单轨(单声道) 和 双轨(双声道/立体声) 两种:

  • 单轨录音:客服、客户 两个人的声音存储在一个轨上,在录音文件转文本后,系统会通过内置算法区分为两个角色的对话,通过设置一组客服可能说的关键词列表,通过对转写文本从上到下逐句分析,当一句话命中某一个关键词时,则判定该句的角色为客服,则另一个角色就是客户,具体使用详见请求入参中的 recognizeRoleDataSetId 和 serviceChannelKeywords。由于对话内容的不可控性(比如两个角色对话存在交叉,两个人同时讲话),所以单轨录音的角色分离无法保证100%准确,强烈建议在保存录音文件时保存为双轨录音。
  • 双轨录音:客服、客户 两个人的声音分别存储在两个轨上,即使两个角色的对话存在交叉录音转文本时可以准确的区分为两个角色,所以直接通过请求参数中的 serviceChannel、clientChannel 来指定客服、客户 即可。

获取质检分析结果

由于录音文件识别是非实时的,所以需要异步获取质检分析结果,有以下2种方式获取结果:

  • 回调:通过在请求参数中指定callbackUrl,在任务完成后由系统主动发起回调,接到回调后再通过getResult接口获取详细结果。
  • 轮询:接口会返回任务ID(taskId),可以用taskId轮训getResult接口异步获取结果,判断返回参数中的status是否完成,轮询间隔建议不要太短,正常情况下会在几分钟内分析完成,建议轮询间隔在30s以上。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String UploadAudioData

系统规定参数。取值:UploadAudioData。

JsonStr String {“callList”:“xxxxx”}

完整Json字符串信息,具体内容参见以下详细信息。

请求参数与Json字符串信息

属性

值类型

是否必须

描述

callList

List

语音文件集合,可以一次性上传多个录音文件,详见下方的 jsonStr.callList 属性说明

autoSplit

Integer

多数情况下适用于 单轨 录音,取值:0、1,是否自动分轨,1为自动分轨,0为不分轨;默认:1;若指定为1,则表示上传的音频为单轨; 自动分轨会额外占用处理时间。

recognizeRoleDataSetId

Long

数据集ID,使用一个已存在的数据集,因为数据集在创建时会设置角色分离规则(可以查看新建数据集功能中的话者角色配置),此处指定数据集ID,则本次上传的文件会复用此数据集的角色分离规则。适用于 单轨 录音。

serviceChannelKeywords

List

多数情况下适用于单轨录音,设置一组客服可能说的关键词列表(请确保选择那些区别性比较高的关键词),通过对转写文本从上到下逐句分析,当一句话命中某一个关键词时,则判定该句的角色为客服,则另一个角色就是客户。当recognizeRoleDataSetId和serviceChannelKeywords都存在时,recognizeRoleDataSetId优先级更高;若两者均未设置,则使用系统内置的分轨规则进行兜底。

serviceChannel

Integer

适用于 双轨 录音,指定客服角色的轨道编号,取值:0、1,默认0,即第0轨为客服;通常音轨都是从0开始编号,2个轨就是0,1;具体0是客服还是客户,需要您自行确认。单轨文件忽略此参数。

clientChannel

Integer

适用于 双轨 录音,指定客户角色的轨道编号,取值:0、1,默认1,即第1轨为客户;通常音轨都是从0开始编号,2个轨就是0,1;具体0是客服还是客户,需要您自行确认。单轨文件忽略此参数。

ruleIds

List

规则id列表,用于指定录音文件使用哪些规则进行质检分析,若不指定,则会过所有规则;注意:单个文件允许最大规则数为100,如果超过100,则会截取前100个规则。

ruleBusinessNames

List

适用业务列表,系统会使用这些适用规则所关联的规则进行质检分析。与ruleIds不同,该参数适用于规则经常变化的场景:新建规则时,将规则与对应的适用业务关联即可,这样增加了新的规则,不需要修改请求参数,就可以使用新建的规则进行质检分析。

sampleRate

Integer

录音文件的采样率,可选值:8(8000hz);16(16000hz);默认8。需要正确指定录音文件采样率,错误的采样率会导致转写结果错误,通常呼叫中心产生的录音采样率是8000hz。

callbackUrl

String

回调地址,不指定则不回调,请保证回调地址公网可访问,不支持ip;录音分析完成后会发起回调;详细说明请查看下方的 回调参数说明

vocabId

String

热词模型Id,不指定则不使用热词;id值可以从控制台的 "基础设置" -> "热词" -> "热词组ID" 中查看。

modelId

String

语言模型Id,不指定则使用通用模型;id值可以从控制台的 "基础设置" -> "语言模型"中查看。

baseModelId

String

基础模型id,取值:mandarin(中文普通话8k,默认),mandarin16(中文普通话16k),cantonese(粤语,需要开通白名单);默认:mandarin。

jsonStr.callList 属性说明:

属性

值类型

是否必须

描述

voiceFileUrl

String

录音文件,具体要求详见API说明中的 录音文件URL要求

fileName

String

音频文件名称,如audio.wav;虽不是必填项,但为方便统计,请尽量提供此参数;若不提供,则会从voiceFileUrl中获取,比如 http://www.aliyun.com/audio.wav, 则文件名解析为:audio.wav。

autoSplit

Integer

参见上层对象参数说明;如为空,会采用上层对象对应值。

recognizeRoleDataSetId

Long

参见上层对象参数说明;如为空,会采用上层对象对应值。

serviceChannel

Integer

参见上层对象参数说明;如为空,会采用上层对象对应值。

clientChannel

Integer

参见上层对象参数说明;如为空,会采用上层对象对应值。

sampleRate

Integer

参见上层对象参数说明;如为空,会采用上层对象对应值。

callStartTime

Long

录音发生的时间,格林威治时间1970年01月01日00时00分00秒到现在的毫秒数(即毫秒时间戳,例如:1584535485856),若不指定,则会取当前时间。

vocabId

String

参见上层对象参数说明;如为空,会采用上层对象对应值。

customerServiceId

Long

客服Id。可从控制台-基础设置-人员管理页面获取,正确填入客服id,客服登录控制塔时可以查看与自己关联的录音文件。

customerServiceName

String

客服姓名。

skillGroupId

Long

技能组Id。

skillGroupName

String

技能组名称。

callType

Integer

呼叫类型,可取值:1(呼出);3(呼入)。

callee

String

被叫号码,呼出时指的是客户号码,呼入时指的是客服号码。

caller

String

主叫号码,呼出时指的是客服号码,呼入时指的是客户号码。

callId

String

通话id,可以是呼叫中心系统中的通话id,或者其他可以标识通话的id。

business

String

业务线名称,属于自定义数据,用于分类统计。

remark1

String

自定义数据1,可以存放与您业务相关的自定义字段,最大长度为64字符。

remark2

String

自定义数据2,可以存放与您业务相关的自定义字段,最大长度为64字符。

remark3

String

自定义数据3,可以存放与您业务相关的自定义字段,最大长度为64字符。

remark4

String

自定义数据4,可以存放与您业务相关的自定义字段,最大长度为64字符。

remark5

Long

自定义数据5,可以存放与您业务相关的自定义字段,格式为有符号的long型。

remark6

String

自定义数据6,可以存放与您业务相关的自定义字段,最大长度为1024字符。

回调参数说明

假设调用方传入的回调地址是: http://aliyun.com/callback,那么回调时的完整url为http://aliyun.com/callback?taskId=xxx&timestamp=xxx&signature=xxx&event=xxx, 其中:

  • taskId 为任务id
  • timestamp 为调用时的时间戳,单位:毫秒
  • aliUid 为调用方阿里云主账号uid
  • signature 为签名,调用方可用来判断请求是否来自阿里云;计算说明:将taskId=xxx&timestamp=xxx&aliUid=xxx 进行md5+base64加密,注意顺序;调用方接到回调后,taskId和timestamp可以从回调url中获取,aliUid即为阿里云主账号ID,使用主账号登录访问 https://account.console.aliyun.com 会看到账号ID。,通过计算来比对自己计算出的signature,与url中的signature是否一致,详见下方Java代码示例。
  • event 为事件名称,调用方可用来判断是什么事件触发的回调,取值为 TaskComplete:任务完成时的回调;

public static void signature() {
    long timestamp = System.currentTimeMillis();
    String taskId = "xxxx";
    String aliUid = "xxxxx";
    // 将 taskId=xxx&timestamp=xxx&aliUid=xxx 进行md5 + base64加密,放在signature字段
    String signature;
    try {
        signature = URLEncoder.encode(md5Base64("taskId=" + taskId + "&timestamp=" + timestamp + "&aliUid=" + aliUid), "utf-8");
        System.out.println(signature);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

public static String md5Base64(String str) throws NoSuchAlgorithmException {
    //string 编码必须为utf-8
    byte[] utfBytes = str.getBytes(StandardCharsets.UTF_8);
    MessageDigest mdTemp = MessageDigest.getInstance("MD5");
    mdTemp.update(utfBytes);
    byte[] md5Bytes = mdTemp.digest();
    return Base64.encodeBase64String(md5Bytes);
}

请求入参示例


{
    "autoSplit":1,
    "serviceChannelKeywords":[
        "留学",
        "客服老师"
    ],
    "ruleIds":[
        18128,
        15589
    ],
    "vocabId":"a7735a24c9ef4213b2fa41d****",
    "modelId":"9706",
    "callList":[
        {
            "voiceFileUrl":"https://sca-ccc-test.oss-cn-beijing.aliyuncs.com/%E7%A1%85%E8%AF%AD-%E7%95%99%E5%AD%A6%E5%BD%9B3.wav",
            "fileName":"abc.wav",
            "callStartTime":"1584535485856",
            "customerServiceId":"30",
            "customerServiceName":"Aagent",
            "skillGroupId":"34sd24",
            "skillGroupName":"售前技能组",
            "callType":1,
            "callee":18888888888,
            "caller":"01023232323",
            "callId":2345645734,
            "business":"售前一组",
            "remark1":"38节大促"
        }
    ]
}
ID

返回数据

名称 类型 示例值 描述
Code String 200

结果代码,200表示成功,若为别的值则表示失败,调用方可根据此字段判断失败原因。

Data String 76DB5D8C-5BD9-42A7-B527-5AF3A5***

任务ID,在获取任务结果时使用。

Message String successful

出错时表示出错详情,成功时为successful。

RequestId String 76DB5D8C-5BD9-42A7-B527-5AF3A5F8***

请求id,提工单时可提供此字段值用于排查问题。

Success Boolean true

请求是否成功,调用方可根据此字段来判断请求是否成功:true表示成功;false/null表示失败。

示例

请求示例

http(s)://qualitycheck.cn-hangzhou.aliyuncs.com/?Action=UploadAudioData
&JsonStr={“callList”:“xxxxx”}
&<公共请求参数>

正常返回示例

XML 格式

<UploadAudioDataResponse>	
	  <code>200</code>
	  <data>76DB5D8C-5BD9-42A7-B527-5AF3A5F****</data>
	  <message>successful</message>
	  <requestId>76DB5D8C-5BD9-42A7-B527-5AF3***</requestId>
	  <success>true</success>
</UploadAudioDataResponse>

JSON 格式

{
  "code": "200",
  "data": "76DB5D8C-5BD9-42A7-B527-5AF3A5F83***" ,
  "message": "successful",
  "requestId": "76DB5D8C-5BD9-42A7-B527-5AF3A5F83***",
  "success": true
}

错误码

访问错误中心查看更多错误码。