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초)를 지원합니다.
신뢰도 점수	모든 응답에는 학습된 신뢰도 헤드(confidence head)가 포함되어 있어, 애플리케이션이 행동할지, 명확화를 요청할지, 거부할지 결정할 수 있습니다.

작동 원리

• 계층화된 Simple Attention 네트워크 – 각 깊이(2‑20층)가 완전히 배포 가능한 서브 모델인 "Simple Attention" 백본. 기존 피드포워드 네트워크 대신 Monarch Hadamard MLP, 인과 컨볼루션 탭이 있는 GQA 어텐션, engram n‑gram 메모리, 멀티 레인 하이퍼 커넥션을 사용합니다.
• 파라미터 효율성 – 대부분의 가중치는 engram에 저장되며, 121 M 파라미터 모델이 50 M 파라미터 모델처럼 동작합니다.
• 바이트 수준 문법 – JSON 스키마에서 컴파일된 문법이 토큰 생성을 제한하여 구문적으로 올바른 출력을 보장합니다.
• 양자화 – 가중치는 가중치당 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에서 직접 가져온 것이며, 외부의 가정은 추가되지 않았습니다.