Metadata-Version: 2.4
Name: acorn-llm
Version: 0.9.1
Summary: Acorn — Big models. Tiny footprint. 以小搏大的 AI 运行与训练框架（INT4 压缩态推理 / KV int8 / 层流式 / 投机解码 / LoRA / 能效治理 / 零依赖核心）
Author: Acorn Contributors
License: MIT
Project-URL: Homepage, https://github.com/yourname/acorn
Keywords: llm,inference,quantization,int4,transformers,qwen,llama,cpu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: fast
Requires-Dist: numpy>=1.24; extra == "fast"
Provides-Extra: gpu
Requires-Dist: torch>=2.0; extra == "gpu"
Provides-Extra: dev
Requires-Dist: numpy>=1.24; extra == "dev"

<div align="center">

<img src="assets/logo.svg" width="160" alt="Acorn Framework Logo"/>

# Acorn Framework 🌰

**Big models. Tiny footprint. —— 芥子纳须弥，把大模型装进口口袋。**

*以小搏大的 AI 运行与训练框架：更小的空间 · 更快的速度 · 更少的痛苦*

![status](https://img.shields.io/badge/status-v0.3--native--kernel-green) ![deps](https://img.shields.io/badge/core%20deps-0-blue) ![python](https://img.shields.io/badge/python-3.9%2B-blue) ![license](https://img.shields.io/badge/license-MIT-black)

</div>

---

## 为什么是 Acorn？

模型越来越大，设备没有变大。7B 参数的模型以 FP16 存储要 **14 GB**，而世界上绝大多数设备只有 8–16 GB 内存。

Acorn 的信念：**推理和训练不应该被显存大小判处死刑。**

| 痛点 | Acorn 的回答 | 实测 |
|---|---|---|
| 模型放不进显存 | **int4 压缩态常驻**（0.5 B/参数，绝不物化 fp 矩阵）+ **层流式** | 7B = **2.91 GB**；流式 **154 MB**（省 19x） |
| 推理太慢 | **原生 AVX2 内核** + 常驻线程池 + RoPE + KV Cache + 投影融合 | 7B decode **4.7 tok/s**（带宽已到机器上限 72%） |
| 量化掉精度 | **AutoBit**：逐层敏感度实测（跨度 10⁵×）→ 字节预算下自动混合位宽 | 同预算 KL **↓87%** |
| 长上下文吃内存 | **KV Cache int8**（逐 token absmax 量化） | 内存 **28%**，输出偏差 0.4% |
| 模型太大 | **结构化剪枝 + 稀疏内核**（FFN 神经元幅度剪枝 + 位图跳零） | 50% 剪枝：字节 50%，**加速 x5.8**，loss 仅 x1.08 |
| 接不了真模型 | **safetensors 零依赖读写 + LLaMA 架构 + BPE 分词器 + 流式转换器** | 数值与独立参考实现一致（rel 1.5e-7） |
| 框架太重 | **零依赖核心**（NumPy 可选加速），纯 Python 也能跑全链路 | 0 依赖 |
| 训练门槛高 | **LoRA**：冻结基座只训适配器，合并后可直接打包 | 25.3% 参数学新语料 |
| API 记不住 | **3 行代码跑模型**，流式输出、top-k/top-p 开箱即用 | — |

### 🖥️ v0.9：聊天室 UI + GPU 后端

```
交互式聊天（examples/chat.py）:
  • 思考流: [thinking...] 深灰显示思考 → [think done] → 正文
  • 终端 Markdown 渲染（粗体/代码块/标题/列表, 零依赖 ANSI）
  • 多轮对话跨轮 KV 复用 · /eco /spec /raw 命令

GPU 后端（acorn.gpu, torch CUDA）:
  • 发现并启用了本机被闲置的 Quadro P620 4GB（装 cu126 torch 后可用）
  • 数值验证通过（top-1 与 CPU 一致）
  • 诚实结论: P620 + eager torch = 10.9 tok/s < 自研 AVX2 CPU 内核 12.6 tok/s
    （Pascal 算力弱 + 250 内核发射/token 的 eager 开销吞掉带宽优势）
  • 这反而证明: 自研 CPU 内核已把这台机器推到 GPU 难以企及的效率
```

### 🍃 v0.8 颠覆点：性能/瓦特治理（行业忽视的维度）

**实测颠覆**：decode 带宽受限负载下，**2 线程跑出与 16 线程相同的速度**，
而 16 线程多烧 CPU 时间（发热/风扇）只为心理安慰——这是所有默认全核的
推理框架（含 Ollama）都在犯的错。

```
Qwen2.5-0.5B 实测（60 token 贪心）:
  档位       线程   tok/s    CPU秒/token   风扇
  turbo      16    9.44     0.2500        轰鸣
  whisper     2    9.60     0.2357        几乎不转   <- 同速、更省电、更安静
```

```python
m = acorn.load("qwen.acorn", tokenizer_path=..., eco="whisper")
# whisper  = 2 线程 + race-to-idle 间隙 + 低进程优先级（静音）
# balanced = 4 线程（速度甜点）;  turbo = 全核（默认）
```

### 🌌 v0.7 终极验证：Qwen3-8B 上机

```
16.5GB RAM / 无 GPU 的机器，加载并运行 8B 模型（PyTorch 在此机器直接 OOM）

┌────────────────────────────────────────────────────────────┐
│ 转换: 5 分片 bf16 (16.4GB) --流式(RAM峰值<1GB)--> 4.10GB INT4 │
│ 加载: 77.6s | 常驻 4.10GB（fp32 等价 16.4GB → 内存 ÷16）      │
│ 速度: 1.7-2.2 tok/s（纯 CPU decode）                          │
├────────────────────────────────────────────────────────────┤
│ "用一句话解释量子纠缠" -> "首先，我需要确保自己正确理解…"      │
│   （Qwen3 思维链被正确激活）                                   │
│ "check if a number is prime" -> 推理式英文回答                │
│ 数学链 3+3=6, 4+4=8, 5+5=10 … 全对                            │
└────────────────────────────────────────────────────────────┘
```

> `python examples/run_qwen3.py`。架构支持：Qwen3 QK-Norm（数值 vs 独立参考
> 实现 rel=3.8e-7）+ 多分片 safetensors 流式转换（`acorn.shard`）。

### ⚡ v0.6 破壁：投机解码 + 聪明度修正

```
投机解码 (Prompt-Lookup Decoding) —— 打破自回归串行墙:
  一次前向验证 K 个草稿 token, 接受率 1.8-2.3, 实测加速 1.3-1.7x
  金标准验证: 贪心投机输出与常规解码逐字一致（数学保证 + 实测确认）

聪明度三件套 (Instruct 模型的正确打开方式):
  ChatML/Llama3 模板 + 重复惩罚 + 停止序列 -> 裸续写 -> 真正的对话质量

  fibonacci 任务: 10.8 -> 18.3 tok/s (x1.70)
  Q&A 模式任务  : 13.0 -> 21.5 tok/s (x1.65)
```

```python
text, stats = m.generate_chat(
    "Write a Python function",        # 自动 ChatML 模板
    max_tokens=128,
    temperature=0.7, repetition=1.15, # 重复惩罚
    speculative=True,                 # 投机解码 (贪心验证)
)
```

### 📊 全维度实测数据（examples/benchmark_report.py）

| 维度 | 基线 | Acorn | 倍数 |
|---|---|---|---|
| 8B 权重体积 | 16.4 GB bf16 | **4.10 GB INT4** | **÷4** |
| 8B 常驻内存 | 16.4 GB+（本机 OOM） | **4.10 GB** | **÷16**（vs fp32） |
| 8B 转换 RAM 峰值 | 32 GB+（常规 OOM） | **<1 GB**（流式） | 16GB 机器转 8B |
| GEMV 4096×11008 | 12.3 ms fp32 BLAS | **1.95 ms** int4 内核 | **快 6.3×** |
| KV Cache（ctx2048×36层） | 0.60 GB fp32 | **0.15 GB** int8 | **÷4**（偏差0.4%） |
| 0.5B 投机 decode | 9.7 tok/s | **12.8-21.5 tok/s** | **快 1.3-1.65×** |
| 同预算量化质量 | 统一 INT4 KL=0.00104 | **AutoBit KL=0.00014** | **↓87%** |
| 训练吞吐（CPU 参考） | — | **3284 tok/s** | — |

### 🏆 v0.5 王牌验证：真实 AI 模型在 Acorn 上运行

```
Qwen2.5-0.5B-Instruct (阿里通义, Apache-2.0, 0.49B 参数)
┌──────────────────────────────────────────────────────────────┐
│ 原始     : 988 MB bf16 (safetensors)                          │
│ Acorn    : 249 MB INT4 (25%) + KV int8                        │
│ 生成速度 : 10+ tok/s                                           │
│ 依赖     : transformers/torch/llama.cpp = 0 （全部自研）       │
├──────────────────────────────────────────────────────────────┤
│ "The capital of France is"  ->  " located in which of the..." │
│ "人工智能的未来"            ->  "是什么？2020年，人工智能..."   │
│ "def hello_world():"        ->  " print(\"I'm so very..."      │
└──────────────────────────────────────────────────────────────┘
```

> `python examples/run_qwen.py` 一键复现。链路上每一环——safetensors 读取、
> LLaMA 前向、BPE 分词、INT4 量化、AVX2 内核、KV int8、采样——都是 Acorn 自己实现的。

### v0.4 实测（真实 7B 规格，非玩具模型）

```
┌─ LLaMA-7B 规格 (L=32, d=4096, H=32, KV=8, FFN=11008, V=32000) ─────┐
│ int4 常驻内存 : 2.91 GB   (fp32 等价 23.2 GB, 压缩 7.98x)           │
│ decode 吞吐   : 4.7 tok/s   (18.6 GB/s 有效带宽 = 机器上限 72%)      │
│ 层流式常驻    : 154 MB     (省 19x, 磁盘 IO 代价 5.9x)              │
│ AutoBit 同预算: KL 0.000138 vs 统一 INT4 的 0.001036 (↓87%)        │
│ 数值正确性    : 与独立参考实现 rel=1.5e-7                            │
└─────────────────────────────────────────────────────────────────────┘
```

> 数据来自 `examples/bench_llama7b.py` / `bench_stream.py`，真实运行输出。
> **关于物理极限**：decode 是带宽受限任务，本机内存带宽上限 ~26 GB/s（实测
> memcpy），我们达到 18.6 GB/s = 72%。要再快只有两条路：**读更少的字节**
> （AutoBit/稀疏化）或**换更强的内存**（GPU/更快的 DDR）。

## 30 秒上手

```bash
python examples/hello_acorn.py        # 全链路：训练→量化→流式生成→bench→LoRA
```

```python
import acorn

model = acorn.train(steps=200)            # 1. 训练（RoPE + warmup/cosine）
acorn.pack(model, "mymodel.acorn")        # 2. INT4 量化打包（全模型 6.4x）
model = acorn.load("mymodel.acorn")       # 3. 加载
for tok in model.generate_stream("Acorn: ", 90, top_p=0.95):
    print(tok, end="")                    # 4. 流式生成（KV Cache）
```

CLI 也是一等公民：

```bash
python -m acorn train  --steps 200 --out hello.acorn
python -m acorn run    --model hello.acorn --prompt "Acorn: " --stream
python -m acorn bench  --model hello.acorn
python -m acorn lora   --model hello.acorn --corpus my.txt --steps 150
```

### 原生内核（可选，零依赖仍可运行）

有 gcc/cl 时自动编译并缓存内核（AVX2 + 常驻线程池）；没有编译器则自动回退
NumPy 路径，**功能完全一致，只是慢一些**：

```python
from acorn import _kernels as K
K.info()   # {'native': True, 'avx2': True, 'threads': 16, 'compiler': '...'}
```

内核做三件事：**① 在线解包 int4**（不物化权重）**② SIMD FMA 点积** ③ **常驻线程池**。

## 仓库结构

```
acorn-framework/
├── PLAN.md                 # 🗺️ 总体项目计划（愿景/里程碑/风险）
├── RUNTIME_PLAN.md         # ⚙️ 运行模型的详细计划（格式/内存/量化/API）
├── assets/                 # Logo 资产
│   ├── logo.svg            #   主 logo（≥32px 场景，全细节版）
│   ├── logo_favicon.svg    #   16–24px 简化版（无闪电、亮黄茎）
│   ├── logo_dark.svg       #   深色背景版（提亮帽体/茎）
│   └── logo_wordmark.svg   #   横版字标（图形 + ACORN + 口号）
├── acorn/                  # 框架核心（零第三方依赖）
│   ├── _kernels/           #   原生内核后端（可选，可自动编译）
│   │   ├── acorn_int4.c    #     AVX2 int4 在线解包 + FMA 点积 + 线程池
│   │   └── __init__.py     #     自动编译/探测/ctypes 绑定/NumPy 回退
│   ├── _ops.py             #   零依赖张量算子（NumPy 加速 + 纯 Python 回退）
│   ├── _autograd.py        #   微型自动微分引擎（requires_grad 冻结机制）
│   ├── model.py            #   TinyGPT（RMSNorm/RoPE/MHA/MLP + KV Cache 前向）
│   ├── train.py            #   训练引擎（AdamW/梯度裁剪/warmup+cosine）
│   ├── pack.py             #   INT4 逐通道量化 + .acorn 容器格式
│   ├── runtime.py          #   运行时（加载/流式生成/top-p/KV Cache 主循环）
│   ├── lora.py             #   LoRA：冻结基座 + 低秩适配器 + merge
│   ├── bench.py            #   性能基准（prefill/decode/缓存收益）
│   └── __main__.py         #   CLI（train/run/bench/lora）
├── examples/
│   ├── hello_acorn.py      # 全链路演示（训练→量化→流式→bench→LoRA→merge）
│   └── bench_7b.py         # 7B 规格实测（内存占用 + decode 吞吐）
└── tests/                  # 26 项自测（梯度对拍/KV一致性/LoRA/内核/CLI）
```

## 技术支柱

```
        ┌──────────────────────────────────────┐
        │            SIZE  ·  更小              │
        │   AutoBit 动态混合位宽 · INT4/3/2      │
        │   结构化剪枝 · 低秩权重共享            │
        ├──────────────────────────────────────┤
        │            SPEED ·  更快              │
        │   层流式加载 · 分页 KV Cache          │
        │   算子融合 · 稀疏注意力 · 可插拔内核    │
        ├──────────────────────────────────────┤
        │           SIMPLE ·  更简单            │
        │   3 行推理 · 5 行训练 · 零依赖核心     │
        │   自动设备编排 (NVMe/RAM/VRAM)        │
        ├──────────────────────────────────────┤
        │           SCALE ·  更从容             │
        │   QLoRA 轻训练 · CPU offload          │
        │   弹性断点续训 · 声明式配置            │
        └──────────────────────────────────────┘
```

## 路线图（摘要）

| 阶段 | 代号 | 目标 | 状态 |
|---|---|---|---|
| M0 | **Seed 种子** | 设计冻结 + 种子内核（训练/量化/生成全链路可跑） | ✅ 本仓库 |
| M1 | **Sprout 发芽** | 推理 MVP：7B 模型 INT4 在 8GB 内存无独显设备跑通 | 🔜 |
| M2 | **Grow 生长** | 训练 MVP：单张 12GB 消费级 GPU QLoRA 微调 7B | ⏳ |
| M3 | **Tree 成树** | 生态：模型 Hub、HF 一键转换、插件内核 | ⏳ |
| M4 | **Forest 成林** | 分布式训练、编译器级图优化 | ⏳ |

详见 [PLAN.md](PLAN.md) 与 [RUNTIME_PLAN.md](RUNTIME_PLAN.md)。

## 差异化定位（诚实版）

Acorn 不假装在所有维度都赢过成熟项目：

| | PyTorch | llama.cpp | vLLM | **Acorn** |
|---|---|---|---|---|
| 内核极致性能 | ✓ | ✓✓ | ✓✓ | 借力可插拔内核 |
| 小内存运行 | 部分 | ✓ | ✗ | ✓（核心目标） |
| 训推一体轻量化 | 训强推弱 | 推强训弱 | 仅推理 | ✓（核心目标） |
| 上手心智负担 | 高 | 中 | 中 | **3 行代码**（核心目标） |
| 动态混合位宽量化 | 插件 | 手动 | ✗ | ✓ AutoBit（核心目标） |

策略：**不重造轮子，做统一编排层**——自有模型格式 + 自动量化 + 内存编排 + 极简 API，内核可插拔（NumPy 参考内核 → 未来适配 llama.cpp/自研内核）。

## License

MIT
