cactus README

The project's README from github.com/cactus-compute/cactus. As one markdown file: README.md.

Cactus Compute - Sub-50mb Super Intelligence For Consumer Devices

Run text, speech and vision models locally with one Python package. Cactus provides tool calling, structured extraction, transcription, image understanding and model fine-tuning.

Install

pip install -U cactus-compute

Python 3.9 or later. The package downloads and caches the engine and requested model weights on first use. Inference runs locally and does not require JAX.

Agents

Needle 3 calls tools, extracts structured data and embeds text.

import cactus

@cactus.tool
def get_weather(city: str):
    "Get the current weather for a city."
    return {"city": city, "temp_c": 27, "sky": "clear"}

with cactus.Cactus(tools=[get_weather]) as agent:
    print(agent.run("What's the weather in Lagos?")["results"])

run() executes your functions and returns their results. Use complete() when you want to inspect the proposed calls before executing them.

Voice

Whistle transcribes speech in seven languages, with word timestamps and speech embeddings.

import cactus

print(cactus.transcribe("clip.wav")["text"])

Use a 16 kHz WAV file. Install cactus-compute[mic] for other sample rates or microphone capture.

Vision

Mirage describes images and extracts structured data.

import cactus

print(cactus.Mirage().describe("photo.png"))

Documentation

Migrating from cactus-needle? Use import cactus and the cactus command. Needle 2 remains on the legacy branch with cactus-compute<4. The earlier general inference SDK is now cactus-engine.

Anonymous Python usage counts can be disabled with CACTUS_TELEMETRY=0. See LICENSE for the Apache 2.0 license.

cactus (cactus-compute/cactus)

Searching Database…

14.5K ·GitHub
这是什么?Needle 2 是一个开放的 45M 参数模型,用于工具调用、设备操作和结构化数据提取。它以单个 14MB 的二进制文件发布,一个完整会话只占用约 28MB 内存。这个仓库是它的 Python 包,用于推理、LoRA 微调和导出。
它是 Python 库还是在设备上运行的模型?两个阶段都有:这个仓库是可以通过 pip 安装的 Python 包,而它的产出是一个自包含的 .cact 模型,供设备端引擎使用。该项目面向手机、可穿戴设备、智能家居、机器人、汽车和微控制器。
怎么把它跑起来?运行 pip install cactus-needle,描述你的工具,然后在 Python 中调用它们——推理引擎会从 Hugging Face 拉取一次并缓存,没有其他需要构建的东西。完全隔离(air-gapped)设备的离线安装方式见 doc/apis.md。
对话多长之后会内存不够用?它维护一个 256 token 的滑动窗口,并把工具固定为 KV sink,所以无论会话运行多久,内存都保持在 28MB 左右——但窗口本身很小。对于大型工具目录,内置的检索头每轮只渲染排名前五的工具。
它会把我的一些数据发送出去吗?推理完全不联网。Cactus 只收集严格匿名的使用遥测数据——函数名、包版本和操作系统,绝不会收集你的提示词、输出或数据。设置 NEEDLE_TELEMETRY=0 或 DO_NOT_TRACK=1 即可关闭。
和其他小模型相比怎么样?按 README 里的基准测试,它与 FunctionGemma 270M、LFM2.5 230M 和 Apple FM 互有胜负,同时体积只有它们的 1/5 到 1/70,并且以 2 bit 运行,而对手用 f16。
安装之前能在浏览器里先试试吗?可以——Playground 让你选择一个预设,编辑工具或提示词后直接运行,后续提问会延续同一个对话。它的 Finetune 按钮会运行微调流程,并返回一个可下载的 .cact 文件。
它底层用的是什么架构?它是一个 Simple Attention Network:用 Hadamard MLP 替代了 FFN,再加上 GQA 注意力、engram 键值记忆和多通道超连接(hyper-connections)。设计和消融实验见 arXiv:2607.18363 的论文。
它能从纯文本中提取结构化数据,不只是调用工具吧?可以——把结构声明成 Pydantic 模型,然后调用 extract(),就会返回一个带类型的对象。使用原始 JSON schema 以及用 complete() 手动驱动循环的方式见 doc/apis.md。
Size
4.8 MB
Stars
14.5K
Updated
CommitNov 05
Age
8mo
Commits · 90 Days