GitHub 趋势 · 第 40 期
14MB 的模型跑在设备里：1 万 star 的 Needle 2，把工具调用从云端拽回设备
#端侧推理#工具调用#结构化抽取
这个仓库赌的方向，和眼下绝大多数 AI 工具是反着的：主流是「把最强的模型接进来」，它是把模型做到 14MB，只干一件事——把用户说的一句话，变成一次格式永远合法的工具调用。45M 参数、单文件 14MB、整场会话约 28MB 内存、推理时不需要网络。10,786 颗星，本月涨 7,395，Apache-2.0。
现在的工具调用（tool calling）链路，对一个智能开关来说太重了：你要把整份工具 schema 发到云端，等首字延迟、按 token 付钱，模型吐回的 JSON 不合法还要重试，而重试要再付一次钱。设备侧最要命的是网络——断网那一刻，语音开关灯直接变砖。Needle 2 想解决的就是中间这一小段：不做通用对话，只把自然语言翻译成结构化的调用参数，而且这件事在设备本地做完。
它到底是什么
README 第一段的定义可以直接引用：Needle 2 is an open 45M-parameter model for tool calling, device use and structured extraction. The whole model is a single 14MB binary that runs a full session in about 28MB of RAM.
也就是说，它把权重直接烘进了自己的推理引擎：没有单独的模型文件要管理，推理过程不走网络。这个仓库本身是 Python 包（cactus-needle），提供推理、LoRA 微调和导出三件事，引擎二进制在第一次使用时从 Hugging Face 拉一次并缓存，剩下的没有需要你自己编译的东西。
模型骨架叫 Simple Attention Network：用 Hadamard MLP 替掉 FFN、GQA 注意力、engram 键值记忆、多通道超连接，再用自家的 Cactus Quants 压到 CQ2-bit，附带一篇论文（README 标注 arXiv:2607.18363）。但真正决定它能不能用在产品里的，不是这堆名词，而是下面这个设计。
它的每一次解码都被语法约束：byte-level grammar 由你给的 schema 编译而来，逐 token 限制，所以返回的 arguments 一定符合你声明的形状，不存在「JSON 又坏了」这种事。README 的原话是 the call is always well-formed。
核心能力：五条，都在 README 原文里
| 能力 | README 的原文口径 |
|---|---|
| 自包含 | weights baked into a single 14MB engine; no separate model files to manage, and inference does no network |
| 结构契约 | tool calls come back as structured data, text in, JSON out; a byte-level grammar compiled from your schemas constrains every token |
| 置信度门控 | every response carries a calibrated confidence score from a learned head; set a threshold, act above it, escalate below it |
| 工具检索 | declare a large catalogue and a built-in retrieval head renders only the top five tools per turn, with the grammar constrained to that subset |
| 有界内存 | a 256-token sliding window with the tools pinned as KV sinks, so total memory stays near 28MB no matter how long the conversation runs |
把这五条连起来看，它的产品形态就清楚了：一个常驻设备、内存占用恒定、输出永远能被下游程序解析的调度器。它不产生漂亮话，只产生函数名和参数——需要总结、写作、闲聊的部分，仍旧交给你接的大模型。
边缘设备上还有一个很实际的问题：模型跑得动吗。llms.txt 里写明了引擎按平台分发——needle download
上手：命令全部取自 README 原文
运行时只装了推理，依赖清单里只有一个 huggingface_hub：
pip install cactus-needle
最简用法是给函数加一个装饰器——签名给类型、docstring 当工具描述，run() 负责整个循环：模型挑调用、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它预置了六个现成的工具面，拿来就能跑冻结的验收用例：smart_home、media_player、productivity、wearable、kitchen_appliance、data_capture。
from needle.environments import smart_home
smart_home.agent.complete("dim the study lights to 30 percent")
smart_home.run_tests()要按自己的业务微调，链路是「合成数据 → LoRA → 导出单个 .cact」，仍然是 README 原命令：
pip install "cactus-needle[train]" export OPENROUTER_API_KEY=sk-or-... needle generate-data --tools my_tools.json --num-samples 500 --output data.jsonl needle finetune data.jsonl --epochs 10 --generate 300 --lora-rank 16 --lora-alpha 32 needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.pkl --out my_needle.cact # add --bits 2 for a smaller model
训练是纯 JAX，NVIDIA 装 cactus-needle[train,gpu]，Apple Silicon 装 cactus-needle[train,metal]。导出的 .cact 是单文件归档，引擎与权重解耦——同一个引擎直接跑你微调过的模型，不用重编译；换机器就用 needle download
那张基准图，我打开读了一遍
README 里没有数字表，只有一张 assets/frontier.png 的散点图。我把它拉下来放大逐点读，纵轴是 Mobile-Actions accuracy（%），横轴是总参数量。读数如下（是我从图里读的近似值，仓库没有提供文本版数字）：
| 模型 | 参数量 | 精度口径 | 图上读数 |
|---|---|---|---|
| Needle 2 | ~45M | CQ2-bit | 约 63% |
| FunctionGemma 270M | 270M | f16 · vLLM | 约 63% |
| LFM2.5 230M | 230M | f16 · vLLM | 约 68% |
| Apple FM | ~3B | on-device | 约 57% |
结论比宣传语诚实：在移动端动作这一项基准上，Needle 2 和 270M 的 FunctionGemma 基本齐平，比 230M 的 LFM2.5 低一档，但明显高于 3B 量级的 Apple 端上模型；而它只用了大约 1/6 甚至 1/70 的体积，并且是 2-bit 对别人的 f16。README 自己的措辞也正是 trades wins——它卖的不是精度第一，是「小两个数量级还能打平」。另外要注意口径差异：对手都是 f16 + vLLM，它是 CQ2-bit，这张图严格来说不是同精度对比。
我的判断：适合谁，不适合谁
适合这几类场景：
- ▪设备端指令入口：智能家居、可穿戴、机器人、车机的语音或按键指令路由
- ▪数据不出设备的结构化抽取：发票、表单、工单、字段提取，本地跑完再决定要不要上云
- ▪手机 App 里的本地工具路由，省掉每次请求的 token 成本与首字延迟
- ▪需要严格 JSON 的下游自动化——语法约束替你省掉了一整层重试与校验逻辑
- ▪要在离线或隔离环境里验证 tool calling 的团队，官方给了 air-gap 的预下载路径
不适合：
- ▪要自由对话、开放问答、写总结的：无关输入它返回空 function_calls，没有文本兜底
- ▪需要长上下文或多跳复杂规划的：滑动窗口 256 token，一次会话一套工具，超过 5 个工具每轮只渲染前 5 个
- ▪想开箱即用就拿到高精度的：45M 参数，硬任务要靠自己的数据微调
- ▪工具描述写不细的团队——README 原话是 describing them well is the whole game
上手前值得先知道的七个坑：
① 遥测默认开启：匿名上报函数名、包版本、系统，绝不含 prompt 与输出；关掉用 NEEDLE_TELEMETRY=0，或通用的 DO_NOT_TRACK=1，CI 环境自动排除。一个主打本地优先的项目里，这条最容易被忽略。
② 「不联网」指的是推理时不联网：引擎二进制首次使用要从 Hugging Face 下载并缓存，真正的离线要先 needle fetch 预下载、配合 HF_HUB_OFFLINE 与 NEEDLE_LIB_PATH；而合成训练数据这一步需要 OPENROUTER_API_KEY，默认模型是 deepseek/deepseek-v4-flash，属于外部服务。整条链路离线是做不到的。
③ 没有自由文本兜底：不支持的输入返回空 function_calls，产品里必须自己处理这个空分支。
④ 置信度只对基座模型有效：官方写明校准头不随微调更新，一旦用 weights= 载入微调的 .cact，confidence 会返回 None。如果你的兜底逻辑依赖阈值判断，微调之后这条链就断了。
⑤ 引擎不能卸载权重：绑定过微调模型之后，再构造基座 agent 会直接报错。要用基座就先构造，或者拆成两个进程。
⑥ 微调依赖链比运行时重得多：train extra 会拉 JAX、flax、optax，metal 那组还锁了 jax==0.4.38 和 jax-metal，Apple Silicon 上建议单独开虚拟环境。
⑦ 仓库没有 GitHub Release：版本只随 PyPI 走，当前是 cactus-needle 2.0.12（requires-python >=3.9）。要跟版本变化得盯 PyPI，而不是 Releases 页。
项目：cactus-compute/needle（Needle 2）· https://github.com/cactus-compute/needle
Star：10,786（GitHub REST API 实测）· 月榜快照 10,782，本月 +7,395；fork 689、open issue 35、watcher 62
语言 Python · 许可 Apache-2.0（仓库 LICENSE 为标准 Apache-2.0 全文，无附加限制；Hugging Face 权重卡片同为 apache-2.0，未 gated）
版本：cactus-needle 2.0.12（PyPI）· 仓库无 GitHub Release · 最近提交 2026-09-08 · 创建于 2026-02-24
权重与引擎：https://huggingface.co/Cactus-Compute/needle2 · 下载 54,648、likes 294、最后更新 2026-09-03，按平台提供预编译引擎（含 android-arm64 / armv7 / riscv64）
基准数字为 assets/frontier.png 读图的近似值，官方未提供文本版数值表
数据来源：GitHub Trending 官方页面（daily / weekly / monthly）+ GitHub REST API + raw README / llms.txt / LICENSE / pyproject.toml 原文 · 抓取时间：2026-09-11 14:30
你现在的设备端指令是怎么做的——还在把 schema 发到云端等模型回 JSON，还是已经在本地跑小模型了？留言说说你踩过的坑，我会挑有意思的下期展开。
下期写 xai-org/x-algorithm（33,083 star，本月 +6,248，Rust）：X 那个 For You 信息流的推荐算法本体。备选是 apache/maka（5,208 star，本月 +3,941）——Apache 孵化项目，把 agent 做过的每一件事都完整留痕；以及 NVIDIA-NeMo/Switchyard（2,839 star，本月 +2,628），跨模型路由但保持 OpenAI 与 Anthropic 原生 API 兼容。核实下来撑不起一期，我就换月榜下一个高动量项目，绝不硬写。
#端侧推理#工具调用#结构化抽取