概要
Needle 2は、高度に圧縮された45Mパラメータモデルであり、単一の14MBバイナリにパッケージ化され、スマートフォン、ウェアラブルデバイス、ロボットを対象としています。ツール呼び出し、デバイス操作、構造化抽出をサポートし、信頼度ゲーティングを備え、メモリ使用量は約28MBです。Pythonパッケージは、推論、LoRAファインチューニング、エクスポート機能を提供します。
README プレビュー
\n\n# Needle 2\n\nNeedle 2 is an open 45M-parameter model for tool calling, device use and structured extraction. The whole model is a single 14MB binary that runs a full session in about 28MB of RAM. It is built on our Simple Attention Network findings, compressed to CQ2-bit with Cactus Quants, and baked into its own engine. On the benchmarks below, Needle 2 trades wins with other small models like FunctionGemma 270M, LFM2.5 230M and Apple FM, at 5x to 70x smaller, and 2 bits against their f16.\n\nThis repository is the Python package: inference, LoRA fine-tuning, and export. `pip install cactus-needle`, describe your tools, and call them from Python. The inference engine is fetched once from Hugging Face and cached; there is nothing else to build.\n\n- **Self-contained**: weights baked into a single 14MB engine; no separate model files to manage, and inference does no network.\n- **Simple contract**: tool calls come back as structured data, text in, JSON out; a byte-level grammar compiled from your schemas constrains every token.\n- **Confidence-gated**: every response carries a calibrated confidence score from a learned head; set a threshold, act above it, escalate below it.\n- **Tool retrieval**: declare a large catalogue and a built-in retrieval head renders only the top five tools per turn, with the grammar constrained to that subset.\n- **Bounded memory**: a 256-token sliding window with the tools pinned as KV sinks, so total memory stays near 28MB no matter how long the conversation runs.\n\nWeights: [huggingface.co/Cactus-Compute/needle2](https://huggingface.co/Cactus-Compute/needle2) · source: [github.com/cactus-compute/needle](https://github.com/cactus-compute/needle).\n\n\n\n## Simple Attention Network\n\nNeedle 2 is a Simple Attention Network, our dense small-model recipe: a Hadamard MLP in place of the FFN, GQA attention, engram key-value memory, and multi-lane hyper-connections. See the paper for the design and ablations: [arXiv:2607.18363](htt
FAQ (5)
トラブル対応cactus-needle 3.0.5 をインストールした後、cactus_needle-3.0.2 wheel の 'needle fetch' 404 を修正するにはどうすればよいですか?
この障害は、cactus-needle 3.0.5 が engine wheel 3.0.2 を要求しているのに対し、Hugging Face リポジトリには 3.0.0 と 3.0.1 しかないために発生します。
即時の回避策: engine を 3.0.1 にピン留めしている 3.0.4 へダウングレードしてください。
pip install --force-reinstall cactus-needle==3.0.4
needle fetchコードの修正では、needle/agent/fetch.py 内の ENGINE_VERSIONS[3] を 3.0.2 から公開済みの 3.0.1 wheel に戻すか、その修正を含むリリースをインストールします。あるいは、3.0.2 の wheel を Cactus-Compute/needle3 Hugging Face リポジトリにアップロードする必要があります。
トラブル対応needle finetune の実行時に "unrecognized arguments: --layers" エラーを修正する方法
needle finetune に --layers を渡さないでください。このオプションは古いヘルプテキストに記載されているだけで、finetune パーサーではサポートされていません。これを指定せずにファインチューニングを実行してください。例: needle finetune data.jsonl --checkpoint <path>。Rung の選択はビルドステップで行います。needle build --layers N を使用してください。ローカルでのファインチューニングは全 20 レイヤーで実行されます。古いヒントが引き続き表示される場合は、CLI ヘルプの修正を含むリリースに更新してください。
トラブル対応Needle generation=2 インスタンスを再利用する際に、交互の連続リクエストで `function_calls` が空になる問題を修正する方法
これは、complete()/_complete() が各呼び出しを同一の会話における1つのターンとして扱うために発生します。無関係なプロンプトが履歴に蓄積され、confidence が低下したり、ツール呼び出しが function_calls: [] と交互に現れたりする原因となります。
独立したプロンプトの場合は、呼び出しの合間に会話をリセットしてください:
agent = needle.Needle(tools=[get_weather, send_message], generation=2)
for prompt in prompts:
resp = agent._complete(prompt)
print(resp["function_calls"], resp["confidence"])
agent.reset()
agent.close()あるいは、インストールされているバージョンに含まれている場合は、stateless モードを使用してください:
agent = needle.Needle(
tools=[get_weather, send_message],
generation=2,
stateless=True,
)stateless=True を指定すると、各クエリの前に自動的にリセットされます。独立したリクエストごとに新しい Needle インスタンスを作成してクローズすることも、有効な回避策です。リセットせずにインスタンスを再利用するのは、プロンプトが実際に1つの会話の一部である場合のみにしてください。
トラブル対応Hugging Face で cactus_needle-3.0.2 wheel の 404 により Needle の初期化が失敗する問題を解決するにはどうすればよいですか？
この失敗は、needle がエンジンの wheel cactus_needle-3.0.2-py3-none-manylinux2014_x86_64.whl を要求する一方で、Cactus-Compute/needle3 の Hugging Face リポジトリには 3.0.0 と 3.0.1 しか公開されていないために発生します。fetch の修正を含むリリースへ cactus-needle をアップグレードしてください。修正済みのリリースがまだインストールされていない場合は、ローカルでエンジンを 3.0.1 に固定してください:
import pathlib, needle
p = pathlib.Path(needle.__file__).parent / "agent" / "fetch.py"
s = p.read_text()
p.write_text(s.replace("3.0.2", "3.0.1"))その後、Python プロセス/Colab ランタイムを再起動し、needle.Needle() を再度初期化してください。あるいは、利用可能な 3.0.1 の wheel をまだ参照しているパッケージバージョンを使用してください。
トラブル対応Needle が "5 June 19:30" の時刻を年として解析し、日付を ungrounded としてマークしてしまう問題は、どのように修正すればよいですか？
これは _source_years 内の needle/__init__.py における正規表現のバグです。日/月パターンが (\d{1,4})(?![0-9A-Za-z]) を使用しているため、19:30 の 19、14:00 の 14、7 pm の 7 が誤って年として扱われます。issue #153 の修正を含むリリースにアップグレードしてください。直ちにパッチを適用する必要がある場合は、末尾の年の先読みを時刻の接尾辞を拒否するように変更してください。例えば: (\d{1,4})(?!\s*:\d{2}|\s*[ap]\.?m\.?(?![A-Za-z])|[0-9A-Za-z]) とし、大文字小文字を区別しないマッチングを行います。これでも "5th September 42" のような短い年は引き続き許容されます。一時的な回避策として、"5 June 2026 19:30" のように明示的な4桁の年を含めてください。needle._source_years("Book a table on 5 June 19:30") で検証してください。これは set() を返すはずです。その後、pytest -q -m "not slow" を実行してください。