cactus-compute/needle

Needle 2

Needle 2 เป็นโมเดลแบบเปิดขนาด 45M พารามิเตอร์สำหรับการเรียกใช้เครื่องมือ การใช้งานบนอุปกรณ์ และการดึงข้อมูลแบบมีโครงสร้าง โมเดลทั้งหมดเป็นไบนารีขนาด 14MB เพียงไฟล์เดียวที่สามารถรันเซสชันเต็มรูปแบบโดยใช้ RAM ประมาณ 28MB สร้างขึ้นจากผลการวิจัย Simple Attention Network ของเรา บีบอัดเป็น CQ2-bit ด้วย Cactus Quants และฝังอยู่ในเอนจินของตัวเอง จากการทดสอบประสิทธิภาพด้านล่าง Needle 2 มีผลลัพธ์ที่สามารถแข่งขันกับโมเดลขนาดเล็กอื่นๆ เช่น FunctionGemma 270M, LFM2.5 230M และ Apple FM โดยมีขนาดเล็กกว่า 5 ถึง 70 เท่า และใช้ 2 บิตเทียบกับ f16 ของโมเดลเหล่านั้น

repository นี้คือแพ็กเกจ Python: สำหรับการอนุมาน (inference), การปรับแต่ง LoRA (LoRA fine-tuning) และการส่งออก (export) เพียงแค่ pip install cactus-needle อธิบายเครื่องมือของคุณ แล้วเรียกใช้จาก Python เอนจินสำหรับการอนุมานจะถูกดึงมาครั้งเดียวจาก Hugging Face และแคชไว้ ไม่จำเป็นต้องสร้างอะไรเพิ่มเติม และการตั้งค่าแบบออฟไลน์สำหรับอุปกรณ์ที่ไม่มีการเชื่อมต่อเครือข่ายก็มีระบุไว้ใน doc/apis.md

• ครบวงจรในตัวเอง: น้ำหนักโมเดลถูกฝังอยู่ในเอนจินขนาด 14MB เพียงไฟล์เดียว ไม่ต้องจัดการไฟล์โมเดลแยกต่างหาก และการอนุมานไม่จำเป็นต้องใช้เครือข่าย
• สัญญาที่เรียบง่าย: การเรียกใช้เครื่องมือจะส่งกลับมาเป็นข้อมูลที่มีโครงสร้าง โดยรับข้อความเข้าและส่งออกเป็น JSON; ไวยากรณ์ระดับไบต์ที่คอมไพล์จาก schema ของคุณจะจำกัดทุกโทเค็น
• มีเกณฑ์ความเชื่อมั่น: ทุกการตอบสนองมีคะแนนความเชื่อมั่นที่ปรับเทียบแล้วจาก learned head; คุณสามารถกำหนดเกณฑ์ ทำงานเมื่อคะแนนสูงกว่า และส่งต่อเมื่อคะแนนต่ำกว่า
• การดึงเครื่องมือ: ประกาศแค็ตตาล็อกขนาดใหญ่ และ retrieval head ในตัวจะแสดงเฉพาะเครื่องมือห้าอันดับแรกต่อรอบ โดยไวยากรณ์จะถูกจำกัดเฉพาะชุดย่อยนั้น
• หน่วยความจำที่จำกัด: หน้าต่างเลื่อนขนาด 256 โทเค็นพร้อมเครื่องมือที่ถูกตรึงไว้เป็น KV sinks ทำให้หน่วยความจำรวมยังคงอยู่ใกล้ 28MB ไม่ว่าการสนทนาจะดำเนินไปนานแค่ไหน

น้ำหนักโมเดล: huggingface.co/Cactus-Compute/needle2 · ซอร์สโค้ด: github.com/cactus-compute/needle

Simple Attention Network

Needle 2 เป็น Simple Attention Network ซึ่งเป็นสูตรโมเดลขนาดเล็กแบบหนาแน่นของเรา: ใช้ Hadamard MLP แทน FFN, GQA attention, engram key-value memory และ multi-lane hyper-connections ดูเอกสารวิจัยสำหรับการออกแบบและการทดลองตัดส่วนประกอบ (ablations): arXiv:2607.18363

แต่ละบล็อกมีกฎการอัปเดตของตัวเอง โดยที่ x̂ คือการปรับให้เป็น RMS-normalised ของสี่ residual streams, H คือการแปลง Walsh-Hadamard แบบ orthonormal (เมทริกซ์คงที่ที่ใช้ในเวลา n log n โดยไม่มีน้ำหนักให้อ่าน), (kₜ, vₜ) คือแถวที่รวบรวมจากตาราง n-gram ที่ถูกแฮช, และ P คือการปรับให้เป็น doubly-stochastic normalisation ของ routing logits A ซึ่งคำนวณโดย Sinkhorn iteration; a, b, g และ σ-gates ทั้งหมดถูกเรียนรู้และขึ้นอยู่กับอินพุต ทั้ง attention และ MLP residuals ถูก sandwich-normed และ gated, engram sites ทำงานที่สองเลเยอร์ และการถอดรหัสถูกจำกัดด้วยไวยากรณ์ระดับไบต์ที่คอมไพล์จาก schemas ที่ประกาศไว้

