Needle：14MB 就能跑的基础模型，手机/手表/机器人皆可本地推理

在「大模型越大越强」的叙事里，cactus-compute/needle 走了一条完全相反的路——它把一个能执行工具调用、结构化抽取的完整模型，压缩成了仅仅 14MB 的单个二进制文件，运行一整个会话只需要约 28MB 内存。

这个项目最近在 GitHub Trending 上快速蹿升（单日新增 300+ star），原因是它精准踩中了「端侧 AI」的痛点：手机、可穿戴设备、智能家居、机器人这些算力与内存都极度受限的场景，终于有了一个真正能落地的开源选择。

一、Needle 是什么

Needle 2 是一个开源的 4500 万参数模型，专为三大任务设计：工具调用（tool calling）、设备使用（device use）、结构化抽取（structured extraction）。它的核心亮点可以概括为四点：

• 自包含：权重直接烘焙进单个 14MB 引擎，没有独立的模型文件需要管理，推理过程完全不依赖网络。
• 极简契约：文本进、JSON 出。工具调用以结构化数据返回，一个从你的 schema 编译出来的「字节级语法」约束每一个 token，保证输出一定是合法 JSON。
• 置信度门控：每个响应都带有一个经校准的置信度分数。你可以设定阈值，高于阈值直接执行动作，低于阈值则升级处理，非常适合对安全敏感的场景。
• 有界内存：256 token 的滑动窗口 + 工具作为 KV sink，无论对话多长，内存占用始终稳定在 28MB 左右。

在基准测试上，Needle 2 与 FunctionGemma 270M、LFM2.5 230M、Apple FM 等小型模型互有胜负，但体积只有它们的 1/5 到 1/70，且量化到 2 bit（对手是 f16）。

二、技术特色

Needle 2 构建在团队提出的 Simple Attention Network（简单注意力网络）之上，这是一种密集小型模型的配方：

• Hadamard MLP 取代传统 FFN（前馈网络）；
• GQA 注意力（分组查询注意力）；
• Engram 键值记忆；
• 多通道 hyper-connection；
• 通过 Cactus Quants 压缩到 CQ2-bit。

相关论文见 arXiv:2607.18363。简单说，它用一系列工程技巧，把「能干活」的模型极限往下压了好几个数量级。

三、详细使用步骤

安装只需一行：

pip install cactus-needle

推理引擎会从 Hugging Face 拉取一次并缓存，之后无需任何构建。

1. 基础用法：装饰函数定义工具

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

函数签名决定参数类型，docstring 是工具描述，run() 自动完成「选调用 → 执行 → 回填结果 → 返回」的整个循环。

2. 进阶：约束参数

用 Literal 定义固定选项，或用 needle.Field 通过 Annotated 内联约束取值范围、正则、长度等：

from typing import Annotated
import needle

@needle.tool
def send_money(
    amount: Annotated[float, needle.Field(gt=0, le=10000, description="USD, up to 10,000")],
    to: Annotated[str, needle.Field(pattern=r"^@[a-z0-9_]+$", description="recipient handle")],
    memo: Annotated[str, needle.Field(max_length=80)] = "",
):
    "Send money to a handle."
    return {"sent": amount, "to": to}

这些约束会被编译进解码语法，模型只能输出满足条件的值，从根源上杜绝幻造。

3. 结构化抽取

抽取数据和工具调用本质是同一个操作——声明一个 schema，然后把内容喂进去：

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

4. 浏览器 Playground

needle playground            # 基础模型，http://127.0.0.1:7860
needle playground --weights my.cact   # 微调后的模型

你可以直接在浏览器里挑选预设、编辑工具和提示词、点击 Run 试跑，还能一键启动微调流程并下载 .cact 模型。

四、适用场景

• 智能家居 / 物联网中控：在 28MB 内存的设备上，用自然语言控制灯光、温控、家电。
• 可穿戴设备：手表、耳机等资源极端受限的设备上做本地意图识别与动作执行。
• 机器人：端侧实时工具调度，无需把数据上传到云端，保护隐私、降低延迟。
• 移动端离线助手：在没有网络的环境下完成结构化信息抽取（发票、收据、表单）。

GitHub 地址：https://github.com/cactus-compute/needle

如果你正在做端侧 AI 或对「小而能打」的模型感兴趣，这个项目绝对值得 star 并跑一遍试试——14MB，比一张朋友圈截图还小。