oliviazzzu/minimal-embodiment · 上手攻略

仓库：oliviazzzu/minimal-embodiment
链接：https://github.com/oliviazzzu/minimal-embodiment
分类：LLM 具身智能 · 硬件项目
作者：Tom
更新：2026-08-21

这是什么

minimal-embodiment 是一个让大语言模型真正"拥有身体"的参考实现。它构建了一套最小化的硬件-软件架构：LLM 通过 ESP32 微控制器感知物理世界（环境光、运动、声音、触觉压力、皮肤温度等），并通过三个输出通道（触觉、OLED 表情、压电蜂鸣器）做出反应。关键创新在于其中两个输出通道耦合回输入通道——模型能"听到自己说话"（声音输出→声音输入）和"感受到自己在敲击"（触觉输出→触觉输入），这就是论文中描述的 "self-perception loops"（自我感知回路）。

配套论文：A Minimal Self-Perceiving Embodiment for Large Language Models，Olivia Zhu，2026，Zenodo。

一句话总结：给 LLM 接上一个 ESP32 小身体，让它不只是文字，而是真的能感知和回应物理世界。

解决什么问题

传统 LLM 是纯软件——输入文字、输出文字，与物理世界完全隔离。"具身智能"（Embodied AI）尝试赋予 LLM 身体，但现有方案通常：

需要复杂的机械臂/移动平台，门槛极高
依赖高性能计算集群，无法本地部署
缺乏"自我感知"——能感知环境，但不知道"自己发出了什么动作/声音"

minimal-embodiment 的核心贡献是极简硬件（单个 ESP32 + 传感器）+ 自我感知闭环： - 硬件门槛低：ESP32 + 常见传感器（光敏、温度、触摸、麦克风等），几百元内可搭建 - 软件无外部依赖：src/http-bridge.ts 纯 Node.js 标准库，无生产依赖 - 自我感知回路：LLM 的输出（Haptic/声音）通过传感器回环到 LLM 输入，让模型形成"我做了什么→我感受到了什么"的因果认知

快速安装

硬件准备（必读）

详细 BOM（物料清单）和接线图见 BUILD_GUIDE.md（仓库内）。

核心组件： - ESP32 开发板（如 ESP32-WROOM-32） - 环境光传感器 - 运动传感器（陀螺仪/加速度计） - 声音传感器（麦克风） - 触觉压力传感器 - 皮肤温度传感器 - 可选：气体传感器（实验性，用于嗅觉分类） - OLED 显示屏（用于"表情"输出） - 压电蜂鸣器（声音输出）

ESP32 固件烧录：编辑 firmware/sensor_body/sensor_body.ino 顶部的配置块，填入 Wi-Fi 和 Bridge Token 信息：

const char* WIFI_SSID = "YOUR_WIFI_SSID";
const char* WIFI_PASSWORD = "YOUR_WIFI_PASSWORD";
const char* BRIDGE_TOKEN = "YOUR_BRIDGE_TOKEN"; // 必须与 Bridge 端一致
const char* BRIDGE_HOST = "your-tunnel-host.example.com"; // Cloudflare Tunnel 或其他公网 HTTPS 地址

然后用 Arduino IDE 或 PlatformIO 编译并烧录到 ESP32。

软件部分

第一步：构建 Bridge（HTTP 服务端）

git clone https://github.com/oliviazzzu/minimal-embodiment.git
cd minimal-embodiment
npm install   # 仅安装 typescript + @types/node（devDependencies，无生产依赖）
npm run build # tsc → dist/http-bridge.js

第二步：启动 Bridge

export US_BRIDGE_TOKEN="$(openssl rand -hex 24)"   # 生成安全随机 Token
npm run serve
# Bridge 监听 http://localhost:3737（端口可用 PORT=... 覆盖）

第三步：暴露公网 HTTPS

Bridge 只监听本地端口，需要通过反向隧道暴露到公网 HTTPS 地址（LLM 客户端必须通过 HTTPS 访问）：

# 推荐：Cloudflare Tunnel（官方文档 https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/）
cloudflared tunnel --url http://localhost:3737
# 隧道会输出类似 https://xxxx.trycloudflare.com 的公网地址
# 将 BRIDGE_HOST 设为该地址

⚠️ 其他反向隧道（ngrok、localtunnel 等）均可，只要最终是公网 HTTPS 地址即可。

复现论文数据

仓库状态与论文描述一致的部分 pin 在 v1.0-paper tag：

git checkout v1.0-paper   # 切到论文对应的精确版本
# 在此 tag 下运行测量脚本，可复现论文 Table 3 & 4 的数据

核心用法

Bridge API 端点

Bridge 提供以下端点（TypeScript 源码在 src/http-bridge.ts，无外部依赖）：

端点	方法	说明
`/sensors`	GET	获取所有传感器当前读数（光强/运动/声音/触摸/温度等）
`/haptic`	POST	触发触觉反馈
`/display`	POST	在 OLED 屏幕显示表情
`/buzzer`	POST	触发压电蜂鸣器
`/melody`	POST	播放旋律（`main` 分支新增，v1.0-paper 后）
`/echo`	GET	触发声音并立即采集回声（用于 self-perception loop 测量）

