cactus-compute/needle

Needle – 超小型デバイス向け基盤モデル

概要 – Needleは、モバイル、ウェアラブル、ロボット、スマートホームハブ、車載ECU、さらにはマイクロコントローラーといった非常に小さなデバイスに適合する基盤モデルファミリー（最新は Needle 3）です。モデル全体が単一の8‑29 MBのバイナリ（.cactファイル）として提供され、CPU、WASI、ブラウザ、その他のエッジランタイムで動作するカスタムC++エンジン上で実行されます。

主な機能

機能	内容
ツール呼び出し	公開したPython関数（ツール）のリストに基づき、Needleは適切なツールを選択し、自然言語入力からすべての引数を埋めます。複数の呼び出しを順次返すことも、一致するツールがない場合に空のリストを返すことも可能です。
構造化抽出	JSONスキーマ（形状）を宣言します。乱雑なテキストを入力すると、Needleは常に解析可能な型付きフィールドを、調整済みの信頼度スコアと共に返します。
テキスト埋め込み	同一モデルで任意の文に対して高密度ベクトルを出力でき、ローカルでのセマンティック検索、ルーティング、類似度マッチングを可能にします。
音声認識 (Whistle)	Needleのエンジンを共有する16.9 MBの音声モデルです。言語検出、タイムスタンプ、キーワードバイアス、ストリーミングサポートを備えたワンパス転写（最大30秒）が可能です。
信頼度スコア	すべての応答には学習済みの信頼度ヘッドが含まれており、アプリケーションが行動するか、明確化を求めるか、拒否するかを判断できます。

仕組み

• 階層化Simple Attentionネットワーク – 各深さ（2‑20層）が完全にデプロイ可能なサブモデルである「Simple Attention」バックボーン。従来のフィードフォワードネットワークの代わりにMonarch Hadamard MLP、因果畳み込みタップを備えたGQAアテンション、engram n‑gramメモリ、マルチレーンハイパーコネクションを使用しています。
• パラメータ効率 – ほとんどの重みはengramに存在し、121 Mパラメータのモデルが50 Mパラメータモデルのように動作します。
• バイトレベル文法 – JSONスキーマからコンパイルされた文法がトークン生成を制約し、構文的に正しい出力を保証します。
• 量子化 – 重みは1重みあたり2.125ビット（Cactus Quants）で保存され、出荷されるバイナリは8‑29 MBです。

はじめに

pip install cactus-needle          # コアライブラリ + ランタイム
pip install "cactus-needle[train]"  # オプションのトレーニングユーティリティ

import needle

@needle.tool
def get_weather(city: str):
    """都市の現在の天気を取得します。"""
    return {"city": city, "temp_c": 27, "sky": "clear"}

agent = needle.Needle(tools=[get_weather])
print(agent.run("what's it like in Lagos right now?")['results'])
# → [{'city': 'Lagos', 'temp_c': 27, 'sky': 'clear'}]

• run呼び出しは、function_calls、モデル内部のreasoningトレース、およびconfidenceスコアを含むJSONオブジェクトを返します。
• 音声の場合は、単にneedle.transcribe("clip.wav")を呼び出すか、ストリーミングAPI needle.stream(chunks)を使用してください。

ベンチマーク

• ツール呼び出し – 完全なテスト分割における完全一致精度は、10倍のサイズのモデルを上回ります。
• 構造化抽出 – フィールドレベルのmicro‑F1は、より大きなベースラインを上回ります。
• Whistle – Whisper‑baseよりも8.6倍小さく、最初のトークンまでの速度が6.6倍速く、LibriSpeech、SPGISpeech、Earnings‑22、FLEURSなどで低い単語誤り率を達成しています（リポジトリ内のベンチマークSVGおよびCactus Computeサイトの詳細テーブルを参照）。

カスタマイズと微調整

• LoRAベースのローカル微調整 (needle finetune) – ベースを凍結したままアテンション投影のアダプターをトレーニングし、needle buildで微調整済み.cactをエクスポートします。
• フルモデルプラットフォーム微調整 (needle platform finetune) – Cactus GPU上で実行され、すべての深さをトレーニングし、オプションで信頼度ヘッドを再調整し、任意の層数に対応する微調整済みバイナリを返します。
• 微調整されたサブネットワーク（最小2層）は、特定のツールセットにおいてDeepSeek V4 Flashのような29 Mパラメータモデルを上回ることがあります。

デプロイメント

• ターゲットプラットフォーム（macOS‑arm64, linux‑arm64, WASIなど）ごとに事前構築されたエンジンバイナリが提供されます。
• needle build --platform <folder> [--layers N]でデプロイメントフォルダを構築します。このコマンドは適切なエンジンを取得し、その横に.cact重みを配置します。
• バイナリを直接実行します：./macos-arm64/needle --model needle3.cact --tools tools.json --serve。
• テレメトリはデフォルトで有効です。NEEDLE_TELEMETRY=0およびDO_NOT_TRACK=1で無効にできます。

リソース

• モデルの重みとエンジン – Hugging Faceリポジトリ Cactus-Compute/needle3 および Cactus-Compute/whistle。
• ドキュメントとガイド – 設計ツール、信頼度処理、構造化抽出、微調整、サポートデバイス、.cactファイル形式、移植ノートはすべてCactus Computeブログにあります（READMEにリンクが記載されています）。
• インタラクティブデモ – https://cactuscompute.com/needle でブラウザ上でNeedleを試してください。

引用 研究や製品でNeedleを使用する場合は、提供されているBibTeXエントリを引用してください。

---

上記の情報はすべてリポジトリのREADMEから直接取得したものであり、外部の仮定は追加されていません。