树莓派跑大模型工具调用：Needle 2 用 14MB 做完 GPT-4 级任务

在树莓派上跑 AI 模型这件事，这两年不缺 demo，缺的是真正能用的方案。

大多数「端侧 AI」项目演示的是跑通，而不是跑好——跑一个 7B 模型得到每秒 0.3 个 token 的体验，换谁都想把模型删了改用 API。但最近一个叫 Needle 2 的项目让我重新审视了这个判断：在树莓派 5 上跑到 500 tokens/秒、14MB 的二进制文件、全程离线运行——这个数字组合值得认真看一下。

14MB 背后是什么

Needle 2 来自一家叫 Cactus Compute 的团队，核心是一个 45M 参数的模型，整个权重压缩进了一个 14MB 的 .cact 文件，运行一次会话占用约 28MB RAM。

参数规模比一颗 M2 芯片的 CPU 还小，但它做的事是工具调用（Tool Calling）和结构化信息提取——这是 GPT-4 级别模型才真正做好的任务。具体来说，它能：

• 读懂自然语言指令，自动选择该调用哪个工具
• 按照你定义的 schema 填充参数，严格输出 JSON
• 从一段文字里提取发票、地址、联系人等结构化数据
• 支持 Pydantic 模型定义，直接返回类型正确的 Python 对象

这是正经的 Agent 用例，不是玩具。

CQ2-bit 量化：比 2bit 更小的压缩路径

大多数端侧模型走到 4-bit 量化就停了，Needle 2 用的是团队自研的 Cactus Quants 压缩到 CQ2-bit——比普通的 INT2 更紧凑，用更少的位宽表达更精确的数值分布。arXiv 论文（2607.18363）有完整的消融实验，说明这个量化路径在极低参数预算下的质量损失是可接受的。

实际速度（来自 HuggingFace 官方数据）：

• 树莓派 5：~500 tokens/秒
• Meta Quest 3S / Apple Vision Pro：400–1,500 tokens/秒
• 三星 A 系列等 200 美元以下手机：300–700 tokens/秒
• ESP32-P4 微控制器：~28MB 内存峰值（有社区用户报告在 ESP32-S3 上用约 11MB 跑通）

和同级别模型横向比，Needle 2 的体积是 FunctionGemma 270M 的 1/6、LFM2.5 230M 的 1/5，精度却「trades wins」——不是完胜，但打得有来有回。

三个真正解决痛点的工程细节

1. Confidence Gate：解决幻觉的实用机制

每个响应都带一个校准后的置信度分数，来自一个独立的学习头。你设一个阈值，高于阈值模型自行执行，低于阈值上报给用户或切换到云端模型。这个机制比单纯看 logprob 有据可查，比加 prompt 约束更稳定。

对于需要自动执行的设备端场景，这个设计很关键——你不希望机器人在低置信度时还硬着头皮执行。

2. Tool Retrieval：管理大规模工具目录

实际场景里，一个智能家居系统可能有几十个设备、几百个指令。传统方案是把所有工具描述塞进 context，token 很快爆炸。

Needle 2 的做法是内置一个检索头，每次只把 top-5 最相关的工具子集放进上下文，并强制解码器只在那个子集里选择。实测支持大规模工具目录，不会被 context 长度卡死。

3. 完全离线部署路径

推理引擎首次从 HuggingFace 下载后缓存，之后零网络依赖。文档（doc/apis.md）专门有一节讲 air-gapped 设备怎么部署，这对工业 IoT 和某些合规场景是刚需。

谁该用它，谁不该用

适合的场景：

• 嵌入式 / MCU 设备需要本地 AI 决策（工厂机械臂、农业传感器、智能门锁）
• 隐私数据不能出设备（医疗设备端录入、离线文档处理）
• 需要在手机、手表、AR 眼镜上做快速结构化提取
• 智能家居中控本地化执行，不用每次请求都走云端

不适合的场景：

• 复杂多步推理（需要链式调用多工具的场景，它目前定位是单轮工具选择）
• 需要大规模知识问答或长文本生成
• 对标 GPT-4 / Claude 的通用对话能力——这不是它的设计目标

代码层面：5 行跑起来的工具调用

pip install cactus-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'}]

用 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

Fine-tuning 走 LoRA 路线，合成数据、训练、导出成一个新 .cact 文件，全流程在文档（doc/finetuning.md）里有完整说明。不需要重训基座模型，adapter 合并后还是 14MB。

部署平台一览

Python 包：pip install cactus-needle，带 [gpu] / [metal] 扩展。推理引擎从 HuggingFace 下载一次后缓存，无需公网访问。

值得关注的几个问题

1. 工具描述的质量直接影响效果

README 里说得很直白：「describing them well is the whole game」。Needle 2 的能力天花板在很大程度上取决于你给它的工具描述质量。docstring 怎么写、参数类型怎么定义、choices 约束怎么加，都会影响工具选择准确率和参数填充质量。上手容易，用好需要花时间调教描述。

2. Simple Attention Network 值得跟进

支撑 Needle 2 的基础架构论文（arXiv:2607.18363）发现了一个有意思的结论：在参数量、FLOPs、深度同时控制的条件下，attention-only 模型和标准 Transformer 的差距可以压缩到 0.006 nats（约 0.27% 的 loss 差异），可复现到 1/10000 的精度。FFN 层并不是 Transformer 的必要组件。这篇论文目前只有 10 页，值得读。

3. 社区目前偏小

目前 6.1k Star，issues 25 个，还处于早期阶段。文档相对完整，但社区案例和最佳实践还在积累中。如果你在找生产级、大规模部署的成熟方案，需要自己评估维护风险。

可执行的下一步

1. 立刻试用：macOS / Linux 一行命令 pip install cactus-needle，5 分钟跑完 Quickstart，看它对你的工具集效果如何
2. 端侧部署测试：有树莓派或 Android 设备的，直接用 needle playground 起一个本地服务感受 500 tokens/s 是什么体验
3. 读论文：arXiv 2607.18363，10 页不长，但 Simple Attention Network 这个方向可能会影响未来端侧模型的设计范式
4. 关注工具描述工程：花时间优化 docstring 和 schema 定义，这是 Needle 2 效果的天花板

仓库：cactus-compute/needle | 权重：Cactus-Compute/needle2 | 论文：arXiv:2607.18363