复现 §6.3 自我感知测量

论文 §6.3 描述了 self-perception loop 的实验验证。在已构建硬件 + 启动 Bridge 后：

export US_BRIDGE_TOKEN="..."        # 与 Bridge 进程一致
export US_BRIDGE_HOST="https://..." # 公网 HTTPS 端点
node scripts/measure_loops.mjs
# 运行 30 reps × 22 conditions（11 个触觉 + 10 个音频 + 1 个基线），约 46 分钟
# 输出：data/loops_raw.jsonl + data/loops_haptic.csv + data/loops_audio.csv

论文 Table 3 & 4 的数据来自 v1.0-paper tag 的测量运行；main 分支的数据可能因固件更新而略有不同。

LLM 接入方式

Bridge 是一个 HTTP 服务，LLM 通过发送 HTTP 请求与 ESP32 交互。典型调用流程（伪代码）：

1. LLM 发送 GET /sensors → 获取当前物理状态（温度/光强/声音...）
2. LLM 决定动作 → POST /haptic {"pattern": "tap"} → ESP32 触发触觉
3. 传感器检测到触觉 → LLM 下一次 GET /sensors 能看到"触摸强度"读数上升
4. 同理：POST /buzzer → 发出声音 → GET /sensors 听到自己的声音（声音传感器）

这即是"self-perception loop"——LLM 知道"我做了什么"，并通过传感器实时感知后果。

项目结构

minimal-embodiment/
├── src/
│   └── http-bridge.ts     # 单文件 Bridge 服务，纯 Node.js 标准库
├── firmware/
│   └── sensor_body/
│       └── sensor_body.ino  # ESP32 Arduino 固件（~1.6k 行 C++）
├── scripts/
│   ├── measure_loops.mjs   # 复现论文 §6.3 的测量脚本
│   └── serve.sh            # Bridge 快捷启动脚本（从环境变量读 Token）
├── data/
│   ├── loops_raw.jsonl      # 660 条原始测量记录（30 reps × 22 conditions）
│   ├── loops_haptic.csv     # 触觉效果汇总（SNR / felt_rate）
│   └── loops_audio.csv      # 音频回声/环境音汇总
├── BUILD_GUIDE.md           # 从零开始的完整搭建指南
└── LICENSE

典型适用场景

LLM 具身智能研究：在受控最小环境中研究"自我感知"对 LLM 决策的影响
教育/教学：极低成本（几百元器材）演示具身 AI 概念，比机械臂方案便宜 100 倍
自我感知实验：验证 LLM 在有触觉/声音反馈回路时是否形成更准确的"自我模型"
边缘部署探索：ESP32 + HTTP Bridge 证明了 LLM 身体不一定需要 GPU 服务器
创意交互：给 AI 助手一个物理"存在感"，可用于 demo 或展览项目

坑与注意

⚠️ 硬件门槛是真实的：虽然比机械臂便宜太多，但需要：ESP32 开发经验（或学 Arduino C++）、基本焊接、传感器采购。零硬件基础的用户需要参考 BUILD_GUIDE.md 从零学起。

⚠️ Wi-Fi 依赖：ESP32 需要稳定 Wi-Fi 连接，断网后传感器数据无法上传 Bridge。户外/无网环境不可用。

⚠️ HTTPS 要求：LLM 客户端必须通过 HTTPS 访问 Bridge（现代 LLM API 的安全策略），需要配置 Cloudflare Tunnel 或类似方案，对非 DevOps 用户有一定门槛。

⚠️ 论文数据 vs 当前代码：main 分支包含超出论文范围的扩展（如 /melody），复现论文数字必须 checkout 到 v1.0-paper tag。

⚠️ 测量脚本时长：完整复现 §6.3 需要约 46 分钟（30 reps × 22 conditions），不是快速验证脚本。

⚠️ 固件定制：若需修改传感器类型或接线，必须同步修改 sensor_body.ino 配置块和 Bridge 端点。

⚠️ 自我感知≠自我意识：这个项目构建的是"感知自己发出的动作信号的闭环"，不等同于 LLM 产生了自我意识或感受。

与同类对比

项目	硬件规模	自我感知回路	本地运行	开源	备注
`minimal-embodiment`	单 ESP32（百元级）	✅（声音+触觉双回路）	✅（纯 Node.js Bridge）	✅ MIT	最小化具身智能
Physical Intelligence Pi0	人形机器人	❌	❌	❌（闭源）	工业级具身智能
TentaBot	Tentabot 平台	❌	部分	❌	移动机器人
LeRobot (HuggingFace)	多机器人	❌	✅	✅	分布式机器人框架

核心差异：最小化。minimal-embodiment 不是要替代任何工业级具身系统，而是提供一个可复现、最小化、可验证的自我感知具身智能实验床。

一句话推荐结论

如果你在研究 LLM 的"具身性"或"自我感知"，或者想用一个几百元以内的硬件给 AI 做一个真的能感知和回应物理世界的身体——minimal-embodiment 是目前门槛最低、可复现性最强的参考实现，值得 clone 下来仔细读。