深入解读Needle 3的.cact格式：Cactus Quants如何把权重压到2.125比特-平芜编程栈

深入解读Needle 3的.cact格式：Cactus Quants如何把权重压到2.125比特

Needle 3 是一款面向手机、可穿戴设备和微控制器的超小型 AI 基础模型，它的整个模型被装进一个名为.cact格式的单一文件 needle3.cact（约 35.3 MB）中。本文将带你读懂这个.cact文件：Cactus Quants 量化方案如何把 1.21 亿个权重平均压缩到2.125 比特/权重，以及各平台引擎如何直接映射这个文件完成推理。

📦 .cact 格式是什么：单文件 AI 模型容器

大多数模型生态需要一串文件：权重文件、词表、配置、运行时依赖。而 Needle 3 的部署侧非常克制：

组成	文件	作用
模型容器	needle3.cact	量化后的全部权重 + 部署元数据，35,335,380 字节
模型配置	config.json	架构、量化方案、部署格式声明
微调检查点	checkpoints/needle3.safetensors	供微调用的全精度权重（242 MB）
分词器	tokenizer/tokenizer.model、tokenizer/tokenizer.vocab	词表（vocab_size 仅 8192）

在 config.json 的deployment段可以看到它对自身格式的定位：

"format": "cact"
"runtime": "self-contained C++ / WebAssembly, no dependencies"

也就是说，.cact是"模型即文件"的容器：官方文档描述引擎会把这个文件map 到内存并在原地读取（in place），无需解压出一个临时模型目录。这对存储和内存都紧张的设备很关键——文件打开即加载，不产生额外拷贝。

⚡ 2.125 比特：Cactus Quants 的压缩账本

total_parameters为 121,021,910（见 config.json）。按不同位宽算一笔账：

格式	比特/权重	121M 权重所需空间
FP32（微调检查点）	32	≈ 484 MB
4-bit 量化	4	≈ 60.5 MB
2-bit 量化	2	≈ 30.3 MB
CQ2 混合精度	2.125	≈ 32.1 MB（纯权重数据）
.cact 实际文件	≈ 2.34	35.3 MB（含权重之外的部署数据）

几个要点：

相对 FP32 压缩约 13.7 倍：242 MB 的 needle3.safetensors 变成 35.3 MB 的 needle3.cact。
2.125 是加权平均值：并非所有权重都是 2-bit（下文方案详解），纯权重数据约 32.1 MB，加上字节级语法（grammar）等部署数据后，文件整体约 35.3 MB。
KV Cache 与激活保持 8-bit（kv_cache_bits: 8、activation_bits: 8），压缩集中在权重上，推理中间结果不受损。

🔍 混合精度方案：config.json 里的量化细节

config.json 的quantization段完整描述了 Cactus Quants 的配置：

"quantization": { "method": "cactus-quants", "scheme": "embedding=4,mhc=4,default=2", "group_size": 128, "kv_cache_bits": 8, "activation_bits": 8 }

📌 逐项解读：

embedding=4,mhc=4,default=2：分层混合精度。词嵌入（embedding）和多通道超连接（MHC，mhc_lanes: 4）使用 4-bit，其余权重（default）使用 2-bit。4-bit 只占很小比例，加权后恰好落在 2.125 比特/权重——README 中称其为CQ2-bit。
group_size: 128：每 128 个权重共享一组缩放参数（group-wise quantization）。这是低比特量化的标准做法：分组越细，组内动态范围越小，2-bit 下精度损失越可控。
KV Cache / 激活 8-bit：只压权重、不压运行时状态，保证生成质量。

🚀 引擎如何加载 .cact：各平台接口一览

仓库中每个平台文件夹都带一个不到 1 MB 的引擎，启动时加载needle3.cact：

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

不同接入方式读取同一份.cact字节流：

接入方式	接口	位置
C API	`needle_load(const unsigned char* cact, unsigned long long n)`	linux-x86_64/needle.h
WASI 组件	`load: func(model: list<u8>) -> result<_, failure>`	wasm-component/needle.wit
Python	`pip install cactus-needle`，引擎与权重一次拉取并缓存	python/ 下的各平台 wheel
浏览器	WebAssembly 引擎 + JS 胶水	wasm/needle.wasm、wasm/needle.js

C API 的加载接口直接接收原始字节数组（cact指针 + 长度），印证了.cact就是引擎可就地解析的二进制容器；WASI 侧的load(model: list<u8>)同样是"字节流进、模型出"。

🗂 一个模型，13 个平台目录

.cact是跨平台的中枢：同一份文件被下列每个平台的引擎加载，目录结构见 README.md 的 Deploy 一节：

桌面/服务器：linux-x86_64/、linux-arm64/、linux-riscv64/、linux-mipsel/、macos-arm64/
移动端：android-arm64/、android-armv7/、ios-arm64/、ios-sim-arm64/
嵌入式与浏览器：wasm/、wasm-component/、watchos-arm64/、tvos-arm64/、windows-x86_64/、windows-arm64/

📎 小结与延伸阅读

.cact是 Needle 3 的单文件部署容器：量化权重 + 部署元数据，35.3 MB 装下 121M 参数。
Cactus Quants 采用2-bit 为主、embedding/MHC 用 4-bit 的混合精度，group_size: 128分组缩放，平均 2.125 比特/权重。
各平台引擎 < 1 MB，直接映射.cact就地推理，运行时零依赖（C++ / WebAssembly）。

延伸阅读建议从这些文件入手：