5 分钟把小爱音箱接入大模型：MiGPT 实操配置指南

5 分钟把小爱音箱接入大模型：MiGPT 实操配置指南

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

"小爱同学，请讲个笑话。"音箱停顿两秒，用你设定的那个角色语气开口——不是小爱同学自己的声线，也不是小爱同学自己的答案。这就是 MiGPT 完成后的日常：一个通过小米 MIoT 协议把小爱音箱接入大语言模型、改造成 AI 语音助手的服务。保留小爱音箱作为入口和喇叭，把回答换成 OpenAI 兼容模型的输出，支持流式回复和自定义音色。本文按"先跑通、再调性"的顺序讲：5 分钟内让音箱开口，之后是配置详解、换大脑换音色，以及排错速查。

01 环境清单与准备工作

硬件与运行环境要求如下：

项目	要求
音箱	小爱音箱，推荐小爱音箱 Pro（官方反馈最完整）；其他兼容型号见 docs/compatibility.md
运行环境	Node.js 16.0 及以上
账号	小米账号 ID 与密码（注意：不是手机号，也不是邮箱）
网络	音箱与运行 MiGPT 的设备处于同一局域网

小度音箱、天猫精灵、HomePod 不在支持范围内，官方也无相关适配计划。

拉取代码并安装依赖：

git clone https://gitcode.com/GitHub_Trending/mi/mi-gpt cd mi-gpt pnpm install

安装完成即自动初始化本地数据库（postinstall触发 Prisma 迁移），无需额外建库。然后把两个示例配置复制成正式配置：

cp .migpt.example.js .migpt.js cp .env.example .env

接下来的工作就是分别编辑这两个文件。

02 配置音箱：.migpt.js 关键项

小米 ID 在哪找

打开小米账号官网的「个人信息」，或在米家 App 中查看自己的「小米 ID」。它是一串纯数字账号 ID，直接填入.migpt.js。

.migpt.js中必须确认的四项：

字段	作用	填什么
speaker.userId	小米账号 ID	一串数字，不是手机号或邮箱
speaker.password	小米账号密码	明文填入
speaker.did	指定音箱设备	音箱的 DID 或米家中设置的名称，空格、大小写、错别字都会匹配失败
speaker.ttsCommand/wakeUpCommand	朗读与唤醒的 MIoT 指令	按机型填写，小爱音箱 Pro（LX06）为[5, 1]/[5, 3]

ttsCommand、wakeUpCommand与机型绑定，其他型号去 MIoT 规格站或 docs/compatibility.md 查对应值，示例文件里保留的 Pro 默认值不能照抄。

03 配置模型：.env 关键项

.env决定"大脑"来自哪里，只有三个必填项：

OPENAI_BASE_URL=https://api.openai.com/v1 # 大模型服务接口，一般以 /v1 结尾 OPENAI_MODEL=gpt-4o-mini # 使用的模型名 OPENAI_API_KEY=sk-proj-xxxxxxxx # 模型服务商的 API 密钥

变量名以OPENAI_开头不代表只能接 OpenAI：任何 OpenAI 兼容接口改这三个值即可，通义千问、DeepSeek、Moonshot（Kimi）等都可以直接接，接法见 docs/faq.md。不兼容 OpenAI 协议的模型（如豆包、文心一言），需要用 One API、simple-one-api 之类的聚合工具转成 OpenAI 兼容格式后再接入。

04 启动验证：跑通最小路径

启动服务：

pnpm start

看到MiGPT v4.2.0版本行、Speaker服务就绪，且没有登录报错，即为启动成功。

验证方式，按顺序试三种：

1. 单轮提问：说"小爱同学，请讲个笑话"。以callAIKeywords（默认["请", "你", "傻妞"]）开头的消息才会转给大模型回答，其余消息仍走小爱自带逻辑。
2. 唤醒模式（连续对话）：说"小爱同学，召唤傻妞"（以wakeUpKeywords开头），进入 AI 模式后连续提问，不必每句都以"小爱同学"开头；等它说完onAIReplied的提示语（默认"我说完了，还有其他问题吗"），再等 1-2 秒继续。
3. 退出唤醒模式：说"退出傻妞"（以exitKeywords开头）。

注意：连续对话默认关闭（streamResponse: false），部分机型无法正确查询播放状态，强行开启会异常。

05 .migpt.js 配置速查

