• 人工智能
• 基础模型
• 工具调用
• 模型量化
• 本地部署
• Embedding

Needle 3 是 Cactus Compute 开源的端侧结构化 JSON 提取模型：声明 schema 后把脏文本喂进去，解码语法保证输出必为合法 JSON，秒级返回类型化字段，全程本地运行、无需云端。本文带你快速安装、声明 schema、理解"语法级保证"的原理，并把它部署到手机、树莓派和浏览器。

为什么需要"语法级"的结构化提取

用传统大模型做信息抽取，通常是这样的流程：

1. 让模型"输出 JSON"；
2. 用try/except捕获解析失败；
3. 处理截断、多余逗号、中文引号、字段缺失、类型错误……

这些兜底代码越多，线上翻车的概率越大。而且云端调用还有延迟、隐私和成本三座大山。

Needle 3 换了一条思路：把 schema 编译成字节级语法（decode grammar），在解码阶段约束每一个生成的 token。输出不是"大概率能解析"，而是语法上不可能解析失败——脏文本进，类型化字段出，一步到位。

一分钟上手：pip 安装 Needle 3

安装非常简单，一条命令即可：

pip install cactus-needle

引擎与权重会从仓库获取一次并本地缓存，之后完全离线可用。首次安装后即可跑通第一次提取。

声明 schema：把脏文本变成类型化字段

结构化提取的核心玩法是record as the only tool：把你想抽取的"记录形状"声明为一个 schema，作为唯一工具交给模型，然后直接把原始脏文本喂给它。

发票、订单、预订、通知、表单都可以。声明的形状决定返回的字段：

import needle invoice = { "name": "Invoice", "description": "Extract invoice details from raw text.", "type": "object", "properties": { "amount": {"type": "number"}, "currency": {"type": "string"}, "paid": {"type": "boolean"} } } agent = needle.Needle(tools=[invoice]) result = agent.run("收到发票，金额 1280.50 美元，状态：已付款") print(result)

每一轮返回一个 JSON 对象，包含三部分：

• function_calls：类型化提取结果（这里就是符合 schema 的字段）；
• reasoning：模型的推理过程；
• confidence：经过标定的置信度分数。

字段类型、缺失情况、枚举取值都由你声明的 schema 决定，拿到即可直接入表、入库，不需要二次清洗。

语法级保证是怎么做到的？

这是 Needle 3 与普通"提示词约束"最大的区别：

除了解码约束，模型本身还有几个为端侧设计的细节：

• 权重经 Cactus Quants 压缩为 2-bit，整个模型是单个 8–29 MB 文件（见 needle3.cact）；
• 架构参数（121M 参数、20 层、8K 上下文）定义在 config.json 中；
• 需要微调时，仓库提供了全量检查点 checkpoints/needle3.safetensors，以及 tokenizer.model 供数据处理使用。

树莓派 5 上可达 4k tokens/s 的解码速度，"秒变"名副其实。

用 enum 字段做分类

结构化提取还能自然泛化到分类场景：把类别声明为enum字段即可。

例如对客服消息做意图识别，schema 里声明"intent": {"type": "string", "enum": ["billing", "complaint", "support"]}——模型只能从这三个取值中选一个，不存在"自由发挥"输出第四种意图的可能。配合confidence分数，可以按"执行 / 确认 / 拒绝"三档路由：高分直接执行，中分弹窗确认，低分转人工。

从笔记本到手机：多平台部署

仓库为每个平台准备了一个独立文件夹，里面是不到 1 MB 的引擎 + C 头文件，启动时加载 needle3.cact 即可。常见平台包括 linux-x86_64、linux-arm64、android-arm64、ios-arm64、macos-arm64 等。

CLI 运行（以 Linux x86_64 为例）：

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

C API 集成（接口定义见 linux-x86_64/needle.h）：

• needle_init(system_prompt, tools_json, tool_index_path)：初始化，schema 从tools_json传入；
• needle_complete(input, max_new_tokens, out, out_capacity)：喂入脏文本，取出类型化结果；
• needle_embed：同一模型还能返回句子向量，方便本地检索与路由。

浏览器 / WASM：仓库提供 wasm/needle.js 与 wasm/needle.wasm，以及 WASI 组件 wasm-component/needle.component.wasm（接口见 wasm-component/needle.wit），无依赖即可在网页里跑结构化提取。

小结

• 声明 schema：把目标记录的形状写成一个 record，作为唯一工具交给 Needle 3；
• 语法级保证：schema 编译为字节级解码语法，输出必然可解析；
• 附带能力：enum 字段即分类、内置标定 confidence 可路由决策、同一模型可出向量；
• 端侧运行：8–29 MB 单文件模型，覆盖手机、树莓派、浏览器与离线设备。

更多细节可参阅仓库内的 README.md。

• 人工智能
• 基础模型
• 工具调用
• 模型量化
• 本地部署
• Embedding