摘要
luogantt/LLM-inference-engine 是一个面向 DeepSeek-R1-Distill-Qwen-7B 的实验型 C++/CUDA 推理引擎。它没有把 forward 委托给 PyTorch、Transformers、vLLM 或 llama.cpp,而是把模型权重加载、RMSNorm、RoPE、GQA Attention、SwiGLU MLP、KV Cache 和 greedy decode 都落在 src/llm_cuda_lib.cu 里。我选的核心技术主题是:用一个 CUDA 动态库实现单 batch、单 token decode 的完整 forward 路径,并把 Python 压缩到 tokenizer 与 detokenizer 边界。这个仓库最适合当作“推理引擎拆解样本”:不是生产级 serving 框架,而是能看见每一步张量如何进 GPU、如何过 transformer block、如何进入下一 token 的最小骨架。
仓库版本:
bcee599eddd57929789d8a7ae6b92d77b1f39679。源码地址:luogantt/LLM-inference-engine。核心技术价值
常见的 LLM 推理学习路径有两个极端:一边是直接调用
transformers.generate(),易用但核心路径被框架藏起来;另一边是读 vLLM、TensorRT-LLM、llama.cpp 这类成熟项目,性能强但系统层次很多。这个仓库的价值在中间:它把 Qwen2/DeepSeek-R1-Distill-Qwen-7B 的 decode 路径压成一个单文件 CUDA 实现,牺牲通用性、批处理吞吐和工程完备性,换来可读、可改、可 benchmark 的底层推理链路。它真正解决的问题不是“替代成熟推理框架”,而是让工程师能把下面这些问题对应到代码:权重怎么从 safetensors 变成 GPU 指针,GQA 的 28 个 query head 怎么映射到 4 个 KV head,RoPE 旋转后的 K/V 如何写入 cache,decode 阶段怎样从上一轮 logits 做 argmax,再把 token 喂回 forward。
README 给出的性能记录是
max_seq=800、max_new_tokens=512、512 tokens = 65.6845 tok/s、max forward_ms = 16.1768。仓库里的 log.txt 也保留了 decode 每步约 14 到 16ms 的时间日志。这个数字我没有在当前机器复跑,因为本机没有 nvcc 和可用 CUDA 环境;它应被视作仓库记录,而不是本文重新验证的 benchmark。仓库定位
核心文件很少:
src/llm_cuda_lib.cu:主实现,包含 safetensors 扫描、CUDA kernel、权重加载、工作区分配、C ABI。
python_infer.py:Python 入口,用 HuggingFace tokenizer 编码 prompt,通过ctypes调用 CUDA 动态库,再解码生成 token。
Makefile.cuda_lib:动态库构建入口,目标产物是build/libllm_cuda.so。
deepseek-r1-7b/config.json:模型结构元数据,显示这是 Qwen2ForCausalLM 结构,hidden_size=3584、num_hidden_layers=28、num_attention_heads=28、num_key_value_heads=4、intermediate_size=18944、vocab_size=152064。
llm_cuda_python_tokenizer_v2/:较早版本,说明“Python tokenizer + CUDA shared library”的边界设计。
README 也明确写了它的目标:不依赖 PyTorch、Transformers、vLLM、llama.cpp,手写 RMSNorm、RoPE、GQA Attention、SwiGLU、KV Cache、decode。这里要注意一个细节:运行入口仍使用
transformers.AutoTokenizer,但模型 forward 不依赖 Transformers。核心依赖
CUDA Runtime / CUDA C++ 是运行时核心。
src/llm_cuda_lib.cu 直接包含 cuda_runtime.h,并用 cudaMalloc、cudaMemcpy、kernel launch 和 cudaDeviceSynchronize 管理 GPU 计算与内存。CUDA half / bf16 支持 用于权重存储与转换。源码包含
cuda_bf16.h、cuda_fp16.h,并定义 using WeightT = half。BF16 safetensors 权重读入后会转成 FP16 存到 GPU,以降低权重显存占用;部分 norm/bias 路径保持 FP32。NVIDIA WMMA 是一个可选优化入口。源码包含
mma.h,并有 USE_WMMA_LINEAR 编译开关;默认值是 0,因此默认路径仍走手写逐行 dot-product kernel。这个设计保留了 Tensor Core 方向,但没有把它作为默认行为。HuggingFace Transformers tokenizer 只在 Python 边界使用。
python_infer.py 用 AutoTokenizer.from_pretrained、apply_chat_template、encode 和 decode 处理文本与 token id,forward/decode 则交给 C ABI。safetensors 文件格式 是权重加载入口,但仓库没有依赖 safetensors C++ 库。它用 C++ 读取文件头长度、正则扫描 header 中的 dtype、shape、data_offsets,再定位 tensor bytes。这让依赖更少,也让格式处理很直观;代价是解析方式比较脆弱,不如正式 JSON/safetensors parser 健壮。
机制一:模型结构被编译成固定形状
这个引擎不是通用模型运行时。它把 DeepSeek-R1-Distill-Qwen-7B/Qwen2 这一组尺寸写成编译期常量:
load_config() 会读取模型目录里的 config.json,但它只允许这些关键尺寸与编译期常量一致;否则直接抛错。换句话说,配置文件主要用于读取 rms_norm_eps、rope_theta 这类运行参数,同时防止用户把不同结构的模型误加载进这个二进制。这是一种典型的学习型/实验型推理引擎取舍:牺牲多模型通用性,换来 kernel 和 buffer 维度都可以按目标模型写死,代码路径更短,也更方便定位性能热点。
机制二:手写 safetensors 扫描和权重落盘到 GPU
权重加载分两步。第一步是扫描模型目录里所有
.safetensors 文件,读取 safetensors header,并解析每个 tensor 的 dtype、shape 和 data offset:第二步是按名字加载具体 tensor。
load_tensor() 会把 BF16/F16/F32 转为 host FP32,再 cudaMalloc 和 cudaMemcpy 到 GPU;load_tensor_bf16() 则把 BF16/F32 转为 FP16,最后以 WeightT* 存在 GPU 上。真正组装模型的是
load_model():它加载 embedding、final norm、lm head,然后循环 28 层,逐层加载 q_proj/k_proj/v_proj/o_proj、attention bias、gate_proj/up_proj/down_proj、两组 layernorm 权重,并为每层分配 K/V cache:这里的核心价值是透明:成熟框架通常把权重加载、dtype 转换、device placement、KV cache 分配封装起来;这个仓库把它们放在同一个文件里,适合学习“一个模型实例到底占了哪些 GPU buffer”。
机制三:单 token forward 串起 transformer block
forward_token() 是整条推理链路的中心。它接收一个 token id 和当前位置 pos,先查 embedding,再跑 28 层 transformer block,最后输出 vocab logits:这段代码体现了一个重要简化:它没有实现批量 prefill 的矩阵化路径。
llm_prefill() 只是把 prompt token 一个个调用 forward_token(),逐步填 KV cache。因此它的目标不是最大化长 prompt prefill 吞吐,而是把 decode 视角下的单步 forward 讲清楚。机制四:GQA Attention、RoPE 和 KV Cache
模型配置里有 28 个 query head、4 个 KV head,所以这是 GQA。源码里
KV_DIM = N_KV_HEADS * HEAD_DIM = 512,而 query 仍是 HIDDEN = 3584。qkv_linear_kernel() 会在一个 kernel 中按 output 范围把计算分发给 Q、K、V:Q 输出 3584 维,K/V 各输出 512 维。RoPE 和 cache 写入融合在
rope_store_kv_kernel() 中。它对 Q 和 K 做旋转,同时把旋转后的 K 写入 kc[pos],把 V 写入 vc[pos]。这正是 decode 的关键:后续 token 不再重算历史 K/V,只需要在 attention 中读 [0..pos] 的 cache。attention_fused_kernel() 每个 block 对应一个 query head。它先根据 group = N_HEADS / N_KV_HEADS 把 query head 映射到 KV head,然后在当前位置之前的所有 token 上计算 score、做 softmax,再加权 V cache 得到当前 head 的 context。这不是 FlashAttention 风格的高性能实现,也没有分页 KV cache;它的价值是把 GQA 的 head 映射、RoPE、cache layout、softmax/apply 的数据流放在一段能读完的 CUDA 代码里。
机制五:Python 只守住 tokenizer 边界
python_infer.py 的 CudaLLM 类通过 ctypes.CDLL 加载 libllm_cuda.so,声明 llm_create、llm_prefill、llm_decode_one、llm_set_repetition_penalty 等 C ABI。Python 负责:- 用
AutoTokenizer加载 tokenizer。
- 可选使用 chat template,把 prompt 变成 token ids。
- 把 token ids 传给
llm_prefill()。
- 循环调用
llm_decode_one(),再用 tokenizer 解码文本。
C++ 对外暴露的接口很窄:
这个边界设计很适合实验:Python 保留文本处理和 CLI 便利性,CUDA 动态库保留 forward 的可控性。代价是采样策略也很简单,目前是 GPU 上两阶段 argmax,加一个 repetition penalty 标记表,没有 top-k、top-p、temperature 或 beam search。
执行流
一次生成大致是这样:
一个容易忽略的细节是
llm_decode_one() 先从现有 logits 采样 token,再用这个 token 做下一轮 forward。因此 llm_prefill() 结束后,最后一个 prompt token 的 forward 已经产生了第一轮可采样的 logits。可复用的实现经验
第一,学习型推理引擎可以故意固定模型形状。把层数、hidden size、head 数写死,会让它不通用,但能把注意力集中在 CUDA kernel、cache layout 和 decode 生命周期上。
第二,Python/CUDA 边界可以非常薄。只要 token id 协议稳定,Python 不需要参与 forward;这也让底层库未来可以被 CLI、服务端或 benchmark harness 复用。
第三,KV cache 是 decode 引擎的骨架。这个仓库按 layer 分配
kc/vc,每步在 pos 写入新 K/V,再让 attention 只扫 [0..pos]。哪怕实现不是高性能版本,也准确呈现了 cache 的语义。第四,手写 parser 和 kernel 让系统可读,但需要清楚承认边界。这里的 safetensors header 用正则解析,Makefile 和 CUDA 环境也比较依赖作者机器;如果要走向可复用项目,需要补正式解析、构建兼容性、错误测试和跨 GPU benchmark。
验证记录
我在当前环境做了这些验证:
git rev-parse HEAD:确认分析版本是bcee599eddd57929789d8a7ae6b92d77b1f39679。
python -m py_compile python_infer.py llm_cuda_python_tokenizer_v2/python_infer.py:Python 入口语法检查通过。
nvcc --version:当前机器没有nvcc,无法本地编译 CUDA 动态库。
make -f Makefile.cuda_lib -n lib A=sm_80:在当前 macOS/GNU make 环境返回Makefile.cuda_lib:11: *** missing separator. Stop.。文件里使用了.RECIPEPREFIX := >和>前缀 recipe;这在本机没有通过 dry-run。子目录llm_cuda_python_tokenizer_v2/Makefile使用 tab recipe,看起来更传统。
- 没有复跑 README 中的 65.6845 tok/s benchmark,因为缺少 CUDA 编译与 GPU 运行环境。
源码索引
- README 的项目目标、运行方式与性能记录:
- Python tokenizer/C ABI 入口:
- CUDA 推理核心:
- 模型配置样本:
- 性能日志:
结论
LLM-inference-engine 最值得看的不是“它是不是最快”,而是它把 LLM decode 的关键组件拆到了足够低、又没有大到难以追踪。对于想理解推理引擎的人,它提供了一条清晰路径:从 token id 进入 embedding,到 QKV、RoPE、GQA、KV cache、MLP、lm head,再到 argmax 采样和下一 token。如果要把它继续工程化,优先方向应该是:修复/统一 Makefile 构建体验,引入可靠 safetensors/JSON 解析,增加最小数值正确性测试,对比 Transformers 输出,随后再做 CUDA Graph、GEMV/MLP kernel 重写、量化和 speculative decoding。
- Author:迪
- URL:https://tangly1024.com/article/llm-inference-engine-cuda-single-token-decode
- Copyright:All articles in this blog, except for special statements, adopt BY-NC-SA agreement. Please indicate the source!
Relate Posts


