嵌入式 NERTC SDK（NERtcSDK）是网易云信面向 IoT 智能硬件设备 的实时音频传输与 AI 对话 SDK。本文重点说明设备侧接入的适用场景、典型流程、接入前准备和鉴权主口径。具体的 SDK 获取方式、初始化代码、AEC 方案和硬件适配细节，请参考后续专项文档。

适用范围

嵌入式 NERTC SDK 适用于智能硬件设备侧集成实时对话 AI 的场景，例如陪伴机器人、AI 玩具、儿童设备、老人陪伴设备和其他 IoT 终端。该方案面向设备侧的音频采集、实时传输、设备激活、智能体绑定和 AI 对话控制等完整链路。

如果您的目标是在硬件设备中接入实时语音对话能力，并对设备侧音频链路、AEC、唤醒、打断和设备管理有完整控制需求，推荐优先使用嵌入式 NERTC SDK。

与 音视频通话 NERTC SDK 的区别：

对比项	嵌入式 NERTC SDK	音视频通话 NERTC SDK
定位	IoT 智能硬件	移动端/桌面端/Web
平台	ESP32, 杰理, 博通等 MCU	Android, iOS, Windows, Web
核心能力	音频传输 + AI 对话	音视频通话 + 互动直播
传输协议	MQTT + RTP / WebSocket + RTP	WebRTC / UDP
音频编码	OPUS / PCM	OPUS / AAC / PCM
体积	轻量级，适配 MCU 资源限制	全功能
不包含	音视频频编解码、音频采集驱动	—

核心能力

• 实时音频传输：设备端麦克风采集 → OPUS 编码 → RTP 发送至云端；云端 AI 音频 → RTP 下发 → 设备端解码播放
• AI 对话：对接云端 ASR（语音识别）、TTS（语音合成）、LLM（大语言模型）服务
• 实时字幕：将用户语音实时转写为文字字幕
• 语音打断：在 AI 说话时通过语音或手动方式打断
• 唤醒词：支持自定义离线语音唤醒词
• 多平台适配：ESP32、杰理、博通、Linux 等
• 网易云音乐播放：可以直接免登录播放网易云音乐
• MCP：支持设备的自定义 MCP，云端也有丰富的 MCP 可供配置

核心概念与 ID 关系

理解以下概念是顺利接入的基础：

核心关系：

• 智能体平台：配置设备 device_id、音色、唤醒词、LLM 等
• iot-demo/nertc_sdk：硬件设备对话入口
• 客户端（如网易小派微信小程序）：配网、绑定设备、切换智能体

串联所有模块的核心标识为：device_id（MAC 地址）

各 ID 说明

概念	说明	由谁创建	示例
App Key	应用唯一标识，顶层容器	网易云信控制台	a3fd1073748******4f9ad0472281bd0
设备 ID	设备唯一标识，使用 MAC 地址	开发者自行维护	AA:BB:CC:DD:EE:FF

关键约束

• 一台设备只能绑定一个智能体 — 设备与智能体是 1:1 关系
• 设备 ID 必须使用 MAC 地址 — 确保设备级别的唯一性和持久性，且需在服务端激活

SDK 生命周期

textnertc_create_engine_with_config()    创建引擎（静态配置：AppKey、设备ID、音频参数）
         │
nertc_init_engine()                  初始化引擎（运行态配置：事件回调、工作模式）
         │
nertc_join()                         建立 AI 对话 Session（Token、Channel、UID）
         │
nertc_start_ai_with_config()         开启 AI 对话
         │
nertc_push_audio_encoded_frame()     发送音频流（循环）
         │
nertc_ai_manual_interrupt()          手动打断 AI 对话（可选）
         │
nertc_leave()                        结束 AI 对话 Session
         │
nertc_destroy_engine()               销毁引擎实例

音频 AEC

回声消除（AEC）是实现语音打断的前提条件。如果设备没有 AEC 能力，AI 播放的声音会被麦克风回收，导致服务端无法正确识别用户的打断语音。

要支持语音打断，需要满足以下两点：

• 设备必须具备 AEC 能力：对麦克风采集的音频做回声消除，避免 AI 播放的声音干扰语音识别
• 音频必须持续发送：无论设备当前状态机处于 speaking（AI 说话）还是 listening（设备收音），音频采集和发送都不能中断，确保服务端能持续检测用户的打断意图

三种引擎模式

engine_mode 用于指定 SDK 引擎的模式，可选值：

模式	枚举	说明
Lite 模式	NERTC_SDK_ENGINE_MODE_LITE	低延迟 AI 对话场景。需要在协议初始化前使用云信 OTA 返回的 mqtt 参数完成相关初始化。不支持打电话及 RTC 通话
Normal 模式	NERTC_SDK_ENGINE_MODE_NORMAL	全能力模式，具备 AI 对话与音视频通话的全部能力，支持打电话及 RTC 通话
PTT 模式	NERTC_SDK_ENGINE_MODE_PTT	按键说话，由 App 层手动控制音频发送的开始/结束，适用于对讲机、按键式交互场景

平台差异

虽然 SDK 核心是跨平台的，但不同芯片的编译环境、构建系统、音频采集方式差异很大：

芯片平台	编译环境	构建系统	代码入口
ESP32	ESP-IDF v5.5.2	CMake + idf.py	demo/esp32/main/
杰理 AC7911	—	—	demo/jieli-ac791/
博通 BK7258	ARM IDK v1.2	—	demo/bk7258/bk_aidk/

功能支持

功能	ESP32	杰理 AC7911	博通 BK7258
AI 对话	✅	✅	✅
网易云音乐播放	✅	✅	❌
MCP	✅	✅	❌

ESP32 和杰理平台均已支持 MCP，设备端可自定义 MCP 工具，云端也有丰富的 MCP 可供配置。

详细的环境搭建和编译说明，请查看各芯片方案：乐鑫 ESP32 | 杰理 AC7911 | 博通 BK7258。

下一步

• 查看完整 API 参考：接口列表
• 对接小程序：对接小程序