在ESP32-S3上运行Needle 2：分步DIY指南

模型45M 参数下载 13.7 MB / 约 14 MB 硬件ESP32-S3 N16R816 MB flash · 8 MB octal PSRAM 用途离线工具调用执行设备操作，不做通用对话源码状态已审核 2026-08-30作者已演示 · LocalClaw 尚未实测

原始演示

看 Better Stack 怎么把它搭起来

原始视频仍挂在项目页上。播放使用 YouTube 的隐私增强播放器，只有你点击播放后才会开始加载。

视频：I Can't Believe This AI Model Fits in 14 Megabytes (Needle 2)，作者 Better Stack。LocalClaw 不转载也不修改该视频。

!兼容性门槛

N16R8 不是可选项

随便一块标着 ESP32-S3 的板子不够用。参考实现要求 16 MB flash 和 8 MB octal PSRAM。2 MB 或 quad-PSRAM 的板子跑不了这套有文档记录的构建。芯片ESP32-S3，双核 Xtensa LX7Flash要求 16 MB；仅模型就需要约 13.1 MBPSRAM8 MB octal PSRAM；需要 N16R8 级别的板子LED板载 WS2812 RGB LED，位于 GPIO48，供随附的 demo 使用控制台UART 桥接 USB 口软件ESP-IDF 5.5+、Python 3、CMake 和 Git 验证边界： LocalClaw 已按审核时的 commit 对照作者仓库和 Cactus Compute 的模型页核对了上述要求与命令。审核的运行时 commit：61cafad7014a。LocalClaw 对本文做过源码层面的审核，但没有实际复现这套构建。

物料清单

买兼容的硬件

这些按钮会通过 LocalClaw 打开对应地区的 Amazon 搜索。下单前请在卖家页面确认具体规格。 01必需

ESP32-S3 N16R8 开发板

确认商品页明确写出 16 MB flash 和 8 MB octal PSRAM。只标 ESP32-S3 是不够的。在 Amazon 查看 ↗02未随附则必需

USB-C 数据线

要选能传数据的线，不能是只供电的充电线。烧录和串口控制台都依赖 USB 数据传输。在 Amazon 查看 ↗03可选

面包板与杜邦线套装

板载 RGB LED 已足够跑通随附的演示。要把工具调用改接到传感器或舵机上时，再加面包板和杜邦线。在 Amazon 查看 ↗ 联盟披露：作为 Amazon Associate，LocalClaw 可从符合条件的购买中获得收益。原始作者并不为这些购买链接背书，价格与库存可能发生变化。

分步操作

在 ESP32-S3 上构建 Needle 2

为保证技术准确性，命令均按原样保留；说明、顺序与检查项由 LocalClaw 依据所引用的第一手资料独立整理。

购买前先确认具体板型

参考移植版本针对的是某一款 N16R8 级别的 ESP32-S3 开发板。确认具备 16 MB flash、8 MB octal PSRAM，以及接在 GPIO48 上的板载 WS2812 LED。

排除 2 MB PSRAM 的版本。
排除未标明 flash 与 PSRAM 容量的商品页面。
不要以为所有 ESP32-S3 DevKit 都兼容。

安装主机端依赖

安装 ESP-IDF 5.5 或更新版本、Python 3、CMake 和 Git。先完成 Espressif 常规的工具链配置再继续。ESP-IDF 安装指南 →

克隆作者的实现

使用原始演示所用的 Apache-2.0 仓库。终端

git clone https://github.com/andrisgauracs/needle-2-esp32.git
cd needle-2-esp32

创建 Python 环境

辅助工具依赖 NumPy、Rich、PySerial、Hugging Face Hub 和 SentencePiece。终端

python3 -m venv .venv
.venv/bin/pip install numpy rich pyserial huggingface_hub sentencepiece

下载 Needle 2 模型

把官方的 Cactus Compute .cact 二进制文件下载到本地模型目录。该模型从 Hugging Face 下载，并不存放在 ESP32 仓库中。终端

mkdir -p model
.venv/bin/python -c "from huggingface_hub import hf_hub_download; import shutil; shutil.copy(hf_hub_download('Cactus-Compute/needle2', 'needle2.cact'), 'model/needle2.cact')"

构建并试运行宿主引擎

先编译桌面参考引擎。这样能在较慢的微控制器烧录流程之前，先发现宿主侧的配置问题。终端

