小爱音箱接入大语言模型：从Docker部署到自定义语音助手的完整教程-开发者社区

小爱音箱接入大语言模型：从Docker部署到自定义语音助手的完整教程

【免费下载链接】mi-gpt🏠 将小爱音箱接入 ChatGPT 和豆包，改造成你的专属语音助手。项目地址: https://gitcode.com/GitHub_Trending/mi/mi-gpt

周五晚上，你对客厅的小爱音箱说"小爱同学，给我讲个睡前故事"，等回来一句"抱歉，我没听懂"。设备本身没有坏，音乐能放、灯光能控，问题出在对话能力上：内置语音助手按固定场景应答，缺少上下文理解和自然对话能力。开源项目 MiGPT 做的事情正是不用换硬件，把小爱音箱接入 ChatGPT、豆包等大语言模型，改造成一个有记忆、能自定义人设的家庭语音助手。

项目概览

MiGPT 以独立服务运行（Docker 容器或 Node.js 进程），通过小米 IoT 开放接口轮询小爱音箱的云端对话记录，把命中关键词的提问转发给大语言模型，再把回答经 TTS 合成后从音箱播放出来。服务运行在小爱音箱同一局域网之外的服务器上也完全可以，不依赖本地组网。

核心能力包括：

多模型接入：兼容一切 OpenAI API 格式的服务，OpenAI、通义千问、DeepSeek、Moonshot 均可通过修改三个环境变量切换
长短期记忆：内置记忆管理器，默认携带最近 10 条对话和两阶段记忆进入上下文，无需额外配置
角色扮演：助手名字、性格、你自己的简介都可自定义，默认模板即"傻妞"人设
连续对话与第三方 TTS：支持"召唤"进入连续对话状态，可接入火山引擎（豆包同款音色）或本地 ChatTTS 等语音引擎

动手前的准备：四项前置条件

小爱音箱：大部分型号可用，小爱音箱 Pro（LX06）运行最稳定，具体以兼容型号列表为准；小度、天猫精灵、HomePod 不在支持范围
小米账号：需要数字形式的小米 ID（不是手机号、不是邮箱，在小米账号资料页的"小米 ID"处查看）和账号密码
大语言模型 API Key：国内网络环境建议直接使用通义千问、DeepSeek 等国产服务的密钥，免去配置代理
一台能跑 Docker 或 Node.js 的设备：家用电脑、NAS 或云服务器均可，约 1G 内存即可，无需与音箱同网

部署实操：两条路径任选其一

选择建议：不想装 Node.js 环境的选 Docker，全程 3 步约 5 分钟完成；计划改源码做二次开发、或想提交反馈的选源码方式。两条路径共用同一套配置文件。

路径一：Docker 启动

第 1 步，克隆项目并准备两个配置文件（均从模板重命名而来）：

git clone https://gitcode.com/GitHub_Trending/mi/mi-gpt cd mi-gpt cp .env.example .env cp .migpt.example.js .migpt.js

克隆约 30 秒完成；.env存放 API 密钥等环境变量，.migpt.js存放角色、设备、唤醒词配置，后续所有参数修改都在这两个文件里。

第 2 步，按下一节"配置详解"填写参数。

第 3 步，启动容器：

docker run -d --env-file $(pwd)/.env -v $(pwd)/.migpt.js:/app/.migpt.js idootop/mi-gpt:latest

这条命令把.env作为环境变量注入、把.migpt.js挂载进容器。Windows 终端（PowerShell、cmd）下$(pwd)不生效，需要改成两个文件的绝对路径，例如D:/mi-gpt/.env。

路径二：源码启动

第 1 步，同上克隆项目并创建两个配置文件。

第 2 步，安装依赖并启动（需要 Node.js 20 及以上版本，首次运行会自动初始化本地数据库）：

pnpm install pnpm dev

pnpm install视网络约需 1-2 分钟；pnpm dev会自动读取同目录的.env，服务行为与 Docker 方式一致。

两条路径都启动成功后，控制台会打印 MiGPT 横幅和"Speaker 服务已启动"日志：

配置详解：.migpt.js 与 .env 的五个功能域

身份与设备识别

参数	文件	说明	常见坑
`userId`	.migpt.js	小米 ID（数字）	填了手机号，启动即报"70016：登录验证失败"
`password`	.migpt.js	小米账号密码	触发异地登录保护时，需先在相同网络下用该账号登录小米官网通过安全验证
`did`	.migpt.js	米家中的设备名称或设备 DID	名称须逐字一致：注意大小写、空格、错别字（"响"与"箱"）

确认名称无误仍提示"找不到设备"时，多半是 Mina 与 MIoT 两侧设备名不一致：在配置里打开debug: true和enableTrace: true并重启，从控制台"MiNA 设备列表"中找到miotDID填入did，完成后记得把两个开关改回false。

大语言模型接入

模型相关配置全部集中在.env，变量名固定为OPENAI_*前缀，只改值不改名。以接入通义千问为例：

OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 OPENAI_MODEL=qwen-turbo OPENAI_API_KEY=你的API_KEY

DeepSeek、Moonshot 等国内模型同理，把兼容端点地址和模型名填入OPENAI_BASE_URL、OPENAI_MODEL即可。国内网络直连 OpenAI 官方接口时，在.env中追加HTTP_PROXY=http://127.0.0.1:7890（按实际代理端口填写）。

