一天一个开源项目（第202篇）：Needle 2 - 14MB 的端侧工具调用模型

引言

"The 2-bit model you deploy is the model that was trained."

这是"一天一个开源项目"系列的第 202 篇文章。今天带你了解的项目是 Needle 2。

大语言模型的端侧部署有一道绕不开的墙：参数量、内存、延迟三者之间的三角矛盾。要想在手机或嵌入式设备上跑 AI，要么牺牲精度，要么牺牲速度，要么两个都牺牲。

Cactus Compute 用一个反直觉的方案绕开了这堵墙：不做通用模型，只做工具调用。

Needle 2 是一个专为工具调用（Tool Calling）、结构化提取和设备控制设计的基础模型：

45M 参数，CQ2-bit 量化
14MB 单一二进制，不需要单独的模型文件
运行时仅占 28MB 内存，会话内存固定不随对话增长
在工具调用基准上与 FunctionGemma 270M（6 倍大）基本持平

9.2k Stars，Apache 2.0，已在 Pebble Index Ring 等可穿戴设备上真实部署。

你将学到什么

Needle 2 的 SAN（Simple Attention Network）架构和三个核心设计选择
CQ2-bit 量化为什么比事后量化更有优势
置信度门控（Confidence Gating）如何实现本地 + 云端的智能路由
如何用 @needle.tool 装饰器快速接入工具
LoRA 微调 + .cact 导出的完整流程

前置知识

了解 Function Calling / Tool Use 的基本概念
Python 基础（会用装饰器）
对模型量化有基本了解（知道 INT4/INT8 是怎么回事）

项目背景

项目简介

Needle 2 不是通用聊天模型的缩水版，而是一个专门针对工具调用任务从头设计的基础模型。

它回答的问题是：如果一个模型只需要做好"接收自然语言查询 → 决定调用哪个工具 → 生成正确参数 → 返回结构化结果"这一件事，能做到多小？

答案是 14MB，运行时 28MB。

这个数字意味着什么：普通手机 App 的安装包远大于此，28MB 内存在 2026 年的任何 Android 手机上都是零压力，树莓派 5 上能跑到 500+ tok/s。

作者/团队介绍

公司：Cactus Compute, Inc.（旧金山）
核心成员：Henry Ndubuaku、Karen Mosoyan、Jakub Mroz 等多位联合创始人
定位：专注端侧 AI 推理的初创公司，Needle 系列是其核心产品
联系方式 ：founders@cactuscompute.com

项目数据

⭐ GitHub Stars: 9,200+
🍴 Forks: 592
📄 License: Apache 2.0
🧪 论文: arxiv.org/abs/2607.18...
🤗 模型权重: HuggingFace Cactus-Compute/needle2
📦 安装: pip install cactus-needle

主要功能

核心作用

Needle 2 提供三种能力，本质上都是"自然语言 → 结构化输出"的变体：

javascript 复制代码

自然语言查询
    ↓
Needle 2 推理引擎（14MB 二进制，28MB 内存）
    ↓
┌─────────────┬──────────────┬───────────────┐
│  工具调用    │  结构化提取  │  设备控制      │
│ tool calls  │  JSON 提取   │ device actions │
└─────────────┴──────────────┴───────────────┘

每次输出都附带一个置信度分数，可以基于阈值决定是在本地处理还是升级到云端模型。

使用场景

可穿戴设备的离线语音助手
- Pebble Index Ring 已在真实产品中使用 Needle，语音指令离线解析成 API 调用，无需联网。
IoT 和智能家居控制
- 树莓派或 ESP32 等设备上跑本地语音控制，"关掉卧室灯" → turn_off(room="bedroom")，无云端延迟。
文档结构化提取
- 把非结构化文本（发票、表格、报告）提取成强类型 JSON，schema 约束保证输出格式正确。
移动端 AI Agent
- 在安卓/iOS 上跑一个本地 Agent，处理简单任务，复杂任务按置信度路由到云端------省 API 费用也省延迟。
边缘推理节点
- 在 Meta Quest 3S 或 Apple Vision Pro 上 400--1500 tok/s，空间计算场景直接本地推理。

快速开始

bash 复制代码

pip install cactus-needle

工具调用：

python 复制代码

import needle

@needle.tool
def get_weather(city: str) -> dict:
    """Get the current weather for a city.

    Args:
        city: The city name to query.
    """
    # 实际业务逻辑
    return {"city": city, "temp_c": 27, "sky": "clear"}

@needle.tool
def send_message(to: str, body: str) -> dict:
    """Send a message to a contact.

    Args:
        to: Recipient name or number.
        body: Message content.
    """
    return {"sent": True}

agent = needle.Needle(tools=[get_weather, send_message])
result = agent.run("拉各斯现在天气怎么样？")
print(result["results"])  # [{"city": "Lagos", "temp_c": 27, "sky": "clear"}]

