用 Meta 开源 Muse 代码做一台桌面 AI 小装置

这台装置长这样：巴掌大的开发板塞进一个小壳子里，插上 USB 供电，按一下按钮，对着它说一句"帮我把明天的会议改到下午三点"，桌面上的小喇叭过一两秒把回答念出来。它不依赖某个大厂成品，从固件到语音链路都在自己手里，出问题能一层一层往下查。

Muse 提供的是装置侧 agent 循环与设备接入的参考实现，仓库里目录结构、示例名称、命令行参数都会随版本变化，凡涉及具体命令，一律以官方仓库的 README 和 examples 为准。这篇教程把"从零到一问一答"的全过程拆开讲，重点是每一步怎么验证自己做对了。

前置条件清单

硬件

• 一块带 Wi-Fi 的开发板，ESP32-S3 一类即可。选型时看三点：有没有 PSRAM（音频缓冲很吃内存）、I2S 引脚有没有引出来、供电电路能不能扛住功放的电流尖峰。
• 一路数字麦克风，I2S 接口的（INMP441 这类很常见）；或者用带 USB 声卡的麦克风模块。
• 一路 I2S 功放模块加一个小喇叭，MAX98357A 这类。
• 杜邦线若干、3.3V 稳压模块（给功放单独供电用）、一个按钮、可选 WS2812 灯环。
• 一根能传数据的 USB 线。注意：很多线只能充电，插上电脑看不到串口，这是排错排到怀疑人生的头号原因。

软件

• Git、Python 3、ESP-IDF（版本以官方文档当前版本为准，别混装两套）、串口驱动、一个串口终端工具。

账号与网络

• 一个大模型 API key，一个语音识别/TTS 的 key，可以同一家也可以分开。
• 2.4GHz 的 Wi-Fi。多数 ESP32 只连 2.4G，家里如果是 5G 单独 SSID，直接连不上。

第一步：先把链路画清楚，再动手

整个装置就一条主链路：

```

按钮/唤醒 → 录音（16kHz 单声道 16bit PCM） → 本地断句（VAD）

→ 上传到你的中继服务 → ASR 转文字 → LLM 出回答 → TTS 合成音频

→ 回传设备 → I2S 播放

```

建议把"设备端"和"服务端"彻底分开：设备只负责采集、上传、播放，密钥和模型调用全放在你电脑或小服务器上的一个中继服务里。好处是密钥不烧进固件，换模型不用重新烧录，出了问题看服务端日志就知道卡在哪一环。

第二步：拉仓库、读结构

```bash

git clone <Muse 官方仓库地址>

cd <仓库目录>

ls

cat README.md

```

先别急着编译。按这个顺序读：README 的快速开始 → examples 目录里哪个例子最接近"录音+上传+播放" → 固件里的配置文件（通常是 Kconfig 或 sdkconfig 的形式）里有哪些必填项。

Muse 给出的装置侧 agent 循环负责的是"组织一轮对话的状态与工具调用"，音频采集播放、网络传输这些往往需要你按官方示例接上自己的硬件。所以下一步是把示例跑起来，再往你的板子上迁。

第三步：装工具链，先把板子点亮

以 ESP-IDF 为例（命令以官方文档当前版本为准）：

```bash

拉取并安装 ESP-IDF 工具链，按官方文档的安装脚本执行

./install.sh

. ./export.sh

进入固件目录

cd firmware # 目录名以仓库实际结构为准

设置目标芯片

idf.py set-target esp32s3

打开配置菜单，填 Wi-Fi、服务端地址、API 配置

idf.py menuconfig

```

配置里大概要填这几类：Wi-Fi SSID 与密码、中继服务的地址与端口、设备 ID / 令牌、音频采样率与 I2S 引脚。填完保存退出。

```bash

idf.py build

idf.py -p /dev/ttyUSB0 flash monitor

```

/dev/ttyUSB0 换成你实际的串口，Windows 上是 COM3 这类。看到启动日志刷出来，说明工具链没问题了。这一步先不要接麦克风和喇叭，先把"能编译、能烧录、能看日志"三件事确认掉。

第四步：接线

麦克风和功放都用 I2S。以 ESP32-S3 为例，典型接法：

三个细节别漏：麦克风的 L/R 脚必须接，悬空会出现"没声音"；麦克风和功放用两组独立的 I2S 通道（一组收、一组发），不要复用同一组时钟引脚；功放的电源线上并在喇叭旁边加一个大一点的电解电容，播放瞬间电流尖峰会让板子掉电重启。

第五步：先验证硬件回环

