acorn-llm 0.9.2__tar.gz

acorn_llm-0.9.2/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: acorn-llm
+Version: 0.9.2
+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

acorn_llm-0.9.2/README.md

@@ -0,0 +1,279 @@
+<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

acorn_llm-0.9.2/acorn/__init__.py

@@ -0,0 +1,53 @@
+"""
+acorn — Big models. Tiny footprint. 芥子纳须弥。
+==================================================
+以小搏大的 AI 运行与训练框架。
+
+三行核心 API:
+    model = acorn.train(steps=200)     # 训练
+    acorn.pack(model, "m.acorn")       # INT4 量化打包
+    model = acorn.load("m.acorn")      # 加载 -> generate / generate_stream
+
+v0.7: Qwen3-8B 上机 (QK-Norm 架构 + 多分片流式转换, 16GB RAM 跑 8B)
+v0.6: 投机解码 (Prompt-Lookup, 1.3-1.7x, 金标准验证) / Chat 模板+重复惩罚+停止序列
+v0.5: 真实模型端到端 (Qwen2.5-0.5B 实跑) / KV Cache int8 / 结构化剪枝+稀疏内核 /
+      Qwen QKV-bias 支持
+v0.4: 真实模型接入 (safetensors/转换器/LLaMA 架构/BPE) / AutoBit 混合位宽 /
+      层流式加载 (常驻省 19x)
+v0.3: 原生 int4 内核 (AVX2 + 常驻线程池) / 压缩态常驻 (0.5B/参数) / 嵌入表 gather
+v0.2: RoPE / KV Cache / 流式生成 / top-p / LoRA / 梯度裁剪 / 余弦调度 / CLI / bench
+
+    python -m acorn train|run|bench|lora --help
+
+计划: PLAN.md / RUNTIME_PLAN.md
+"""
+from __future__ import annotations
+
+__version__ = "0.9.2"
+
+from . import _ops as _ops  # noqa: F401  (内部)
+from .model import TinyGPT, TinyGPTConfig
+from .train import train, AdamW
+from .pack import pack_model, quantize_int4_channelwise, dequantize_int4
+from .runtime import AcornModel, load, to_trainable
+from . import lora  # noqa: F401  (acorn.lora.inject_lora / merge_lora / stats)
+from .bench import bench  # noqa: F401
+from . import autobit  # noqa: F401  (acorn.autobit 敏感度/位宽计划)
+from . import llama as llama_mod  # noqa: F401  (acorn.llama 真实模型转换)
+from . import tokenizer as tokenizer_mod  # noqa: F401  (BPE 分词器)
+
+
+def pack(model, path: str, verbose: bool = True) -> dict:
+    """量化打包模型到 .acorn 文件（train/pack/load 三件套之二）。"""
+    return pack_model(model, path, verbose=verbose)
+
+
+__all__ = [
+    "TinyGPT", "TinyGPTConfig",
+    "train", "AdamW",
+    "pack", "pack_model",
+    "quantize_int4_channelwise", "dequantize_int4",
+    "AcornModel", "load", "to_trainable",
+    "lora", "bench", "autobit", "llama_mod", "tokenizer_mod",
+    "__version__",
+]