diff --git a/README.md b/README.md index 372eaa74..256a9cc6 100755 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ # 小智 AI 聊天机器人 -BiliBili 视频介绍 [【ESP32+SenseVoice+Qwen72B打造你的AI聊天伴侣！】](https://www.bilibili.com/video/BV11msTenEH3/?share_source=copy_web&vd_source=ee1aafe19d6e60cf22e60a93881faeba) - 这是虾哥的第一个硬件作品。 +[ESP32+SenseVoice+Qwen72B打造你的AI聊天伴侣！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/?share_source=copy_web&vd_source=ee1aafe19d6e60cf22e60a93881faeba) + +[手工打造你的 AI 女友，新手入门教程【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/) + ## 项目目的 本项目基于乐鑫的 ESP-IDF 进行开发。 @@ -18,16 +20,16 @@ BiliBili 视频介绍 [【ESP32+SenseVoice+Qwen72B打造你的AI聊天伴侣！ - Wi-Fi 配网 - 支持 BOOT 键唤醒和打断 -- 离线语音唤醒（使用乐鑫方案） +- 离线语音唤醒（乐鑫方案） - 流式语音对话（WebSocket 协议） -- 支持国语、粤语、英语、日语、韩语 5 种语言识别（使用 SenseVoice 方案） +- 支持国语、粤语、英语、日语、韩语 5 种语言识别（SenseVoice 方案） - 声纹识别（识别是谁在喊 AI 的名字，[3D Speaker 项目](https://github.com/modelscope/3D-Speaker)） -- 使用大模型 TTS（火山引擎方案，阿里云接入中） +- 使用大模型 TTS（火山引擎与 CosyVoice 方案） - 支持可配置的提示词和音色（自定义角色） -- 免费提供 Qwen2.5 72B 和 豆包模型（受限于性能和额度，人多后可能会限额） +- Qwen2.5 72B 或 豆包 API - 支持每轮对话后自我总结，生成记忆体 -- 扩展液晶显示屏，显示信号强弱（后面可以显示中文字幕） -- 支持 ML307 Cat.1 4G 模块（可选） +- 扩展液晶显示屏，显示信号强弱 +- 支持 ML307 Cat.1 4G 模块 ## 硬件部分 @@ -35,60 +37,29 @@ BiliBili 视频介绍 [【ESP32+SenseVoice+Qwen72B打造你的AI聊天伴侣！ [《小智 AI 聊天机器人百科全书》](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink) -第二版接线图如下： +面包板接线图如下： -![第二版接线图](docs/wiring2.jpg) +![面包板接线图](docs/wiring2.jpg) ## 固件部分 ### 免开发环境烧录 -新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。 +新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。固件使用的是作者友情提供的测试服，目前开放免费使用，请勿用于商业用途。 -点击 [这里](https://github.com/78/xiaozhi-esp32/releases) 下载最新版固件。 +[Flash烧录固件（无IDF开发环境）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) -固件使用的是作者友情提供的测试服，目前开放免费使用，请勿用于商业用途。 -### 搭建开发环境 +### 开发环境 - Cursor 或 VSCode - 安装 ESP-IDF 插件，选择 SDK 版本 5.3 或以上 - Ubuntu 比 Windows 更好，编译速度快，也免去驱动问题的困扰 -### 配置项目与编译固件 -- 目前只支持 ESP32 S3，Flash 至少 8MB, PSRAM 至少 2MB（注意：默认配置只兼容 8MB PSRAM，如果你使用 2MB PSRAM，需要修改配置，否则无法识别） -- 配置 OTA Version URL 为 `https://api.tenclass.net/xiaozhi/ota/` -- 配置 WebSocket URL 为 `wss://api.tenclass.net/xiaozhi/v1/` -- 配置 WebSocket Access Token 为 `test-token` -- 如果 INMP441 和 MAX98357 接线跟默认配置不一样，需要修改 GPIO 配置 -- 配置完成后，编译固件 +## AI 角色配置 +如果你已经拥有一个小智 AI 聊天机器人，可以参考 [后台操作视频教程](https://www.bilibili.com/video/BV1jUCUY2EKM/) -## 配置 Wi-Fi （4G 版本跳过） - -按照上述接线，烧录固件，设备上电后，开发板上的 RGB 会闪烁蓝灯（部分开发板需要焊接 RGB 灯的开关才会亮），进入配网状态。 - -打开手机 Wi-Fi，连接上设备热点 `Xiaozhi-xxxx` 后，使用浏览器访问 `http://192.168.4.1`，进入配网页面。 - -选择你的路由器 WiFi，输入密码，点击连接，设备会在 3 秒后自动重启，之后设备会自动连接到路由器。 - -## 测试设备是否连接成功 - -设备连接上路由器后，闪烁一下绿灯。此时，喊一声“你好，小智”，设备会先亮蓝灯（表示连接服务器），然后再亮绿灯，播放语音。 - -如果没有亮蓝灯，说明麦克风有问题，请检查接线是否正确。 - -如果没有亮绿灯，或者蓝灯常亮，说明设备没有连接到服务器，请检查 WiFi 连接是否正常。 - -如果设备已经连接 Wi-Fi，但是没有声音，请检查是否接线正确。 - -在 v0.2.1 版本之后的固件，也可以按下连接 GPIO 1 的按钮（低电平有效），进行录音测试。 - -## 配置设备 - -如果上述步骤测试成功，设备会播报你的设备 ID，你需要到 [小智测试服的控制面板](https://xiaozhi.tenclass.net/) 页面，添加设备。 - -详细的使用说明以及测试服的注意事项，请参考 [小智测试服的帮助说明](https://xiaozhi.tenclass.net/help)。 - +详细的使用说明以及测试服的注意事项，请参考 [小智测试服的帮助说明](https://xiaozhi.me/help)。 diff --git a/docs/wiring2.jpg b/docs/wiring2.jpg index 910e2f59..f3a67ae7 100644 Binary files a/docs/wiring2.jpg and b/docs/wiring2.jpg differ diff --git a/websocket.md b/websocket.md deleted file mode 100644 index e644032e..00000000 --- a/websocket.md +++ /dev/null @@ -1,160 +0,0 @@ - -# AI 语音交互通信协议文档 - -## 1. 连接建立与鉴权 - -客户端通过 WebSocket 连接到服务器时，需要在 HTTP 头中包含以下信息： - -- `Authorization`: Bearer token，格式为 "Bearer " -- `Device-Id`: 设备 MAC 地址 -- `Protocol-Version`: 协议版本号，当前为 2 - -WebSocket URL: `wss://api.tenclass.net/xiaozhi/v1` - -## 2. 二进制数据 - -客户端发送的二进制数据使用固定头格式的协议，如下： - -```cpp -struct BinaryProtocol { - uint16_t version; // 二进制协议版本，当前为 2 - uint16_t type; // 消息类型（0：音频流数据，1：JSON） - uint32_t reserved; // 保留字段 - uint32_t timestamp; // 时间戳（保留用作回声消除，也可以用于UDP不可靠传输中的排序） - uint32_t payload_size; // 负载大小 - uint8_t payload[]; // 可以是音频数据（Opus 编码或协商的音频格式），也可以封装 JSON -} __attribute__((packed)); -``` - -注意：所有多字节整数字段使用网络字节序（大端序）。 - -目前二进制数据跟 JSON 都是走同一个 WebSocket 连接，未来实时对话模式下，二进制音频数据可能走 UDP，可以扩展 hello 消息进行协商。 - -## 3. 音频数据传输 - -- 客户端到服务器: 使用二进制协议发送 Opus 编码的音频数据 -- 服务器到客户端: 使用二进制协议发送 Opus 编码的音频数据，格式与客户端发送的相同 - -出现 payload_size 为 0 的音频数据包可以用做句子边界标记，可以忽略，但不要报错。 - -## 4. 握手消息 - -连接建立后，客户端发送一个 JSON 格式的 "hello" 消息，初始化服务器端的音频解码器。 -不需要等待服务器响应，随后即可发送音频数据。 - -```json -{ - "type": "hello", - "response_mode": "auto", - "audio_params": { - "format": "opus", - "sample_rate": 16000, - "channels": 1 - } -} -``` - -应答模式 `response_mode` 可以为 `auto` 或 `manual`。 - -`auto`：自动应答模式，服务器实时计算音频 VAD 并自动决定何时开始应答。 - -`manual`：手动应答模式，客户端状态从 `listening` 变为 `idle` 时，服务器可以应答。 - -## 5. 状态更新 - -客户端在状态变化时发送 JSON 消息: - -```json -{ - "type": "state", - "state": "<新状态>" -} -``` - -可能发送的状态值包括: `idle`, `wake_word_detected`, `listening`, `speaking`。 - -示例: - -1、按住说话（`response_mode` 为 `manual`） - -- 当按住说话按钮时，如果未连接服务器，则连接服务器，并编码、缓存当前音频数据，连接成功后，客户端设置状态为 `listening`，并在 hello 消息之后发送缓存的音频数据。 -- 当按住说话按钮时，如果已连接服务器，则客户端设置状态为 `listening`，并发送音频数据。 -- 当释放说话按钮时，状态变为 `idle`，此时服务器开始识别。 -- 服务器开始应答时，推送 `stt` 和 `tts` 消息。 -- 客户端开始播放音频时，状态设为 `speaking`。 -- 客户端结束播放音频时，状态设为 `idle`。 -- 在 `speaking` 状态下，按住说话按钮，会立即停止当前音频播放，状态变为 `listening`。 - -2、语音唤醒，轮流对话（`response_mode` 为 `auto`） - -- 连接服务器，发送 hello 消息，发送唤醒词音频数据，然后发送状态 `wake_word_detected`，服务器开始应答。 -- 客户端开始播放音频时，状态设为 `speaking`，此时客户端不会发送音频数据。 -- 客户端结束播放音频时，状态设为 `listening`，此时客户端发送音频数据。 -- 服务器计算音频 VAD 自动选择时机开始应答时，推送 `stt` 和 `tts` 消息。 -- 客户端收到 `tts`.`start` 时，开始播放音频，状态设为 `speaking`。 -- 客户端收到 `tts`.`stop` 时，停止播放音频，状态设为 `listening`。 - -3、语音唤醒，实时对话（`response_mode` 为 `real_time`） - -- 连接服务器，发送 hello 消息，发送唤醒词音频数据，然后发送状态 `wake_word_detected`，服务器开始应答。 -- 客户端开始播放音频时，状态设为 `speaking`。 -- 客户端结束播放音频时，状态设为 `listening`。 -- 在 `speaking` 和 `listening` 状态下，客户端都会发送音频数据。 -- 服务器计算音频 VAD 自动选择时机开始应答时，推送 `stt` 和 `tts` 消息。 -- 客户端收到 `stt` 时，状态设为 `listening`。如果当前有音频正在播放，则在当前 sentence 结束后停止播放音频。 -- 客户端收到 `tts`.`start` 时，开始播放音频，状态设为 `speaking`。 -- 客户端收到 `tts`.`stop` 时，停止播放音频，状态设为 `listening`。 - -## 6. 服务器到客户端的消息 - -### 6.1 语音识别结果 (STT) - -```json -{ - "type": "stt", - "text": "<识别出的文本>" -} -``` - -### 6.2 文本转语音 (TTS) - -TTS开始: -```json -{ - "type": "tts", - "state": "start", - "sample_rate": 24000 -} -``` - -句子开始: -```json -{ - "type": "tts", - "state": "sentence_start", - "text": "你在干什么呀？" -} -``` - -句子结束: -```json -{ - "type": "tts", - "state": "sentence_end" -} -``` - -TTS结束: -```json -{ - "type": "tts", - "state": "stop" -} -``` - -## 7. 连接管理 - -- 客户端检测到 WebSocket 断开连接时，应该停止音频播放并重置为空闲状态 -- 在断开连接后，客户端按需重新发起连接（比如按钮按下或语音唤醒） - -这个文档概括了 WebSocket 通信协议的主要方面。