Quickstart

pip install cactus-needle

Needle อ่านคำอธิบายเครื่องมือของคุณเพื่อตัดสินใจว่าจะเรียกใช้อะไรและจะเติมอาร์กิวเมนต์อย่างไร ดังนั้นการอธิบายเครื่องมือให้ดีจึงเป็นสิ่งสำคัญที่สุด

แบบง่าย: ตกแต่งฟังก์ชันด้วย decorator ซิกเนเจอร์ของฟังก์ชันจะระบุประเภทอาร์กิวเมนต์ ส่วน docstring คือคำอธิบายเครื่องมือ และ run() จะทำให้ลูปสมบูรณ์: โมเดลเลือกการเรียกใช้, Needle รันฟังก์ชันของคุณ, ป้อนผลลัพธ์กลับไป, และส่งคืนการตอบสนองสุดท้ายพร้อมผลลัพธ์ของเครื่องมือที่รันแล้วแนบมาใน results

import needle

@needle.tool
def get_weather(city: str):
    "Get the current weather for a city."
    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'}]

การดึงข้อมูล: หากต้องการดึงข้อมูลที่มีโครงสร้างออกจากข้อความ ให้ประกาศรูปร่างของข้อมูลและเรียกใช้ extract() ส่ง Pydantic model เข้าไป แล้วคุณจะได้อ็อบเจกต์ที่มีประเภทกลับมา

from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    due_date: str

invoice = needle.extract("Invoice from Acme Corp, $1,200.00, due 2026-09-01", Invoice)
print(invoice.vendor, invoice.total)   # -> Acme Corp 1200.0

คำอธิบายและตัวเลือกต่ออาร์กิวเมนต์, ข้อจำกัดค่าที่คอมไพล์ลงในไวยากรณ์การถอดรหัส, JSON schemas ดิบ, การขับเคลื่อนลูปด้วย complete(), สัญญาการตอบสนอง, ข้อเท็จจริงของระบบ, การดึงเครื่องมือ และ confidence gating ทั้งหมดนี้ครอบคลุมอยู่ใน doc/apis.md

Playground

ลองใช้โมเดลใดก็ได้ในเบราว์เซอร์: เลือก preset, แก้ไขเครื่องมือหรือ prompt แล้วกด Run การสอบถามติดตามผลจะดำเนินต่อไปในการสนทนาเดียวกัน

needle playground                      # base model, http://127.0.0.1:7860
needle playground --weights my.cact    # a tuned model

เซิร์ฟเวอร์จะดาวน์โหลดและเริ่มต้นโมเดลก่อนที่จะให้บริการ ดังนั้นการสอบถามครั้งแรกจะใช้เวลาสักครู่ ปุ่ม Finetune on these tools จะรันไปป์ไลน์การปรับแต่งด้านล่างจาก UI และส่งคืนไฟล์ .cact ที่สามารถดาวน์โหลดได้

การปรับแต่ง (Fine-tuning)

Needle ปรับแต่งด้วย LoRA บนฐานโมเดลที่ถูกตรึง (frozen base) และรวมอะแดปเตอร์เข้าด้วยกันเมื่อส่งออก ดังนั้นการรันจึงมีค่าใช้จ่ายต่ำ และโมเดลที่ปรับแต่งแล้วยังคงเป็นไฟล์ .cact ไฟล์เดียวที่รันบนเอนจินเดียวกัน ขั้นตอนการทำงานคือ: (ทางเลือก) สังเคราะห์ข้อมูล, ปรับแต่ง LoRA, จากนั้นสร้างไฟล์ .cact ที่ปรับแต่งแล้ว ดู doc/finetuning.md สำหรับขนาดชุดข้อมูล, การอ่านกราฟ loss และการแก้ไขปัญหา

รูปแบบข้อมูล ไฟล์ JSONL โดยมีหนึ่งตัวอย่างต่อบรรทัด reasoning เป็นทางเลือก; ตัวอย่างที่ไม่อยู่ในหัวข้อจะมี answers: []

