LiteInfer

从零手写的 GPT-2 Small CPU 推理引擎（C++17）。

完整实现：Tensor → 算子（matmul/attention/LayerNorm/GELU/Softmax）→ Transformer Block → 权重加载 → byte-level BPE → 贪婪自回归生成， 并通过与 PyTorch 的逐层差分测试验证正确性。

架构地基

按工业标准分四层，依赖单向（core <- ops <- model <- engine），由 test_architecture 强制检查，违规即 CI 失败：

engine   Engine 生成编排 / CLI / bench
model    GPT2Model / KVCache / BPETokenizer
ops      matmul / attention / norm / gelu / softmax
         kernel 注册表 + KernelContext（ISA/几何/设备派发）
         形状推导 infer_*（执行计划基础）
core     Tensor（dtype 化字节存储 + owned/borrowed）/ DType / Device /
         Status / Span / Shape / Allocator(Arena) / KernelContext /
         ISA 检测 / Profiler / util

地基契约（详见 docs/foundation.md 与 docs/adr）：

• 可预期失败一律返回 Status（模型/分词器加载），编程错误用异常
• 热路径零 malloc 目标由 ArenaAllocator 支撑
• decode 链路全部临时张量从 KernelContext 的 Arena 分配（M3 已闭环）
• 运行时 ISA 检测（core/isa.h），kernel 派发不写死在构建参数
• 新算子/后端 = 注册新 kernel（ops/kernel_registry.h），调用点零改动
• 新模型 = 实现 IModel + 注册工厂（model/interface.h），Engine 零改动
• 模型层不感知 CLI；量化是显式状态（quantize() / quantized()）

项目整体评估（规模/架构/正确性/性能/工程化/差距与路线）见 docs/assessment.md。

性能（本机实测，124M fp32 模型）

指标	naive V1.0	当前（KV Cache + AVX2/OpenMP）
prefill ~1000 token	38.7 tok/s	~400 tok/s
decode	27226 ms/token	~31-35 tok/s（fp32）/ ~50-56 tok/s（INT8）
32 token 端到端	2.1 tok/s	~33 tok/s（fp32）/ ~60+ tok/s（INT8）

详见 docs/optimization.md。每次新的性能结论都应按 基准复现规范记录硬件、编译器、线程数、权重与命令，避免将不同机器的数字直接比较。

构建

.\build.ps1

（build.ps1 已配置本机 MSYS2 g++、便携 CMake 与本地 GoogleTest 源码。）

需要 CMake + 支持 OpenMP/AVX2 的编译器；Linux/macOS 用户可直接：

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DLITEINFER_WEIGHTS_DIR=weights
cmake --build build -j
ctest --test-dir build

运行

.\build\liteinfer.exe --weights weights --prompt "Hello, my name is" --max-tokens 32
.\build\liteinfer.exe --weights weights --prompt "Hello, my name is" --max-tokens 32 --quantize

基准与性能回归门槛

.\build\liteinfer_bench.exe --weights weights --prefill-len 974 --decode-steps 50
.\build\liteinfer_bench.exe --weights weights --prefill-len 974 --decode-steps 50 --quantize
.\build\liteinfer_bench.exe --weights weights --prefill-len 974 --decode-steps 50 --json bench.json

基准支持 --json <file> 结构化输出，并默认用 bench/thresholds.json 做性能回归门槛（超阈值非零退出；换机器用 --no-threshold）。 完整的复现与报告格式见 docs/benchmarking.md。 将某次正确性或性能结果作为正式发布结论前，还应遵循 发布证据规范：轻量 CI 绿色不能替代带真实权重的手动差分验证。

测试

.\build\ctest.exe --test-dir build --output-on-failure

11 个测试套件：core、Tensor、Shape 推断、算子、kernel 注册表、架构依赖 检查、BPE、模型接口工厂、GPT-2 差分（logits/hidden vs PyTorch）、端到端 生成（逐 token 与 PyTorch 贪婪输出一致）、INT8 量化质量门槛。

无权重环境（CI）：依赖权重的套件自动 SKIP，其余全量执行。

CI 三个任务：quick（Release 全量无权重测试 + 架构门槛）、 sanitizers（Debug + ASan/UBSan 无权重套件）、full-weights （手动触发，下载权重跑完整差分验证）。

项目结构

src/
  core/        # Tensor(dtype化字节存储+owned/borrowed)/DType/Device/Status/Span/Shape/Allocator/ISA/Profiler/util
  ops/         # matmul/attention/norm/activation（AVX2/INT8/标量多路径）
  model/       # GPT2Model/GPT2Block/KVCache + 权重加载
  tokenizer/   # byte-level BPE
  runtime/     # Engine + CLI 入口
tests/         # 11 个测试套件 + PyTorch 参考数据
bench/         # 性能基准
docs/          # foundation.md（地基目标）/ ADR / architecture / optimization
.github/workflows/ci.yml

权重准备

python scripts\export_weights.py --weights weights --output-dir weights
python scripts\dump_reference.py --weights weights

weights/ 需要 HuggingFace gpt2 的 model.safetensors / config.json / vocab.json / merges.txt（约 522MB）。

状态

• 项目骨架 + 构建系统 + GoogleTest
• Tensor / 基础算子 + 单测
• GPT-2 模型 + 权重导出加载 + BPE
• KV Cache 增量解码 + AVX2/OpenMP matmul
• INT8 权重量化（decode 1.9x，--quantize）
• 与 PyTorch 逐层差分 + 端到端生成一致
• 四层架构地基 + Status 错误体系 + Arena/ISA/Profiler
• 架构测试（依赖方向） + CI（轻量全绿/手动完整验证）
• 性能基准与文档
• CUDA 后端（下一阶段）

架构

见 docs/architecture.md。