KuiperLLama 动手自制大模型推理框架，支持LLama2/3和Qwen2.5

新闻：新课发布，《动手自制大模型推理框架》，全手写cuda算子，课程框架支持LLama2和3.x以及Qwen2.5模型

嗨，各位朋友们好！我是 KuiperInfer 的作者。KuiperInfer 作为一门开源课程，迄今已经在 GitHub 上已斩获 2.5k star。 如今在原课程的基础上，我们全新推出了《动手自制大模型推理框架》， 新课程支持Llama系列大模型（包括最新的LLama3.2）以及Qwen2.5系列大模型，同时支持 Cuda 加速和 Int8 量化，自推出以来便广受好评。

《动手自制大模型推理框架》课程目录：

https://tvle9mq8jh.feishu.cn/docx/AGb0dpqwfohQ9oxx4QycqbCjnJh

《动手自制大模型推理框架》课程优势

1. 采用最新的C++ 20标准去写代码，统一、美观的代码风格，良好的错误处理；
2. 优秀的项目管理形式，我们采用CMake+Git的方式管理项目，接轨大厂；
3. 授人以渔，教大家怎么设计一个现代C++项目，同时教大家怎么用单元测试和Benchmark去测试验证自己的项目；
4. CPU算子和CUDA双后端实现，对时新的大模型（LLama3和Qwen系列）有非常好的支持。

如果你对大模型推理感兴趣，想要深入了解并掌握相关技术，想在校招、秋招面试当中脱颖而出，那么这门《动手自制大模型推理框架》课程绝对不容错过。快来加入我们，一起开启学习之旅吧！ 感兴趣的同学欢迎扫一扫课程下方二维码或者添加微信 lyrry1997 参加课程

《动手自制大模型推理框架》课程项目运行效果

LLama1.1b fp32模型，视频无加速，运行平台为Nvidia 3060 laptop，速度为60.34 token/s

第三方依赖

借助企业级开发库，更快地搭建出大模型推理框架

1. google glog https://github.com/google/glog
2. google gtest https://github.com/google/googletest
3. sentencepiece https://github.com/google/sentencepiece
4. armadillo + openblas https://arma.sourceforge.net/download.html
5. Cuda Toolkit

模型下载地址

1. LLama2 https://pan.baidu.com/s/1PF5KqvIvNFR8yDIY1HmTYA?pwd=ma8r 或 https://huggingface.co/fushenshen/lession_model/tree/main

2. Tiny LLama

• TinyLLama模型 https://huggingface.co/karpathy/tinyllamas/tree/main
• TinyLLama分词器 https://huggingface.co/yahma/llama-7b-hf/blob/main/tokenizer.model

3. Qwen2.5/LLama

   请参考本项目配套课程，课程参加方式请看本文开头。

模型导出

python export.py llama2_7b.bin --meta-llama path/to/llama/model/7B
# 使用--hf标签从hugging face中加载模型， 指定--version3可以导出量化模型
# 其他使用方法请看export.py中的命令行参数实例

编译方法

  mkdir build 
  cd build
  # 需要安装上述的第三方依赖
  cmake ..
  # 或者开启 USE_CPM 选项，自动下载第三方依赖
  cmake -DUSE_CPM=ON ..
  make -j16

生成文本的方法

./llama_infer llama2_7b.bin tokenizer.model

LLama3.2 推理

• 以 meta-llama/Llama-3.2-1B 为例，huggingface 上下载模型：

export HF_ENDPOINT=https://hf-mirror.com
pip3 install huggingface-cli
huggingface-cli download --resume-download meta-llama/Llama-3.2-1B --local-dir meta-llama/Llama-3.2-1B --local-dir-use-symlinks False

• 导出模型：

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

• 编译：

mkdir build 
cd build
# 开启 USE_CPM 选项，自动下载第三方依赖，前提是需要网络畅通
cmake -DUSE_CPM=ON -DLLAMA3_SUPPORT=ON .. 
make -j16

• 运行：

./build/demo/llama_infer Llama-3.2-1B.bin meta-llama/Llama-3.2-1B/tokenizer.json
# 和 huggingface 推理的结果进行对比
python3 hf_infer/llama3_infer.py

Qwen2.5 推理

• 以 Qwen2.5-0.5B 为例，huggingface 上下载模型：

export HF_ENDPOINT=https://hf-mirror.com
pip3 install huggingface-cli
huggingface-cli download --resume-download Qwen/Qwen2.5-0.5B --local-dir Qwen/Qwen2.5-0.5B --local-dir-use-symlinks False