结构化提取：

python 复制代码

from typing import Annotated
import needle

schema = {
    "invoice_number": str,
    "total_amount": Annotated[float, needle.Field(gt=0)],
    "line_items": list[{"description": str, "qty": int, "unit_price": float}],
}

text = "Invoice #1042, Total: $384.00. 3x Widget @ $128.00"
data = needle.extract(text, schema)
# {"invoice_number": "1042", "total_amount": 384.0, "line_items": [...]}

置信度门控：

python 复制代码

result = agent.complete("帮我设置明天早上 8 点的闹钟")
if result["confidence"] < 0.7:
    # 置信度不足，升级到云端处理
    response = cloud_llm.complete(result["query"])
else:
    # 本地处理足够
    execute_tool_calls(result["tool_calls"])

核心特性

1. 工具装饰器 @needle.tool

直接装饰普通 Python 函数，docstring 自动解析成工具 schema
支持 needle.Field 约束（范围、正则、枚举），编码进 JSON Schema，推理时语法约束保证合法值

2. 语法约束输出（Grammar-Constrained Decoding）

输出不是"请输出 JSON"的软性要求，而是推理引擎在每个 token 位置只允许语法合法的字符
语法约束还能跳过 98% 的词汇表投影计算------这是速度的来源之一

3. 置信度分数

每次调用返回 confidence：后验校准头评分与解码概率的最小值
"The failure mode is escalation, not wrong execution"------宁可升级云端，不做错误执行

4. 工具检索（Tool Retrieval）

工具数量超过 5 个时自动启用嵌入检索，每轮只把最相关的 5 个工具放入上下文
"An unselected tool is unreachable, not merely unlikely"------从根本上消除幻觉调用

5. Engram 记忆系统

世界知识存入哈希 n-gram 表，读取时"零算术成本"
知识和计算完全解耦，这是 Hadamard MLP 能减少参数的前提

性能基准

任务	FunctionGemma 270M (f16)	LFM2.5 230M (f16)	Needle 2 (CQ2)
Mobile Actions (961行)	64.0%	69.1%	63.7%
DroidCall (200行)	17.5%	---	17.0%
Seal-Tools 域内	16.3%	26.9%	32.6%
Seal-Tools 域外	15.6%	17.0%	28.7%
模型大小	270M (f16)	230M (f16)	45M (CQ2)
每 token 算力	540 MFLOPs	460 MFLOPs	70 MFLOPs

Needle 2 以 1/6 的参数量在三项基准上与最强竞品相当，在 Seal-Tools 上甚至领先------这正是"专用模型"的优势所在。

项目详细剖析

SAN 架构：三个反常识的选择

Needle 2 使用 Simple Attention Network（SAN）而不是标准 Transformer，核心是三个设计选择：

选择 1：Hadamard MLP 替代标准 FFN

标准 Transformer 的 FFN 层是参数量最大的部分（约 2/3 的参数在这里）。SAN 用固定 Walsh-Hadamard 变换（一种没有可学习参数的线性变换）替代密集投影，几乎不消耗参数预算。

lua 复制代码

标准 FFN（参数多）：  x → W1 → ReLU → W2 → output
Hadamard MLP（几乎无参）：  x → H（固定变换）→ output

这不是砍功能，而是把"知识存储"的工作全部转移到 Engram 记忆系统。

选择 2：Engram 记忆 = 哈希 n-gram 表

世界知识（"巴黎是法国首都"、"list.append() 的语法"）存在一个哈希 n-gram 表里，推理时直接查表------零乘法，零参数消耗。

这个分离使模型的"计算部分"（Attention + Hadamard）极度精简，而知识密度不受影响。

选择 3：多通道残差流（Multi-lane Hyper-connections）

27 层 × 512 宽的网络用多通道连接获得比标准残差更灵活的路由，效果相当于"更宽的模型"，但不增加宽度。

CQ2-bit：训练即量化

大多数模型的量化是事后操作：先用 float16/bfloat16 训练，然后量化到 INT4 或 INT8。这个过程不可避免地会损失精度，且越低精度损失越大。

Needle 2 用的 Cactus Quants (CQ2-bit) 从训练阶段就针对 2-bit 量化优化：

arduino 复制代码

标准流程：FP16 训练 → 事后量化 → INT4 部署（精度下降）
CQ2 流程：CQ2-bit 感知训练 → CQ2-bit 部署（训练即部署目标）

官方的说法："The 2-bit model you deploy is the model that was trained." 没有训练-部署精度差，量化不是妥协而是设计目标。

推理引擎的三个速度来源

来源 1：权重在向量寄存器内展开，不解压到内存

传统量化模型在推理时需要把权重从低精度解压到高精度再计算。CQ2-bit 的权重可以直接在 SIMD 寄存器里操作，省去了解压步骤。

来源 2：语法约束跳过 98% 的词汇表投影

