该文档介绍乐鑫ESP32-S3平台SDK接入大模型互动服务的最佳实践，引导用户快速跑通流程，解答常见的问题。

基础:跑通全流程

第一步:控制台开通云服务，配置互动智能体

1.注册云账号

2.开通大模型互动服务

3.创建和配置智能体

4.云上测试智能体

5.免费申请测试license

第二步:运行云对接服务示例

说明：百度智能云服务API接口，均采用AK/SK鉴权，为了增强安全性，要求在服务器上调用（不建议在设备上）。该示例代码实现一个访问中转，接收设备端连接请求，代理访问百度大模型互动API接口创建互动智能体，返回设备端侧访问云服务所需的token、agentid等信息。该代码可作为服务端对接的实现参考。

准备工作

1.下载云端对接服务示例代码

2.配置云对接服务参数

3.运行云对接服务示例

第三步:下载和运行设备端代码示例

准备工作

1.下载设备SDK和DEMO代码

2.修改参数配置项

3.音视频采集及播放代码说明

4.其他主要函数、事件代码说明

进阶:常见问题及解决办法

• 三种对话模式说明

  系统支持典型的3种语音对话：按键说话、连续对话（唤醒词打断）、连续对话（插话打断）。

  1.按键说话

  模式说明

  Plain Text 复制

  1- 终端设备上按住按键开始说话，松开按键结束说话。这种模式不需要开启云端VAD，不需要开启回声消除AEC。

  创建智能体进入模式

  Plain Text 复制

  1- 在服务器调用generateAIAgentCall接口，传入config参数`asr_long_audio_mode:true`

  动态切换进入模式

  Plain Text 复制

  1- 在设备上发送控制EVENT：`[E]:[CMD]:[ASR_DISABLE_REALTIME]` 进入到按键对话模式

  开始与结束单轮收音

  Plain Text 复制

  1- 在设备上发送控制EVENT：`[E]:[CMD]:[ASR_START_LONGTEXT_REC]` 通知服务端开始收音
  2- 在设备上发送控制EVENT：`[E]:[CMD]:[ASR_STOP_LONGTEXT_REC]` 通知服务器结束收音。
  3服务器会将这两次事件之间接收音频数据，一次性送到ASR模块转化成文本，送到后续环节。
  4注意：端侧采集到的音频数据需要流式、均匀发送到服务器。

  2.连续对话（唤醒词打断）

  模式说明

  Plain Text 复制

  1- 终端设备连续对话，但是只能通过离线唤醒词或在线唤醒词打断语音播报。这种模式不需要开启回声消除AEC。

  创建智能体进入模式

  Plain Text 复制

  1- 在服务器上调用generateAIAgentCall接口，传入config参数`disable_voice_auto_int:true`

  动态切换进入模式

  Plain Text 复制

  1- 在设备上发送控制EVENT：`[E]:[CMD]:[ASR_ENABLE_REALTIME]` 进入到连续对话模式
  2- 在设备上发送控制EVENT：`[SET]:[AUTO_INT]:[FALSE]` 关闭自动打断功能

  开始与结束单轮收音

  为了降低端设备的性能消耗，建议依据语音播报状态、设备是否处于被唤醒状态，控制开启MIC是否采集声音.

  Plain Text 复制

  1- 设备上接收到消息：`[E]:[TTS_BEGIN_SPEAKING]` 关闭MIC收音。
  2- 设备上接收到消息：`[E]:[TTS_END_SPEAKING]` 开启MIC收音，音频数据流式发送到服务器。
  3- 设备处于休眠状态（例如30秒没有对话，自动进入休眠状态），关闭MIC收音。
  4- 设备处于唤醒状态，开启MIC收音，音频数据流式发送到服务器。

  注意：端侧采集到的音频数据需要流式、均匀发送到服务器。

  离线唤醒词打断语音播报

  如设备上集成离线唤醒词功能，唤醒后打断当前语音播报。

  Plain Text 复制

  1  - 设备上离线唤醒词命中且响应后，在设备发送控制EVENT：`[B]:[BEGIN]:3000`到服务器；服务器接收到该指令后，立即打断当前语音播报，且持续3000ms丢弃用户输入的语音，或服务器收到`[B]:[END]`停止丢弃语音。
  2  该指令是是解决唤醒词语音也同步发送到服务器上，让服务器忽略唤醒词的模型回答。 丢弃音频时长大小请根据设备的唤醒词长度，响应速度自行调节。

  在线唤醒词打断语音播报

  如终端设备上没有集成离线唤醒词功能，可采用在线唤醒词实现相似的功能。在线唤醒词、回复语，可根据业务自行修改。

  Plain Text 复制

  1  - 启用在线唤醒词打断语音播报：在服务器上调用generateAIAgentCall接口，传入config参数`disable_voice_auto_int:false, interruption_words:"小文小文，你好小文", interruption_answer:"我在呢，咱们一起聊聊天吧。"`

  3.连续对话（插话打断）

  模式说明

  Plain Text 复制

  1- 终端设备连续对话，检测到用户说话则立即打断语音播报，跟人与人之间自然对话一样，随意打断。这种模式强依赖回声消除AEC功能。

  创建智能体进入模式

  Plain Text 复制

  1- 在服务器上调用generateAIAgentCall接口，传入config参数`disable_voice_auto_int:false`

  动态切换进入模式

  Plain Text 复制

  1- 在设备上发送控制EVENT：`[E]:[CMD]:[ASR_ENABLE_REALTIME]` 进入到连续对话模式
  2- 在设备上发送控制EVENT：`[SET]:[AUTO_INT]:[TRUE]` 开启自动打断功能

  开始与结束单轮收音

  该模式终端连续MIC收音，音频数据流式、均匀发送到服务器；设备接收到的服务器播报的语音，解码播放即可。无需过多状态控制。

