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 LX7Flash16 MB 必須。モデルだけで約 13.1 MB を占めるPSRAM8 MB octal PSRAM。N16R8 クラスのボードが必要LEDオンボードの WS2812 RGB LED、GPIO48。付属デモが使用コンソール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 で見る ↗ アフィリエイト開示：LocalClaw は Amazon Associate として、条件を満たす購入から収益を得ることがある。元の作者はこれらの購入リンクを推奨していない。価格と在庫は変わりうる。

手順

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

注意： 作者の記録した構成では、モデルの書き込みには約 3 分かかる。やり直しが必要なのはモデルを変更したときだけ。

ターミナル UI を起動して 1 つのアクションを試す

シリアル 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 トークン。推論オフで 1 リクエスト約 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 に関する FAQ

Needle 2 はどの ESP32-S3 開発ボードでも動きますか？動きません。この移植版は N16R8 相当の ESP32-S3、つまり 16 MB flash と 8 MB octal PSRAM を必要とします。より小さいものや quad-PSRAM のものは、文書化されているビルドとは互換性がありません。Needle 2 は小型のオフラインチャットボットですか？違います。Needle 2 はツール呼び出し、デバイス操作、構造化抽出のために訓練されています。宣言された関数を 1 つ選び、その引数を埋めるだけで、一般的な会話や世界知識のために訓練されたものではありません。デモに Wi-Fi やクラウド API は必要ですか？不要です。推論も LED の操作もマイコン上でローカルに動作します。インターネット接続が必要なのは、セットアップ中にソースコードの依存関係とモデルバイナリをダウンロードするときだけです。Needle 2 は ESP32-S3 でどのくらい速いですか？文書化されている開発ボードでは毎秒約 1.87 トークンです。リクエストには推論なしで約 25 秒、推論ありで約 47 秒かかります。LED をサーボや他のデバイスに置き換えられますか？できます。リポジトリには、ツール schema を記述し、デバイスハンドラを書き、そのハンドラをファームウェアに登録するという 3 段階のカスタム手順が記録されています。

← コミュニティのDIYビルドを見る