字段	默认示例	作用
systemTemplate	角色对话模板	系统提示词，{{botName}}、{{messages}}、{{shortTermMemory}}、{{longTermMemory}}等模板变量控制角色设定与上下文注入
bot.name/bot.profile	傻妞	AI 一方的名字与人设
master.name/master.profile	陆小千	你的称呼与人设
room.name/room.description	会话群名称	会话场景名与简介，会进入提示词
callAIKeywords	["请", "你", "傻妞"]	消息以此开头时调用大模型回答
wakeUpKeywords/exitKeywords	["打开", "进入", "召唤"]/["关闭", "退出", "再见"]	进入 / 退出连续对话的关键词
onEnterAI/onExitAI/onAIAsking/onAIReplied/onAIError	见示例文件	各阶段提示语；数组设为[]即关闭对应提示
tts	xiaoai	TTS 引擎；custom表示走第三方 TTS
streamResponse	false	是否启用连续对话
exitKeepAliveAfter	30	连续对话无响应多少秒后自动退出，建议不超过 60
checkInterval	1000	播放状态检测间隔（毫秒，最低 500），调小可减小回答间停顿感
checkTTSStatusAfter	3	下发 TTS 后多少秒开始检测播放状态，长文本被过早截断时调大
playingCommand	未启用	播放状态查询指令，播放状态异常时再配置
timeout	5000	网络请求超时（毫秒）
debug/enableTrace	false	调试日志开关，日常保持关闭

最小化的角色与提示词修改示例：

export default { systemTemplate: `你是「傻妞」，回复简洁、口语化，直接说内容。`, bot: { name: "傻妞", profile: "性格乖巧可爱" }, master: { name: "你", profile: "她的朋友" }, speaker: { userId: "你的小米ID", password: "你的小米密码", did: "小爱音箱Pro", ttsCommand: [5, 1], wakeUpCommand: [5, 3], onAIAsking: ["让我先想想"], onAIReplied: ["我说完了"], }, };

06 换大脑与换音色

换大脑：改三行环境变量

模型切换不改代码。以通义千问为例：

OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 OPENAI_MODEL=qwen-turbo OPENAI_API_KEY=你的通义千问API密钥

通义千问还支持QWEN_ENABLE_SEARCH=true让回答参考互联网搜索结果（qwen-vl、qwen 开源系列与 qwen-long 不支持）。

换音色：第三方 TTS

默认tts: "xiaoai"用小米自带 TTS。换豆包同款音色或其他声音，需要一台对 MiGPT 可见的 TTS 服务（如 MiGPT-TTS，火山引擎，或本地 ChatTTS），然后：

1. .env配置TTS_BASE_URL=http://<局域网或公网地址>:<端口>/api（不能用 localhost 或 127.0.0.1）；
2. .migpt.js把speaker.tts改为custom；
3. 对音箱说"小爱同学，把声音换成 xxx"即可切换音色。

接口与音色细节见 docs/tts.md。

07 常见坑与排错

现象	原因与处理
型号不在支持列表	查 docs/compatibility.md；ttsCommand/wakeUpCommand必须按机型替换，"正常运行"的机型需保持streamResponse: false
报70016：登录验证失败	账号密码不对，或把手机号当成了小米 ID
触发小米账号异地登录风控	在常用网络/常用设备登录，或改用 Docker 部署；细节见 docs/faq.md
回答慢	换更快的模型（如gpt-4o）；onAIAsking/onAIReplied置[]去掉提示语；checkInterval调到 500
连续对话没反应	等提示语说完 1-2 秒再说；小爱 Pro 顶部指示灯常亮时表示在听；无反应就重新唤醒一次
长回复被截断	checkTTSStatusAfter适当调大；打断回复可重新唤醒后说"请你闭嘴"

两个容易忽略的细节：

• 指令触发小爱原生功能（播放音乐、讲笑话等）时，消息不会进入历史记录，外部收不到。此时先让音箱暂停再对话，否则会出不可预期的错误。
• Docker 启动命令是docker run -d --env-file $(pwd)/.env -v $(pwd)/.migpt.js:/app/.migpt.js idootop/mi-gpt:latest；配置文件改动后需重启容器，Windows 终端下要把$(pwd)换成绝对路径。

08 进阶玩法

方向	做法
精细角色设定	编辑systemTemplate与bot.profile，配合{{shortTermMemory}}、{{longTermMemory}}变量控制上下文与记忆注入，教程见 docs/prompt.md
多设备	每台音箱独立一套userId/did/ 角色配置，分别部署，角色互不相同
Docker 部署	不想维护 Node 环境时用上面的 Docker 命令，镜像见 Dockerfile

全部字段含义在 docs/settings.md 有完整说明，原理部分看 docs/how-it-works.md。

09 接下来做什么

1. 通读一遍 docs/settings.md，确认每个字段都是有意配置的；
2. 关注仓库 issues 区，新机型适配参数基本都沉淀在那里；
3. 先把"小爱同学，请 xxx"单轮问答跑稳，再开streamResponse试连续对话；
4. 部署一个第三方 TTS 服务，体验换音色效果。

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