cmake -S host -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j8
.venv/bin/python tools/needle_tui.py --local

构建并烧录 ESP32-S3 固件

加载 ESP-IDF 环境，将目标设为 ESP32-S3，构建固件，然后把示例串口替换成你机器上显示的端口。终端

. /path/to/esp-idf/export.sh
cd esp32/needle_demo
idf.py set-target esp32s3
idf.py build
idf.py -p /dev/cu.usbmodemXXXX flash

注意： 在 Linux 上，串口通常是 /dev/ttyUSB0 或 /dev/ttyACM0。在 macOS 上，用 ls /dev/cu.usb* 列出候选端口。

将模型写入其 flash 分区

回到仓库根目录，按参考项目使用的分区偏移量写入模型二进制文件。终端

cd ../..
esptool.py --chip esp32s3 -p /dev/cu.usbmodemXXXX -b 921600 write_flash 0x210000 model/needle2.cact

注意： 在作者记录的配置中，烧录模型大约需要三分钟，只有在模型变更时才需要重做。

运行终端界面并测试一个动作

启动串口 TUI，等待一次性的提示词预热，然后用自然语言请求一个 LED 动作。终端

.venv/bin/python tools/needle_tui.py --serial /dev/cu.usbmodemXXXX

测试提示词Flash a red light for 3 seconds.``Shine a purple light for 7 seconds.``What is the capital of France?注意： 最后一个提示词是故意放在工具 schema 之外的。正确的结果是空的工具调用，而不是聊天机器人的回答。

预期性能

慢、本地、有明确用途

工具调用、设备动作和结构化提取——不是通用聊天。所记录的 ESP32-S3 端口受算力限制，所以把它当作离线的设备动作演示，而不是对话助手。解码在记录的 240 MHz 开发板上为每秒 1.87 个 token推理关闭每个请求约 25 秒推理开启每个请求约 47 秒首次启动预热约 51 秒

故障排查

那些看起来神秘的故障

参考仓库记录了几种无声的配置故障。在改动推理引擎之前，先检查这些。没有串口输出使用 UART 桥接的 USB 端口，并让 ESP-IDF 的控制台选择保持默认。为控制台启用 USB-Serial/JTAG 可能会让程序看起来毫无输出。启动循环或 PSRAM 错误确认开发板有 8 MB octal PSRAM，并且 CONFIG_SPIRAM_MODE_OCT=y 和 CONFIG_SPIRAM_SPEED_80M=y 已生效。推理大约慢 1.5 倍检查 CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y 是否已应用。否则 ESP-IDF 可能会把 ESP32-S3 默认设为 160 MHz。模型选错动作Needle 2 受工具 schema 及其描述约束。让字段描述简短明确，并记住它是调度器，而不是通用聊天机器人。

来源与致谢

顺着作品找到创作者

原始演示由 Better Stack 发布。独立的 ESP32-S3 推理实现由 Andris Gauracs 构建并撰写文档。LocalClaw 的页面独立运营，不代表任何被引用的创作者、模型作者或工具维护者的认可。

许可说明： 本文引用的 ESP32 实现与 Needle 2 相关材料均标注 Apache 2.0 许可。LocalClaw 仅链接到原始仓库，不在本页面上重新分发其源代码或模型二进制文件。

常见问题

Needle 2 ESP32-S3 常见问题

Needle 2 能在任意 ESP32-S3 开发板上运行吗？不能。此移植版本要求 N16R8 级别的 ESP32-S3，即 16 MB flash 和 8 MB octal PSRAM。更小的或 quad-PSRAM 版本与文档所述的构建不兼容。Needle 2 是一个小型离线聊天机器人吗？不是。Needle 2 针对工具调用、设备操作和结构化提取进行训练。它会选择一个已声明的函数并填充其参数；它并未针对一般对话或世界知识进行训练。演示需要 Wi-Fi 或云 API 吗？不需要。推理和 LED 操作都在微控制器上本地运行。在设置期间需要互联网访问，以下载源代码依赖项和模型二进制文件。Needle 2 在 ESP32-S3 上有多快？文档所述的开发板达到约每秒 1.87 个 token。请求在不进行推理时约需 25 秒，进行推理时约需 47 秒。我能把 LED 换成舵机或其他设备吗？可以。仓库记录了由三部分组成的自定义流程：描述工具 schema、编写设备处理程序，并在固件中注册该处理程序。

← 浏览社区 DIY 构建