#前言

該文檔介紹SigmastarPcupid系列(Comake_pi_D1SSU9353XSSD235XSSU9222XSSU9383CM)如何對接火山引擎RTC服務實現板端音視頻AI對話和視覺推理，這里主要介紹測試環境的搭建，DemoCode跟著SDK釋放，如客戶有需要可以聯系對應支持的FAE兄弟獲取。

ComakePiD1的客戶可以通過https://www.comake.online/index.php?p=down_list&lanmu=4&c_id=15&id=59"GUI開發Demo"欄位下載flythings_gui_demo，火山引擎交互對應的代碼路徑為“zkgui_demo/zk_mini/jni/logic/volc”。

#準備條件

##硬件環境搭建

完整的ComakePID1開發板(可以在社區商店購買https://www.comake.online/index.php?p=shop)，包含攝像頭,模擬麥克風，喇叭，并準備能訪問外網的網絡環境。

##軟件環境搭建

ComakePID132Bit軟件默認有集成火山引擎Demo，但是沒有提供對應的火山賬號，需要開發者參考如下步驟去開通自己的賬號，火山有提供一定額度的免費體驗token。否則運行火山引擎會提示不存在如下配置文件/customer/zkgui_mini/resource/sample/config.json[空的config.json下載路徑](https://dev-comake-1251124109.cos.ap-guangzhou.myqcloud.com/file/1755226688840272/config.json)。

###火山引擎云服務開通

火山引擎的實時音視頻RTC功能，需要依賴語音識別（ASR）、語音合成（TTS）、大語言模型（LLM），我們先創建自己的火山引擎賬號，并開通對應的服務。

###開通RTC服務并創建應用ID

參考https://www.volcengine.com/docs/6348/69865開通實時音視頻服務(RTC)，并創建RTC應用，**獲取App_ID、APP_KEY并保留**，后面需要將此信息填入通訊配置config.json對應的欄位，這兩個分別是應用標識符和對應的密鑰，需要妥善保管以防泄漏。

```

"RTC_APP_ID":"XXXXXXXXXXXX",

"RTC_APP_KEY":"XXXXXXXXXX",

```

###開通語音識別（ASR）、語音合成（TTS）、大語言模型（LLM）服務

參考https://www.volcengine.com/docs/6348/1315561開通ASR、LLM、TTS服務。

需要注意的最后需要為賬號配置策略，不然會出現板端收不到智能體回復數據的情況。

####**開通語音識別、語音合成服務**

根據場景需求，開通ASR和TTS服務（ASR和TTS服務存在一些可選配置，不同的配置價格不同）https://console.volcengine.com/speech/app。

**記錄TTS_AST_APP_ID和TTS_TOKEN_ID填入config.json**

```

"ASR_APP_ID":"67790xxxxx",

"TTS_APP_ID":"67790xxxxx",

"TTS_TOKEN_ID":"OKly6Lr3XFFIw3xxxxx",

```

另外需要注意代碼里TTS的配置和應用配置的權限要對上，例如如果應用沒有開通音頻生成大模型，代碼就不能配置"Provider"為"volcano_bidirection"，只能配置為volcano，也不能傳遞tts_token,不然音頻傳生成功能會異常，進入房間聽不到歡迎語，demo代碼默認使用的音頻生成和語音識別，沒有使用大模型。

下圖是具體的示意圖：


####**開通大語言模型服務**

根據場景需要，開通需要的LLM服務（不同的LLM大模型價格不同，我們演示使用的是Doubao-1.5-vision-pro-32k）通過https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint創建應用，并記錄應用ID號，**填入config.json"LLM_END_POINT_ID":"ep-xxxxxx",**

這步如果沒有正常開通，demo也會遇到沒有歡迎語的提示

下圖是具體開通步驟的示意圖：


####**配置不同權限賬號調用智能體**

開通完服務后，還需要為角色配置策略，打開https://console.volcengine.com/rtc/aigc/iam,前往**跨服務授權**，點擊一鍵開通跨服務授權配置角色。


配置成功后你可以在https://console.volcengine.com/iam/identitymanage/role角色管理中找到該角色，該角色擁有SAFullAccess、MaaSExperienceAccess和RTCFullAccess權限。下圖為配置后的示意圖：


最后在https://console.volcengine.com/iam/keymanage界面獲取ACCESS_KEY

```

"ACCESS_KEY":"XXXX",

"SECRET_ACCESS_KEY":"XXX==",填入config.json

```


####**如果是使用子賬號，在板端調用權限有所同，注意參考https://www.volcengine.com/docs/6348/1315561設定**


###**依賴庫移植**

該AIdemo開啟智能體使用的是API方式，因而需要通過網絡發送httppost數據包，需要為板端移植相關的庫，訪問網絡時使用到的庫有：openssl、cares、curl。此外，由于火山引擎RTC服務的音頻不支持pcm格式，目前僅支持opus，g722，aac，g711a格式，根據實際需求移植相關的音頻編解碼庫，本AIdemo使用的是opus。

注意需要使用對應的Toolchain編譯對應的Lib庫，libVolcEngineRTCLite.so需要聯系火山引擎軟件人員并提供Toolchain，其他依賴庫可以使用BuildRoot環境進行更新。目前Demo只支持glibc12.4.0arm32Bit的開發環境。

###配置文件準備

板端運行該AIdemo需要輸入一個配置文件config.json，前面篇章有介紹到的字段均需要寫入此配置文件中。

配置好后推送到主板/customer/zkgui_mini/resource/sample/config.json即可使用火山引擎Demo。

該配置文件包含了火山引擎服務的Key和Id信息，文件中的各字段所表示的意義可以參考開啟智能體API（https://www.volcengine.com/docs/6348/1558163）時所使用的參數。

```

config.json

{

"RTC_APP_ID":"xxx",

"RTC_APP_KEY":"xxx",

"ACCESS_KEY":"xxx",

"SECRET_ACCESS_KEY":"xxx",

"ROOM_ID":"xxx",

"USER_ID":"xxx",

"AGENT_USER_ID":"xxx",

"TASK_ID":"xxx",

"TOKEN_VALUE":"xxx",

"ASR_APP_ID":"xxx",

"TTS_APP_ID":"xxx",

"TTS_TOKEN_ID":"xxx",

"LLM_END_POINT_ID":"xxx",

"SERVER_MESSAGE_URL":"xxx",

"SERVER_MESSAGE_SIGNATURE":"xxx"

}

```

其中如下4項"ROOM_ID""USER_ID":"AGENT_USER_ID""TASK_ID":"task1"，為房間信息用戶填寫，而"TOKEN_VALUE"目前是根據上述信息自動生產。

如下兩項可以保持默認值不變

"SERVER_MESSAGE_URL":"https://pm.comake.online/doubao_debug.log?type=subv",

"SERVER_MESSAGE_SIGNATURE":"892495980b78182f2fbab8e317e607a1bd6f1111c0b43a6ebb37337a6971c2bb"

#demo介紹

##demo流程說明

該AIdemo實現了AI對話以及視頻圖像推理的功能。用戶通過關鍵詞喚醒設備后，將語音輸入（opus）和圖像輸入（h264）通過火山引擎的RTCSDK傳輸到火山引擎的云服務，通過火山引擎的RTCSDK回調接收智能體的語音回復，解碼后進行播放。從而實現AI式對話和視覺推理的功能。如下所示為該AIdemo的框圖:


由**VIF**接收**Sensor**的數據，送到**ISP**和**SCL**進行圖像處理和圖像的縮小，將處理后的圖像送到**SWVENC**進行軟件編碼得到h264碼流數據，當Audio往火山傳輸數據時，同時發生VideoH264I幀數據。

由**AI(AudioInput)**接收**Mic**的輸出，經過**AEC**回聲消除處理、**APC**降噪處理、**VAD**語音檢測、**KWS**關鍵詞檢測，將語音輸入編碼成opus格式。

通過火山引擎RTC的接口，將編碼后的語音和視頻數據發送到火山引擎云端進行分析，等待火山引擎云端回復分析結果，將回復的語音數據進行opus解碼后通過**AO**輸出到**Speaker**。

##demo使用說明

###demo使用流程

###網絡環境

```

該demo需要訪問外部網絡，連接外網

Demo軟件可以通過如下命令設定Mac地址通過DHCP獲取IP地址:

ifconfigeth0hwether00:71:30:1B:xx:xx

ifconfigeth0up

udhcpc-ieth0-s/etc/init.d/udhcpc.script

獲取IP后確認ping豆包官網access.rtc.volcvideo.com是否成功

```

###demo運行

ComakePiD132Bit軟件默認有集成此Demo,UI點擊"火山引擎"即可打開。

###查看加入房間打印以及歡迎語

demo成功跑起來后會收到RTC加入房間的回調打印以及聽到智能體的歡迎語（你好，我是小星，我是你的好朋友，可以陪你談天說地！），如下所示：


上圖中紅框部分就是RTC加入房間的回調打印以及智能體的歡迎語回復信息打印，看到這些信息基本可以說明智能體已經正常開始工作了。

###查看關鍵詞打印

當聽到智能體的歡迎語后就可以開始對話了，對話前，請先說關鍵詞："你好，小星"。當板端檢測到關鍵詞后，會有這個打印后，此時可以開始詢問問題：


超過60s沒有檢測到實時語音就需要再次通過關鍵詞觸發。

###查看發送音頻/視頻數據打印

demo發送一幀音頻或一幀h264時，會出現如下類似打印：


上圖中sendopusencode是發送的一幀音頻數據的打印；sendvideoframe是發送的一幀h264的打印。

####查看智能體回復打印

不管發送視頻還是音頻數據，只要智能體有回復數據時，就可以看到如下圖所示打印：


####實例演示


##火山引擎相關開發說明

###RTCSDK接口調用順序

首先是進行RTC的初始化，user和agent加入房間。當APP收到回調函數后，就可以通過byte_rtc_send_audio_data以及byte_rtc_send_video_data接口發送音頻和視頻數據給大模型。經過大模型分析后，會通過回調函數將回復數據給到APP。當用戶離開房間后，就可以關閉房間，但需要等待RTC的回調函數通知才可以銷毀房間。

需要注意的是，demo中使用的是opus編碼格式，火山引擎還支持G722、AAC、G711格式，APP發送什么格式的音頻數據，火山引擎就會回復什么格式的音頻數據。應用場景需要什么編碼格式可自行移植相關編解碼庫進行對接，并通過byte_rtc_set_audio_codec接口告知RTC傳輸的是什么編碼格式，該接口需要在byte_rtc_init之后，byte_rtc_join_room之前調用。


###Toke鑒權

用戶在加入房間時（調用byte_rtc_join_room接口），需要傳入Token參數。在volc_agent.cpp文件中，實現了根據AppID、AppKey、RoomID、UserID、時間戳等參數實時生成Token的程序，而該部分對應的具體生成過程可以參考火山引擎官方文檔：https://www.volcengine.com/docs/6348/70121。

###API簽名驗證

在調用OpenAPI時，需要對API進行簽名以便火山引擎能夠進行身份驗證。在volc_agent.cpp文件中，實現了通過curl庫調用StartVoiceChat等API的程序，而該部分對應的具體簽名過程可以參考火山引擎官方文檔：https://www.volcengine.com/docs/6348/69859。

#問題記錄

##出現signature請求過期的打印

調用開啟智能體API時需要需要按照一定格式發送httppost請求，如果發送請求時出現以下打印：


出現上圖打印說明httppost的簽名是過期的，這個是因為簽名鑒權時需要使用當前時間，板端開機后時間從1970年開始計算，因此，構造的請求就是過期的。

需要確保Demo運行時ntp相關調用沒有異常。

##加入房間沒有成功

在智能體加入房間成功后，會有回調打印顯示，但是如果串口一直在刷如下打印：


當遇到這種情況時，說明智能體并沒有成功加入房間，大概率是地址解析失敗，需要檢查網絡看看，可以嘗試pingaccess.rtc.volcvideo.com這個域名看看需要多久才可以解析出，如果時間超過了5s（RTC那邊握手最多5s），說明網絡有問題，建議更換一個網絡。

##出現globalerror打印

在智能體加入房間時，如果長時間都沒有加入成功（至少5s），并且會有如下打印：


當遇到這種情況時，根據豆包的回復是由于網絡的原因，這種情況豆包那邊會嘗試重新連接，一般最后都會成功，因此，這個錯誤可以暫時不用管。

##智能體沒有回復數據

當出現智能體沒有歡迎語播報,或者智能體沒有回復數據時，可以按照以下步驟進行確認。

###確認ASR、TTS服務是否開通

demo依賴火山引擎云端的語音識別(ASR)和語音合成(TTS)服務的，請務必開通這兩個服務，如下所示：


###確認是否為角色配置策略

智能體要想回復，是需要有權限的，請務必在頁面https://console.volcengine.com/rtc/aigc/iam點擊一鍵開通跨服務授權配置角色進行配置策略，授權后https://console.volcengine.com/iam/identitymanage/role可以看到如下角色權限：


###確認開啟智能體時的json參數配置

除了一些必要的服務以及權限外，在調用開啟智能體API時還會需要配置智能體的一些屬性，SystemMessages系統提示詞，用于輸入控制大模型行為方式的指令，定義了模型的角色、行為準則，特定的輸出格式等，這個配置很重要。

目前，demo中為智能體配置的屬性如下所示：


json中具體每個字段的含義，可以參考該鏈接中的說明：https://www.volcengine.com/docs/6348/1404673。一般情況下，智能體沒有回復，基本都是這個json配置有問題。

##智能體回復不準確

智能體回復不準確，需要修改智能體的初始化人設.方法是修改llm_configSystemMessages字段代碼位置：

zk_minijnilogicvolcvolc_agent.cpp480行，目前人設是一個簡單的陪伴機器人。

```

cJSON_AddItemToArray(system_messages,cJSON_CreateString("你是小星，你是用戶的好朋友，你是一個具備情感陪伴能力的智能機器人，核心目標是通過表情識別與自然語言交互，為用戶提供有溫度的情感支持，回復內容不能包含圖片相關字眼。

請遵循以下原則：角色設定：以朋友身份互動，語氣親切自然，避免機械感（禁用技術術語，多用口語化表達）。

情感優先：任何回復需優先匹配用戶當前表情識別的情緒（如高興、悲傷、疲憊），再結合對話內容。

情緒識別標準：微笑、大笑表示高興，皺眉、流淚表示悲傷，瞪眼、咬牙表示憤怒,瞪眼、張嘴表示驚訝。"));

```

##其它問題

其他問題可以參考火山引擎RTC服務官網中的文檔說明https://www.volcengine.com/docs/6348。

審核編輯 黃宇