🌰 Acorn Framework

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

以小搏大的 AI 运行与训练框架：INT4 压缩态常驻 + 原生 AVX2 内核 + KV int8 + 层流式 + 投机解码 + LoRA + AutoBit + 能效治理，零依赖核心，全部自研。

⚡ 60 秒看到它跑真模型

pip install acorn-llm          # 零依赖；有 gcc 会自动编译 AVX2 内核
acorn chat                     # ← 打开本地 AI 聊天 TUI

============================================================
  Acorn 本地聊天室 | Qwen3-8B | eco=whisper | CPU
  /exit 退出 · /new 新对话 · /eco 切档 · /spec 投机 · /raw 渲染开关
============================================================

你> 1+1等于几？

AI> thinking...
    嗯，用户问的是 1+1 等于几。这是最基础的算术……

    think done

    1+1 等于 2。这是整数加法的基本运算……

实测数据（本机：16 核 CPU / 16.5GB RAM / 无 GPU / 一块 P620）

🧠 这个框架到底做了什么（不是 PPT，全部实测）

📦 安装

pip install acorn-llm              # 零依赖核心（推荐）
pip install acorn-llm[fast]        # + NumPy（BLAS + 向量化，约 50× 提速）
pip install acorn-llm[gpu]         # + PyTorch（CUDA Graph 后端）

要求 Python ≥ 3.9。有 gcc/cl 时首次运行自动编译原生内核（缓存到 ~/.cache/acorn）；没有编译器也不影响使用（自动回退 NumPy 路径，功能一致、速度较低）。

💬 TUI 聊天（装完就能用）

acorn chat                                  # 自动搜索本地模型
acorn chat --model-dir ./models/Qwen3-8B    # 指定模型目录
acorn chat --model-dir ./qwen --auto-convert  # 目录里是 safetensors 就地转换
acorn chat --system "你是一个简洁的技术助手"   # 设定人设
acorn chat --gpu                            # 用 CUDA 后端（若有）
acorn chat --eco turbo                      # 全速（风扇起飞）

模型从哪来？（三种方式）

① 直接下载已转换的模型？ —— 没有官方分发，但转换只需一次（10 分钟内完成）。

② 从 ModelScope / HuggingFace 下载原始权重 → 自动转换（推荐）

# ModelScope（国内直连，无需梯子）
mkdir -p models/Qwen2.5-0.5B
curl -L -o models/Qwen2.5-0.5B/model.safetensors \
  "https://modelscope.cn/api/v1/models/Qwen/Qwen2.5-0.5B-Instruct/repo?FilePath=model.safetensors"
curl -L -o models/Qwen2.5-0.5B/tokenizer.json \
  "https://modelscope.cn/api/v1/models/Qwen/Qwen2.5-0.5B-Instruct/repo?FilePath=tokenizer.json"
curl -L -o models/Qwen2.5-0.5B/config.json \
  "https://modelscope.cn/api/v1/models/Qwen/Qwen2.5-0.5B-Instruct/repo?FilePath=config.json"

# 然后二选一：
acorn chat --model-dir models/Qwen2.5-0.5B --auto-convert   # 自动转 + 直接聊

手动转换（可复用、参数自动读 config.json，rope_theta 等超参不会手填错）：

python -m acorn convert --src models/Qwen2.5-0.5B/model.safetensors \
                        --out models/Qwen2.5-0.5B/qwen.acorn

自动从 config.json 读取：层数 / 维度 / 头数 / KV 头 / FFN / 词表 / rope_theta（Qwen2/3 是 1e6！）/ tie_word_embeddings / qk_norm（Qwen3）。 转换是流式的：RAM 峰值 ≈ 单个张量，16GB 内存机器可转 16GB 模型（多分片自动走流式路径）。

HuggingFace 同理，把 URL 换成 https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct/resolve/main/...。

③ 已有的第三方 .acorn / GGUF？ —— GGUF 暂不支持，请先用 acorn convert（支持 safetensors 系）。

模型目录长什么样

