KuiperLLama_改进版

参考自 https://github.com/zjhellofss/KuiperLLama/tree/main#

KuiperLLama_改进版 是一个面向学习、实验和性能优化的 C++/CUDA 大模型推理框架。项目重点不是“调用现成推理引擎”，而是把推理链路拆到可以手写和分析的粒度：Tensor/Buffer、算子层、模型层、kernel dispatch、CUDA kernel、benchmark、profiling 与消融实验都在仓库内可直接查看和修改。

结合 docs/INDEX.md、docs/reference/project_analysis.md 与活跃文档，当前仓库的核心定位可以概括为：

• 手写 Llama/Qwen 推理框架
• 支持 CPU 与 CUDA 双后端
• 支持 FP32、FP16 混合精度与 INT8 路径
• 围绕 Prefill / Decode 做内核级优化和可复现实验

当前能力

• 模型支持：Llama2/3、Qwen2/2.5
• 精度支持：FP32、FP16 mixed precision（FP16 权重 + FP32 激活）、INT8
• 设备支持：CPU / CUDA
• 推理优化：
  • Sequence-level Prefill GEMM
  • 优化版 GEMV kernel（Decode / GEMV-prefill）
  • 优化版 FP16 GEMM kernel（Tensor Core 路径）
  • 可运行时切换的 kernel dispatch 与统一消融框架
• 工程特性：
  • mmap 权重加载
  • 自定义 CUDA 内存池
  • GQA 支持
  • benchmark / nsys / ncu 分析链路

最近进展

以下结论来自仓库内活跃文档，便于快速建立全局认识：

• docs/active/FP16_MIGRATION_SUMMARY.md：新增 FP16 权重推理路径，模型体积从约 4.7G 降到约 2.4G，且保持旧路径并行存在。
• docs/active/SEQUENCE_GEMM_PREFILL_DESIGN.md：把单序列 Prefill 从逐 token GEMV 改成 sequence-level GEMM，旧 Decode 路径不改。
• docs/active/PROFILING_ANALYSIS.md：在 RTX 4090 + Llama-3.2-1B FP32 + 262 tokens prompt 条件下，Prefill 从 1517ms 降到 229ms，约 6.62x。
• docs/active/record.md：整理了 FP16、GEMM 化、GEMV V7、GEMM V11 与统一消融框架的整体收益与面试化表达。

仓库结构

KuiperLLama1/
├── kuiper/      # 框架主体：base / tensor / op / model / sampler
├── demo/        # 推理、聊天、benchmark、统一消融入口
├── tools/       # 模型导出脚本
├── test/        # 单元测试与算子测试
├── docs/        # 活跃文档、参考文档、归档文档
├── practice/    # 手撕算子与练习材料
└── imgs/        # README 相关资源

如果你想从代码层面理解整个框架，推荐先看 docs/reference/project_analysis.md。

构建依赖

• CMake >= 3.16
• C++17 编译器
• CUDA Toolkit
• glog
• gtest
• Armadillo
• sentencepiece
• 启用 LLAMA3_SUPPORT 或 QWEN2_SUPPORT 时还需要：
  • absl
  • re2
  • nlohmann_json

项目支持两种依赖方式：

• 使用系统安装的依赖
• 通过 -DUSE_CPM=ON 自动拉取依赖

注意：

• 根目录 CMakeLists.txt 当前把 CMAKE_CUDA_ARCHITECTURES 固定为 89。如果你的 GPU 不是 Ada 架构，需要先调整这一项。
• Llama3/Qwen2 相关 demo 需要显式打开对应的 CMake 开关。

编译

mkdir -p build
cd build

# Llama3 / Qwen2.x 一起打开，自动下载依赖
cmake -DUSE_CPM=ON -DLLAMA3_SUPPORT=ON -DQWEN2_SUPPORT=ON ..
cmake --build . -j16

如果只需要 Llama 路径：

cmake -DUSE_CPM=ON -DLLAMA3_SUPPORT=ON ..
cmake --build . -j16

模型导出

Llama3

python3 tools/export.py Llama-3.2-1B.bin --hf=meta-llama/Llama-3.2-1B

Qwen2.5

python3 tools/export_qwen2.py Qwen2.5-0.5B.bin --hf=Qwen/Qwen2.5-0.5B

如果需要从 Hugging Face 镜像拉模型，可以先设置：

export HF_ENDPOINT=https://hf-mirror.com

运行示例

1. Llama 基础推理

./build/demo/llama_infer Llama-3.2-1B.bin meta-llama/Llama-3.2-1B/tokenizer.json

FP16 或 INT8 模型可追加：

./build/demo/llama_infer model.bin tokenizer.json --fp16
./build/demo/llama_infer model.bin tokenizer.json --quant

2. Prefill GEMV vs GEMM 对比

./build/demo/llama_seq_infer Llama-3.2-1B.bin \
  meta-llama/Llama-3.2-1B/tokenizer.json \
  --long 200 --mode compare

3. 统一 benchmark / ablation 入口

./build/demo/llama_unified model.bin tokenizer.json --benchmark --lengths 50,100,200

./build/demo/llama_unified tok.json \
  --ablation \
  --fp32-model Llama-3.2-1B.bin \
  --fp16-model Llama-3.2-1B-Instruct-fp16.bin \
  --lengths 50,100,200

交互式模式可切换 Prefill 策略和优化开关：

./build/demo/llama_unified model.bin tokenizer.json \
  --interactive --prefill gemm --opt-gemv --opt-gemm

4. Qwen2.5 推理

./build/demo/qwen_infer Qwen2.5-0.5B.bin Qwen/Qwen2.5-0.5B/tokenizer.json

文档导航

docs/ 已按“活跃 / 参考 / 归档”整理，入口见 docs/INDEX.md。

建议优先阅读：

• docs/reference/project_analysis.md：项目架构、模块分层、代码全景
• docs/active/FP16_MIGRATION_SUMMARY.md：FP16 路径设计与落地
• docs/active/SEQUENCE_GEMM_PREFILL_DESIGN.md：Prefill GEMM 化方案
• docs/active/PROFILING_ANALYSIS.md：benchmark、nsys、ncu 数据分析
• docs/active/QUICK_REFERENCE.md：关键入口文件与定位手册
• docs/active/GEMM_OPTIMIZATION_ROADMAP.md：后续优化路线
• practice/operator_handwrite/：算子手写练习

说明：

• docs/active/ 保存当前仍在使用的主文档
• docs/reference/ 保存深度参考材料
• docs/_archive/ 保存历史分析包，不建议作为当前入口

推荐阅读顺序

1. 先看 docs/reference/project_analysis.md 理解框架层次。
2. 再看 docs/active/FP16_MIGRATION_SUMMARY.md 和 docs/active/SEQUENCE_GEMM_PREFILL_DESIGN.md 理解两条主要优化线。
3. 最后看 docs/active/PROFILING_ANALYSIS.md 和 docs/active/QUICK_REFERENCE.md 对照代码和 profiler 结果。

备注

• README 这里只保留项目现状与高频入口，详细分析以 docs/ 为准。
• 如果你准备继续做 kernel 优化或写实验报告，优先从 docs/INDEX.md 进入，而不是直接翻归档文档。

todo

• 待上传整理好的文档 []