From 5ed1757976e85cf4132cfdb966ee17dac5ee62c2 Mon Sep 17 00:00:00 2001 From: kalicyh <34980061+kaliCYH@users.noreply.github.com> Date: Sun, 16 Feb 2025 19:11:11 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=83=20docs(readme):=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E6=95=B4=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 557 +++++++++-------------------------------- docs/Deployment.md | 293 ++++++++++++++++++++++ docs/firmware-build.md | 83 ++++++ 3 files changed, 488 insertions(+), 445 deletions(-) create mode 100644 docs/Deployment.md create mode 100644 docs/firmware-build.md diff --git a/README.md b/README.md index 21799b8c..154f2cba 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,15 @@ （中文 | [English](README_en.md)） -本项目为开源智能硬件项目 [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) -提供后端服务。根据[小智通信协议](https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh)使用`Python`实现。 +本项目为开源智能硬件项目 [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) 提供后端服务。根据 [小智通信协议](https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh) 使用 `Python` 实现。 -## 适用人群 +--- -本项目需要配合esp32硬件设备使用，如果童鞋们已经购买了esp32相关硬件，且成功对接虾哥部署的后端，并且想自己独立搭建 -`xiaozhi-esp32`后端服务，可学习本项目。 +## 适用人群 👥 -想看使用效果,请猛戳这个视频 +本项目需要配合 ESP32 硬件设备使用。如果您已经购买了 ESP32 相关硬件，且成功对接过虾哥部署的后端服务，并希望独立搭建自己的 `xiaozhi-esp32` 后端服务，那么本项目非常适合您。 + +想看使用效果？请猛戳这个视频 🎥 @@ -20,526 +20,193 @@ -要想完整体验本项目，需要以下总体步骤： +--- -- 准备一套兼容`xiaozhi-esp32` - 项目的硬件设备，具体型号可[点击这里](https://rcnv1t9vps13.feishu.cn/wiki/DdgIw4BUgivWDPkhMj1cGIYCnRf)。 -- 拥有一台至少4核CPU 8G内存的普通电脑或服务器，运行本项目。部署后可以在控制台看到本项目服务的接口地址。 -- 下载`xiaozhi-esp32`项目，把`接口地址`修改成本项目地址，然后编译，把新固件烧录到硬件设备上。 -- 启动设备，查看电脑或服务器的控制台，如果看到日志，说明成功连到本项目的接口了。 +## 系统要求与部署前提 🖥️ -## 警告 +- **硬件**：一套兼容 `xiaozhi-esp32` 的硬件设备（具体型号请参考 [此处](https://rcnv1t9vps13.feishu.cn/wiki/DdgIw4BUgivWDPkhMj1cGIYCnRf)）。 +- **服务器**：至少 4 核 CPU、8G 内存的电脑或服务器。 +- **固件编译**：请将后端服务的接口地址更新至 `xiaozhi-esp32` 项目中，再重新编译固件并烧录到设备上。 + +--- + +## 警告 ⚠️ 本项目成立时间较短，还未通过网络安全测评，请勿在生产环境中使用。 -如果您在公网环境中部署学习本项目。请务必在配置文件`config.yaml`开启防护。 +如果您在公网环境中部署学习本项目，请务必在配置文件 `config.yaml` 中开启防护： -``` +```yaml server: auth: # 开启防护 enabled: true ``` -开启防护后，你要根据自己的情况，要么校验机器的token，要么校验机器的mac地址，详细可看配置。 +开启防护后，您需要根据实际情况校验机器的 token 或 mac 地址，详细请参见配置说明。 -## 功能清单 +--- -## 已实现 +## 功能清单 ✨ -- `xiaozhi-esp32` 通信 WebSocket 协议 -- 支持唤醒对话、手动对话、实时打断对话 -- 支持国语、粤语、英语、日语、韩语 5 种语言识别（FunASR（默认）） -- 自由更换 LLM（openai接口支持ChatGLM（默认）、阿里百炼、DeepSeek等，dify接口支持Dify官方及私有化部署） -- 自由更换 TTS（支持EdgeTTS（默认）、火山引擎豆包TTS） +### 已实现 ✅ -## 正在实现 +- **通信协议** + 基于 `xiaozhi-esp32` 协议，通过 WebSocket 实现数据交互。 +- **对话交互** + 支持唤醒对话、手动对话及实时打断。 +- **多语言识别** + 支持国语、粤语、英语、日语、韩语（默认使用 FunASR）。 +- **LLM 模块** + 支持灵活切换 LLM 模块，默认使用 ChatGLMLLM，也可选用阿里百炼、DeepSeek、Ollama 等接口。 +- **TTS 模块** + 支持 EdgeTTS（默认）、火山引擎豆包 TTS 等多种 TTS 接口，满足语音合成需求。 -- 长时间不聊天进入休眠状态 -- 对话记忆 -- 更换心情模式 +### 正在开发 🚧 -## 本项目支持的平台/组件列表 +- 长时间无对话时自动休眠 +- 对话记忆功能 +- 多种心情模式 -| 类型 | 平台名称 | 使用方式 | 收费模式 | 备注 | -|:----|:----------|:----------:|:--------|:----------------------------------------------------------------| -| LLM | 阿里百炼 | openai接口调用 | 消耗token | [点击申请密钥](https://bailian.console.aliyun.com/?apiKey=1#/api-key) | -| LLM | 深度求索 | openai接口调用 | 消耗token | [点击申请密钥](https://platform.deepseek.com/) | -| LLM | 智谱 | openai接口调用 | 免费 | [点击创建密钥](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) | -| LLM | Dify | dify接口调用 | 消耗token | 本地化部署 | -| TTS | 火山引擎 | 接口调用 | 消耗token | [点击创建密钥](https://console.volcengine.com/speech/service/8) | -| TTS | EdgeTTS | 接口调用 | 免费 | | -| VAD | SileroVAD | 本地使用 | 免费 | | -| ASR | FunASR | 本地使用 | 免费 | | +--- -实际上，任何支持openai接口调用的LLM，都可以接入使用。 +## 本项目支持的平台/组件列表 📋 -# 部署方式 +### LLM -本项目支持docker快速部署、借助docker环境运行部署和本地源码运行三种方式。三种方式怎么选，每个人的情况不一样，以下是一些推荐。 +| 类型 | 平台名称 | 使用方式 | 收费模式 | 备注 | +|:----:|:-----------------------------:|:-------------------:|:-------------:|:------------------------------------------------------------------------------------------:| +| LLM | 阿里百炼 (AliLLM) | openai 接口调用 | 消耗 token | [点击申请密钥](https://bailian.console.aliyun.com/?apiKey=1#/api-key) | +| LLM | 深度求索 (DeepSeekLLM) | openai 接口调用 | 消耗 token | [点击申请密钥](https://platform.deepseek.com/) | +| LLM | 智谱（ChatGLMLLM） | openai 接口调用 | 消耗 token | 需注册申请 API key，请参考 [BigModel](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) | +| LLM | OllamaLLM | ollama 接口调用 | 免费/自定义 | 需预先下载模型（`ollama pull`），服务地址：`http://localhost:11434` | +| LLM | DifyLLM | dify 接口调用 | 消耗 token | 本地化部署，注意配置提示词需在 Dify 控制台设置 | +| LLM | GeminiLLM | gemini 接口调用 | 免费 | [申请 API](https://aistudio.google.com/apikey)；请遵守使用规定 | +| LLM | CozeLLM | coze 接口调用 | 消耗 token | 需提供 bot_id、user_id 及个人令牌 | -如果您主要是想快速体验，推荐使用`方式一：docker快速部署`。 +实际上，任何支持 openai 接口调用的 LLM 均可接入使用。 -如果您已经安装docker，不想折腾环境，又想对代码进行DIY修改，推荐`方式二：借助docker环境运行部署`。 +--- -如果您对conda的使用得心应手，或想从零开始学习搭建环境，推荐`方式三：本地源码运行`。 +### TTS -如果你对小智的回答速度非常的敏感，不希望有丝丝的性能损失，推荐`方式三：本地源码运行`。 +| 类型 | 平台名称 | 使用方式 | 收费模式 | 备注 | +|:----:|:-----------------------------------:|:---------------:|:-------------:|:-------------------------------------------------------------------------------------------------------------------------:| +| TTS | EdgeTTS | 接口调用 | 免费 | 默认 TTS，基于微软语音合成技术 | +| TTS | 火山引擎豆包 TTS (DoubaoTTS) | 接口调用 | 消耗 token | [点击创建密钥](https://console.volcengine.com/speech/service/8)；建议使用付费版本以获得更高并发 | +| TTS | CosyVoiceSiliconflow | 接口调用 | 消耗 token | 需申请硅基流动 API 密钥；输出格式为 wav | +| TTS | CozeCnTTS | 接口调用 | 消耗 token | 需提供 Coze API key；输出格式为 wav | +| TTS | FishSpeech | 接口调用 | 免费/自定义 | 本地启动 TTS 服务；启动方法见配置文件内说明 | +| TTS | GPT_SOVITS_V2 | 接口调用 | 免费/自定义 | 本地启动 TTS 服务，适用于个性化语音合成场景 | -## 方式一：docker快速部署 +--- -docker镜像已支持x86架构、arm64架构的CPU，支持在国产操作系统上运行。 +### VAD -### 1. 安装docker +| 类型 | 平台名称 | 使用方式 | 收费模式 | 备注 | +|:----:|:----------:|:---------:|:--------:|:----:| +| VAD | SileroVAD | 本地使用 | 免费 | | -如果您的电脑还没安装docker，可以按照这里的教程安装：[docker安装](https://www.runoob.com/docker/ubuntu-docker-install.html) +--- -### 2. 创建目录 +### ASR -安装完后，你需要为这个项目找一个安放配置文件的目录，我们暂且称它为`项目目录`，这个目录最好是一个新建的空的目录。 +| 类型 | 平台名称 | 使用方式 | 收费模式 | 备注 | +|:----:|:--------:|:---------:|:--------:|:----:| +| ASR | FunASR | 本地使用 | 免费 | | -### 3. 下载配置文件 +--- -用浏览器打开[这个链接](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/config.yaml)。 +## 部署方式 🚀 -在页面的右侧找到名称为`RAW`按钮，在`RAW`按钮的旁边，找到下载的图标，点击下载按钮，下载`config.yaml`文件。 把文件下载到你的 -`项目目录`。 +[部署文档](./docs/Deployment.md) -### 4. 修改配置文件 +本项目支持以下三种部署方式，您可根据实际需求选择： -修改刚才你下载的`config.yaml`文件，配置本项目所需的各种参数。默认的LLM使用的是`ChatGLMLLM` -，你需要配置密钥，因为他们的模型，虽然有免费的，但是仍要去[官网](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)注册密钥，才能启动。 +1. **Docker 快速部署** + 适合快速体验，不需过多环境配置。 +2. **借助 Docker 环境运行部署** + 适用于已安装 Docker 且希望对代码进行自定义修改的用户。 +3. **本地源码运行** + 适合熟悉 Conda 环境或希望从零搭建运行环境的用户。 + 对于对响应速度要求较高的场景，推荐使用本地源码运行方式以降低额外开销。 -默认的TTS使用的是`EdgeTTS`，这个无需配置，如果你需要更换成`豆包TTS`，则需要配置密钥。 +--- -配置说明：这里是各个功能使用的默认组件，例如LLM默认使用`ChatGLMLLM`模型。如果需要切换模型，就是改对应的名称。 +## 常见问题 ❓ -本项目的默认配置原则是成本最低配置原则（`glm-4-flash`和`EdgeTTS`都是免费的），如果需要更优的更快的搭配，需要自己结合部署环境切换各组件的使用。 +### 1、TTS 经常失败，经常超时 ⏰ -``` -selected_module: - ASR: FunASR - VAD: SileroVAD - LLM: ChatGLMLLM - TTS: EdgeTTS -``` +建议：如果 `EdgeTTS` 经常失败，请先检查是否使用了代理（梯子）。如果使用了，请尝试关闭代理后再试； +如果用的是火山引擎的豆包 TTS，经常失败时建议使用付费版本，因为测试版本仅支持 2 个并发。 -比如修改`LLM`使用的组件，就看本项目支持哪些`LLM` API接口，当前支持的是`openai`、`dify`。欢迎验证和支持更多LLM平台的接口。 +### 2、我想通过小智控制电灯、空调、远程开关机等操作 💡 -使用时，在`selected_module`修改成对应的如下LLM配置的名称： +建议：在配置文件中将 `LLM` 设置为 `DifyLLM`，并通过 `Dify` 编排智能体来实现相关控制。 -``` -LLM: - AliLLM: - type: openai - ... - DeepSeekLLM: - type: openai - ... - ChatGLMLLM: - type: openai - ... - DifyLLM: - type: dify - ... -``` +### 3、我说话很慢，停顿时小智老是抢话 🗣️ -有些服务，比如如果你使用`Dify`、`豆包的TTS`，是需要密钥的，记得在配置文件加上哦！ - -### 5. 执行docker命令 - -打开命令行工具，`cd` 进入到你的`项目目录`，执行以下命令 - -``` -#如果你是linux，执行 -ls -#如果你是windows，执行 -dir -``` - -如果你能看到`config.yaml`文件，确确实实进入到了`项目目录`，接着执行以下命令： - -``` -docker run -d --name xiaozhi-esp32-server --restart always --security-opt seccomp:unconfined -p 8000:8000 -v $(pwd)/config.yaml:/opt/xiaozhi-esp32-server/config.yaml ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest -``` - -如果首次执行，可能需要几分钟时间，你要耐心等待他完成拉取。正常拉取完成后，你可以在命令行执行以下命令查看服务是否启动成功 - -``` -docker ps -``` - -如果你能看到`xiaozhi-server`，说明服务启动成功。那你还可以进一步执行以下命令，查看服务的日志 - -``` -docker logs -f xiaozhi-esp32-server -``` - -如果你能看到，类似以下日志,则是本项目服务启动成功的标志。 - -``` -2025-xx-xx xx:51:59,492 - core.server - INFO - Server is running at ws://xx.xx.xx.xxx:8000 -2025-xx-xx xx:51:59,516 - websockets.server - INFO - server listening on 0.0.0.0:8000 -``` - -接下来，你就可以开始 `编译esp32固件`了，请往下翻，翻到编译`esp32固件`相关章节。那么由于你是用docker部署，你要自己查看自己本机电脑的ip是多少。 -正常来说，假设你的ip是`192.168.1.25`，那么你的接口地址就是：`ws://192.168.1.25:8000`。这个信息很有用的，后面`编译esp32固件` -需要用到。 - -请注意，你的接口地址是`websocket`协议的地址，你可以使用`apifox`等工具调试。但是不能直接用浏览器打开访问，如果用浏览器打开，日志会显示错误，会让你怀疑是否部署成功了。 - -后期如果想升级版本，可以这么操作 - -1、备份好`config.yaml`文件，一些关键的配置到时复制到新的`config.yaml`文件里。 - -2、执行以下命令 - -``` -docker stop xiaozhi-esp32-server -docker rm xiaozhi-esp32-server -docker rmi ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest -``` - -3.按本教程重新来一遍 - -## 方式二：借助docker环境运行部署 - -这个方法的原理，其实是和第一种方式类似。区别在于，第一种方式只要下载一个配置文件，而本方式要下载项目源码。 - -优点就是源码在你主机躺着，你可以使用本机的代码编辑器加载项目和修改源码。每次修改完项目，想要看效果，那就要重启docker。 - -缺点就要下载本项目的代码，还要下载模型文件，如果这个项目不常用，确实会占用您电脑的空间。 - -你先要下载本项目源码，源码可以通过`git clone`命令下载，如果你不熟悉`git clone`命令。 - -你可以用浏览器打开这个地址`https://github.com/xinnan-tech/xiaozhi-esp32-server.git` - -打开完，找到页面中一个绿色的按钮，写着`Code`的按钮，点开它，然后你就看到`Download ZIP`的按钮。 - -点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫`xiaozhi-esp32-server-main` -你需要把它重命名成`xiaozhi-esp32-server`，好了请记住这个目录，我们暂且称它为`项目目录`。 - -下载源码后，需要下载模型文件。 默认使用`SenseVoiceSmall`模型，进行语音转文字。因为模型较大，需要独立下载，下载后把`model.pt` -文件放在`model/SenseVoiceSmall` -目录下。下面两个下载路线任选一个。 - -- 线路一：阿里魔塔下载[SenseVoiceSmall](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt) -- 线路二：百度网盘下载[SenseVoiceSmall](https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg&pwd=qvna) 提取码: - `qvna` - -下载模型后，需要按照`方式一：docker快速部署`修改配置文件`config.yaml` - -修改完配置后，打开命令行工具，`cd`进入到你的项目目录下，执行以下命令 - -``` -docker run -d --name xiaozhi-esp32-server --restart always --security-opt seccomp:unconfined \ - -p 8000:8000 \ - -v $(pwd):/opt/xiaozhi-esp32-server \ - ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest -``` - -``` -docker logs -f xiaozhi-esp32-server -``` - -如果你能看到，类似以下日志,则是本项目服务启动成功的标志。 - -``` -2025-xx-xx xx:51:59,492 - core.server - INFO - Server is running at ws://xx.xx.xx.xxx:8000 -2025-xx-xx xx:51:59,516 - websockets.server - INFO - server listening on 0.0.0.0:8000 -``` - -接下来，你就可以开始 `编译esp32固件`了，请往下翻，翻到编译`esp32固件`相关章节。那么由于你是用docker部署，你要自己查看自己本机电脑的ip是多少。 -正常来说，假设你的ip是`192.168.1.25`，那么你的接口地址就是：`ws://192.168.1.25:8000`。这个信息很有用的，后面`编译esp32固件` -需要用到。 - -请注意，你的接口地址是`websocket`协议的地址，你可以使用`apifox`等工具调试。但是不能直接用浏览器打开访问，如果用浏览器打开，日志会显示错误，会让你怀疑是否部署成功了。 - -后期，如果你修改了代码，想让新代码跑起来，可以用以下命令让docker容器重启： - -``` -docker restart xiaozhi-esp32-server -# 查看日志输出 -docker logs -f xiaozhi-esp32-server -``` - -## 方式三：本地源码运行 - -### 1.安装基础环境 - -本项目使用`conda`管理依赖环境，安装好后，开始执行以下命令。 - -``` -conda remove -n xiaozhi-esp32-server --all -y -conda create -n xiaozhi-esp32-server python=3.10 -y -conda activate xiaozhi-esp32-server -``` - -执行以上命令后， 如果你的电脑是Windows或Mac，执行下面的语句： - -``` -conda activate xiaozhi-esp32-server -conda install conda-forge::libopus -conda install conda-forge::ffmpeg -``` - -如果你的电脑是ubuntu，执行下面的语句： - -``` -apt-get install libopus0 ffmpeg -``` - -### 2.安装本项目依赖 - -你先要下载本项目源码，源码可以通过`git clone`命令下载，如果你不熟悉`git clone`命令。 - -你可以用浏览器打开这个地址`https://github.com/xinnan-tech/xiaozhi-esp32-server.git` - -打开完，找到页面中一个绿色的按钮，写着`Code`的按钮，点开它，然后你就看到`Download ZIP`的按钮。 - -点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫`xiaozhi-esp32-server-main` -你需要把它重命名成`xiaozhi-esp32-server`，好了请记住这个目录，我们暂且称它为`项目目录`。 - -``` -# 使用dos或者终端，进入到你的项目目录，执行以下命令 -conda activate xiaozhi-esp32-server -pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ -pip install -r requirements.txt -``` - -### 3.下载语音识别模型 - -默认使用`SenseVoiceSmall`模型，进行语音转文字。因为模型较大，需要独立下载，下载后把`model.pt`文件放在`model/SenseVoiceSmall` -目录下。下面两个下载路线任选一个。 - -- 线路一：阿里魔塔下载[SenseVoiceSmall](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt) -- 线路二：百度网盘下载[SenseVoiceSmall](https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg&pwd=qvna) 提取码: - `qvna` - -### 4.配置项目 - -修改`config.yaml`文件，配置本项目所需的各种参数。默认的LLM使用的是`ChatGLMLLM` -，你需要配置密钥，因为他们的模型，虽然有免费的，但是仍要去[官网](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)注册密钥，才能启动。 -默认的TTS使用的是`EdgeTTS`，这个无需配置，如果你需要更换成`豆包TTS`，则需要配置密钥。 - -``` -# 如果您是一名开发者，建议阅读以下内容。如果不是开发者，可以忽略这部分内容。 -# 在开发中，在项目根目录创建data目录，将【config.yaml】复制一份，改成【.config.yaml】，放进data目录中 -# 系统会优先读取【data/.config.yaml】文件的配置。 -# 这样做，可以避免在提交代码的时候，错误地提交密钥信息，保护您的密钥安全。 -``` - -配置说明：这里是各个功能使用的默认组件，例如LLM默认使用`ChatGLMLLM`模型。如果需要切换模型，就是改对应的名称。 - -本项目的默认配置仅是成本最低配置（`glm-4-flash`和`EdgeTTS`都是免费的），如果需要更优的更快的搭配，需要自己结合部署环境切换各组件的使用。 - -``` -selected_module: - ASR: FunASR - VAD: SileroVAD - LLM: ChatGLMLLM - TTS: EdgeTTS -``` - -比如修改`LLM`使用的组件，就看本项目支持哪些`LLM` API接口，当前支持的是`openai`、`dify`。欢迎验证和支持更多LLM平台的接口。 -使用时，在`selected_module`修改成对应的如下LLM配置的名称： - -``` -LLM: - DeepSeekLLM: - type: openai - ... - ChatGLMLLM: - type: openai - ... - DifyLLM: - type: dify - ... -``` - -有些服务，比如如果你使用`Dify`、`豆包的TTS`，是需要密钥的，记得在配置文件加上哦！ - -### 5.运行项目 - -启动项目 - -``` -# 确保在本项目的根目录下执行 -conda activate xiaozhi-esp32-server -python app.py -``` - -启动后，会看到类似以下日志 - -``` -2025-xx-xx xx:51:59,492 - core.server - INFO - Server is running at ws://192.168.1.25:8000 -2025-xx-xx xx:51:59,516 - websockets.server - INFO - server listening on 0.0.0.0:8000 -``` - -其中上面的`ws://192.168.1.25:8000`就是本项目提供的接口地址了，当然你自己的机器和我的是不一样的，记得要找到自己的地址。 - -请注意，你的接口地址是`websocket`协议的地址，你可以使用`apifox`等工具调试。但是不能直接用浏览器打开访问，如果用浏览器打开，日志会显示错误，会让你怀疑是否部署成功了。 - -# 编译esp32固件 - -1. 下载`xiaozhi-esp32` - 项目，按照这个教程配置项目环境[《Windows搭建 ESP IDF 5.3.2开发环境以及编译小智》](https://icnynnzcwou8.feishu.cn/wiki/JEYDwTTALi5s2zkGlFGcDiRknXf) - -2. 打开`xiaozhi-esp32/main/Kconfig.projbuild`文件，找到`WEBSOCKET_URL`的`default`的内容，把`wss://api.tenclass.net` - 改成你自己的地址，例如，我的接口地址是`ws://192.168.1.25:8000`，就把内容改成这个。 - -修改前： - -``` -config WEBSOCKET_URL - depends on CONNECTION_TYPE_WEBSOCKET - string "Websocket URL" - default "wss://api.tenclass.net/xiaozhi/v1/" - help - Communication with the server through websocket after wake up. -``` - -修改后(示例)： - -``` -config WEBSOCKET_URL - depends on CONNECTION_TYPE_WEBSOCKET - string "Websocket URL" - default "ws://192.168.1.25:8000/xiaozhi/v1/" - help - Communication with the server through websocket after wake up. -``` - -注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。 - -注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。 - -注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。 - -3. 设置编译参数 - -``` -# 终端命令行进入xiaozhi-esp32的根目录 -cd xiaozhi-esp32 -# 例如我使用的板子是esp32s3，所以设置编译目标为esp32s3，如果你的板子是其他型号，请替换成对应的型号 -idf.py set-target esp32s3 -# 进入菜单配置 -idf.py menuconfig -``` - -![图片](docs/images/build_setting01.png) - -进入菜单配置后，再进入`Xiaozhi Assistant`，将`CONNECTION_TYPE`设置为`Websocket` -回退到主菜单，再进入`Xiaozhi Assistant`，将`BOARD_TYPE`设置你板子的具体型号 -保存退出，回到终端命令行。 - -![图片](docs/images/build_setting02.png) - -4. 编译固件 - -``` -idf.py build -``` - -5. 打包bin固件 - -``` -cd scripts -python release.py -``` - -编译成功后，会在项目根目录下的`build`目录下生成固件文件`merged-binary.bin`。 -这个`merged-binary.bin`就是要烧录到硬件上的固件文件。 - -注意：如果执行到第二命令后，报了“zip”相关的错误，请忽略这个错误，只要`build`目录下生成固件文件`merged-binary.bin` -，对你没有太大影响，请继续。 - -6. 烧录固件 - 将esp32设备连接电脑，使用chrome浏览器，打开以下网址 - -``` -https://espressif.github.io/esp-launchpad/ -``` - -打开这个教程，[Flash工具/Web端烧录固件（无IDF开发环境）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS)。 -翻到：`方式二：ESP-Launchpad 浏览器WEB端烧录`，从`3. 烧录固件/下载到开发板`开始，按照教程操作。 - -# 常见问题 - -## 1、TTS 经常失败，经常超时 - -建议：如果`EdgeTTS`经常失败，先检查一下是否用了梯子，如果用了梯子，请把梯子关了试试。 -如果用的是`火山引擎的豆包TTS`经常失败，最好使用付费版本，因为他们的测试版本只有2个并发。 - -## 2、我想通过小智控制电灯、空调、远程开关机等操作。 - -建议：在配置文件里，将`LLM`设置成`DifyLLM`，然后通过`Dify`编排智能体实现。 - -## 3、我说话很慢，我停顿一下，小智老是抢我的话，咋办。 - -建议：在配置文件里，找到这一段，将`min_silence_duration_ms`值改大一点，比如改成`1000`。 - -``` +建议：在配置文件中找到如下部分，将 `min_silence_duration_ms` 的值调大（例如改为 `1000`）： +```yaml VAD: SileroVAD: threshold: 0.5 model_dir: models/snakers4_silero-vad - min_silence_duration_ms: 700 # 如果说话停顿比较长，可以把这个值设置大一些 + min_silence_duration_ms: 700 # 如果说话停顿较长，可将此值调大 ``` -## 4、如何才能提高小智对话响应速度？ +### 4、如何提高小智对话响应速度？ ⚡ -本项目的默认配置，是成本最低的配置。建议刚上手的童鞋，使用默认的免费模型，先解决了“跑得动”的问题，再解决“跑得快”的问题。 -如果要提高响应速度，需要更换各组件来解决。以下是本项目各组件的响应速度测试Tip。 +本项目默认配置为低成本方案，建议初学者先使用默认免费模型，解决“跑得动”的问题，再优化“跑得快”。 +如需提升响应速度，可尝试更换各组件。以下为各组件的响应速度测试数据（仅供参考，不构成承诺）： -以下内容和结论仅供参考，不构成任何形式的承诺或保证。 - -### LLM 类组件 +#### LLM 类组件 | 排名 | 组件名称 | 响应速度(ms) | -|:---|:------------|:--------:| -| 1 | AliLLM | 630 | -| 2 | ChatGLMLLM | 2000 | -| 3 | DeepSeekLLM | 6800 | +|:---:|:---------------:|:------------:| +| 1 | AliLLM | 630 | +| 2 | ChatGLMLLM | 2000 | +| 3 | DeepSeekLLM | 6800 | ``` 测试地点：广东省佛山市禅城区 测试时间：2025年2月9日 16:12 宽带运营商：中国移动 -测试方法：更换配置后，执行core/utils/llm.py文件 +测试方法：更换配置后，执行 core/utils/llm.py 文件 ``` -### TTS 类组件 +#### TTS 类组件 | 排名 | 组件名称 | 响应速度(ms) | -|:---|:----------|:--------:| -| 1 | DoubaoTTS | 645 | -| 2 | EdgeTTS | 1019 | +|:---:|:--------------:|:------------:| +| 1 | DoubaoTTS | 645 | +| 2 | EdgeTTS | 1019 | ``` 测试地点：广东省佛山市禅城区 测试时间：2025年2月9日 16:12 宽带运营商：中国移动 -测试方法：更换配置后，执行core/utils/tts.py文件 - +测试方法：更换配置后，执行 core/utils/tts.py 文件 ``` -### 结论 +### 结论 🔍 `2025年2月9日`，如果我的电脑在`广东省佛山市禅城区`，且使用的是`中国移动`网络，我会优先使用： - LLM：`AliLLM` - TTS：`DoubaoTTS` -## 5、更多问题，可联系我们反馈 +### 5、更多问题，可联系我们反馈 💬 ![图片](docs/images/wechat.jpg) -# 鸣谢 +--- -- 本项目受[百聆语音对话机器人](https://github.com/wwbin2017/bailing)项目启发，基于该项目的基础思路完成实现。 -- 感谢[腾讯云](https://cloud.tencent.com/)为本次项目提供免费docker镜像空间。 -- 感谢[十方融海](https://www.tenclass.com/)在小智通讯协议上提供充分的文档支持。 +## 鸣谢 🙏 + +- 本项目受 [百聆语音对话机器人](https://github.com/wwbin2017/bailing) 启发，并在其基础上实现。 +- 感谢 [腾讯云](https://cloud.tencent.com/) 提供免费 Docker 镜像空间。 +- 感谢 [十方融海](https://www.tenclass.com/) 对小智通讯协议提供的详尽文档支持。 diff --git a/docs/Deployment.md b/docs/Deployment.md new file mode 100644 index 00000000..63911b71 --- /dev/null +++ b/docs/Deployment.md @@ -0,0 +1,293 @@ +# 方式一：docker快速部署 + +docker镜像已支持x86架构、arm64架构的CPU，支持在国产操作系统上运行。 + +## 1. 安装docker + +如果您的电脑还没安装docker，可以按照这里的教程安装：[docker安装](https://www.runoob.com/docker/ubuntu-docker-install.html) + +## 2. 创建目录 + +安装完后，你需要为这个项目找一个安放配置文件的目录，我们暂且称它为`项目目录`，这个目录最好是一个新建的空的目录。 + +## 3. 下载配置文件 + +用浏览器打开[这个链接](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/config.yaml)。 + +在页面的右侧找到名称为`RAW`按钮，在`RAW`按钮的旁边，找到下载的图标，点击下载按钮，下载`config.yaml`文件。 把文件下载到你的 +`项目目录`。 + +## 4. 修改配置文件 + +修改刚才你下载的`config.yaml`文件，配置本项目所需的各种参数。默认的LLM使用的是`ChatGLMLLM` +，你需要配置密钥，因为他们的模型，虽然有免费的，但是仍要去[官网](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)注册密钥，才能启动。 + +默认的TTS使用的是`EdgeTTS`，这个无需配置，如果你需要更换成`豆包TTS`，则需要配置密钥。 + +配置说明：这里是各个功能使用的默认组件，例如LLM默认使用`ChatGLMLLM`模型。如果需要切换模型，就是改对应的名称。 + +本项目的默认配置原则是成本最低配置原则（`glm-4-flash`和`EdgeTTS`都是免费的），如果需要更优的更快的搭配，需要自己结合部署环境切换各组件的使用。 + +``` +selected_module: + ASR: FunASR + VAD: SileroVAD + LLM: ChatGLMLLM + TTS: EdgeTTS +``` + +比如修改`LLM`使用的组件，就看本项目支持哪些`LLM` API接口，当前支持的是`openai`、`dify`。欢迎验证和支持更多LLM平台的接口。 + +使用时，在`selected_module`修改成对应的如下LLM配置的名称： + +``` +LLM: + AliLLM: + type: openai + ... + DeepSeekLLM: + type: openai + ... + ChatGLMLLM: + type: openai + ... + DifyLLM: + type: dify + ... +``` + +有些服务，比如如果你使用`Dify`、`豆包的TTS`，是需要密钥的，记得在配置文件加上哦！ + +## 5. 执行docker命令 + +打开命令行工具，`cd` 进入到你的`项目目录`，执行以下命令 + +``` +#如果你是linux，执行 +ls +#如果你是windows，执行 +dir +``` + +如果你能看到`config.yaml`文件，确确实实进入到了`项目目录`，接着执行以下命令： + +``` +docker run -d --name xiaozhi-esp32-server --restart always --security-opt seccomp:unconfined -p 8000:8000 -v $(pwd)/config.yaml:/opt/xiaozhi-esp32-server/config.yaml ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest +``` + +如果首次执行，可能需要几分钟时间，你要耐心等待他完成拉取。正常拉取完成后，你可以在命令行执行以下命令查看服务是否启动成功 + +``` +docker ps +``` + +如果你能看到`xiaozhi-server`，说明服务启动成功。那你还可以进一步执行以下命令，查看服务的日志 + +``` +docker logs -f xiaozhi-esp32-server +``` + +如果你能看到，类似以下日志,则是本项目服务启动成功的标志。 + +``` +2025-xx-xx xx:51:59,492 - core.server - INFO - Server is running at ws://xx.xx.xx.xxx:8000 +2025-xx-xx xx:51:59,516 - websockets.server - INFO - server listening on 0.0.0.0:8000 +``` + +接下来，你就可以开始 `编译esp32固件`了，请往下翻，翻到编译`esp32固件`相关章节。那么由于你是用docker部署，你要自己查看自己本机电脑的ip是多少。 +正常来说，假设你的ip是`192.168.1.25`，那么你的接口地址就是：`ws://192.168.1.25:8000`。这个信息很有用的，后面`编译esp32固件` +需要用到。 + +请注意，你的接口地址是`websocket`协议的地址，你可以使用`apifox`等工具调试。但是不能直接用浏览器打开访问，如果用浏览器打开，日志会显示错误，会让你怀疑是否部署成功了。 + +后期如果想升级版本，可以这么操作 + +1、备份好`config.yaml`文件，一些关键的配置到时复制到新的`config.yaml`文件里。 + +2、执行以下命令 + +``` +docker stop xiaozhi-esp32-server +docker rm xiaozhi-esp32-server +docker rmi ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest +``` + +3.按本教程重新来一遍 + +# 方式二：借助docker环境运行部署 + +这个方法的原理，其实是和第一种方式类似。区别在于，第一种方式只要下载一个配置文件，而本方式要下载项目源码。 + +优点就是源码在你主机躺着，你可以使用本机的代码编辑器加载项目和修改源码。每次修改完项目，想要看效果，那就要重启docker。 + +缺点就要下载本项目的代码，还要下载模型文件，如果这个项目不常用，确实会占用您电脑的空间。 + +你先要下载本项目源码，源码可以通过`git clone`命令下载，如果你不熟悉`git clone`命令。 + +你可以用浏览器打开这个地址`https://github.com/xinnan-tech/xiaozhi-esp32-server.git` + +打开完，找到页面中一个绿色的按钮，写着`Code`的按钮，点开它，然后你就看到`Download ZIP`的按钮。 + +点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫`xiaozhi-esp32-server-main` +你需要把它重命名成`xiaozhi-esp32-server`，好了请记住这个目录，我们暂且称它为`项目目录`。 + +下载源码后，需要下载模型文件。 默认使用`SenseVoiceSmall`模型，进行语音转文字。因为模型较大，需要独立下载，下载后把`model.pt` +文件放在`model/SenseVoiceSmall` +目录下。下面两个下载路线任选一个。 + +- 线路一：阿里魔塔下载[SenseVoiceSmall](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt) +- 线路二：百度网盘下载[SenseVoiceSmall](https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg&pwd=qvna) 提取码: + `qvna` + +下载模型后，需要按照`方式一：docker快速部署`修改配置文件`config.yaml` + +修改完配置后，打开命令行工具，`cd`进入到你的项目目录下，执行以下命令 + +``` +docker run -d --name xiaozhi-esp32-server --restart always --security-opt seccomp:unconfined \ + -p 8000:8000 \ + -v ./:/opt/xiaozhi-esp32-server \ + ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest +``` + +``` +docker logs -f xiaozhi-esp32-server +``` + +如果你能看到，类似以下日志,则是本项目服务启动成功的标志。 + +``` +2025-xx-xx xx:51:59,492 - core.server - INFO - Server is running at ws://xx.xx.xx.xxx:8000 +2025-xx-xx xx:51:59,516 - websockets.server - INFO - server listening on 0.0.0.0:8000 +``` + +接下来，你就可以开始 `编译esp32固件`了，请往下翻，翻到编译`esp32固件`相关章节。那么由于你是用docker部署，你要自己查看自己本机电脑的ip是多少。 +正常来说，假设你的ip是`192.168.1.25`，那么你的接口地址就是：`ws://192.168.1.25:8000`。这个信息很有用的，后面`编译esp32固件` +需要用到。 + +请注意，你的接口地址是`websocket`协议的地址，你可以使用`apifox`等工具调试。但是不能直接用浏览器打开访问，如果用浏览器打开，日志会显示错误，会让你怀疑是否部署成功了。 + +后期，如果你修改了代码，想让新代码跑起来，可以用以下命令让docker容器重启： + +``` +docker restart xiaozhi-esp32-server +# 查看日志输出 +docker logs -f xiaozhi-esp32-server +``` + +# 方式三：本地源码运行 + +## 1.安装基础环境 + +本项目使用`conda`管理依赖环境，安装好后，开始执行以下命令。 + +``` +conda remove -n xiaozhi-esp32-server --all -y +conda create -n xiaozhi-esp32-server python=3.10 -y +conda activate xiaozhi-esp32-server +``` + +执行以上命令后， 如果你的电脑是Windows或Mac，执行下面的语句： + +``` +conda activate xiaozhi-esp32-server +conda install conda-forge::libopus +conda install conda-forge::ffmpeg +``` + +如果你的电脑是ubuntu，执行下面的语句： + +``` +apt-get install libopus0 ffmpeg +``` + +## 2.安装本项目依赖 + +你先要下载本项目源码，源码可以通过`git clone`命令下载，如果你不熟悉`git clone`命令。 + +你可以用浏览器打开这个地址`https://github.com/xinnan-tech/xiaozhi-esp32-server.git` + +打开完，找到页面中一个绿色的按钮，写着`Code`的按钮，点开它，然后你就看到`Download ZIP`的按钮。 + +点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫`xiaozhi-esp32-server-main` +你需要把它重命名成`xiaozhi-esp32-server`，好了请记住这个目录，我们暂且称它为`项目目录`。 + +``` +# 使用dos或者终端，进入到你的项目目录，执行以下命令 +conda activate xiaozhi-esp32-server +pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ +pip install -r requirements.txt +``` + +## 3.下载语音识别模型 + +默认使用`SenseVoiceSmall`模型，进行语音转文字。因为模型较大，需要独立下载，下载后把`model.pt`文件放在`model/SenseVoiceSmall` +目录下。下面两个下载路线任选一个。 + +- 线路一：阿里魔塔下载[SenseVoiceSmall](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt) +- 线路二：百度网盘下载[SenseVoiceSmall](https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg&pwd=qvna) 提取码: + `qvna` + +## 4.配置项目 + +修改`config.yaml`文件，配置本项目所需的各种参数。默认的LLM使用的是`ChatGLMLLM` +，你需要配置密钥，因为他们的模型，虽然有免费的，但是仍要去[官网](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)注册密钥，才能启动。 +默认的TTS使用的是`EdgeTTS`，这个无需配置，如果你需要更换成`豆包TTS`，则需要配置密钥。 + +``` +# 如果您是一名开发者，建议阅读以下内容。如果不是开发者，可以忽略这部分内容。 +# 在开发中，在项目根目录创建data目录，将【config.yaml】复制一份，改成【.config.yaml】，放进data目录中 +# 系统会优先读取【data/.config.yaml】文件的配置。 +# 这样做，可以避免在提交代码的时候，错误地提交密钥信息，保护您的密钥安全。 +``` + +配置说明：这里是各个功能使用的默认组件，例如LLM默认使用`ChatGLMLLM`模型。如果需要切换模型，就是改对应的名称。 + +本项目的默认配置仅是成本最低配置（`glm-4-flash`和`EdgeTTS`都是免费的），如果需要更优的更快的搭配，需要自己结合部署环境切换各组件的使用。 + +``` +selected_module: + ASR: FunASR + VAD: SileroVAD + LLM: ChatGLMLLM + TTS: EdgeTTS +``` + +比如修改`LLM`使用的组件，就看本项目支持哪些`LLM` API接口，当前支持的是`openai`、`dify`。欢迎验证和支持更多LLM平台的接口。 +使用时，在`selected_module`修改成对应的如下LLM配置的名称： + +``` +LLM: + DeepSeekLLM: + type: openai + ... + ChatGLMLLM: + type: openai + ... + DifyLLM: + type: dify + ... +``` + +有些服务，比如如果你使用`Dify`、`豆包的TTS`，是需要密钥的，记得在配置文件加上哦！ + +## 5.运行项目 + +启动项目 + +``` +# 确保在本项目的根目录下执行 +conda activate xiaozhi-esp32-server +python app.py +``` + +启动后，会看到类似以下日志 + +``` +2025-xx-xx xx:51:59,492 - core.server - INFO - Server is running at ws://192.168.1.25:8000 +2025-xx-xx xx:51:59,516 - websockets.server - INFO - server listening on 0.0.0.0:8000 +``` + +其中上面的`ws://192.168.1.25:8000`就是本项目提供的接口地址了，当然你自己的机器和我的是不一样的，记得要找到自己的地址。 + +请注意，你的接口地址是`websocket`协议的地址，你可以使用`apifox`等工具调试。但是不能直接用浏览器打开访问，如果用浏览器打开，日志会显示错误，会让你怀疑是否部署成功了。 \ No newline at end of file diff --git a/docs/firmware-build.md b/docs/firmware-build.md new file mode 100644 index 00000000..731372b7 --- /dev/null +++ b/docs/firmware-build.md @@ -0,0 +1,83 @@ +# 编译esp32固件 + +1. 下载`xiaozhi-esp32` + 项目，按照这个教程配置项目环境[《Windows搭建 ESP IDF 5.3.2开发环境以及编译小智》](https://icnynnzcwou8.feishu.cn/wiki/JEYDwTTALi5s2zkGlFGcDiRknXf) + +2. 打开`xiaozhi-esp32/main/Kconfig.projbuild`文件，找到`WEBSOCKET_URL`的`default`的内容，把`wss://api.tenclass.net` + 改成你自己的地址，例如，我的接口地址是`ws://192.168.1.25:8000`，就把内容改成这个。 + +修改前： + +``` +config WEBSOCKET_URL + depends on CONNECTION_TYPE_WEBSOCKET + string "Websocket URL" + default "wss://api.tenclass.net/xiaozhi/v1/" + help + Communication with the server through websocket after wake up. +``` + +修改后(示例)： + +``` +config WEBSOCKET_URL + depends on CONNECTION_TYPE_WEBSOCKET + string "Websocket URL" + default "ws://192.168.1.25:8000/xiaozhi/v1/" + help + Communication with the server through websocket after wake up. +``` + +注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。 + +注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。 + +注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。 + +3. 设置编译参数 + +``` +# 终端命令行进入xiaozhi-esp32的根目录 +cd xiaozhi-esp32 +# 例如我使用的板子是esp32s3，所以设置编译目标为esp32s3，如果你的板子是其他型号，请替换成对应的型号 +idf.py set-target esp32s3 +# 进入菜单配置 +idf.py menuconfig +``` + +![图片](images/build_setting01.png) + +进入菜单配置后，再进入`Xiaozhi Assistant`，将`CONNECTION_TYPE`设置为`Websocket` +回退到主菜单，再进入`Xiaozhi Assistant`，将`BOARD_TYPE`设置你板子的具体型号 +保存退出，回到终端命令行。 + +![图片](images/build_setting02.png) + +4. 编译固件 + +``` +idf.py build +``` + +5. 打包bin固件 + +``` +cd scripts +python release.py +``` + +编译成功后，会在项目根目录下的`build`目录下生成固件文件`merged-binary.bin`。 +这个`merged-binary.bin`就是要烧录到硬件上的固件文件。 + +注意：如果执行到第二命令后，报了“zip”相关的错误，请忽略这个错误，只要`build`目录下生成固件文件`merged-binary.bin` +，对你没有太大影响，请继续。 + +6. 烧录固件 + 将esp32设备连接电脑，使用chrome浏览器，打开以下网址 + +``` +https://espressif.github.io/esp-launchpad/ +``` + +打开这个教程，[Flash工具/Web端烧录固件（无IDF开发环境）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS)。 +翻到：`方式二：ESP-Launchpad 浏览器WEB端烧录`，从`3. 烧录固件/下载到开发板`开始，按照教程操作。