models/Qwen2.5-0.5B/
├── model.safetensors     # 原始权重（可选，--auto-convert 用）
├── config.json           # HF 配置（--auto-convert / convert 自动读它）
├── tokenizer.json        # 必需
└── qwen.acorn            # 转换产物（必需，或由 --auto-convert 生成）

该下载哪个模型？（已验证可跑）

Qwen3 用 QK-Norm 架构，Acorn 已支持（数值 vs 独立参考实现 rel=3.8e-7）； Qwen2/3 的 rope_theta=1e6 会在转换时自动从 config.json 读取（手填 10000 会得到乱码）。

TUI 里的命令

界面说明

• 思考流：模型的 thinking 内容以深灰逐字显示，头部 thinking...，结束切 think done
• 正文：正常色逐字符流式，标题/列表/代码块自动着色（Markdown）
• 跨轮复用 KV：每轮只前向增量，历史不重算

🧪 30 秒训一个自己的模型

import acorn

model = acorn.train(corpus=open("my_novel.txt", encoding="utf-8").read(),
                    steps=300, batch_size=12, ctx=64)
acorn.pack(model, "mymodel.acorn")     # INT4 打包
m = acorn.load("mymodel.acorn")
print(m.generate("第一章", 200, temperature=0.8))

训练栈全是自研：矩阵级 autograd（13 个可微节点）· AdamW · warmup + 余弦调度 · 全局范数梯度裁剪 · 数值对拍测试（44+9 位置有限差分）。

LoRA 轻量微调

import acorn
from acorn import lora

model = acorn.train(steps=100)
lora.inject_lora(model, rank=8)          # 冻结基座 + 注入低秩适配器
acorn.train(model=model, corpus="新领域文本…", steps=60)
lora.merge_lora(model)                   # 合并回稠密权重
acorn.pack(model, "tuned.acorn")

真实模型微调（诚实说明）

• 0.5B 级：本机可行（acorn.to_trainable(acorn.load(...)) → LoRA 流程同上）
• 8B 级：fp32 反量化需 32GB 内存，本机不可行；且 LLaMA 路径目前是数值推理路径，尚未接入 autograd 图——这是路线图 M2 项

🖥️ CLI 全表

acorn chat                             # ★ 交互式 TUI 聊天
acorn train  --steps 200 --out m.acorn # 训练 + INT4 打包
acorn run    --model m.acorn --stream  # TinyGPT 推理
acorn convert --src X.safetensors --out X.acorn   # 真实模型转换（自动读 config.json）
acorn run-llama --model X.acorn --tokenizer tok.json --prompt "你好" --stream
acorn bench  --model m.acorn           # 基准（吞吐/带宽/规模外推/内核状态）
acorn lora   --model m.acorn --corpus my.txt --steps 150   # LoRA 微调

🧰 Python API 速查

🎛️ 调优菜单（按需叠加，互不冲突）

🏗️ 架构

L5 用户 API      acorn chat / train / pack / load / generate_chat / bench
L4 编排层       AutoBit · LoRA · 剪枝 · 转换器 · 能效治理
L3 运行时        AcornPack 容器 · 层流式调度 · 分页/int8 KV Cache · 投机解码
L2 计算层        微型 autograd(13 节点) · RoPE · SwiGLU · GQA
L1 内核后端      AVX2 int4 GEMM(在线解包+FMA) · 常驻线程池 · CUDA Graph
L0 算子层        NumPy 加速 + 纯 Python 回退（零依赖）

📁 项目结构