{"query": "dim the kitchen to 10", "tools": [{"name": "set_lights", "parameters": {"type": "object", "properties": {"room": {"type": "string"}, "brightness": {"type": "integer"}}, "required": ["room"]}}], "answers": [{"name": "set_lights", "arguments": {"room": "kitchen", "brightness": 10}}], "reasoning": "'kitchen' -> room; 'dim to 10' -> brightness 10"}

1. สังเคราะห์ข้อมูล (ไม่บังคับ) ต้องใช้ OPENROUTER_API_KEY เริ่มต้นจากไฟล์ tool schema หรือขยายชุดข้อมูลที่มีอยู่:

export OPENROUTER_API_KEY=sk-or-...
needle generate-data --tools my_tools.json --num-samples 500 --output data.jsonl
needle generate-data --augment data.jsonl --num-samples 500      # expand an existing JSONL

ตั้งค่า OPENROUTER_URL เพื่อใช้เกตเวย์ที่เข้ากันได้กับ OpenAI แทน endpoint ของ OpenRouter เริ่มต้น

2. ปรับแต่ง LoRA checkpoint ฐานจะดาวน์โหลดอัตโนมัติจาก Hugging Face หากคุณไม่ได้ส่ง --checkpoint --generate N จะสังเคราะห์ตัวอย่างเพิ่มเติม N ตัวอย่างจากเครื่องมือในข้อมูลของคุณก่อน (ยังต้องใช้ OPENROUTER_API_KEY)

needle finetune data.jsonl --epochs 10
needle finetune data.jsonl --epochs 10 --generate 300 --lora-rank 16 --lora-alpha 32

ตัวเลือกสำคัญ: --epochs (ค่าเริ่มต้น 3), --lora-rank (16), --lora-alpha (32), --lr (1e-4), --batch-size (16), --max-len (1024), --val-split (0.1), --checkpoint <base.pkl>, --out <adapter.pkl> อะแดปเตอร์จะถูกเขียนไปยัง checkpoints/needle_lora.pkl ค่า validation loss จะถูกพิมพ์ออกมาในแต่ละ epoch จากส่วนที่ถูกกันไว้

การฝึกอบรมเป็น JAX ธรรมดาและรันบน accelerator ใดๆ ที่ JAX รองรับ บนเครื่อง NVIDIA ให้ติดตั้ง CUDA build และคำสั่งเดียวกันนี้จะฝึกอบรมบน GPU:

pip install "cactus-needle[gpu]"

บน Apple Silicon ส่วนเสริม metal จะฝึกอบรมบน GPU:

pip install "cactus-needle[metal]"

3. สร้างไฟล์ .cact ที่ปรับแต่งแล้ว รวมอะแดปเตอร์เข้ากับฐานโมเดลและควอนไทซ์ ฐานโมเดลจะดาวน์โหลดอัตโนมัติหากไม่มีอยู่

needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.pkl --out my_needle.cact

เพิ่ม --bits 2 สำหรับโมเดลที่เล็กลง (โดยค่าเริ่มต้น การส่งออกจะตามแผนที่บิตต่อเลเยอร์ที่ประกาศไว้ใน checkpoint โดยจะกลับไปใช้ 4 บิตหาก checkpoint ไม่ได้ประกาศไว้) หรือตั้งค่า NEEDLE_HF_REPO=<you>/<model> และส่ง --upload เพื่อเผยแพร่ไฟล์ .cact คำสั่ง needle download <you>/<model>/my_needle.cact ที่ตรงกันจะดึงไฟล์เก็บถาวรที่เผยแพร่แล้วบนเครื่องใดก็ได้

4. รันโมเดล เอนจินไม่ขึ้นกับน้ำหนักโมเดล ดังนั้นไฟล์ .cact ที่ปรับแต่งแล้วสามารถรันบนเอนจินได้โดยตรง - ไม่ต้องคอมไพล์ใหม่:

import needle
agent = needle.Needle(weights="my_needle.cact", tools=[...])
agent.run("...")

การอ้างอิง

Needle 2 สร้างโดยทีม Cactus Compute หากคุณใช้ในงานของคุณ โปรดอ้างอิง:

@misc{needle2_2026,
  title        = {Needle 2: A 45M-Parameter Foundation Tool-Calling Model for Tiny Devices},
  author       = {Ndubuaku, Henry and Mosoyan, Karen and Mroz, Jakub and Cylich, Noah and
                  Kumar, Satyajit and Sandhu, Parkirat and Shemet, Roman and Lee, Justin H.},
  year         = {2026},
  organization = {Cactus Compute, Inc.},
  howpublished = {\url{https://github.com/cactus-compute/needle}}
}

ติดต่อ founders@cactuscompute.com สำหรับการเป็นพันธมิตร ความร่วมมือ การทำงานร่วมกัน และการนำ Needle2 ไปใช้ในผลิตภัณฑ์ของคุณ