Needle 最不为人知的秘密不是工具调用，而是结构化提取。输入长文本，输出有效 JSON。仅 14MB 大小即可在浏览器中运行。JSON 架构由与工具调用相同的约束采样技术保证。
https://t.co/FH18v6a3iT https://t.co/BHU2ZdqRpC

cactus-compute/needle

来源：https://github.com/cactus-compute/needle

Needle 2

Needle 2 是一个开源的 45M 参数模型，专注于工具调用、设备操作和结构化提取。整个模型是一个 14MB 的单一二进制文件，运行时仅占用约 28MB 内存。基于我们的简单注意力网络（Simple Attention Network）研究成果构建，通过仙人掌量化（Cactus Quants）压缩至 CQ2 位，并封装在其专属引擎中。

在以下基准测试中，Needle 2 与其他小模型（如 FunctionGemma 270M、LFM2.5 230M 和 Apple FM）各有胜负，体积缩小 5 至 70 倍，使用 2 位量化对比对方的 f16 精度。

本仓库提供 Python 包：包含推理、LoRA 微调和导出功能。

pip install cactus-needle  

只需描述工具，即可在 Python 中调用。推理引擎首次运行时从 Hugging Face 获取并缓存；无需额外构建，离线设备部署方案详见 doc/apis.md。

• 自包含：权重封装在单个 14MB 引擎内；无需管理独立模型文件，推理过程无网络请求。
• 简洁契约：工具调用以结构化数据返回，输入文本、输出 JSON；字节级语法根据您的架构约束每个生成的 token。
• 置信度门控：每个响应都携带经学习头校准的置信度分数；设置阈值，高于阈值直接执行，低于阈值则上报处理。
• 工具检索：声明大型工具库时，内置检索头每轮仅呈现前五项工具，且语法约束仅应用于该子集。
• 内存可控：256 token 滑动窗口配合工具作为 KV 缓存锚点，确保对话时长不影响总内存（始终约 28MB）。

权重：huggingface.co/Cactus-Compute/needle2 (https://huggingface.co/Cactus-Compute/needle2)
源码：github.com/cactus-compute/needle (https://github.com/cactus-compute/needle)

质量-体积前沿：适用于移动端及更轻量级场景

简单注意力网络

Needle 2 采用简单注意力网络（Simple Attention Network），这是我们专为紧凑型模型设计的密集架构：

• 用 Hadamard MLP 替换前馈网络
• 采用分组查询注意力（GQA）
• 集成记忆痕迹键值存储（engram key-value memory）
• 多通道超连接（multi-lane hyper-connections）

设计细节与消融实验详见论文：arXiv:2607.18363 (https://arxiv.org/abs/2607.18363)

简单注意力网络架构
每个模块包含其更新规则。其中：

• x̂ 是四条残差流的 RMS 标准化展平结果
• H 是正交沃尔什-哈达玛变换（固定矩阵，以 n log n 时间复杂度应用，无需读取权重）
• (kt, vt) 行来自哈希 n-gram 表
• P 是路由逻辑 A 的双随机归一化结果，通过 Sinkhorn 迭代计算
• a、b、g 及所有 σ 门均为可学习的输入相关参数

注意力与 MLP 残差均经过三明治归一化与门控处理；记忆痕迹位点在两层被激活；解码过程受声明架构编译的字节级语法约束。

快速开始

pip install cactus-needle  

运行时包不包含训练栈。使用微调或检查点导出时需添加 train 额外依赖：

pip install "cactus-needle[train]"  

Needle 会读取您的工具描述来决定调用方式及参数填充，因此良好的描述是关键。

简单用法：用装饰器定义函数。签名提供参数类型，文档字符串作为工具描述，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 模型即可获得类型化对象。

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 架构、驱动循环的 complete() 方法、响应契约、系统提示、工具检索及置信度门控等详细信息，请参阅 doc/apis.md。

演示平台

在浏览器中体验任意模型：选择预设模板，编辑工具或提示，点击运行。后续查询会延续同一对话。

needle playground  
# 基础模型，访问 http://127.0.0.1:7860  

needle playground --weights my.cact  
# 使用微调模型  

服务器会在启动时下载并初始化模型，因此首次查询立即响应。微调这些工具按钮可通过界面运行下方微调流程，并返回可下载的 .cact 文件。

预设环境

needle.environments 提供现成的工具集：smart_home（智能家居）、media_player（媒体播放器）、productivity（生产力工具）、wearable（可穿戴设备）、kitchen_appliance（厨房电器）和 data_capture（数据采集）。每个工具集经过人工策划，其枚举值、边界和描述完美适配 Needle 的约束解码机制，并包含现成的代理程序和冻结的测试套件。

from needle.environments import smart_home  

smart_home.agent.complete("dim the study lights to 30 percent")  
smart_home.run_tests()  

通过 python -m needle.environments.smart_home 可从终端运行测试套件。若要将环境适配到您的产品，只需替换 Literal 值（如房间、联系人、类别），保持数据结构：封闭集用枚举表示，有界数值保持范围，自由文本直接复制，工具数量控制在五个以内。完整工具集与套件契约详见 doc/environments.md。

微调

Needle 使用 LoRA 在冻结的基础模型上进行微调，并在导出时合并适配器，因此单次运行成本低廉，且微调后的模型仍是单个 .cact 文件，可直接运行于同一引擎。

工作流程包括：（可选）数据合成→LoRA 微调→构建微调版 .cact。
详见 doc/finetuning.md 了解数据集规模、损失曲线解读及问题排查。

数据格式：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。可从工具架构文件生成种子数据，或扩展现有数据集：

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  

设置 OPENROUTER_URL 可使用 OpenAI 兼容网关替代默认 OpenRouter 端点。

2. LoRA 微调
若未指定 --checkpoint，基础检查点将自动从 Hugging Face 下载。--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、--checkpoint-dir（默认 checkpoints）、--out、--generate、--model（默认 deepseek/deepseek-v4-flash）、--workers（默认 8）。

--generate 使用配置的 OpenRouter 端点在训练前合成额外示例。适配器默认写入 checkpoints/needle_lora.pkl。每个 epoch 都会从验证集打印验证损失。训练基于纯 JAX 实现，支持所有 JAX 兼容加速器。

在 NVIDIA 机器上安装 CUDA 版本即可在 GPU 上训练：

pip install "cactus-needle[train,gpu]"  

在 Apple Silicon 上使用 metal 依赖进行 GPU 训练：

pip install "cactus-needle[train,metal]"  

3. 构建微调版 .cact
将适配器合并到基础模型并量化。若基础模型不存在将自动下载。

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

添加 --bits 2 可获得更小模型（默认情况下，导出会沿用检查点声明的逐层位宽映射，若未声明则回退至 4 位）。设置 NEEDLE_HF_REPO=/ 并传入 --upload 可发布 .cact 文件。对应的 needle download //my_needle.cact 命令可在任意机器拉取已发布的归档文件，needle download <platform>（如 macos-arm64）则获取对应平台的引擎运行器。

4. 运行模型
引擎与权重解耦，因此微调后的 .cact 文件可直接运行，无需重新编译：

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

遥测数据

Cactus Compute 仅收集完全匿名的使用数据（函数名称、包版本、操作系统），绝不涉及提示内容、输出结果或用户数据。可通过 NEEDLE_TELEMETRY=0 或 DO_NOT_TRACK=1 选择退出。

引用

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}}  
}  

如需合作、协同或在产品中部署 Needle 2，请联系 [email protected]。