角色设定与对话体验

bot（角色名与人设）、master（你的名字与简介）、systemTemplate（系统提示词模板）三个字段共同决定对话风格，默认人设是《魔幻手机》里的"傻妞"。系统提示词模板支持{{botName}}、{{messages}}等变量，详细用法见 docs/prompt.md。

以下参数决定"什么时候才调用 AI"：

参数	作用
`callAIKeywords`	消息以这些词开头时调用 AI（默认`["请", "你", "傻妞"]`）
`wakeUpKeywords`	消息以这些词开头时进入连续对话状态（默认`["打开", "进入", "召唤"]`）
`exitKeywords`	以这些词开头时退出连续对话（默认`["关闭", "退出", "再见"]`）
`onAIAsking`/`onAIReplied`	AI 开始/结束回答的提示语，设为空数组`[]`即可静音

一段最小可用的账号与唤醒词配置（.migpt.js片段）：

speaker: { userId: "你的小米ID", password: "你的密码", did: "小爱音箱Pro", callAIKeywords: ["请", "你"], wakeUpKeywords: ["召唤"], },

记忆系统

记忆功能随默认配置开启，不需要单独写参数：默认systemTemplate会自动把最近 10 条消息、短期记忆、长期记忆一起注入上下文；每新增 10 条消息，系统异步汇总一条新的短期记忆，长期记忆在短期记忆基础上逐层沉淀。想省 token 的话，从systemTemplate中删掉"短期记忆"和"长期记忆"两个段落即可关闭。

设备指令、TTS 与连续对话

ttsCommand、wakeUpCommand、playingCommand三个 MIoT 指令的值因型号而异，小爱音箱 Pro（LX06）对应[5, 1]和[5, 3]。具体值在 MIoT 规格站点 home.miot-spec.com 上按型号查询：

参数	说明
`ttsCommand`	播放 TTS 指令，填错会导致 AI 有回答但音箱不发声
`wakeUpCommand`	唤醒指令，影响连续对话状态下的唤醒行为
`playingCommand`	播放状态查询指令，默认无需配置，回答被中途截断时再开启
`tts`	语音引擎，默认`"xiaoai"`（音箱自带）；接入第三方 TTS 后生效
`switchSpeakerKeywords`	对话中切换 TTS 音色的关键词，如`["把声音换成"]`
`streamResponse`	连续对话开关（实验性功能），默认`false`，部分型号必须保持关闭
`checkInterval`	连续对话时播放状态检测间隔，默认 1000ms，最低 500ms
`checkTTSStatusAfter`	下发 TTS 后多少秒开始检测播放状态，默认 3 秒
`exitKeepAliveAfter`	连续对话无响应多久自动退出，默认 30 秒

第三方 TTS（火山引擎、本地 ChatTTS 等）的接入步骤在 docs/tts.md 中有完整说明，核心动作是.env里配置TTS_BASE_URL并修改tts引擎取值。

高频问题的调试与排错

问题一：控制台提示"70016：登录验证失败"现象：服务启动即失败。原因：userId/password有误，或触发小米异地登录保护。解决：核对小米 ID 为数字；若为异地保护，在与 MiGPT 相同的网络环境下用该账号登录小米官网通过验证，约 1 小时后重试。

问题二：提示"找不到设备：xxx"现象：初始化 Mi Services 失败。原因：did与米家中名称不一致（大小写、空格、错别字），或设备是共享设备（共享设备暂不支持）。解决：从米家设备主页直接复制名称；仍失败时按上文方法获取miotDID填入。

问题三：对小爱说话，AI 没有应答现象：控制台能收到消息但未调用模型。原因：MiGPT 只处理以callAIKeywords开头的消息，且必须先用"小爱同学"唤醒音箱。解决：把"请问地球为什么是圆的"改为"小爱同学，请问地球为什么是圆的"；连续对话中没反应时，重新唤醒一次即可。

问题四：回答说到一半戛然而止现象：长回复被提前截断。原因：该型号无法通过 Mina 正确查询播放状态。解决：按 MIoT 规格配置playingCommand；无效时关闭streamResponse（连续对话功能随之失效）。

问题五："LLM 响应异常，401 Invalid Authentication"现象：AI 回复失败。原因：OPENAI_API_KEY无效或未生效。解决：单独验证密钥可用性；Docker 环境下修改配置后，需要删除旧容器重新执行docker run才会生效（仅改提示语等参数有时也需重建）。

404 模型不存在、Connection error 需要代理等其余情况，可在项目 FAQ 文档中按错误码检索。

部署完成后的玩法拓展

连续对话：说"小爱同学，召唤傻妞"进入 AI 模式，此后追问无需重复"小爱同学"，等提示语"我说完了"之后接着提问；30 秒内不说话会自动退出。小爱音箱 Pro 顶部指示灯常亮表示正在聆听
运行时换角色：不改任何配置，直接说"小爱同学，你是xxx，你xxx"即可临时更换人设，"我是xxx，我xxx"可更新你的简介
换音色：接入火山引擎 TTS 后，对话中说"把声音换成xxx"可实时切换发音人，音色与豆包一致
本地模型：用 Ollama 在带显卡的机器上跑本地模型，它自带 OpenAI 兼容 API，把OPENAI_BASE_URL指向本地地址即可，回答全程不出内网