• 导出模型：

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

• 编译：

mkdir build 
cd build
# 开启 USE_CPM 选项，自动下载第三方依赖，前提是需要网络畅通
cmake -DUSE_CPM=ON -DQWEN2_SUPPORT=ON .. 
make -j16

• 运行：

./build/demo/qwen_infer Qwen2.5-0.5B.bin Qwen/Qwen2.5-0.5B/tokenizer.json
# 和 huggingface 推理的结果进行对比
python3 hf_infer/qwen2_infer.py

Qwen3推理

和上面同理，我们先从huggingface仓库中将模型下载到本地。

1. tools/export_qwen3/load.py中导出为pth，模型的输入model_name和输出地址output_file依次需要填写；
2. 导出pth格式的模型后，再用同文件夹下的write_bin.py导出qwen.bin；
3. 用CMake选项QWEN3_SUPPORT重新编译项目，其他步骤就都是一样的了。

KuiperLLama 快速上手指南

KuiperLLama 是一个基于 C++20 手写的大模型推理框架，支持 Llama2/3/3.2 及 Qwen2.5/3 系列模型，提供 CPU 与 CUDA 双后端加速及 Int8 量化支持。

1. 环境准备

系统要求

• 操作系统: Linux (推荐) 或 Windows (需配置相应编译环境)
• 编译器: 支持 C++20 标准的编译器 (如 GCC 9+, Clang 10+, MSVC 2019+)
• 构建工具: CMake 3.14+
• GPU 加速 (可选): NVIDIA GPU + CUDA Toolkit

前置依赖

项目支持自动下载依赖，但需确保网络畅通。若需手动安装，主要依赖如下：

• google glog (日志)
• google gtest (单元测试)
• sentencepiece (分词)
• armadillo + openblas (线性代数)
• CUDA Toolkit (如需 GPU 加速)

提示：国内用户建议在下载 HuggingFace 模型时配置镜像源。

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

2. 安装与编译

步骤一：克隆项目

git clone <项目仓库地址>
cd <项目目录>

步骤二：配置与编译

推荐使用 USE_CPM 选项自动管理第三方依赖。根据目标模型开启对应支持选项。

通用编译命令（自动下载依赖）：

mkdir build 
cd build
# 默认支持 Llama2，如需支持 Llama3 或 Qwen 请添加对应标志
cmake -DUSE_CPM=ON .. 
make -j16

针对特定模型的编译配置：

• 支持 Llama3/3.2:

  cmake -DUSE_CPM=ON -DLLAMA3_SUPPORT=ON ..
  

• 支持 Qwen2.5:

  cmake -DUSE_CPM=ON -DQWEN2_SUPPORT=ON ..
  

• 支持 Qwen3:

  cmake -DUSE_CPM=ON -DQWEN3_SUPPORT=ON ..
  

3. 模型准备与导出

在运行推理前，需将 HuggingFace 格式的模型导出为框架专用的 .bin 格式。

场景 A：Llama3.2 示例

1. 下载模型：

   pip3 install huggingface-cli
   huggingface-cli download --resume-download meta-llama/Llama-3.2-1B --local-dir meta-llama/Llama-3.2-1B --local-dir-use-symlinks False
   

2. 导出模型：

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

场景 B：Qwen2.5 示例

1. 下载模型：

   huggingface-cli download --resume-download Qwen/Qwen2.5-0.5B --local-dir Qwen/Qwen2.5-0.5B --local-dir-use-symlinks False
   

2. 导出模型：

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

场景 C：Qwen3 示例

1. 先运行 tools/export_qwen3/load.py 导出为 .pth 格式。
2. 再运行 tools/export_qwen3/write_bin.py 转换为 .bin 格式。

4. 基本使用

编译完成并准备好模型文件后，即可运行推理演示程序。

运行 Llama 系列模型

# 格式：./llama_infer <模型.bin> <分词器文件>
./build/demo/llama_infer Llama-3.2-1B.bin meta-llama/Llama-3.2-1B/tokenizer.json

运行 Qwen 系列模型

# 格式：./qwen_infer <模型.bin> <分词器文件>
./build/demo/qwen_infer Qwen2.5-0.5B.bin Qwen/Qwen2.5-0.5B/tokenizer.json

验证结果（可选）

框架提供了 Python 脚本以便与 HuggingFace 官方推理结果进行对比：

# Llama3 对比
python3 hf_infer/llama3_infer.py

# Qwen2.5 对比
python3 hf_infer/qwen2_infer.py