From 46ff69d923af04a4505c415cc65e7d976c0df77c Mon Sep 17 00:00:00 2001 From: WJG Date: Mon, 10 Jun 2024 16:39:34 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E9=87=8D=E6=9E=84=20docs=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=9B=AE=E5=BD=95=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 222 +++--------------------------- CHANGELOG.md => docs/changelog.md | 32 +++-- docs/development.md | 3 + docs/faq.md | 129 +++++++++++++++++ docs/how-it-works.md | 3 + docs/roadmap.md | 32 +++++ docs/settings.md | 59 ++++++++ TODO.md => docs/todo.md | 53 +++---- 8 files changed, 284 insertions(+), 249 deletions(-) rename CHANGELOG.md => docs/changelog.md (90%) create mode 100644 docs/development.md create mode 100644 docs/faq.md create mode 100644 docs/how-it-works.md create mode 100644 docs/roadmap.md create mode 100644 docs/settings.md rename TODO.md => docs/todo.md (57%) diff --git a/README.md b/README.md index 80d0e4b..12bf5cd 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ 而小爱音箱就像是你的智能家居专属管家，全心全意为你服务，释放智能家居的真正潜力。 -## ⚡️ 项目预览 +## 🔥 项目预览 👉 查看完整演示视频：【[整活！将小爱音箱接入 ChatGPT 和豆包，改造成你的专属语音助手～](https://www.bilibili.com/video/BV1N1421y7qn/?share_source=copy_web&vd_source=5d4e78ff2a0dc6a661baa65f479199c1)】 @@ -26,14 +26,14 @@ ## ✨ 项目亮点 -- **🎓 LLM 回答**。想象一下，你的小爱音箱变身聊天高手，可以使用 [ChatGPT](https://chat.openai.com) 等大模型来回答你的问题。 +- **🎓 AI 问答**。想象一下，当小爱音箱接入大模型后，上知天文，下知地理，从“人工智障”秒变学霸。 - **🎭 角色扮演**。一秒调教小爱，无论是成为你的完美伴侣，还是那个能听你倾诉心事的贴心闺蜜，都不在话下。 - **💬 流式响应**。爱情来得太快就像龙卷风，而你的小爱音箱也是，对你的爱意秒回，爱你不会让你等太久。 - **🧠 长短期记忆**。小爱音箱现在能记住你们之间的每一次对话，越聊越默契，就像是你身边的老朋友。 - **🔊 自定义 TTS**。厌倦了小爱同学的语音？帮你解锁[「豆包」](https://doubao.com)同款音色，就像真人在回你的消息。 - **🤖️ 智能家居 Agent**。心情不好？小爱立刻懂你，自动帮你播放喜欢的音乐，调节灯光，逗你开心。_TODO_ -## 🚀 启动项目 +## ⚡️ 快速开始 `MiGPT` 有两种启动方式: [Docker](#docker) 和 [Node.js](#nodejs)。 @@ -43,15 +43,13 @@ 对于电脑小白或者不想自己配置代码运行环境（Node）的同学，可以使用 Docker 启动方式。 -请先按照[「配置参数」](#%EF%B8%8F-配置参数)章节，配置好你的 `.env` 和 `.migpt.js` 文件，然后使用以下命令启动 docker： +请先按照 [⚙️ 参数设置](https://github.com/idootop/mi-gpt/blob/main/docs/settings.md) 相关说明，配置好你的 `.env` 和 `.migpt.js` 文件，然后使用以下命令启动 docker： ```shell -docker run -d --env-file $(pwd)/.env \ - -v $(pwd)/.migpt.js:/app/.migpt.js \ - idootop/mi-gpt:latest +docker run --env-file $(pwd)/.env -v $(pwd)/.migpt.js:/app/.migpt.js idootop/mi-gpt:latest ``` -注意：在 Windows 终端下不支持使用 `$(pwd)` 获取当前工作路径，需要将配置文件路径替换为绝对路径。 +注意：在 Windows 终端下需要将配置文件路径 `$(pwd)` 替换为绝对路径。 ### Node.js @@ -63,7 +61,7 @@ docker run -d --env-file $(pwd)/.env \ npm install mi-gpt # 安装依赖 ``` -然后，创建并启动 `MiGPT` 实例。初始化参数的具体含义请看下面的[「配置参数」](#%EF%B8%8F-配置参数)章节。 +然后，创建并启动 `MiGPT` 实例。初始化参数的具体说明请到 [⚙️ 参数设置](https://github.com/idootop/mi-gpt/blob/main/docs/settings.md) 查看。 ```typescript import { MiGPT } from "mi-gpt"; @@ -82,199 +80,20 @@ async function main() { main(); ``` -注意：此模式下并不会主动读取 `.env` 和 `.migpt.json` 中的配置信息，你需要自己初始化 Node 环境变量， +注意：此模式下并不会主动读取 `.env` 和 `.migpt.js` 中的配置信息，你需要手动初始化 Node 环境变量，并将 `.migpt.js` 中的参数作为 `MiGPT.create` 的初始化参数传入。👉 [示例代码](https://github.com/idootop/mi-gpt/blob/example/index.ts) -并将 `.migpt.json` 中的参数作为 `MiGPT.create` 的初始化参数传入。👉 [示例代码](https://github.com/idootop/mi-gpt/blob/example/index.ts) +## 📖 项目文档 -## ⚙️ 配置参数 +更多配置教程和使用说明，请参考下方文档。 -### .migpt.js +- [⚙️ 参数设置](https://github.com/idootop/mi-gpt/blob/main/docs/settings.md) +- [💬 常见问题](https://github.com/idootop/mi-gpt/blob/main/docs/faq.md) +- [🛠️ 本地开发](https://github.com/idootop/mi-gpt/blob/main/docs/development.md) +- [💎 工作原理](https://github.com/idootop/mi-gpt/blob/main/docs/how-it-works.md) +- [✨ 更新日志](https://github.com/idootop/mi-gpt/blob/main/docs/changelog.md) +- [🚀 Roadmap](https://github.com/idootop/mi-gpt/blob/main/docs/roadmap.md) -重命名本项目根目录下的 [.migpt.example.js](https://github.com/idootop/mi-gpt/blob/main/.migpt.example.js) 文件为 `.migpt.js`。 - -然后，将里面的配置参数修改成你自己的，参数含义如下： - -| 参数名称 | 描述 | 示例 | -| ---------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------- | -| **bot** | | | -| `name` | 对方名称（小爱音箱） | `"傻妞"` | -| `profile` | 对方的个人简介/人设 | `"性别女，性格乖巧可爱，喜欢搞怪，爱吃醋。"` | -| **master** | | | -| `name` | 主人名称（我自己） | `"陆小千"` | -| `profile` | 主人的个人简介/人设 | `"性别男，善良正直，总是舍己为人，是傻妞的主人。"` | -| **room** | | | -| `name` | 会话群名称 | `"魔幻手机"` | -| `description` | 会话群简介 | `"傻妞和陆小千的私聊"` | -| **speaker** | | | -| `userId` | [小米 ID](https://account.xiaomi.com/fe/service/account/profile)（注意：不是手机号或邮箱） | `"987654321"` | -| `password` | 账户密码 | `"123456"` | -| `did` | 小爱音箱 ID 或名称 | `"小爱音箱 Pro"` | -| `ttsCommand` | 小爱音箱 TTS 指令（[可在此查询](https://home.miot-spec.com)） | `[5, 1]` | -| `wakeUpCommand` | 小爱音箱唤醒指令（[可在此查询](https://home.miot-spec.com)） | `[5, 3]` | -| **speaker 其他参数（可选）** | -| `callAIKeywords` | 当消息以关键词开头时，会调用 AI 来响应用户消息 | `["请", "傻妞"]` | -| `wakeUpKeywords` | 当消息以关键词开头时，会进入 AI 唤醒状态 | `["召唤傻妞", "打开傻妞"]` | -| `exitKeywords` | 当消息以关键词开头时，会退出 AI 唤醒状态 | `["退出傻妞", "关闭傻妞"]` | -| `onEnterAI` | 进入 AI 模式的欢迎语 | `["你好，我是傻妞，很高兴认识你"]` | -| `onExitAI` | 退出 AI 模式的提示语 | `["傻妞已退出"]` | -| `onAIAsking` | AI 开始回答时的提示语 | `["让我先想想", "请稍等"]` | -| `onAIReplied` | AI 结束回答时的提示语 | `["我说完了", "还有其他问题吗"]` | -| `onAIError` | AI 回答异常时的提示语 | `["出错了，请稍后再试吧！"]` | -| `playingCommand` | 查询小爱音箱是否在播放中指令（[可在此查询](https://home.miot-spec.com)） | `[3, 1, 1]` | -| `streamResponse` | 是否启用流式响应（部分小爱音箱型号不支持查询播放状态，此时需要关闭流式响应） | `true` | -| `exitKeepAliveAfter` | 无响应一段时间后，多久自动退出唤醒模式（单位秒，默认 30 秒） | `30` | - -### 环境变量 - -重命名本项目根目录下的 [.env.example](https://github.com/idootop/mi-gpt/blob/main/.env.example) 文件为 `.env`。 - -然后，将里面的环境变量修改成你自己的，参数含义如下： - -| 环境变量名称 | 描述 | 示例 | -| ---------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ | -| **OpenAI** | | | -| `OPENAI_API_KEY` | OpenAI API 密钥 | `abc123` | -| `OPENAI_MODEL` | 使用的 OpenAI 模型 | `gpt-4o` | -| `OPENAI_BASE_URL` | 可选，OpenAI API BaseURL | `https://api.openai.com/v1` | -| `AZURE_OPENAI_API_KEY` | 可选，[Microsoft Azure OpenAI](https://www.npmjs.com/package/openai#microsoft-azure-openai) | `abc123` | -| **提示音效（可选）** | | | -| `AUDIO_SILENT` | 静音音频链接 | `"https://example.com/slient.wav"` | -| `AUDIO_BEEP` | 默认提示音链接 | `"https://example.com/beep.wav"` | -| `AUDIO_ACTIVE` | 唤醒提示音链接 | `"https://example.com/active.wav"` | -| `AUDIO_ERROR` | 出错提示音链接 | `"https://example.com/error.wav"` | -| **豆包 TTS（可选）** | | | -| `TTS_DOUBAO` | 豆包 TTS 接口 | `"https://example.com/tts.wav"` | -| `SPEAKERS_DOUBAO` | 豆包 TTS 音色列表接口 | `"https://example.com/tts-speakers"` | - -## 💬 常见问题 - -**Q：支持哪些型号的小爱音箱？** - -大部分型号的小爱音箱都支持，推荐小爱音箱 Pro（完美运行）。部分机型的 MioT 接口开放能力并不完整，比如小米音箱 Play 增强版（L05C），将会导致 `MiGPT` 部分功能异常，相关 [issue](https://github.com/idootop/mi-gpt/issues/14)。 - -**Q：除了 OpenAI 还支持哪些模型，如何设置？** - -理论上兼容 [OpenAI SDK](https://www.npmjs.com/package/openai) 的模型都支持，只需修改环境变量即可接入到 MiGPT。 - -比如：[通义千问](https://help.aliyun.com/zh/dashscope/developer-reference/compatibility-of-openai-with-dashscope/?spm=a2c4g.11186623.0.i1)、[零一万物](https://platform.01.ai/docs#making-an-api-request)、[Moonshot](https://platform.moonshot.cn/docs/api/chat)、[DeepSeek](https://platform.deepseek.com/api-docs/) 等，以 Moonshot 为例： - -```shell -OPENAI_BASE_URL=https://api.moonshot.cn/v1 -OPENAI_MODEL=moonshot-v1-8k -OPENAI_API_KEY=$MOONSHOT_API_KEY -``` - -**Q：什么是唤醒模式？** - -`唤醒模式` 类似于小爱技能，可能让你在跟小爱互动的时候，无需每句话都要以“小爱同学”开头唤醒。 - -关于唤醒模式的更多细节，请查看这里：https://github.com/idootop/mi-gpt/issues/28 - -**Q：提示登录小米账号失败，无法正常启动** - -1. **账号密码不正确**：小米 ID 并非手机号或邮箱，请在[「个人信息」-「小米 ID」](https://account.xiaomi.com/fe/service/account/profile)查看。 -2. **网络环境异常**：如果你是在海外服务器等，非中国大陆网络环境下登录小米账号，需要先同意小米的「个人数据跨境传输」协议，然后按照提示验证手机号或邮箱，等待大约 30 分钟之后即可正常登录。[👉 相关教程](https://github.com/idootop/mi-gpt/issues/22#issuecomment-2150535622) - -**Q：小爱音箱收到消息后，没有调用 AI 进行回复** - -`MiGPT` 收到消息默认不会调用 AI 进行回复，只会回复以唤醒词开头的消息，比如：“请问 xxx”、“你 xxx” 等，你也可以自定义唤醒词（`callAIKeywords`）列表。 - -**Q：小爱音箱没有播放 AI 的回答，但控制台有打印 AI 的回复** - -不同型号的小爱音箱 TTS 指令不同: [issues#5](https://github.com/idootop/mi-gpt/issues/5#issuecomment-2122881495) - -请到 查询具体指令，并修改配置文件中的 `ttsCommand` 参数。 - -
-👉 查看教程 - -![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/search.jpg) -![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/command.jpg) - -
- -**Q：小爱音箱没有读完整个句子，总是戛然而止** - -部分型号的小爱音箱不支持通过 Mina 获取设备播放状态，只能通过 MiOT 指令查询。 - -请到 查询具体指令，并修改配置文件中的 `playingCommand` 参数。 - -
-👉 查看教程 - -![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/playing.png) - -
- -如果修改参数后问题仍然存在，说明你的设备不支持通过开放接口查询播放状态（比如：小米音箱 Play 增强版），**此问题无解**。建议更换其他型号的小爱音箱（推荐小爱音箱 Pro），相关 [issue](https://github.com/idootop/mi-gpt/issues/14)。 - -或者你也可以关闭配置文件中的流式响应（streamResponse）选项，确保小爱能够回复完整的句子。不过需要注意的是，关闭流式响应后，唤醒模式等功能将会失效。 - -**Q: 为什么小爱音箱会在 AI 回答之前抢话？** - -与本项目的实现原理有关。本项目通过轮询小米接口获取最新的对话信息，当检测到小爱在回复的时候会通过播放静音音频等方式快速 mute 掉小爱原来的回复。 - -但是从小爱开始回复，到上报状态给小米服务云端，再到本项目通过小米云端接口轮训到这个状态变更，中间会有大约 1 -2 秒的延迟时间，无解。 - -这个问题，理论上需要通过刷机才能完美解决，可以参考下面的相关讨论： - -- https://github.com/yihong0618/xiaogpt/issues/515#issuecomment-2121602572 -- https://github.com/idootop/mi-gpt/issues/21#issuecomment-2147125219 - -**Q：启动 docker 提示 ERR_MODULE_NOT_FOUND，无法正常启动** - -在 Windows 终端（比如：PowerShell、cmd）下，无法使用 `$(pwd)` 获取当前工作目录绝对路径，需要填写 `.env` 和 `.migpt.js` 文件的绝对路径。相关 [issue](https://github.com/idootop/mi-gpt/issues/26#issuecomment-2151381521) - -
-👉 查看示例 - -请将下面的 `/绝对路径/` 替换为你当前目录的绝对路径： - -```shell -docker run -d --env-file /绝对路径/.env \ - -v /绝对路径/.migpt.js:/app/.migpt.js \ - idootop/mi-gpt:latest -``` - -Windows PowerShell 终端 - -```shell -docker run -d --env-file $pwd\.env ` - -v $pwd\.migpt.js:/app/.migpt.js ` - idootop/mi-gpt:latest -``` - -Windows cmd 终端 - -```shell -docker run -d --env-file %cd%\.env ^ - -v %cd%\.migpt.js:/app/.migpt.js ^ - idootop/mi-gpt:latest -``` - -
- -**Q：我 Clone 了这个仓库，但是本地启动失败** - -如果你是通过 clone 本项目仓库的方式来运行，记得在 `start` 之前先 `build` 一下。 - -```shell -pnpm install && pnpm build && pnpm start -``` - -另外， `start` 命令默认没有注入 `.env` 文件里的环境变量。你可以在 VS Code 里按 F5 直接运行，会自动读取 `.env` ，或者将启动脚本改为： - -```shell -node --env-file=.env app.js -``` - -**Q：怎样使用豆包的音色** - -此功能需要豆包 TTS 接口支持，本项目暂不对外提供此服务。 - -**Q：我还有其他问题** - -请在此处提交 [issue](https://github.com/idootop/mi-gpt/issues) 反馈，并提供详细的问题描述和相关错误截图。 +> 提示：大多数的问题都可以在「[💬 常见问题](https://github.com/idootop/mi-gpt/blob/main/docs/faq.md)」中找到答案。 ## 🚨 免责声明 @@ -285,6 +104,7 @@ node --env-file=.env app.js ## ❤️ 鸣谢 -- -- -- +- https://github.com/yihong0618/xiaogpt +- https://github.com/jialeicui/open-lx01 +- https://github.com/inu1255/mi-service +- https://github.com/Yonsm/MiService diff --git a/CHANGELOG.md b/docs/changelog.md similarity index 90% rename from CHANGELOG.md rename to docs/changelog.md index c27fe39..19c355a 100644 --- a/CHANGELOG.md +++ b/docs/changelog.md @@ -1,72 +1,74 @@ -# v3.0.1 +# ✨ 更新日志 + +## v 3.0.1 - 修复 README 配置参数表格样式 -# v3.0.0 +## v 3.0.0 -## ✨ 新功能 & 优化 +### ✨ 新功能 & 优化 - 新增 `streamResponse` 流式响应控制开关，确保小爱的回复是完整的句子（[issue#20](https://github.com/idootop/mi-gpt/issues/20)） - 添加其他 LLM 的配置教程（比如通义千问，moonshot 等）（[issue#11](https://github.com/idootop/mi-gpt/issues/11)） - 添加对支持小爱音箱型号的说明（[issue#14](https://github.com/idootop/mi-gpt/issues/14)） - 优化配置文件示例和使用教程（[issue#22](https://github.com/idootop/mi-gpt/issues/22)） -## 🐛 修复 +### 🐛 修复 - 修复 AI 响应异常时未播放提示语/音的问题 - 修复提示音链接为空时自动播放音乐的问题 -# v2.1.2 +## v 2.1.2 - 修复小爱回复无法被终止的问题（[issue#5](https://github.com/idootop/mi-gpt/issues/5)） -# v2.1.1 +## v 2.1.1 - 修复 DB 初始化失败的问题（[issue#17](https://github.com/idootop/mi-gpt/issues/17)） - 优化版本号读取方式（import 静态导入） -# v2.1.0 +## v 2.1.0 - 优化 Docker 镜像体积 - 新增 `playingCommand` 选项 - 修复小爱音箱回复戛然而止的问题（[issue#14](https://github.com/idootop/mi-gpt/issues/14)） -# v2.0.1 +## v 2.0.1 - 新增 ARMv7 Docker 镜像（[issue#15](https://github.com/idootop/mi-gpt/issues/15)） - 新增 debug 开关，用于调试（[issue#14](https://github.com/idootop/mi-gpt/issues/14)） -# v2.0.0 +## v 2.0.0 -## 🚨 Breaking changes +### 🚨 Breaking changes - `callAIPrefix` 更名为 `callAIKeywords` - `wakeUpKeywords`、`exitKeywords` 匹配规则由包含(includes)变更为起始(startsWith) -## ✨ 新功能 & 优化 +### ✨ 新功能 & 优化 - 支持 Microsoft Azure OpenAI（[#7](https://github.com/idootop/mi-gpt/issues/7)） - 新增 LLM 响应完毕提示语：onAIReplied - 优化 `.mi.example.js` 配置参数实例 - 优化唤醒模式下播放状态检测间隔，限制最低为 500 ms -## 🐛 修复 +### 🐛 修复 - 修复唤醒模式下 LLM 回复不发音或过短的问题（[#9](https://github.com/idootop/mi-gpt/issues/9)） - 修复部分场景下 LLM 返回数据格式异常的问题 - 修复唤醒词配置格式，使其与原始文档行为一致（[#8](https://github.com/idootop/mi-gpt/issues/8)） -# v1.2.0 +## v 1.2.0 - 新增小爱音箱 TTS 与唤醒指令选项 - 更新默认模型为 gpt-4o -# v1.1.0 +## v 1.1.0 - 新增 Arm64 Docker 镜像 - 替换 Yarn 包管理工具为 Pnpm -# v1.0.0 +## v 1.0.0 - 支持人物设定 - 支持连续对话 diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..10e6ec2 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,3 @@ +# 🛠️ 本地开发 + +整理中，稍后更新。 \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..2ac4166 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,129 @@ +# 💬 常见问题 + +### Q：支持哪些型号的小爱音箱？ + +大部分型号的小爱音箱都支持，推荐小爱音箱 Pro（完美运行）。部分机型的 MioT 接口开放能力并不完整，比如小米音箱 Play 增强版（L05C），将会导致 `MiGPT` 部分功能异常，相关 [issue](https://github.com/idootop/mi-gpt/issues/14)。 + +### Q：除了 OpenAI 还支持哪些模型，如何设置？ + +理论上兼容 [OpenAI SDK](https://www.npmjs.com/package/openai) 的模型都支持，只需修改环境变量即可接入到 MiGPT。 + +比如：[通义千问](https://help.aliyun.com/zh/dashscope/developer-reference/compatibility-of-openai-with-dashscope/?spm=a2c4g.11186623.0.i1)、[零一万物](https://platform.01.ai/docs#making-an-api-request)、[Moonshot](https://platform.moonshot.cn/docs/api/chat)、[DeepSeek](https://platform.deepseek.com/api-docs/) 等，以 Moonshot 为例： + +```shell +OPENAI_BASE_URL=https://api.moonshot.cn/v1 +OPENAI_MODEL=moonshot-v1-8k +OPENAI_API_KEY=$MOONSHOT_API_KEY +``` + +### Q：什么是唤醒模式？ + +`唤醒模式` 类似于小爱技能，可能让你在跟小爱互动的时候，无需每句话都要以“小爱同学”开头唤醒。 + +关于唤醒模式的更多细节，请查看这里：https://github.com/idootop/mi-gpt/issues/28 + +### Q：提示登录小米账号失败，无法正常启动 + +1. ## 账号密码不正确：小米 ID 并非手机号或邮箱，请在[「个人信息」-「小米 ID」](https://account.xiaomi.com/fe/service/account/profile)查看。 +2. ## 网络环境异常：如果你是在海外服务器等，非中国大陆网络环境下登录小米账号，需要先同意小米的「个人数据跨境传输」协议，然后按照提示验证手机号或邮箱，等待大约 30 分钟之后即可正常登录。[👉 相关教程](https://github.com/idootop/mi-gpt/issues/22#issuecomment-2150535622) + +### Q：小爱音箱收到消息后，没有调用 AI 进行回复 + +`MiGPT` 收到消息默认不会调用 AI 进行回复，只会回复以唤醒词开头的消息，比如：“请问 xxx”、“你 xxx” 等，你也可以自定义唤醒词（`callAIKeywords`）列表。 + +### Q：小爱音箱没有播放 AI 的回答，但控制台有打印 AI 的回复 + +不同型号的小爱音箱 TTS 指令不同: [issues#5](https://github.com/idootop/mi-gpt/issues/5#issuecomment-2122881495) + +请到 查询具体指令，并修改配置文件中的 `ttsCommand` 参数。 + +
+👉 查看教程 + +![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/search.jpg) +![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/command.jpg) + +
+ +### Q：小爱音箱没有读完整个句子，总是戛然而止 + +部分型号的小爱音箱不支持通过 Mina 获取设备播放状态，只能通过 MiOT 指令查询。 + +请到 查询具体指令，并修改配置文件中的 `playingCommand` 参数。 + +
+👉 查看教程 + +![](https://raw.githubusercontent.com/idootop/mi-gpt/main/assets/playing.png) + +
+ +如果修改参数后问题仍然存在，说明你的设备不支持通过开放接口查询播放状态（比如：小米音箱 Play 增强版），## 此问题无解。建议更换其他型号的小爱音箱（推荐小爱音箱 Pro），相关 [issue](https://github.com/idootop/mi-gpt/issues/14)。 + +或者你也可以关闭配置文件中的流式响应（streamResponse）选项，确保小爱能够回复完整的句子。不过需要注意的是，关闭流式响应后，唤醒模式等功能将会失效。 + +### Q: 为什么小爱音箱会在 AI 回答之前抢话？ + +与本项目的实现原理有关。本项目通过轮询小米接口获取最新的对话信息，当检测到小爱在回复的时候会通过播放静音音频等方式快速 mute 掉小爱原来的回复。 + +但是从小爱开始回复，到上报状态给小米服务云端，再到本项目通过小米云端接口轮训到这个状态变更，中间会有大约 1 -2 秒的延迟时间，无解。 + +这个问题，理论上需要通过刷机才能完美解决，可以参考下面的相关讨论： + +- https://github.com/yihong0618/xiaogpt/issues/515#issuecomment-2121602572 +- https://github.com/idootop/mi-gpt/issues/21#issuecomment-2147125219 + +### Q：启动 docker 提示 ERR_MODULE_NOT_FOUND，无法正常启动 + +在 Windows 终端（比如：PowerShell、cmd）下，无法使用 `$(pwd)` 获取当前工作目录绝对路径，需要填写 `.env` 和 `.migpt.js` 文件的绝对路径。相关 [issue](https://github.com/idootop/mi-gpt/issues/26#issuecomment-2151381521) + +
+👉 查看示例 + +请将下面的 `/绝对路径/` 替换为你当前目录的绝对路径： + +```shell +docker run -d --env-file /绝对路径/.env \ + -v /绝对路径/.migpt.js:/app/.migpt.js \ + idootop/mi-gpt:latest +``` + +Windows PowerShell 终端 + +```shell +docker run -d --env-file $pwd\.env ` + -v $pwd\.migpt.js:/app/.migpt.js ` + idootop/mi-gpt:latest +``` + +Windows cmd 终端 + +```shell +docker run -d --env-file %cd%\.env ^ + -v %cd%\.migpt.js:/app/.migpt.js ^ + idootop/mi-gpt:latest +``` + +
+ +### Q：我 Clone 了这个仓库，但是本地启动失败 + +如果你是通过 clone 本项目仓库的方式来运行，记得在 `start` 之前先 `build` 一下。 + +```shell +pnpm install && pnpm build && pnpm start +``` + +另外， `start` 命令默认没有注入 `.env` 文件里的环境变量。你可以在 VS Code 里按 F5 直接运行，会自动读取 `.env` ，或者将启动脚本改为： + +```shell +node --env-file=.env app.js +``` + +### Q：怎样使用豆包的音色 + +此功能需要豆包 TTS 接口支持，本项目暂不对外提供此服务。 + +### Q：我还有其他问题 + +请在此处提交 [issue](https://github.com/idootop/mi-gpt/issues) 反馈，并提供详细的问题描述和相关错误截图。 diff --git a/docs/how-it-works.md b/docs/how-it-works.md new file mode 100644 index 0000000..66e54f5 --- /dev/null +++ b/docs/how-it-works.md @@ -0,0 +1,3 @@ +# 💎 工作原理 + +整理中，稍后更新。 \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..6169649 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,32 @@ +# 🚀 Roadmap + +> 以下是一些可以优化的地方或新功能，仅作记录之用，暂时没有开发计划。 + +## 🐛 修复 + +- 【重要】自动刷新小米账号登录凭证 + - 小米账号登录凭证有效期 1 个月，到期后需要自动刷新（mi-service-lite） + +## 💪 优化 + +- 自动识别设备型号 + - 通过查询设备 miot spec 文件，自动获取指令参数 + - 自动识别设备属性值是否有读取权限 +- 添加镜像更新说明 + - 添加 db 文件导入/出教程，用于备份恢复对话历史记录 + +## ✨ 新功能 + +- 增强对话系统 + - 支持自定义对话系统 Prompt 模板 + - 添加是否启用对话模式的开关 + - 支持通过语音命令清除上下文 +- MioT AI Agents + - 支持小爱音箱控制米家设备 + - 通过 Agent 机制自动调用合适的工具（设备） +- RAG + - wikis embedding + - memory embedding +- 插件系统 + - 自定义语音指令 + - 联网查查询最新数据 diff --git a/docs/settings.md b/docs/settings.md new file mode 100644 index 0000000..243252d --- /dev/null +++ b/docs/settings.md @@ -0,0 +1,59 @@ +# ⚙️ 配置参数 + +## .migpt.js + +重命名本项目根目录下的 [.migpt.example.js](https://github.com/idootop/mi-gpt/blob/main/.migpt.example.js) 文件为 `.migpt.js`。 + +然后，将里面的配置参数修改成你自己的，参数含义如下： + +| 参数名称 | 描述 | 示例 | +| ---------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------- | +| **bot** | | | +| `name` | 对方名称（小爱音箱） | `"傻妞"` | +| `profile` | 对方的个人简介/人设 | `"性别女，性格乖巧可爱，喜欢搞怪，爱吃醋。"` | +| **master** | | | +| `name` | 主人名称（我自己） | `"陆小千"` | +| `profile` | 主人的个人简介/人设 | `"性别男，善良正直，总是舍己为人，是傻妞的主人。"` | +| **room** | | | +| `name` | 会话群名称 | `"魔幻手机"` | +| `description` | 会话群简介 | `"傻妞和陆小千的私聊"` | +| **speaker** | | | +| `userId` | [小米 ID](https://account.xiaomi.com/fe/service/account/profile)（注意：不是手机号或邮箱） | `"987654321"` | +| `password` | 账户密码 | `"123456"` | +| `did` | 小爱音箱 ID 或名称 | `"小爱音箱 Pro"` | +| `ttsCommand` | 小爱音箱 TTS 指令（[可在此查询](https://home.miot-spec.com)） | `[5, 1]` | +| `wakeUpCommand` | 小爱音箱唤醒指令（[可在此查询](https://home.miot-spec.com)） | `[5, 3]` | +| **speaker 其他参数（可选）** | +| `callAIKeywords` | 当消息以关键词开头时，会调用 AI 来响应用户消息 | `["请", "傻妞"]` | +| `wakeUpKeywords` | 当消息以关键词开头时，会进入 AI 唤醒状态 | `["召唤傻妞", "打开傻妞"]` | +| `exitKeywords` | 当消息以关键词开头时，会退出 AI 唤醒状态 | `["退出傻妞", "关闭傻妞"]` | +| `onEnterAI` | 进入 AI 模式的欢迎语 | `["你好，我是傻妞，很高兴认识你"]` | +| `onExitAI` | 退出 AI 模式的提示语 | `["傻妞已退出"]` | +| `onAIAsking` | AI 开始回答时的提示语 | `["让我先想想", "请稍等"]` | +| `onAIReplied` | AI 结束回答时的提示语 | `["我说完了", "还有其他问题吗"]` | +| `onAIError` | AI 回答异常时的提示语 | `["出错了，请稍后再试吧！"]` | +| `playingCommand` | 查询小爱音箱是否在播放中指令（[可在此查询](https://home.miot-spec.com)） | `[3, 1, 1]` | +| `streamResponse` | 是否启用流式响应（部分小爱音箱型号不支持查询播放状态，此时需要关闭流式响应） | `true` | +| `exitKeepAliveAfter` | 无响应一段时间后，多久自动退出唤醒模式（单位秒，默认 30 秒） | `30` | + +## 环境变量 + +重命名本项目根目录下的 [.env.example](https://github.com/idootop/mi-gpt/blob/main/.env.example) 文件为 `.env`。 + +然后，将里面的环境变量修改成你自己的，参数含义如下： + +| 环境变量名称 | 描述 | 示例 | +| ---------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ | +| **OpenAI** | | | +| `OPENAI_API_KEY` | OpenAI API 密钥 | `abc123` | +| `OPENAI_MODEL` | 使用的 OpenAI 模型 | `gpt-4o` | +| `OPENAI_BASE_URL` | 可选，OpenAI API BaseURL | `https://api.openai.com/v1` | +| `AZURE_OPENAI_API_KEY` | 可选，[Microsoft Azure OpenAI](https://www.npmjs.com/package/openai#microsoft-azure-openai) | `abc123` | +| **提示音效（可选）** | | | +| `AUDIO_SILENT` | 静音音频链接 | `"https://example.com/slient.wav"` | +| `AUDIO_BEEP` | 默认提示音链接 | `"https://example.com/beep.wav"` | +| `AUDIO_ACTIVE` | 唤醒提示音链接 | `"https://example.com/active.wav"` | +| `AUDIO_ERROR` | 出错提示音链接 | `"https://example.com/error.wav"` | +| **豆包 TTS（可选）** | | | +| `TTS_DOUBAO` | 豆包 TTS 接口 | `"https://example.com/tts.wav"` | +| `SPEAKERS_DOUBAO` | 豆包 TTS 音色列表接口 | `"https://example.com/tts-speakers"` | diff --git a/TODO.md b/docs/todo.md similarity index 57% rename from TODO.md rename to docs/todo.md index 8b0ca45..af15784 100644 --- a/TODO.md +++ b/docs/todo.md @@ -1,61 +1,48 @@ -# TODOs +# v3.1.0 下一版本的更新计划 ## 🔥 Hotfix -- 修复提示语和提示音链接都为空时，不播放提示音。https://github.com/idootop/mi-gpt/issues/30#issuecomment-2153786207 +- 提示语列表为空时，不播放提示语。 +- 提示语和提示音链接都为空时，不播放提示音。https://github.com/idootop/mi-gpt/issues/30#issuecomment-2153786207 - 修复因没有配置环境变量，而导致没有初始化成功 OpenAI 使程序崩溃。 https://github.com/idootop/mi-gpt/issues/30#issuecomment-2153753279 - 修复唤醒模式下，重新匹配唤醒词时，应该走询问 AI 的流程。([issues#25](https://github.com/idootop/mi-gpt/issues/25)) - 修复使用提示音链接时，小爱回答完毕后，仍然重复播放文字提示语的问题。 -## 📒 文档 FAQ +## 💪 优化 + - 优化 unWakeUp 小爱的流程，增加指令间的执行间隔，降低 ROM 端无响应问题的出现的概率。https://github.com/idootop/mi-gpt/issues/32 - 优化 debug 日志输出，添加 wakeUp、unWakeUp、env 等关键流程和核心数据的打印。 + +## 📒 文档 FAQ + - 优化关于 Azure OpenAI 配置的说明。https://github.com/idootop/mi-gpt/issues/7 - 优化找不到小爱设备的提示文案以及 FAQ 教程。https://github.com/idootop/mi-gpt/issues/28#issuecomment-2153645819 - 添加关于唤醒小爱、唤醒词、唤醒模式的说明和注意事项。 -- 添加关于 clone 项目本地运行的相关配置教程。 +- ✅ 添加关于 clone 项目本地运行的相关配置教程。 +- 添加关于本地构建本项目 docker 镜像的说明。 - 添加关于 playingCommand 的详细说明，默认不需要配置。 - 添加常见小爱音箱型号的支持情况和参数列表。 - 添加关于 clone 项目本地运行提示找不到 bot 的相关说明。 - 添加国内设备代理配置相关的说明。https://github.com/idootop/mi-gpt/issues/29 - 添加国内设备使用 Docker 镜像配置镜像代理的说明。https://github.com/idootop/mi-gpt/issues/31 - 添加关于 OpenAI 401 账号 API_KEY 错误， 403 触发 IP 访问风控的说明。https://github.com/idootop/mi-gpt/issues/19，https://github.com/idootop/mi-gpt/issues/33 -- 添加关于 Node 项目下 MiGPT.create 参数配置的说明。 https://github.com/idootop/mi-gpt/issues/27 -- 添加关于 Widnows 下 docker 启动参数配置的说明。https://github.com/idootop/mi-gpt/issues/26 +- ✅ 添加关于 Node 项目下 MiGPT.create 参数配置的说明。 https://github.com/idootop/mi-gpt/issues/27 +- 【待更新】添加关于 Widnows 下 docker 启动参数配置的说明。https://github.com/idootop/mi-gpt/issues/26 ## ❤️ 感谢 + - @shaoyi1991 补充的关于项目启动和国内配置 docker 镜像的说明。 https://github.com/idootop/mi-gpt/issues/28 -- @shog86 协助调试 Azure OpenAI 相关的配置参数 +- @shog86 协助调试 Azure OpenAI 相关的配置参数 https://github.com/idootop/mi-gpt/pull/34 +- @siseboy 提供群晖 docker 使用教程 https://github.com/idootop/mi-gpt/issues/41 +- @moffefei 提供的 Windows 下 docker 启动命令的示例 https://github.com/idootop/mi-gpt/issues/45 -# Roadmap +# v4.0.0 -> 以下是一些可以优化的地方或新功能，仅作记录之用，暂时没有开发计划。 - -## 🐛 修复 - -- 【重要】自动刷新小米账号登录凭证 - - 小米账号登录凭证有效期 1 个月，到期后需要自动刷新（mi-service-lite） - -## 💪 优化 - -- 自动识别设备型号 - - 通过查询设备 miot spec 文件，自动获取指令参数 - - 自动识别设备属性值是否有读取权限 -- 添加镜像更新说明 - - 添加 db 文件导入/出教程，用于备份恢复对话历史记录 +版本更新计划 ## ✨ 新功能 -- 添加是否启用对话模式的开关 -- 支持通过语音命令清除上下文 -- 支持自定义对话系统 Prompt 模板 -- MioT AI Agents - - 支持小爱音箱控制米家设备 - - 通过 Agent 机制自动调用合适的工具（设备） -- RAG - - wikis embedding - - memory embedding -- 插件系统 - - 自定义语音指令 +- 支持火山引擎 TTS 和音色切换能力 +- 添加更详细的使用和配置视频教程 \ No newline at end of file