• 海外节点接入说明

（端侧同学补充）

• 问题：语音识别不准，怎么处理

语音识别不准确，一般是MIC收音问题：噪音或杂音太大，或者是声音能量值偏小（建议声音能量均值在40～50%），建议在端上优化降噪或增益效果；如端侧无法处理可尝试开启云上3A功能优化。

方法1:设备端上调优降噪ANS、增益AGC

（端侧同学补充）

方法2:云上调优自动降噪ANS、自动增益AGC

• 开启云上自动降噪与自动增益，请参见云端音频3A功能最佳实践

• 问题：端设备自言自语对话（播放的声音，回采后重新回答）

  这种现象一般是回声消除异常导致，建议在端上优化AEC，端侧无法处理可尝试云上优化；或是采用采用单工对话方式。

方法1:设备上调优回声消除AEC

（端侧同学补充）

方法2:云上调优回声消除AEC

• 开启云上回声消除AEC功能，请参见云端音频3A功能最佳实践

方法3:切换到对话模式：按键说话、连续对话（唤醒词打断）

按键说话、连续对话（唤醒词打断），这两种是单工对话，不依赖回声消除功能，可解决这个问题。

• 自定义函数(Function Calling)，提升函数命中率

参见高质量编写Function Calling说明

• 如何自定义人设及使用人设

在控制台上配置人设，高质量编写人设提示词

高质量编写人设提示词最佳实践

如何使用已定义的人设

创建智能体指定已定义的人设

1  - 在服务器上调用generateAIAgentCall接口，传入config参数`sceneRole:人设名称`。 人设名称就是控制台定义的人设名称。

动态切换已定义的人设及音色

在服务器上调用operation?switchSceneRole接口， 指定对应的人设名称、音色名。

• 设备未授权提示及处理办法

  设备连接到服务器后，服务器会下发鉴权请求，如鉴权失败，设备有未授权提示，且服务器主动与设备断开连接。造成这个原因一般有3种情况：

  Plain Text 复制

  1* 设备连接服务未正确传入license、DeviceID、UserID信息，或者license无效。 注意：DeviceID可能是SDK自动获取硬件码，无需填写；Websocket对接则需显示传入。DeviceID、UserID要求appid纬度唯一。
  2* 网络原因导致服务端未及时收到鉴权的响应。 建议切换到良好的网络。
  3* 多台设备非法共用同一个license。 云端会检测到异常，主动断开设备连接。

• 判断对话响应延时正常与否，及优化建议

  • 问题类型延时均值参考范围（采用默认模型）

    • -聊天对话：1.2秒～2秒
    • -联网搜索：1.5秒～2.6秒（关闭垫句）；1.2秒～2秒（开启垫句）
    • -云播有声内容：1.2秒～2秒
    • -Function Calling：1秒～1.8秒 （参数少于2个）

  • 影响延时的因素分析及优化建议

    • 硬件平台：不同的硬件平台延时有较大差异，有大几百毫秒的差别。 移动端SDK（andorid、ios、H5 SDK）延时最低，可达到平台最优值。 RTOS平台中乐鑫ESP32-S3 SDK延时表现最为良好，聊天对话延时最优可达1.4秒左右，其他平台延时大多在1.5～1.8秒范围。
    • RTOS集成方式-SDK or Websocket：在纯语音交互场景，两者延时相差不明显，正常网络情况下差异在100ms之内，弱网SDK表现占优。
    • 技术架构-端到端语音模型 or 三段式结构： 本方案支持端到端语音模型、三段式（ASR+LLM+TTS）两种技术架构。 端到端延时约在1秒左右，但扩展能力弱；三段式模式延时约增加200～400ms，但可定制、扩展性强。选择技术方案根据具体场景而定。
    • TTS音色差异：经实测发现，同等条件下，不同的TTS音色延时差别偏大，最大差异达到800ms。延时表现良好的TTS音色有：1000002、1000012、1000029、1000007、1000011、1000006、1000024等。具体可在控制台上体验挑选。
    • 人设模型差异：系统提供的多个人设模型可选择，不同的模型延时不一样。例如千帆的ip charactor模型比默认模型延时增加300~500ms。
    • 接入第三方模型服务：系统支持接入第三方模型、智能体平台。延时大小 = 第三方模型服务返回首句延时 + 1.0秒。
    • 设备端侧数据缓存大小：建议启播缓冲在100～300ms, 最大缓冲在500～1000ms. 如果结合云端的快速起播功能（近期推出），最大缓冲可适当增大。

    • 创建智能体参数：调用generateAIAgentCall接口，传入config参数：

      • dfda：true 可降低300～500ms延时，在少数硬件平台有解码兼容性问题。
      • tts_end_delay_ms：50 设置较小的值，端侧可以快速接收到TTS_END_SPEAKING事件。

    • 音频格式选择：RTOS设备计算能力、网络能力偏弱， 也会影响到交互延时。建议均衡选择音频编码格式。

      • pcmu或 raw : 采样率8K，计算消耗低，音质一般，数据量适中；
      • raw16k: 采样率16K，计算消耗低，音质适中，数据量大；
      • G722: 采样率16K，计算消耗偏高，音质适中，数据量适中；
      • opus: 采样率从16k~48k, 计算消耗高，数据量小，音质良好。 上下行采样率可设置不同。

• 更多的资料从哪里找

• 集成流程完整介绍
• 声纹使用最佳实践
• 定时器使用最佳时间
• 多语言使用最佳时间
• 产品功能特性表介绍
• 更多的服务端接口