Cactus-Compute/needle3 · Hugging Face

来源：https://huggingface.co/Cactus-Compute/needle3
Needle (https://huggingface.co/Cactus-Compute/needle3/blob/main/assets/banner.svg)
一款为移动设备、可穿戴设备、机器人、智能家居、汽车和微控制器设计的基础模型。整个模型仅是一个大小为8-29 MB的单文件，我们通过牺牲通用聊天能力，使其在移动设备工具调用方面超越了体积是其10倍的模型，并在信息提取能力上匹配了2-3倍体积的模型。Needle 在设备端执行三项任务：

• 工具调用：根据您的应用暴露的函数，Needle 会选出正确的函数，并根据用户所说内容填充每个参数。如果您要求两件事，它会按顺序进行两次调用；如果您请求的是某个工具未覆盖的功能，它会返回一个空列表，而不是猜测。
• 结构化提取：声明一个结构，传入混乱的文本，返回类型化的字段：例如发票、预订通知、表单。解码语法保证输出可解析，且提取能力可推广至分类任务。
• 文本嵌入：同一个模型可以为句子返回向量，因此应用可以在本地进行搜索、匹配和路由。

模型

Needle 3 概览 (https://huggingface.co/Cactus-Compute/needle3/blob/main/assets/model.svg)
Needle 3 是一个阶梯式简单注意力网络（Laddered Simple Attention Network），这是我们的小模型方案：用 Monarch Hadamard MLP 代替前馈网络（FFN），采用带因果卷积的 GQA 注意力机制，通过聚集操作读取 engram n-gram 记忆，并使用多通道超连接。该模型训练方式使得从2层到20层的每一个深度都是一个可部署的模型。其大部分参数位于 engram 中，因此121M参数的模型进行的是50M参数模型级别的运算。权重通过 Cactus Quants 压缩为 CQ2-bit；由您的模式编译的字节级语法约束每个令牌，且每个响应都带有一个来自学习头的校准置信度分数。
架构图可在发布页面 (https://cactuscompute.com/needle) 查看。
仓库包含20层的 needle3.cact 文件、用于微调的 needle3.safetensors 检查点，以及每个平台的引擎。

基准测试

工具调用是基于完整测试集的精确匹配准确率，提取是基于完整测试集的字段微平均F1分数。
Needle 3 与基线模型在六个基准测试上的对比 (https://huggingface.co/Cactus-Compute/needle3/blob/main/assets/benchmarks.svg)
交互式边界图、架构和微调结果可在 cactuscompute.com/needle (https://cactuscompute.com/needle) 查看。

开始使用

pip install cactus-needle

可在浏览器中尝试：cactuscompute.com/needle (https://cactuscompute.com/needle)；Python 包和源代码位于 GitHub (https://github.com/cactus-compute/needle)。

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

每一轮返回一个包含 function_calls（模型的 reasoning 推理过程）和校准 confidence 置信度的 JSON 对象；离题请求会返回空列表而非猜测。
引擎和权重会从本仓库获取一次并缓存。

指南

• 如何为 Needle 3 设计工具 (https://cactuscompute.com/blog/designing-tools-for-needle)：每个操作一个工具、使用用户会提及的名称、在描述中使用格式、在语法中使用约束、触发条件。
• 利用 Needle 的置信度 (https://cactuscompute.com/blog/needle-confidence)：分数衡量的内容、引擎保留的信息、基于行动、确认或拒绝的路由。
• 使用 Needle 进行结构化 JSON 提取 (https://cactuscompute.com/blog/structured-extraction-with-needle)：记录作为唯一工具、类型化结果、使用枚举进行分类。
• 微调 Needle (https://cactuscompute.com/blog/finetuning-needle)：数据格式、命令、解读损失、数据集规模。
• Needle Python 文档 (https://cactuscompute.com/blog/needle-python-docs)：API、响应结构、行为约定、系统事实、工具检索、离线设备、环境、命令行界面。
• Needle 支持哪些设备 (https://cactuscompute.com/blog/needle-supported-devices)：每个平台文件夹、命令行运行器、C API、浏览器、WASI、气隙环境设置。
• .cact 格式 (https://cactuscompute.com/blog/cact-format)：引擎映射并就地读取的文件、Cactus Quants 在每个权重2.125位下的压缩、以及如何自行解析它。
• 移植 Needle 3 (https://cactuscompute.com/blog/porting-needle)：编写您自己的运行时的注意事项、用于测试的预言机、容器承诺的张量顺序、线路传输的提示、阶梯规则、使用 needle_embed 进行检索。

定制化

Needle 为定制化而设计。其容量呈阶梯状，一个最小只有2层的子网络，经过针对某个产品的工具微调后，可在远小于完整模型需求的设备上以最优方式运行。
在 DroidCall 数据集上的微调使每个子网络提升了18至36分，且从4层起，调优后的子网络就超越了 DeepSeek V4 Flash，起始参数量为29M。
在 DroidCall 和 Mobile Actions (https://huggingface.co/Cactus-Compute/needle3/blob/main/assets/finetune.svg) 上微调前后的每个子网络性能
Python 包使用 LoRA 在冻结的、完整的20层基础模型上进行微调，然后 needle build [--layers N] 合并适配器、从2到20层切片出任何子网络，并导出一个可在相同引擎上运行的4位 .cact 文件。
模型背后的2位后训练和量化，使用了 Cactus 专有数据集进行增强，在 Cactus Platform (https://cactuscompute.com/dashboard) 上运行。

部署

此仓库中的每个平台文件夹都包含一个小于1MB的引擎，它在启动时加载 needle3.cact。needle build --platform [--layers N] 会获取引擎和头文件，并在任何深度将权重放置在它们旁边，或者您也可以在此处下载文件夹：
每个平台文件夹对应一个引擎 (https://huggingface.co/Cactus-Compute/needle3/blob/main/assets/deploy.svg)

./needle --model needle3.cact --tools tools.json --prompt "dim the living room to 30"
./needle --model needle3.cact --tools tools.json --serve

工具模式与系统提示和对话共享模型上下文。needle_init 成功时返回令牌化的静态前缀长度，当该前缀不适合模型上下文时失败。
在 C API 中，调用 needle_last_error() 于返回值之后可获取已测量的前缀令牌数和上下文限制。
减少工具描述/模式文本、拆分大型目录，或声明超过五个工具，以便 Needle 能在每轮前缀中仅保留检索到的工具。
在生成时，max_new_tokens 也会预留上下文空间，因此更大的生成上限会为当前轮次和历史记录留下更少的空间。
设备指南 (https://cactuscompute.com/blog/needle-supported-devices) 涵盖了运行器标志、C API、WASI 组件和气隙环境设置。

引用

Needle 3 由 Cactus Compute 团队构建。如果您在工作中使用了它，请引用：

@misc{needle3_2026,
  title = {Needle: 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，请联系 [email protected]。