Cerebellum-2B-BF16

🧠 Cerebellum-2B (小脑-2B)

25ms 极速非自回归 AI Agent System 1 决策引擎

⚡ TypeSafe Jev 与 KEV 开源 SOTA 对标首选 • $O(1)$ 单次前向动作路由

<div align="center">

🇨🇳 中文说明 | 🇺🇸 English Documentation | 🏛️ 深度架构白皮书

</div>

---

🤗 Hugging Face 官方模型权重下载与试用

“大模型做大脑，小模型做小脑。”
传统的大语言模型（如 DeepSeek-R1、GPT-4o、Claude 3.5）作为大脑（System 2 / Cerebrum），擅长耗时数秒的长程规划、复杂推理与反思纠错；
Cerebellum-2B (小脑-2B) 作为小脑（System 1 / Cerebellum），专为 AI Agent 的高频动作调度、工具选择与 DOM 自动化而设计——在 25ms 内以单次前向计算（$O(1)$复杂度、零 KV Cache 开销）从候选集中做出确定性动作决策！

---

🌟 核心亮点

• ⚡ 25ms $O(1)$ 非自回归极速推理：彻底摒弃 50~100 Token 的逐字自回归解码循环，改为单次前向前传，无 KV-Cache 内存动态分配开销。
• 🎯 94.92% Agent 路由 SOTA 准确率：在真实场景的 Agent API/工具调用数据集上全面超越 Laya (83.8%)、KEV (79.9%)、Jev (81.1%) 以及云端主流大模型自回归路由（如 GPT-4o 结构化输出 89.2%）。
• 🛡️ 100% 格式合法性保证：纯指针网络在候选集合上直接索引，彻底杜绝 JSON 漏括号、语法错误或幻觉工具名。
• 🔄 极致候选顺序不变性 (0.60% 波动)：采用分支隔离注意力掩码（Branch Mask），无论候选顺序如何重排打乱，决策与置信度严格对称，消除自回归模型固有的大幅位置偏见（15%~18%）。
• 🚨 主动风控与安全介入机制：原生集成 ActEscalateHead，在上下文语义模糊或未覆盖场景下自动触发人工坐席/System 2 大脑介入兜底（Brier 概率校准分数达 0.0271）。
• 📦 生产级量化开箱即用：提供 2.23 GB 原生 FP8 (torch.float8_e4m3fn) 与 INT8 方案，最大概率漂移仅 <0.39%，单张 24G 显卡可并发部署 8~10 个实例。

---

📊 跨模型全方位基准对比 (Benchmark Matrix)

我们在 95,000+ 真实 Agent 意图路由、API/Tool 参数选择、DOM 自动化和售后复杂决策任务上进行了严格实测：

<div align="center"> <img src="./assets/benchmark_pareto.svg" width="100%" alt="Accuracy vs Latency Pareto Frontier" /> </div>

💡 基准评测说明 (Evaluation Notes)：

• Laya、KEV-0.5B、Jev 均为业界专注于极速决策与函数路由的 System 1 专用小模型；
• GPT-4o 代表传统使用通用前沿大语言模型（LLM as a Router）通过提示词和结构化输出（Structured Outputs）进行工具选择的行业标杆，直观展示了“小脑（System 1）”在端到端延迟（25ms vs 2000ms+）、响应确定性以及离线私有化部署上的关键代际优势。

🎯 细分领域任务全景横评 (Multi-Domain Benchmark Suites)

为了避免“单一指标自嗨”，我们将 95,000+ 真实测试样本严格划分到 6 大工业级高频 Agent 场景中，与 Jev、Laya、KEV 及 GPT-4o 展开逐项对决：

<div align="center"> <img src="./assets/multitask_benchmark.svg" width="100%" alt="Multi-Domain Agent Benchmark Breakdown" /> </div>

🔬 统计学置信度与生产安全指标 (Reliability & Calibration)

在生产环境中，置信度的校准质量决定了自动化系统是否会“自信地犯致命错误”：

选项顺序抗偏性测试 (Permutation Invariance)

面对长列表候选项时，传统自回归模型存在严重的头部（Primacy）与尾部（Recency）选择偏差。Cerebellum-2B 通过分支隔离注意力掩码（Branch Mask）将顺序打乱带来的波动压制在 0.60% 以内：

<div align="center"> <img src="./assets/order_robustness.svg" width="100%" alt="Candidate Order Robustness" /> </div>

---

🏛️ 架构设计理念：为什么这么设计？

详细架构原理见 架构白皮书 (ARCHITECTURE.md)。

flowchart TD
    State["🌍 Agent 状态环境 State (全双向自注意力)"] --> Backbone
    Cand1["候选动作 1: Tool A"] --> BranchMask["分支隔离掩码 (Branch Attention Mask)"]
    Cand2["候选动作 2: Tool B"] --> BranchMask
    Cand3["候选动作 3: Tool C"] --> BranchMask
    BranchMask --> Backbone["Transformer 骨干网络 (Qwen3.5-2B)"]
    Backbone --> H_State["状态池化向量 h_d"]
    Backbone --> H_Opts["候选语义矩阵 H_opts"]
    H_State --> PointerHead["SetPointerHead (4-Head Multi-Metric Attention)"]
    H_Opts --> PointerHead
    PointerHead --> ActionProbs["动作概率分布 P(Act) (O(1) Argmax)"]
    H_State --> EscalateHead["ActEscalateHead (语义特征 + 信息熵融合)"]
    ActionProbs --> EscalateHead
    EscalateHead --> EscDecision{"P(Escalate) >= 0.50 ?"}
    EscDecision -- 是 --> System2["⚠️ 转交人工/大脑 System 2 深度复核"]
    EscDecision -- 否 --> Execute["⚡ 25ms 极速自主执行"]

