ESC
AI 2 分钟阅读

Needle：面向微型设备的14MB基础模型；手机、可穿戴设备、智能家居和机器人

Needle 2是一个开放4500万参数模型，用于工具调用、设备使用和结构化提取。整个模型是单个14MB二进制文件，运行完整会话约需28MB内存。基于简单注意力网络，压缩至CQ2位，并内置引擎。在基准测试中与其他小模型互有胜负，但体积小5到70倍。提供Python包，支持推理、LoRA微调和导出。

来源：GitHub日榜

Needle

Needle 2

Needle 2 是一个开放的4500万参数模型，用于工具调用、设备使用和结构化提取。整个模型是单个14MB二进制文件，运行完整会话约需28MB内存。它基于我们的简单注意力网络研究成果，使用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 sink，因此无论对话多长，总内存都保持在28MB附近。

权重：huggingface.co/Cactus-Compute/needle2 · 源代码：github.com/cactus-compute/needle。

大小-质量前沿：移动端及以下

简单注意力网络

Needle 2 是一个简单注意力网络，我们密集小型模型的配方：用Hadamard MLP替代FFN，GQA注意力，engram键值记忆，以及多通道超连接。设计和消融见论文：arXiv:2607.18363。

简单注意力网络架构

每个块携带其更新规则。这里x̂是四个残差流的RMS归一化展平，H是正交Walsh-Hadamard变换（固定矩阵，以n log n时间应用，无需读取权重），(kₜ, vₜ)行从哈希n-gram表中收集，P是路由逻辑A的双随机归一化，通过Sinkhorn迭代计算；a、b、g及所有σ门都是可学习的且与输入相关。注意力和MLP残差都经过三明治归一化和门控，engram位点在两层触发，解码由从声明的模式编译的字节级语法约束。

快速开始

pip install cactus-needle

Needle读取你的工具描述来决定调用什么以及如何填充参数，因此良好地描述它们是关键。

简单：装饰一个函数。签名提供参数类型，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模型，返回类型化对象。

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    # 自定义模型

服务器在服务前下载并初始化模型，因此首次查询是即时的。Finetune on these tools按钮从UI运行下述微调流程，并返回可下载的.cact文件。

微调

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      # 扩展现有JSONL

设置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 <base.pkl>、--out <adapter.pkl>。适配器写入checkpoints/needle_lora.pkl。每个epoch从保留分割集打印验证损失。

训练是纯JAX，可在JAX支持的任何加速器上运行。在NVIDIA机器上安装CUDA版本，同一命令在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（默认4）以获得更小的模型，或设置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部署到你的产品中。