개요
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()가 각 호출을 동일한 대화의 한 턴으로 처리하기 때문에 발생합니다. 서로 관련 없는 프롬프트가 히스토리에 누적되어 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 인스턴스를 생성하고 닫는 것도 유효한 해결 방법입니다. 프롬프트가 실제로 하나의 대화에 속하는 경우에만 리셋하지 않고 인스턴스를 재사용하세요.
문제 해결Hugging Face에서 cactus_needle-3.0.2 wheel에 대한 404 오류로 Needle 초기화가 실패하는 문제를 어떻게 해결하나요?
이 오류는 needle이 엔진 휠 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 휠을 계속 참조하는 패키지 버전을 사용하세요.
문제 해결Needle이 "5 June 19:30"의 시간을 연도로 파싱하고 날짜를 ungrounded로 표시하는 문제를 어떻게 해결할 수 있나요?
이것은 needle/__init__.py의 _source_years에 있는 정규식 버그입니다. 일/월 패턴이 (\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"처럼 명시적인 네 자리 연도를 포함하세요. needle._source_years("Book a table on 5 June 19:30")로 확인하세요. 이 호출은 set()을 반환해야 합니다. 그런 다음 pytest -q -m "not slow"를 실행하세요.