LLM 生成每个 token 时，通常需要对整个词汇表（数万个 token）算 softmax。Needle 2 的输出格式是结构化 JSON，在任意位置只有极少数合法字符，引擎可以在 softmax 之前跳过绝大多数候选。

来源 3：自动检测 CPU 指令集

单一二进制内置多套指令集优化路径：SDOT（ARMv8.4）、NEON（通用 ARM）、AVX2（x86）、RISC-V Vector Extension、WASM SIMD------运行时自动选择最优路径。

LoRA 微调：从数据到 .cact 文件

微调 Needle 2 比微调通用大模型简单得多，因为任务范围明确。

Step 1：准备数据

jsonl 复制代码

{"query": "明天下午三点提醒我开会", "tools": [{"name": "set_reminder", ...}], "answers": [{"name": "set_reminder", "arguments": {"time": "tomorrow 3pm", "message": "开会"}}]}
{"query": "今天天气怎么样", "tools": [{"name": "set_reminder", ...}], "answers": []}

注意：必须包含约 1/8 的无关示例（"answers": []），防止模型对所有输入都触发工具调用。

Step 2：数据增强（可选）

bash 复制代码

# 用 OpenRouter API 自动扩充数据集
needle generate-data --augment data.jsonl --num-samples 1000

Step 3：LoRA 训练

bash 复制代码

# CPU 训练
needle finetune data.jsonl --epochs 10 --out adapter.pkl

# GPU 加速
pip install "cactus-needle[gpu]"
needle finetune data.jsonl --epochs 10 --out adapter.pkl

# Apple Silicon
pip install "cactus-needle[metal]"
needle finetune data.jsonl --epochs 10 --out adapter.pkl

Step 4：导出 .cact 文件

bash 复制代码

# LoRA adapter 在导出时直接合并进权重
needle build checkpoints/needle2.pkl --lora adapter.pkl --out tuned.cact

Step 5：加载使用

python 复制代码

agent = needle.Needle(tools=[my_tools], weights="tuned.cact")

微调后基准测试显示，精度提升可达 21--58 个百分点，在特定任务上甚至超过 DeepSeek V4 Flash 这类前沿云端模型------这是专用模型在固定工具集上的核心优势。

部署场景与速度

设备	解码速度	内存占用
Raspberry Pi 5	500+ tok/s	~28MB
Apple Vision Pro	1,500 tok/s	~28MB
Meta Quest 3S	400--800 tok/s	~28MB
三星 A 系列手机（<$200）	300--700 tok/s	~28MB
ESP32-S3（微控制器）	支持（需外部 RAM）	~28MB

注意内存占用是固定的------无论对话多长，不随轮次增长，这是 256-token 滑动窗口 KV 缓存的设计结果。

项目地址与资源

官方资源

🌟 GitHub : github.com/cactus-comp...
📚 官网 : cactuscompute.com/needle
🤗 模型权重 : huggingface.co/Cactus-Comp...
📄 论文 : arxiv.org/abs/2607.18...
📦 安装 : pip install cactus-needle

总结与展望

核心要点回顾

专用 > 通用（在固定任务上）：45M 参数专注工具调用，在三项基准上与 6 倍大的模型持平甚至领先
CQ2-bit = 训练即部署：量化不是精度妥协，而是从第一天就是设计目标
SAN 三件套：Hadamard MLP 省参数、Engram 记忆存知识、多通道残差扩路由
置信度门控：不是"猜"，是校准过的概率信号，可以可靠地驱动本地/云端路由决策
28MB 固定内存：256-token 滑动窗口保证内存不随对话增长，嵌入式场景的必要条件

适用人群

端侧 AI / 边缘计算工程师：在资源受限设备上需要可靠的工具调用能力
IoT 和智能家居开发者：离线语音指令解析，零云端依赖
移动 App 开发者：想在 App 内嵌一个本地 Agent，不依赖云端 API
AI 研究者：对 SAN 架构、CQ2-bit 量化、端侧推理优化感兴趣

一句话评价

Needle 2 证明了一件事：当你把问题范围定得足够窄，14MB 可以打赢 270MB------这不是技巧，是架构哲学。

欢迎访问 PrimeSkills ------ 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。

更多实用知识和有趣产品，欢迎访问我的个人主页

一天一个开源项目（第202篇）：Needle 2 - 14MB 的端侧工具调用模型

引言

你将学到什么

前置知识

项目背景

项目简介

作者/团队介绍

项目数据

主要功能

核心作用

使用场景

快速开始

核心特性

性能基准

项目详细剖析

SAN 架构：三个反常识的选择

CQ2-bit：训练即量化

推理引擎的三个速度来源

LoRA 微调：从数据到 .cact 文件

部署场景与速度

项目地址与资源

官方资源

相关资源

总结与展望

核心要点回顾

适用人群

一句话评价