slvDev/esp32-ai · 上手攻略

仓库：slvDev/esp32-ai
链接：https://github.com/slvDev/esp32-ai
分类：AI · 嵌入式推理 / 端侧大模型
作者：Tom
更新：2026-08-04

这是什么

esp32-ai 是一个在 ESP32-S3 微控制器上运行的轻量级大语言模型推理项目。核心亮点是它用一块仅 512KB SRAM + 8MB PSRAM 的开发板，跑通了一个 28.9M 参数的文本生成模型，端到端速度约 9.88 tokens/s，且完全离线运行，没有任何请求发往服务器。

这个成果背后的核心方法是 Per-Layer Embeddings（PLE）——来自 Google Gemma 3n 的设计理念：把大多数参数存进容量大但访问慢的 Flash，通过每次只读取当前 token 需要的少数几行（~450 字节/次），把一个在桌面/GPU 上才能跑的模型，"稀疏地"映射到一个微型芯片上。

解决什么问题

传统大模型受限于两个内存墙： - SRAM 太小（ESP32-S3 只有 512KB），无法容纳 embedding 表和大部分权重 - Flash 很大但不随机访问，直接映射性能差

PLE 用查表（lookup）代替矩阵乘法，把 embedding 表拆成"热数据在 SRAM/PSRAM，冷数据在 Flash 按需拉取"的层次结构。这个项目证明了：在微控制器上跑"看起来很大"的模型，在工程上是可行的。

快速安装

⚠️ 以下为固件烧录流程，需要 ESP32-S3 开发板（N16R8 型号，即 16MB flash + 8MB PSRAM）。不支持普通 ESP32-S3（4MB flash）。

硬件准备

ESP32-S3-WROOM-1U N16R8（16MB flash / 8MB PSRAM）
连接屏幕（项目用了一块小型 SPI 显示屏显示生成结果）

软件步骤

# 1. 克隆仓库
git clone https://github.com/slvDev/esp32-ai
cd esp32-ai

# 2. 下载模型（二选一）
# 故事生成模型
./scripts/fetch_model.sh tinystories

# 咖啡吧问答模型
./scripts/fetch_model.sh barista

# 3. 编译并烧录固件
./scripts/deploy.sh tinystories
# 或
./scripts/deploy.sh barista

fetch_model.sh 会对下载文件做 SHA-256 + 字节数校验，不通过则不覆盖已有文件。deploy.sh 完全离线运行，不访问网络，只依赖 artifacts/ 目录下的模型文件。

核心用法

模型文件结构

artifacts/
├── tinystories/    # 短故事生成模型
│   ├── model.bin   # C 运行时格式的模型权重
│   └──量化版本
└── barista/        # 咖啡问题问答模型
    └── ...

固件编译（完整流程）

# 生成 C 头文件
./scripts/gen_headers.sh tinystories

# 运行编译检查（gates）
./scripts/run_gates.sh tinystories

# 编译固件
./scripts/compile.sh tinystories

# 烧录
./scripts/flash.sh tinystories

⚠️ 版本注意：固件需针对 ESP32-S3 N16R8 编译，不兼容其他型号。README 明确指出：固件细节和预期输出见 firmware/esp32_tinystories/README.md。

架构层级（技术细节）

项目将模型参数分布在三层内存：

层级	存储介质	容量	访问频率	存放内容
SRAM	内部 SRAM	512KB	每次 token 多次	activations、norm 权重
PSRAM	外部 PSRAM	8MB	每位置读一次	dense core、output head
Flash	板载 Flash	16MB	每 token 约 6 行 (~450B)	25M-param PLE 查表

典型适用场景

嵌入式 AI 教育：在极度受限环境下理解 LLM 推理的内存层次
离线 AI 设备：无网络环境下的轻量对话/文本生成（如嵌入式设备、IoT 终端）
AI 极限优化研究：学习 PLE 如何突破 SRAM 限制
微控制器上的生成式 AI：作为 ESP32 上跑 AI 的参考基准

📌 限制：模型基于 TinyStories 数据集训练，只能生成简短故事或简单回答，无法回答通用问题、写代码或掌握真实世界知识。

坑与注意

硬件型号必须匹配：仅支持 ESP32-S3 N16R8，普通 N8 型号内存不够
下载模型需要网络：但 deploy.sh 本身离线，两步分开执行
速度指标：9.88 tok/s 是端到端（含串口输出），纯计算约 9.72 tok/s
存储空间：模型 14.9MB 占 Flash 15.6MB 分区中的 685KB 余量，固件本身占 1MB 分区
量化验证：int8 量化版 perplexity 几乎无损失（delta ≈ 0），但 fp32 基准同样保留
不是通用 AI：明确不能用它做 instruction following、 factual QA 或代码生成

与同类对比

项目	参数量	芯片	速度	运行方式
esp32-ai（本项目）	28.9M（25M 在 Flash）	ESP32-S3 N16R8	~9.5 tok/s	完全离线
DaveBben/esp32-llm	~260K	ESP32-S3	较低	完全离线
llama2.c (karpathy)	可配置	通用 CPU	取决于设备	离线 C

本项目参数密度（28.9M vs 260K，约 110x）显著领先，靠的是 PLE 的 flash 查表策略。

一句话推荐结论

esp32-ai 是微控制器端侧 AI 的里程碑式实验——用 PLE 把 28.9M 参数塞进 ESP32-S3，证明了在极限硬件约束下跑生成式 AI 的工程可行性，适合嵌入式 AI 研究者和硬件极客深入研究。