2D互動(dòng)數(shù)字人接入指南（不支持接入）
本文中含有需要您注意的重要提示信息，忽略該信息可能對(duì)您的業(yè)務(wù)造成影響，請(qǐng)務(wù)必仔細(xì)閱讀。
2D互動(dòng)數(shù)字人產(chǎn)品公測(cè)已結(jié)束，目前2D數(shù)字人產(chǎn)品不支持實(shí)時(shí)交互能力。
2D互動(dòng)數(shù)字人（對(duì)應(yīng)開放平臺(tái)的“智能客服”場(chǎng)景）是虛擬數(shù)字人開放平臺(tái)提供能夠支持用戶與2D數(shù)字人進(jìn)行實(shí)時(shí)語(yǔ)音交互的數(shù)字人產(chǎn)品能力，需要配合智能對(duì)話機(jī)器人產(chǎn)品使用。本篇文檔將介紹如何接入2D互動(dòng)數(shù)字人。
能力介紹
2D互動(dòng)數(shù)字人是虛擬數(shù)字人開放平臺(tái)提供能夠支持用戶與2D數(shù)字人進(jìn)行實(shí)時(shí)語(yǔ)音交互的數(shù)字人產(chǎn)品能力，需要配合智能對(duì)話機(jī)器人產(chǎn)品使用。
目前互動(dòng)數(shù)字人支持文本、語(yǔ)音兩種交互方式，同時(shí)在數(shù)字人說話中可以支持通過特定話術(shù)進(jìn)行打斷，實(shí)現(xiàn)更加友好的雙工語(yǔ)音對(duì)話體驗(yàn)。
使用場(chǎng)景
適用于一些需要真人與數(shù)字人進(jìn)行交互的場(chǎng)景，如線下大屏，數(shù)字人客服等場(chǎng)景。
前置條件
下述介紹接入2D互動(dòng)數(shù)字人需要提前完成的步驟，每個(gè)步驟都需要完成才能順利接入2D互動(dòng)數(shù)字人。
1. 申請(qǐng)阿里云賬號(hào)
具體參考準(zhǔn)備工作
2. 申請(qǐng)購(gòu)買權(quán)限，完成購(gòu)買開通服務(wù)
具體參考開通服務(wù)
3. 開通智能對(duì)話機(jī)器人
進(jìn)入智能對(duì)話機(jī)器人后臺(tái)，創(chuàng)建機(jī)器人，機(jī)器人類型選擇“在線文本機(jī)器人”
配置對(duì)應(yīng)知識(shí)庫(kù)
從智能對(duì)話機(jī)器人控制臺(tái)獲取對(duì)應(yīng)機(jī)器人的機(jī)器人id
4. 進(jìn)入虛擬數(shù)字人開放平臺(tái)創(chuàng)建并配置應(yīng)用
互動(dòng)數(shù)字人的創(chuàng)建和配置與播報(bào)數(shù)字人大體相同，具體創(chuàng)建和配置流程可以參考：創(chuàng)建并配置數(shù)字人項(xiàng)目，下面針對(duì)互動(dòng)數(shù)字人特有的一些配置做一些介紹。
創(chuàng)建互動(dòng)數(shù)字人應(yīng)用時(shí)請(qǐng)?jiān)诓藛芜x擇“互動(dòng)數(shù)字人”，然后點(diǎn)擊創(chuàng)建數(shù)字人應(yīng)用。
4.1 智能對(duì)話機(jī)器人配置
在上述圖中所示位置添加第三步獲取到的智能對(duì)話機(jī)器人的機(jī)器人id，密鑰ID和密鑰Secret是阿里云賬號(hào)的AccessKey ID和AccessKey Secret（點(diǎn)擊獲取，建議通過子賬號(hào)的方式獲取AK&SK）。
技術(shù)接入
請(qǐng)確保完成上述全部前置步驟，獲取到阿里云賬號(hào)的AccessKey ID和AccessKey Secret（點(diǎn)擊獲取），以及獲取到對(duì)應(yīng)數(shù)字人應(yīng)用的tenantId和appId。
下面介紹接入互動(dòng)數(shù)字人的完整步驟以及涉及到API
1. 了解虛擬數(shù)字人開放平臺(tái)服務(wù)端API接入方式
虛擬數(shù)字人開放平臺(tái)的服務(wù)端API采用OpenAPI形式對(duì)外輸出，具體對(duì)接方案見：服務(wù)端API接入。
2. SDK版本要求
該功能需要升級(jí)虛擬數(shù)字人開放平臺(tái)服務(wù)端SDK版本至1.0.5及以上。
3. 調(diào)用OpenAPI啟動(dòng)一路數(shù)字人實(shí)例
下面介紹通過Java調(diào)用OpenAPI啟動(dòng)一路數(shù)字人實(shí)例的代碼示例，獲取到返回的sessionId以及token。
代碼示例：
參考OpenAPI官網(wǎng)調(diào)試頁(yè)面，可在線直接填寫參數(shù)并執(zhí)行測(cè)試。
接口調(diào)用返回的sessionId和token在后續(xù)步驟對(duì)接互動(dòng)數(shù)字人客戶端SDK時(shí)將會(huì)使用到，channel信息在對(duì)接RTC進(jìn)行拉流時(shí)需要使用。
關(guān)于StartInstance API的詳細(xì)信息可以參考：StartInstance - 啟動(dòng)一個(gè)數(shù)字人。同時(shí)OpenAPI提供了在線調(diào)試頁(yè)面，可以直接面代碼調(diào)試API：OpenAPI在線調(diào)試。
4. 通過WebSocket對(duì)接互動(dòng)數(shù)字人
互動(dòng)數(shù)字人需要客戶端通過WebSocket協(xié)議與服務(wù)端進(jìn)行語(yǔ)音流的傳輸，下面將為您介紹如何通過WebSocket對(duì)接互動(dòng)數(shù)字人。
1. 與虛擬數(shù)字人開放平臺(tái)建立WebSocket長(zhǎng)連接
如何與虛擬數(shù)字人開放平臺(tái)建立WebSocket長(zhǎng)連接，請(qǐng)參考：通用WebSocket接入指南。
2. 通過WebSocket發(fā)送互動(dòng)數(shù)字人對(duì)話請(qǐng)求
在建立與虛擬數(shù)字人開放平臺(tái)WebSocket服務(wù)端連接之后，客戶端需要按照互動(dòng)數(shù)字人的對(duì)話協(xié)議發(fā)送對(duì)應(yīng)的請(qǐng)求數(shù)據(jù)。
2.1 啟動(dòng)對(duì)話，初始化對(duì)話配置
通過websocket發(fā)送啟動(dòng)對(duì)話消息，協(xié)議如下：
5{
"messageId": "<messageId>", // 必傳，消息id，需要保證唯一，可以直接生成16位隨機(jī)數(shù)
"receiverId": "ability", // 必傳，固定值
"receiverType": "server", // 必傳，固定值
"sticky": true, // 必傳，固定值
"receiverAppId": "<appId>", // 必傳，數(shù)字人應(yīng)用的開發(fā)者信息中的appId
"content": {
"type": "start", // 必傳，固定值，表示是啟動(dòng)對(duì)話
"sessionId": "<sessionId>", // 必傳，StartInstance接口返回的sessionId
"format": "<format>", // 可選，音頻數(shù)據(jù)格式，目前支持pcm和wav，不傳默認(rèn)pcm
"sampleRate": "<sampleRate>" // 可選，音頻采樣率，目前支持16000和8000，不傳默認(rèn)16000
}
}參考websocket接入文檔，發(fā)送該消息需要在消息體前面增加一個(gè)5，表示是業(yè)務(wù)消息。
2.2 等待服務(wù)端啟動(dòng)完成
服務(wù)端收到啟動(dòng)對(duì)話消息之后會(huì)進(jìn)行對(duì)話的啟動(dòng)，啟動(dòng)完成之后會(huì)下發(fā)一條啟動(dòng)完成的消息，結(jié)構(gòu)如下：
5{
"content": {
"sessionId": "8afe971f-0f9c-466a-996b-6beeafd7ae72",
"type": "startResult", // type=startResult表示啟動(dòng)結(jié)果消息
"status": true // status表示啟動(dòng)成功或者失敗，false表示失敗，如果遇到失敗可重新發(fā)送啟動(dòng)消息
},
"messageId": "473220b6-9062-4b5f-bae6-910f622c943e", // 通信的一些協(xié)議參數(shù)，可直接忽略，重點(diǎn)關(guān)注content內(nèi)容
"tenantId": 20004,
...
}收到該消息，且status=true之后，才能進(jìn)行后續(xù)的語(yǔ)音流的發(fā)送，在此之前發(fā)送語(yǔ)音流會(huì)被服務(wù)端直接丟棄。
2.3 持續(xù)發(fā)送語(yǔ)音流數(shù)據(jù)
5{
"messageId": "<messageId>", // 必傳，消息id，需要保證唯一，可以直接生成16位隨機(jī)數(shù)
"receiverId": "ability", // 必傳，固定值
"receiverType": "server", // 必傳，固定值
"sticky": true, // 必傳，固定值
"receiverAppId": "<appId>", // 必傳，數(shù)字人應(yīng)用的開發(fā)者信息中的appId
"content": {
"type": "dataSend", // 必傳，固定值，表示是發(fā)送語(yǔ)音數(shù)據(jù)
"sessionId": "<sessionId>", // 必傳，StartInstance接口返回的sessionId
"audio": "<語(yǔ)音數(shù)據(jù)base64之后的文本>",// 可選，語(yǔ)音數(shù)據(jù)base64字符串（文本和語(yǔ)音必傳一個(gè)）
"text": "<text>" // 可選，文本，可直接發(fā)送文本與互動(dòng)數(shù)字人進(jìn)行對(duì)話
}
}語(yǔ)音流的發(fā)送建議每隔100ms發(fā)送一次，發(fā)送最快不要小于50ms，發(fā)送太快可能會(huì)導(dǎo)致無(wú)法識(shí)別。語(yǔ)音數(shù)據(jù)在發(fā)送前需要進(jìn)行base64編碼。同時(shí)語(yǔ)音流需要連續(xù)發(fā)送，如果沒有聲音可以發(fā)送靜音包，長(zhǎng)時(shí)間不發(fā)送音頻流可能會(huì)導(dǎo)致對(duì)話中斷。
該協(xié)議支持直接發(fā)送純文本進(jìn)行對(duì)話，也可發(fā)送語(yǔ)音流進(jìn)行對(duì)話，在文本和語(yǔ)音同時(shí)發(fā)送的過程時(shí)無(wú)法保證對(duì)話觸發(fā)的順序。
服務(wù)端在收到客戶端發(fā)送的語(yǔ)音流之后，會(huì)調(diào)用語(yǔ)音轉(zhuǎn)文本服務(wù)，最終拿到文本調(diào)用智能客服機(jī)器人的對(duì)話服務(wù)，如果客戶端發(fā)送的是文本，則直接拿文本調(diào)用智能客戶機(jī)器人的對(duì)話服務(wù)（調(diào)用的機(jī)器人實(shí)例是在互動(dòng)數(shù)字人應(yīng)用配置頁(yè)面配置的機(jī)器人信息），最終拿到智能客服機(jī)器人的回復(fù)文本，觸發(fā)數(shù)字人播報(bào)對(duì)應(yīng)的回復(fù)文本。在這過程中服務(wù)端會(huì)返回客戶端識(shí)別到的文本，以及智能客服機(jī)器人的回復(fù)文本，下面是返回的具體協(xié)議。
2.4 服務(wù)端返回語(yǔ)音文本識(shí)別結(jié)果
服務(wù)端在語(yǔ)音轉(zhuǎn)文本服務(wù)識(shí)別到一句完整的句子時(shí)會(huì)將識(shí)別到的文本返回給客戶端。
5{
"content": {
"type": "asrContent", // 表示是下發(fā)語(yǔ)音識(shí)別文本消息
"sentenceId": "b60e43b53333437a9d312a62518a5b3c", // 本次識(shí)別到的內(nèi)容的id
"text": "你好。", // 本次識(shí)別到的文本
"sessionId": "028f5247-d089-4fd2-800b-dab5148d5407", // 對(duì)應(yīng)的sessionId
"isFinished": true // true表示是一句話結(jié)束
},
"messageId": "221d0c82-c73e-4c13-9324-8c7947cf199a", // 通信的一些協(xié)議參數(shù)，可直接忽略，重點(diǎn)關(guān)注content內(nèi)容
"tenantId": 20004,
...
}服務(wù)端返回的消息也是5開頭。
2.5 服務(wù)端返回對(duì)話回復(fù)結(jié)果
服務(wù)端在語(yǔ)音轉(zhuǎn)文本服務(wù)識(shí)別到一句完整的句子時(shí)會(huì)將識(shí)別到的文本調(diào)用智能客服機(jī)器人的對(duì)話服務(wù)，拿到對(duì)應(yīng)的對(duì)話回復(fù)文本，從而驅(qū)動(dòng)數(shù)字人播報(bào)對(duì)應(yīng)的回復(fù)文本，同時(shí)服務(wù)端會(huì)將回復(fù)文本返回給客戶端。
5{
"content": {
"type": "replyContent", // 表示是下發(fā)智能客服機(jī)器人回復(fù)的文本消息
"sentenceId": "b60e43b53333437a9d312a62518a5b3c", // 本次識(shí)別到的內(nèi)容的id
"text": "我在聽，請(qǐng)講。", // 智能客服機(jī)器人回復(fù)的文本
"sessionId": "028f5247-d089-4fd2-800b-dab5148d5407" // 對(duì)應(yīng)的sessionId
},
"messageId": "221d0c82-c73e-4c13-9324-8c7947cf199a", // 通信的一些協(xié)議參數(shù)，可直接忽略，重點(diǎn)關(guān)注content內(nèi)容
"tenantId": 20004,
...
}服務(wù)端返回的消息也是5開頭。
2.6 停止對(duì)話
在完成一通對(duì)話之后，客戶端可主動(dòng)發(fā)起停止對(duì)話。
5{
"messageId": "<messageId>", // 必傳，消息id，需要保證唯一，可以直接生成16位隨機(jī)數(shù)
"receiverId": "ability", // 必傳，固定值
"receiverType": "server", // 必傳，固定值
"sticky": true, // 必傳，固定值
"receiverAppId": "<appId>", // 必傳，數(shù)字人應(yīng)用的開發(fā)者信息中的appId
"content": {
"type": "stop", // 必傳，固定值，表示是停止對(duì)話
"sessionId": "<sessionId>", // 必傳，StartInstance接口返回的sessionId
}
}在停止對(duì)話之后，需要對(duì)應(yīng)的數(shù)字人實(shí)例沒有停止的情況下，可以重新啟動(dòng)對(duì)話服務(wù)。
停止對(duì)話不會(huì)停止對(duì)應(yīng)的數(shù)字人實(shí)例，如果需要停止數(shù)字人實(shí)例可參考下述步驟5：調(diào)用OpenAPI停止對(duì)應(yīng)數(shù)字人實(shí)例。
5. 接入RTC客戶端進(jìn)行拉流
接入RTC客戶端可參考文檔：3D數(shù)字人實(shí)時(shí)流媒體。需要使用到第二步中獲取到的Channel信息。
6. 調(diào)用OpenAPI停止對(duì)應(yīng)數(shù)字人實(shí)例
下面介紹通過Java調(diào)用OpenAPI啟動(dòng)一路數(shù)字人實(shí)例的代碼示例，需要使用到第二步中獲取的sessionId。
代碼示例：
參考OpenAPI官網(wǎng)調(diào)試頁(yè)面，可在線直接填寫參數(shù)并執(zhí)行測(cè)試。
7. sessionId丟失如何停止數(shù)字人實(shí)例
針對(duì)運(yùn)行中的數(shù)字人實(shí)例，如果sessionId丟失將無(wú)法調(diào)用StopInstance接口停止，此時(shí)可通過調(diào)用QueryRunningIntance接口獲取到正在運(yùn)行中的數(shù)字人實(shí)例列表，從而獲取到對(duì)應(yīng)的sessionId。
代碼示例：
參考OpenAPI官網(wǎng)調(diào)試頁(yè)面，可在線直接填寫參數(shù)并執(zhí)行測(cè)試。