如何5分钟上手Needle 3：pip install一行命令开启端侧工具调用模型

Needle 3 是一个专为端侧（on-device）场景打造的工具调用模型：整个模型只有单个 8–29 MB 的文件，可在手机、穿戴设备、智能家居甚至微控制器上本地运行。只需pip install cactus-needle一行命令，无需 GPU、无需云端 API，5 分钟即可跑通你的第一次端侧 function calling。

🎯 30 秒认识 Needle 3：口袋里的"工具调用专家"

与普通大型聊天模型不同，Needle 3 走的是"小而精"路线——它主动放弃了通用聊天能力，换来了在端侧三大任务上的越级表现（工具调用上击败 10 倍体量的模型，抽取上追平 2–3 倍体量的模型）：

• 🔧 工具调用（Tool calls）：给出 App 暴露的函数列表，Needle 自动选出正确的工具并填好每个参数；请求两件事会按顺序返回两次调用；没有工具能覆盖的请求会返回空列表，而不是瞎猜。
• 📋 结构化抽取（Structured extraction）：声明一个"形状"（schema），丢入杂乱的文本（发票、预订单、通知、表单），拿回类型化字段；解码语法保证输出必然可解析，并天然支持分类任务。
• 🧮 文本向量（Text embedding）：同一个模型可以为句子返回向量，让 App 在本地完成搜索、匹配和路由。

💡 亮点：每次响应都携带一个校准过的置信度分数（calibrated confidence），方便你在"直接执行 / 让用户确认 / 拒绝"之间做分流，这对生产环境的可靠性至关重要。

📦 第 1 分钟：最快安装方法——一行 pip install

pip install cactus-needle

就这一行。Python 包覆盖了主流平台，仓库的 python/ 目录中提供了 macOS（arm64 / x86_64）、Linux（manylinux / musllinux，aarch64 / x86_64）、Windows（amd64 / arm64）的官方 wheel 包。

首次运行时，引擎和模型权重会从仓库自动获取一次并缓存到本地，之后的运行完全离线、零网络依赖。

⚡ 第 3 分钟：5 行代码完成第一次端侧工具调用

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

几个值得注意的行为契约：

每一轮都会返回一个 JSON 对象，包含function_calls、模型的reasoning以及校准过的confidence三个字段，可以直接接入你的业务逻辑。

🔬 幕后揭秘：为什么 8–29 MB 就能装下 121M 参数？

Needle 3 是一套专为小模型设计的"配方"（Laddered Simple Attention Network），核心技巧包括：

• 阶梯式深度（Ladder）：训练时保证 2 到 20 层的每一层深度都是一个可部署模型，小设备只需切片使用浅层子网络；
• Cactus Quants 2-bit 量化：权重压缩到 CQ2-bit，把体积压到极致；
• 字节级语法约束：从你的 schema 编译出解码语法，逐 token 约束输出，保证结果 100% 可解析；
• engram n-gram 记忆：大部分参数放在 engram 中，让 121M 的模型只干 50M 的"算术量"。

架构细节可以查阅仓库中的 config.json（121M 总参数、20 层、GQA 注意力、8192 词表），主模型文件为 needle3.cact，词表在 tokenizer/ 目录。

🌍 不止 Python：一套模型，部署到所有平台

仓库为每个平台都准备了一个不足 1 MB 的独立引擎（自包含 C++ / WebAssembly，无第三方依赖），加载needle3.cact即可工作：

C 接口非常精简，以 linux-x86_64/needle.h 为例，核心只有needle_init、needle_complete、needle_embed、needle_reset、needle_load等几个函数，嵌入自己的 App 几乎零成本。命令行方式同样简单：

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

🛠️ 进阶：用自己的工具微调，准确率再上一个台阶

Needle 天生为定制设计。Python 包支持在完整 20 层基座上以LoRA微调（基座权重见 checkpoints/needle3.safetensors），然后用一条命令切片导出任意深度的 4-bit.cact：

needle build --platform <平台目录> --layers N

官方数据显示：在 DroidCall 数据集上微调后，每个子网络精度提升 18–36 个百分点；4 层以上的子网络（从 29M 参数起步）甚至超过更大的基线模型。也就是说，你完全可以把"某个产品的 10 个工具"蒸馏进一个几 MB 的子模型，塞进手表或车机。

❓ 新手常见问题

Q：运行需要联网吗？首次运行会自动拉取并缓存引擎与权重；之后完全离线，适合内网与气隙环境。

Q：手机/嵌入式设备能跑吗？能。8–29 MB 的单文件模型 + <1 MB 引擎，专为移动端、穿戴、机器人、智能家居、车机和微控制器设计，覆盖 Android、iOS、Linux、Windows、WASM 等。

Q：它和调用云端大模型 API 有什么区别？全部推理在设备本地完成：无网络延迟、无按量计费、数据不出设备，且输出受语法约束、带置信度，可控性更强。

✅ 总结

• 安装：pip install cactus-needle，一行搞定；
• 上手：@needle.tool装饰一个普通 Python 函数，交给Needleagent，就能完成端侧工具调用；
• 特性：工具调用 + 结构化抽取 + 文本向量三合一，输出 100% 可解析且带校准置信度；
• 部署：一个 8–29 MB 的.cact文件通吃所有平台，还可用needle build切出更小、更专精的子模型。

现在就可以打开终端，一行命令体验端侧 AI 的"轻"与"快" 🚀。