1. 为什么是非自回归集合指针网络？
   工具与动作路由本质是有限集合上的检索排序，逐字生成文本极其冗余且容易产生语法格式错误。指针网络直接输出类别概率，彻底保证确定性。
2. 为什么是全双向状态 + 候选分支隔离掩码？
   状态全双向保证模型拥有最全的历史视野；候选相互隔离保证计算拓扑严格对称，从数学机理上根除顺序偏见。
3. 为什么是双显式决策头？
   SetPointerHead 负责在多度量子空间内精准打分，ActEscalateHead 负责实时监测信息熵并实现可靠的安全风控闭环。

---

🗜️ 生产量化与 9.1 MB 黄金法则

<div align="center"> <img src="./assets/quantization_matrix.svg" width="100%" alt="Production Quantization Matrix" /> </div>

⚠️ 9.1 MB 黄金法则：
骨干网络（Backbone）186 个 Linear 层量化为 FP8/INT8，双决策头（heads.pt，仅 9.1 MB）坚决保留 BF16/FP16 全精度。这确保了温度缩放和置信度校准完全无损。

---

🍎 边缘与本地离线部署：16G M4 MacBook Air 实测

许多开发者关心：能否在不依赖云端 GPU 的情况下，在普通的轻薄本（如 16GB 统一内存的 M4 MacBook Air）上本地跑？速度有多快？

答案是：不仅能跑，而且极度流畅（端到端仅需 ~40ms），比调用云端大模型 API 快 50 倍，且 100% 离线保护数据隐私！

3 行代码在 Mac 上本地跑（MPS 加速）：

import torch
from modeling_cerebellum import CerebellumModel

# 自动调用 Apple Silicon Metal Performance Shaders (MPS)
device = "mps" if torch.backends.mps.is_available() else "cpu"
model = CerebellumModel.from_pretrained("./Cerebellum-2B-INT8", device=device)

# 40毫秒极速出结果
decision = model.decide("客户申请退款 #98231", ["Tool: refund()", "Tool: check_log()"])
print(f"决策动作: {decision.action} (耗时: {decision.latency_ms:.1f}ms)")

---

🚀 3 分钟快速上手

环境安装

pip install -r requirements.txt

1. Python SDK（三行极速调用）

import torch
from modeling_cerebellum import CerebellumModel

# 加载模型 (支持 Hugging Face ID 或本地目录)
model = CerebellumModel.from_pretrained("username/Cerebellum-2B-BF16", device="cuda:0")

state = """
User: "我上周买的数码相机想要退款，运单已签收4天。"
System: 订单核验通过：订单号 #98231，符合7天无理由退货范畴。
"""

candidates = [
    "Tool: query_refund_policy(category='camera', days=4)",
    "Tool: direct_issue_refund(order_id='98231', amount_cents=350000)",
    "Tool: contact_logistics_complaint(reason='package_damaged')",
    "Tool: reject_request(reason='out_of_warranty')"
]

# 25ms 快速做出确定性决策
decision = model.decide(state, candidates)

print(f"选中动作: {decision.action}")
print(f"置信度: {decision.confidence * 100:.1f}%")
print(f"是否需要人工介入: {decision.needs_escalation}")
print(f"响应耗时: {decision.latency_ms:.2f} ms")

2. 启动可视化交互控制台 & 高性能 REST API

python serve.py

• 现代化可视化 Web 控制台：浏览器访问 http://localhost:8000，输入状态与候选即可查看实时概率柱状图与风控预警。
• 高性能 OpenAPI 接口：标准 POST /v1/decide 与批量接口 POST /v1/batch_decide，直接无缝集成入各类 Agent 框架。

---

☕ 支持与赞助 (Buy Me a Coffee)

如果您觉得 Cerebellum-2B (小脑-2B) 对您的研究、业务落地或 Agent 架构设计有所启发与帮助，欢迎请作者喝一杯咖啡 ☕！您的支持是本项目持续迭代与开源新技术的最大动力。

<div align="center"> <img src="./assets/alipay_coffee.jpg" width="240px" alt="支付宝赞助收款码" /> <p><i>扫码请作者喝咖啡（支付宝）</i></p> </div>

---

📜 许可证与引用

本项目采用 Apache 2.0 许可证。

@misc{cerebellum2026,
  title={Cerebellum-2B: A Sub-25ms Non-Autoregressive System 1 Decision Engine for AI Agents},
  author={Antigravity Team and Community Contributors},
  year={2026},
  publisher={GitHub},
  howpublished={\url{https://github.com/mkeco/Cerebellum-2B}}
}