上傳離線語音質檢數據(錄音會話文件):適用于熱線坐席場景。場景1:天然集成阿里云呼叫中心(CCC),無需開發,可以一鍵開啟推送通話數據到SCA;場景2:與自有呼叫中心系統對接,呼叫中心每產生一條錄音,就將錄音推送至SCA進行分析。
接口說明
流程說明
API 調用上傳音頻質檢=>錄音文件轉文本=>根據指定的分軌方式對文本進行角色分離(區分客服、客戶)=>使用質檢規則進行分析=>質檢完成。
任務執行效率說明
任務執行的快慢,取決于錄音文件轉文本的快慢,理想情況下,一個長度為 5 分鐘的錄音文件,可以在 2 分鐘內轉寫完成,但是遇到文件轉寫服務排隊任務較多時,會有一個排隊等待的時間,一般會在 6 小時內轉寫完成,一次性上傳大規模數據(半小時內上傳超過 500 小時時長的錄音)的除外。轉寫完成后,質檢分析的速度是毫秒級的。
錄音文件 URL 要求
- 持單軌/雙軌的 wav 格式、mp3 格式的錄音文件,文件大小需要控制在 512M 以下。
- URL 必須是基于 HTTP 可訪問的 URL 地址,不支持提交本地文件;錄音文件訪問權限需要為公開。
- URL 中只能使用域名,不能使用 IP 地址,URL 中不可包含空格,請盡量避免使用中文。
- 系統在錄音轉文本后,會將下載的錄音文件刪除,不會保存錄音副本
- 若您的錄音 URL 是存在訪問有效期的,例如錄音存儲在阿里云 OSS,通過 OSS 生成錄音 URL 時指定了有效期,建議有效期至少為 12 小時,如果條件允許,最好設置為 24 小時。這樣做是因為文件轉寫需要一定的時間,并且偶爾會產生排隊等待,若排隊時間較長,開始轉寫時才會下載錄音,避免下載錄音時錄音 URL 已失效的情況發生。
- 質檢分析完成后,在控制臺復核文件時,播放錄音使用的仍然是您提供的 URL,所以需要保證 URL 長期可用,否則將無法播放錄音。
角色分離說明
錄音轉文本后,系統會自動將文本分為兩個對話角色,但是系統無法判斷哪個角色是客服、哪個是客戶。所以需要您來根據某些規則進行角色分離。角色分離的準確性非常重要,因為我們進行質檢分析時所用的規則,很多時候都有檢測角色的限制(即一個規則只檢測客服或者客戶),如果角色分離錯誤,那么將對質檢結果的準確性產生極大影響。
錄音文件通常分為單軌(單聲道)和雙軌(雙聲道/立體聲)兩種:
- 單軌錄音:客服、客戶兩個人的聲音存儲在一個軌上,在錄音文件轉文本后,系統會通過內置算法區分為兩個角色的對話,通過設置一組客服可能說的關鍵詞列表,通過對轉寫文本從上到下逐句分析,當一句話命中某一個關鍵詞時,則判定該句的角色為客服,則另一個角色就是客戶,具體使用詳見請求入參中的 recognizeRoleDataSetId 和 serviceChannelKeywords。由于對話內容的不可控性(比如兩個角色對話存在交叉,兩個人同時講話),所以單軌錄音的角色分離無法保證 100%準確,強烈建議在保存錄音文件時保存為雙軌錄音。
- 雙軌錄音:客服、客戶兩個人的聲音分別存儲在兩個軌上,即使雙方的對話存在交叉,錄音轉文本仍可以準確的區分。通過請求參數中的 serviceChannel、clientChannel 來指定客服、客戶即可。
獲取質檢分析結果
由于錄音文件識別是非實時的,所以需要異步獲取質檢分析結果,有以下 3 種方式獲取結果:
- 消息通知:詳情請查看消息隊列,收到消息后再通過 GetResult 接口獲取詳細結果。(推薦)
- 回調:通過在請求參數中指定 callbackUrl,在任務完成后由系統主動發起回調;接到回調后再通過 GetResult 接口獲取詳細結果。
- 輪詢:接口會返回任務 ID(taskId),可以用 taskId 輪詢
getResult
接口異步獲取結果,判斷返回參數中的status
是否完成,輪詢間隔建議不要太短,正常情況下會在幾分鐘內分析完成,建議輪詢間隔在 30s 以上。(不推薦)。
調試
您可以在OpenAPI Explorer中直接運行該接口,免去您計算簽名的困擾。運行成功后,OpenAPI Explorer可以自動生成SDK代碼示例。
授權信息
下表是API對應的授權信息,可以在RAM權限策略語句的Action
元素中使用,用來給RAM用戶或RAM角色授予調用此API的權限。具體說明如下:
- 操作:是指具體的權限點。
- 訪問級別:是指每個操作的訪問級別,取值為寫入(Write)、讀取(Read)或列出(List)。
- 資源類型:是指操作中支持授權的資源類型。具體說明如下:
- 對于必選的資源類型,用背景高亮的方式表示。
- 對于不支持資源級授權的操作,用
全部資源
表示。
- 條件關鍵字:是指云產品自身定義的條件關鍵字。
- 關聯操作:是指成功執行操作所需要的其他權限。操作者必須同時具備關聯操作的權限,操作才能成功。
操作 | 訪問級別 | 資源類型 | 條件關鍵字 | 關聯操作 |
---|---|---|---|---|
sca:UploadAudioData | create | *全部資源 * |
| 無 |
請求參數
名稱 | 類型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
JsonStr | string | 是 | 完整 JSON 字符串信息,具體內容參見以下詳細信息。 | {“callList”:“xxxxx”} |
BaseMeAgentId | long | 否 | 業務空間 Id,用于區分多業務空間場景下選擇指定業務空間,默認為默認業務空間。 | 123456 |
請求參數與 JSON 字符串信息
屬性 | 值類型 | 是否必須 | 描述 |
---|---|---|---|
isSchemeData | Integer | 否 | 是否將數據上傳至新版智能對話分析,取值:0:否;1:是,默認值為 0。 |
callList | List | 是 | 語音文件集合,可以一次性上傳多個錄音文件,詳見下方的jsonStr.callList 屬性說明。 |
autoSplit | Integer | 否 | 多數情況下適用于單軌錄音,取值:0、1,是否自動分軌,1 為自動分軌,0 為不分軌;默認:1;若指定為 1,則表示上傳的音頻為單軌;自動分軌會額外占用處理時間。若錄音為雙軌錄音,該參數必須傳 0。 |
recognizeRoleDataSetId | Long | 否 | 數據集 ID,使用一個已存在的數據集,因為數據集在創建時會設置角色分離規則(可以查看新建數據集功能中的話者角色配置),此處指定數據集 ID,則本次上傳的文件會復用此數據集的角色分離規則。適用于單軌錄音。 |
serviceChannelKeywords | List | 否 | 多數情況下適用于單軌錄音,設置一組客服可能說的關鍵詞列表(請確保選擇那些區別性比較高的關鍵詞),通過對轉寫文本從上到下逐句分析,當一句話命中某一個關鍵詞時,則判定該句的角色為客服,則另一個角色就是客戶。當 recognizeRoleDataSetId 和 serviceChannelKeywords 都存在時,recognizeRoleDataSetId 優先級更高;若兩者均未設置,則使用系統內置的分軌規則進行兜底。 |
serviceChannel | Integer | 否 | 適用于雙軌錄音,指定客服角色的軌道編號,取值:0、1,默認 0,即第 0 軌為客服;通常音軌都是從 0 開始編號,2 個軌就是 0,1;具體 0 是客服還是客戶,需要您自行確認。**若使用此參數,請務必傳入 autoSplit 參數,值為 0。**若單軌文件忽略此參數。 |
clientChannel | Integer | 否 | 適用于雙軌錄音,指定客戶角色的軌道編號,取值:0、1,默認 1,即第 1 軌為客戶;通常音軌都是從 0 開始編號,2 個軌就是 0,1;具體 0 是客服還是客戶,需要您自行確認。**若使用此參數,請務必傳入 autoSplit 參數,值為 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 | 否 | 業務線名稱,屬于自定義數據,用于分類統計。 |
callUuid | String | 否 | 全局唯一標識,做冪等(排重)使用,若傳入該字段,系統將查詢最近兩小時內上傳的數據中是否存在相同的 callUuid,若存在則本次上傳請求將被拒絕。 |
sessionGroupId | String | 否 | 會話組 ID,通常把同一個客服和同一個客戶的會話稱之為一個會話組,當傳入會話組 ID 后,可在會話組結果頁查看會話組維度的質檢結果。(僅新版智能對話分析適用) |
customerId | String | 否 | 客戶 ID。(僅新版智能對話分析適用) |
customerName | String | 否 | 客戶姓名。(僅新版智能對話分析適用) |
schemeTaskConfigId | String | 否 | 手動指定的質檢任務 ID(手動指定后則會使用指定的質檢任務進行質檢) 。(僅新版智能對話分析適用) |
remark1 | String | 否 | 自定義數據 1,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark2 | String | 否 | 自定義數據 2,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark3 | String | 否 | 自定義數據 3,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark4 | String | 否 | 自定義數據 4,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark5 | Long | 否 | 自定義數據 5,可以存放與您業務相關的自定義字段,格式為有符號的 long 型。 |
remark6 | String | 否 | 自定義數據 6,可以存放與您業務相關的自定義字段,最大長度為 1024 字符。 |
remark7 | String | 否 | 自定義數據 7,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark8 | String | 否 | 自定義數據 8,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark9 | String | 否 | 自定義數據 9,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark10 | String | 否 | 自定義數據 10,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark11 | String | 否 | 自定義數據 11,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark12 | String | 否 | 自定義數據 12,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark13 | String | 否 | 自定義數據 13,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark14 | Long | 否 | 自定義數據 14,可以存放與您業務相關的自定義字段,格式為有符號的 long 型。 |
remark15 | Long | 否 | 自定義數據 15,可以存放與您業務相關的自定義字段,格式為有符號的 long 型。 |
remark16 | String | 否 | 自定義數據 16,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark17 | String | 否 | 自定義數據 17,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark18 | String | 否 | 自定義數據 18,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark19 | String | 否 | 自定義數據 19,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark20 | String | 否 | 自定義數據 20,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark21 | String | 否 | 自定義數據 21,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark22 | String | 否 | 自定義數據 22,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark23 | String | 否 | 自定義數據 23,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark24 | String | 否 | 自定義數據 24,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
remark25 | String | 否 | 自定義數據 25,可以存放與您業務相關的自定義字段,最大長度為 64 字符。 |
jsonParamStr | String | 否 | 更多自定義字段,格式為 JSON 字符串,key 為字段名稱,value 為字段內容,示例:{"客戶等級":3,"渠道":"官網"}。 |
回調參數說明
假設調用方傳入的回調地址是:http://aliyun.com/callback
,那么回調時的完整 URL 為http://aliyun.com/callback?taskId=xxx×tamp=xxx&aliUid=xxx&signature=xxx&event=xxx
,其中:
- taskId:為任務 ID
- timestamp:為調用時的時間戳,單位:毫秒
- aliUid:為調用方阿里云主賬號 uid
- signature:為簽名,調用方可用來判斷請求是否來自阿里云;計算說明:將
taskId=xxx×tamp=xxx&aliUid=xxx
進行 md5+base64 加密,注意順序;調用方接到回調后,taskId 和 timestamp 可以從回調 URL 中獲取,aliUid 即為阿里云主賬號 ID。通過計算來比對自己計算出的 signature,與 URL 中的 signature 是否一致,詳見下方 Java 代碼示例。 - event:為事件名稱,調用方可用來判斷是什么事件觸發的回調,取值為 TaskComplete:任務完成時的回調;
public static void signature() {
long timestamp = System.currentTimeMillis();
String taskId = "xxx";
String aliUid = "xxx";
// 將 taskId=xxx×tamp=xxx&aliUid=xxx 進行 md5 + base64 加密,放在 signature 字段
String signature;
try {
signature = URLEncoder.encode(md5Base64("taskId=" + taskId + "×tamp=" + 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":[
181**,
155**
],
"vocabId":"a7735a24c9ef4213b2fa41d****",
"modelId":"9706**",
"callList":[
{
"voiceFileUrl":"https://sca-ccc-test.oss-cn-beijing.aliyuncs.com/****.wav",
"fileName":"abc.wav",
"callStartTime":"1584535485856",
"customerServiceId":"30",
"customerServiceName":"Aagent",
"skillGroupId":"34sd24",
"skillGroupName":"售前技能組",
"callType":1,
"callee":188888****,
"caller":"0102323***",
"callId":23456457**,
"business":"售前一組",
"remark1":"38 節大促"
}
]
}
返回參數
示例
正常返回示例
JSON
格式
{
"Code": "200",
"Message": "successful",
"Data": "76DB5D8C-5BD9-42A7-B527-5AF3A5***",
"RequestId": "76DB5D8C-5BD9-42A7-B527-5AF3A5F8***",
"Success": true
}
錯誤碼
訪問錯誤中心查看更多錯誤碼。
變更歷史
變更時間 | 變更內容概要 | 操作 |
---|---|---|
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |
2023-08-01 | API 內部配置變更,不影響調用 | 查看變更詳情 |