cactus-compute/needle

Needle – 微型设备基础模型

简介 – Needle 是一系列基础模型（最新版本为 Needle 3），适用于极小型设备，如手机、可穿戴设备、机器人、智能家居中枢、车用 ECU 甚至微控制器。整个模型以单一 8‑29 MB 二进制文件（.cact 文件）发布，并在自定义 C++ 引擎上运行，支持 CPU、WASI、浏览器及其他边缘运行时。

核心功能

功能	说明
工具调用	根据您提供的 Python 函数（工具）列表，Needle 能选择正确的工具，并从自然语言输入中填入所有参数。它能依次返回多个调用，或在无匹配工具时返回空列表。
结构化提取	定义 JSON schema（结构）。输入杂乱文本，Needle 将返回具备校准置信度分数且必定能解析的类型化字段。
文本嵌入	同一模型可为任何句子生成稠密向量，实现本地语义搜索、路由或相似度比对。
语音转文字 (Whistle)	一个 16.9 MB 的语音模型，共享 Needle 的引擎。支持单次转录（最长 30 秒），具备语言检测、时间戳、关键词偏好及流式支持。
置信度评分	每个响应皆包含学习过的置信度头（confidence head），让应用程序决定是否采取行动、要求澄清或拒绝。

运行原理

• 阶梯式 Simple Attention 网络 – 一种“Simple Attention”骨干，每一层深度（2‑20 层）皆为可完全部署的子模型。架构使用 Monarch Hadamard MLP 取代传统前馈网络，结合 GQA 注意力与因果卷积抽头、engram n‑gram 内存及多通道超连接。
• 参数效率 – 大多数权重存储于 engram 中；一个 121 M 参数的模型表现等同于 50 M 参数模型。
• 字节级语法 – 从您的 JSON schema 编译而成的语法限制了 Token 生成，确保输出的语法正确性。
• 量化 – 权重以每个权重 2.125 比特（Cactus Quants）存储，发布的二进制文件大小为 8‑29 MB。

快速开始

pip install cactus-needle          # 核心库 + 运行时
pip install "cactus-needle[train]"  # 可选训练工具

import needle

@needle.tool
def get_weather(city: str):
    """获取城市的当前天气。"""
    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'}]

• run 调用会返回一个 JSON 对象，包含 function_calls、模型内部的 reasoning 追踪以及 confidence 分数。
• 若要进行语音转录，只需调用 needle.transcribe("clip.wav") 或使用流式 API needle.stream(chunks)。

性能评测

• 工具调用 – 在完整测试集上的精确匹配准确率超越了体积大 10 倍的模型。
• 结构化提取 – 字段级 micro‑F1 分数优于较大的基准模型。
• Whistle – 比 Whisper‑base 小 8.6 倍，首个 Token 生成速度快 6.6 倍，且在 LibriSpeech、SPGISpeech、Earnings‑22、FLEURS 等数据集上具有更低的词错误率（请参阅仓库中的基准测试 SVG 及 Cactus Compute 网站上的详细表格）。

自定义与微调

• 基于 LoRA 的本地微调 (needle finetune) – 在冻结基础模型的情况下训练注意力投影的适配器；使用 needle build 导出微调后的 .cact 文件。
• 全模型平台微调 (needle platform finetune) – 在 Cactus GPU 上运行，训练每一层深度，可选择重新校准置信度头，并返回适用于任何层数的微调二进制文件。
• 微调后的子网络（小至 2 层）在特定工具集上可超越 DeepSeek V4 Flash 等 29 M 参数模型。

部署

• 针对各目标平台（macOS‑arm64, linux‑arm64, WASI 等）提供预先构建的引擎二进制文件。
• 使用 needle build --platform <folder> [--layers N] 创建部署文件夹 – 该指令会获取适当的引擎并将 .cact 权重放置于旁。
• 直接运行二进制文件：./macos-arm64/needle --model needle3.cact --tools tools.json --serve。
• 默认启用遥测功能；可透过 NEEDLE_TELEMETRY=0 及 DO_NOT_TRACK=1 禁用。

资源

• 模型权重与引擎 – Hugging Face 仓库 Cactus-Compute/needle3 与 Cactus-Compute/whistle。
• 文档与指南 – 设计工具、置信度处理、结构化提取、微调、支持设备、.cact 文件格式及移植说明皆位于 Cactus Compute 博客（链接列于 README）。
• 交互式演示 – 请至 https://cactuscompute.com/needle 在浏览器中试用 Needle。

引用 若您在研究或产品中使用 Needle，请引用提供的 BibTeX 条目。

---

以上所有信息皆直接取自仓库的 README；未添加任何外部假设。