acorn-framework/
├── PLAN.md                 # 总体项目计划（里程碑/风险/验收标准）
├── RUNTIME_PLAN.md         # 运行模型详细计划（格式/内存/量化/API）
├── USAGE.md                # 使用手册
├── assets/                 # Logo（主/深色/favicon/横版字标）
├── acorn/
│   ├── _kernels/           # 原生内核：acorn_int4.c + 自动编译/ctypes 绑定
│   ├── _ops.py             # 张量算子（NumPy 加速 + 纯 Python 回退）
│   ├── _autograd.py        # 微型自动微分（requires_grad 冻结机制）
│   ├── model.py            # TinyGPT（RoPE/因果注意力/MLP）
│   ├── llama.py            # LLaMA/Qwen 架构 + 转换器
│   ├── shard.py            # 多分片流式转换（RAM 峰值 < 1GB）
│   ├── safetensors.py      # 零依赖 safetensors 读写
│   ├── tokenizer.py        # BPE 分词器（字节级 + 增量解码）
│   ├── pack.py             # INT4 量化 + .acorn 容器（mmap 加载）
│   ├── stream.py           # 层流式加载
│   ├── kvcache.py          # fp32 / int8 KV 缓存
│   ├── runtime.py          # 运行时主循环
│   ├── session.py          # 多轮对话（跨轮 KV 复用）
│   ├── chat.py             # 模板/惩罚/停止序列
│   ├── chat_cli.py         # TUI 入口（acorn chat）
│   ├── tui.py              # 终端 UI（思考流 + 流式 Markdown）
│   ├── speculative.py      # 投机解码（Prompt-Lookup）
│   ├── autobit.py          # 动态混合位宽
│   ├── prune.py            # 结构化剪枝
│   ├── lora.py             # LoRA
│   ├── train.py            # 训练引擎（AdamW/裁剪/调度）
│   ├── bench.py            # 性能基准
│   ├── eco.py              # 能效治理
│   ├── gpu.py              # CUDA Graph 后端
│   └── __main__.py         # CLI
├── examples/               # 演示脚本（hello_acorn / run_qwen3 / bench_*）
└── tests/                  # 58 项自测

🧪 测试与质量保证

python tests/test_seed.py     # 基础（autograd 数值对拍 / 量化 round-trip）
python tests/test_v02.py      # 框架（RoPE/KV Cache/LoRA/CLI）
python tests/test_v03.py      # 内核（AVX2 数值 / 压缩态 / 性能）
python tests/test_v04.py      # 真实模型（LLaMA 数值 / Qwen bias / BPE）
python tests/test_v04b.py     # 端到端流水线
python tests/test_v06.py      # AutoBit
python tests/test_v07.py      # 层流式
python tests/test_v08.py      # KV int8
python tests/test_v09.py      # 真实模型回归（Qwen2.5）
python tests/test_v10.py      # 剪枝 / 稀疏内核
python tests/test_v11.py      # Chat 层 / 投机解码金标准
python tests/test_v12.py      # Qwen3 QK-Norm / 分片转换
python tests/test_v13.py      # 能效治理

质量红线（均有测试守护）：

• LLaMA/Qwen 前向 vs 独立参考实现：rel ≤ 3.8e-7
• 投机解码 vs 常规贪心：逐字一致
• 稀疏内核 vs 稠密：diff = 0
• AutoBit 同预算：质量 ↓87% 误差

🗺️ 路线图

⚠️ 已知限制（诚实清单）

• int3 量化已实现但很慢（3-bit 无法 SIMD 化，实测比 int4 慢 4 个数量级），默认不用
• CUDA 后端在 P620 上仍不及 CPU int4 内核（Pascal 算力弱 + eager 开销）；CUDA Graph 已解决发射开销，int4 GPU 内核是下一步
• 8B 训练在本机不可行（fp32 反量化 32GB）；且 LLaMA 路径尚未接入 autograd
• 不支持 GGUF / AWQ / GPTQ 权重，只支持 safetensors 系
• 单机单卡，无分布式训练
• TensorFlow 2 对比：在算子库/编译器/分布式/生态上 Acorn 落后几个数量级；Acorn 的主张限定在「小内存 CPU 推理 + 训推一体 + 零依赖 + 能效治理」这条窄道

🤝 参与

git clone <your-fork> && cd acorn-framework
pip install -e .[fast,dev]
python tests/test_seed.py && python tests/test_v04.py

欢迎提交 PR：新模型架构适配、新内核、基准数据、文档。

📄 License

MIT

pip install acorn-llm
acorn chat            # interactive TUI with a local model