不要一上来就接大模型。先在固件里写一个"录音两秒，立刻原样播出来"的循环，或者直接用 ESP-IDF 的 I2S 示例改。能听到自己的声音、不卡顿、不失真，说明采样率、位宽、声道三项全对了。

这一步的常见现象是"哗哗的噪声"：八成是 I2S 的主从模式配反了，或者采样率 16k 的设备被当成 44.1k 在跑。

第六步：写中继服务

服务端收一段 WAV，做 ASR → LLM → TTS，返回音频。用 FastAPI 大概长这样：

```python

from fastapi import FastAPI, UploadFile, Response

app = FastAPI()

@app.post("/chat")

async def chat(file: UploadFile):

audio = await file.read()

1. 语音识别：把 audio 交给 ASR，得到文本

user_text = asr_transcribe(audio)

2. 大模型：带上 system prompt 和历史上下文

reply_text = llm_reply(user_text, system="你是桌面助手，回答控制在三句话以内。")

3. 语音合成：拿到音频

reply_audio = tts_synthesize(reply_text, sample_rate=16000, fmt="pcm16")

return Response(content=reply_audio, media_type="application/octet-stream")

```

三个必须注意的格式约束：

• ASR 一般要求 16kHz、单声道、16bit PCM/WAV。设备端采集时就把参数设成这样，别在服务端做重采样。
• TTS 默认经常返回 MP3，而设备端播放的是裸 PCM。要么让 TTS 直接输出 PCM，要么服务端用 ffmpeg 转一道。
• 回答尽量短。桌面装置的喇叭小，读三句话刚好，读三十句谁都不听。

先在本机用 curl 测通这个接口，别让设备端当调试器。

第七步：设备端接上中继服务

设备端的伪代码逻辑大致是：

```c

// 1. 按键按下，开始采集

// 2. 检测到静音超过 N 毫秒，判定一句话结束

// 3. 把这段 PCM 打包成 WAV（补 44 字节头）

// 4. HTTP POST 到 /chat

// 5. 收到的 PCM 分块写入 I2S 发送通道

// 6. 播放结束后回到待机

```

要点是第 5 步用流式写：不要等整个音频收完再播，一边收一边丢进 I2S，体感延迟会明显下降。同时播放期间把麦克风采集关掉，否则喇叭的声音会被录进去再问一遍模型，形成死循环。

第八步：装壳、加灯、加打断

到这一步功能已经跑通，剩下是体验：

• 外壳用 3D 打印或者买个现成的小盒子，麦克风开孔别对着喇叭，能少一半回声。
• 一个呼吸灯状态机：待机暗蓝、录音亮红、思考闪烁、播放绿色，用户立刻知道它在干什么。
• 打断：播放过程中如果检测到用户说话，立刻停止播放。做法是在播放循环里插一个麦克风能量检测，超阈值就中断 I2S 发送。

常见坑与排错

烧录识别不到串口。 先换线，再换 USB 口，再检查驱动。开发板有 BOOT 键的，按住 BOOT 再按 RESET 进下载模式。

串口被占用。 关掉 monitor 再烧录，或者 idf.py -p PORT monitor 和 flash 分开执行。

连不上 Wi-Fi。 九成是 5GHz 的问题。确认路由器 2.4G 是独立 SSID，或者手机开热点试试。

录音是噪声。 检查 L/R 脚是否接地、主从模式是否配反、采样率是否一致。

一放音就重启。 功放电源和开发板共用一条细线导致的。给功放单独供电，就近加电容。

识别一直空结果。 打印一下上传的数据前几个字节，正常的 WAV 开头是 RIFF。如果不是，说明打包逻辑错了。

偶尔延迟特别大。 多半是整段音频收完再播。改成流式写入。

密钥泄露风险。 不要把 API key 编译进固件。固件里只放中继服务的地址和一个设备令牌，真实密钥留在服务端。

下一步建议

链路通了之后，可以按这个顺序加东西：

1. 唤醒词：从按键触发换成关键词唤醒，体验提升明显。

2. 多轮上下文：中继服务里按设备 ID 存最近几轮对话，就能接着问"那后天呢"。

3. 工具调用：让模型能调用你写的函数，比如查天气、控灯、读日程，这时候它才真叫助手。

4. 加一块小屏幕：把识别到的文字和回答同时显示出来，调试期帮助很大。

5. 本地小模型兜底：网络断了的时候至少能做一些简单指令。

每加一层，都保持"设备只管采集上传播放、逻辑全在服务端"这个结构。结构不乱，这台小东西就能一直往上长。