1. 项目概述一个为学习而生的CPU推理引擎如果你对大型语言模型LLM的底层推理过程充满好奇想亲手拆解一个现代模型看看它是如何在CPU上“思考”并吐出文字的那么你可能会对deepseek.cpp这个项目感兴趣。这不是一个旨在与llama.cpp或vLLM竞争的通用生产级引擎而是一个由开发者 Andrew Chan 出于“好玩和学习”目的创建的、专门针对 DeepSeek 系列模型的 C 实现。它的代码库极其精简核心代码不到2000行就像一个结构清晰的“解剖标本”让你能直观地理解从加载权重、执行注意力计算到生成下一个token的完整流程。对于机器学习工程师、系统开发者或者任何想深入理解 Transformer 模型在 CPU 上如何高效执行推理细节的人来说这个项目提供了一个绝佳的、可随意修改的起点。2. 核心设计思路极简与专注2.1 为何另起炉灶从 yalm 到 deepseek.cpp项目的起源很有意思。作者最初是想在yalm另一个轻量级 LLM C 实现中添加对 DeepSeek 模型的支持。但很快他发现DeepSeek 模型架构特别是 V2 及之后的版本引入了 MoE、MLA 等复杂特性所需的改动如此之大以至于会破坏yalm项目本身的简洁性。于是他决定将这些改动独立出来形成一个专门针对 DeepSeek 的代码库。这个决策背后有几个关键考量保持专注只支持 DeepSeek 家族模型意味着可以移除大量用于适配其他模型架构如 LLaMA、GPT-2 等的通用代码和条件判断。代码逻辑变得直线化更容易阅读和调试。极致精简与llama.cpp超过 25 万行的庞大代码库相比deepseek.cpp的核心逻辑代码不包括第三方库如fmt和json不到 2000 行。这种体量使得任何人都有可能在几个小时内通读整个推理流程。高度可 hack代码精简的直接好处就是“可 hack 性”极强。你想实验一种新的注意力实现方式想调整 MoE 专家的路由策略或者只是想加个日志看看某层输出的具体数值在这样一个小型代码库中这些操作的门槛被大大降低。作者本人也将其用作研究 CPU 上单批次 DeepSeek 解码性能的“试验床”。2.2 性能取舍简单实现 vs. 极致优化deepseek.cpp在性能优化上做了一个明确的选择优先保证代码的清晰易懂而非极致的运行时效率。这体现在几个方面线程模型它直接使用了 OpenMP 的并行指令而不是像llama.cpp那样实现一个复杂的全局线程池配合自旋锁屏障。OpenMP 由编译器管理代码简洁但线程调度的开销和灵活性可能不如手动管理的线程池。对于学习和理解并行计算的基本原理来说OpenMP 的方式更直观。功能范围目前它只实现了解码Decoding阶段即逐个 token 生成的增量推理。预填充Prefill阶段一次性处理整个提示词以及基于预填充的优化技术如推测解码、多 token 预测都尚未实现。这意味着在处理长提示时效率可能不如完整的引擎。但这恰恰简化了代码让你可以集中精力理解最核心的生成循环。内存管理它提供了-L参数来将模型权重锁定在物理内存中避免被交换到磁盘这是保证性能的基本操作。但对于更复杂的内存池、分页加载等优化目前并未涉及。尽管做了这些简化根据作者的基准测试在单批次解码速度上deepseek.cpp竟然能接近llama.cpp的性能。例如在 AWS r6a.12xlarge 实例上运行 DeepSeek-V3 的 Q2_K 量化模型llama.cpp达到 4.57 token/秒而deepseek.cpp达到了 4.02 token/秒。作者坦诚这部分性能得益于直接使用了llama.cpp中高度优化的 Q2_K 量化点积计算内核。这个结果说明一个清晰简单的架构配合关键路径上的高效内核也能获得不错的性能这为学习和后续优化留下了充足的空间。3. 环境搭建与模型准备实操指南3.1 系统环境与依赖安装要运行deepseek.cpp你需要一个支持 C20 的编译环境。以下以 Ubuntu 22.04 LTS 为例展示从零开始的完整步骤。首先安装必要的系统工具和 Git LFS用于下载大模型文件# 更新软件包列表并安装基础编译工具 sudo apt update sudo apt install -y build-essential cmake git # 安装 Git LFSLarge File Storage sudo apt install -y git-lfs git lfs install # 安装 Python 开发环境用于运行转换脚本 sudo apt install -y python3-dev python3-pip3.2 获取代码与模型权重接下来克隆deepseek.cpp的代码仓库并下载一个 DeepSeek 模型。这里我们以较小的DeepSeek-V2-Lite模型为例方便快速测试。# 1. 克隆 deepseek.cpp 仓库 git clone https://github.com/andrewkchan/deepseek.cpp.git cd deepseek.cpp # 2. 克隆 DeepSeek-V2-Lite 模型仓库注意模型文件很大需要耐心等待 git clone https://huggingface.co/deepseek-ai/DeepSeek-V2-Lite ../DeepSeek-V2-Lite注意下载模型可能需要较长时间并且需要足够的磁盘空间DeepSeek-V2-Lite 约 20-30GB。确保你的网络环境稳定。3.3 编译与模型转换deepseek.cpp不能直接使用 Hugging Face 格式的.safetensors文件需要先将其转换为项目自定义的.dseek格式。# 进入项目目录如果不在的话 cd deepseek.cpp # 安装 Python 依赖主要是 torch 和 transformers用于加载原始模型 pip install . # 执行模型转换脚本 # 命令格式python convert.py --quant 量化类型 输出目录名 原始模型路径 # 这里我们转换为 FP16 精度输出到 v2-lite-f16 目录 python convert.py --quant fp16 v2-lite-f16 ../DeepSeek-V2-Lite/转换过程会读取原始模型配置和权重进行必要的重组和格式转换最终在v2-lite-f16目录下生成.dseek权重文件和一个config.json。如果一切顺利你会看到类似 “Done!” 的成功提示。3.4 首次运行测试编译项目并运行一个简单的推理测试# 编译项目使用 make make -j$(nproc) # -j 参数指定并行编译的作业数$(nproc) 是你的 CPU 核心数 # 运行一个简单的文本补全任务 # 命令格式./build/main 模型目录 -i “提示词” -m c -t 温度值 ./build/main v2-lite-f16 -i What is a large language model? -m c -t 1.0-m c指定运行模式为补全completion。-t 1.0设置采样温度为 1.0。温度越高输出随机性越大越低输出越确定。作者指出DeepSeek 模型在较低温度下容易陷入重复循环1.0 左右是个不错的起点。如果看到模型开始逐词输出回答恭喜你环境搭建成功4. 深入使用与参数详解4.1 命令行工具全解./build/main是项目的主要可执行文件。通过-h参数可以查看完整的帮助信息。我们来详细拆解每个选项基础参数checkpoint_dir必需参数。指定转换后的模型目录路径如v2-lite-f16。-L性能关键参数。锁定模型权重到物理内存禁止操作系统将其交换到磁盘。这能显著提升推理速度尤其是在内存紧张时。注意此操作通常需要sudo权限。-m指定运行模式。可选值completion(或c)文本补全/生成模式默认。interactive交互式对话模式。perplexity计算给定文本的困惑度PPL用于评估模型质量。passkey一种测试模型长上下文“大海捞针”能力的模式。-T int设置滑动窗口的上下文长度。设置为 0 则使用模型定义的最大上下文长度。补全模式 (-m c) 专属参数-n int生成 token 的数量。默认 256。设为 0 表示生成直到达到最大序列长度设为 -1 表示无限生成需手动中断。-i string直接输入提示词字符串。-f filepath从指定文件读取提示词。-t float温度用于控制随机性。默认 1.0。-p floatTop-p 采样核采样的 p 值。默认 0.95。与温度结合使用用于控制生成多样性。困惑度模式 (-m perplexity) 专属参数必须通过-i,-f或-w之一提供输入文本。-w使用内部预置的 wikitext 文本来计算困惑度。Passkey 模式 (-m passkey) 专属参数-n int插入的干扰行数。默认 250。用于测试模型在长文本中定位关键信息的能力。-l intpasskey密钥在文本中的位置。设为 -1 表示随机位置。4.2 性能调优关键线程控制CPU 推理的性能极度依赖于线程的合理利用。deepseek.cpp使用 OpenMP 进行并行化你需要通过环境变量OMP_NUM_THREADS来明确指定使用的线程数。# 示例使用 16 个线程运行推理 OMP_NUM_THREADS16 ./build/main v2-lite-f16 -i Explain quantum computing. -m c -t 0.8 # 更常见的做法是绑定到具体的CPU核心避免线程迁移开销需系统支持 # 例如在拥有 32 个逻辑核心的机器上使用前 16 个核心 OMP_NUM_THREADS16 OMP_PROC_BINDclose OMP_PLACEScores ./build/main ...实操心得线程数设置作者建议的一个经验法则是使用物理核心数的一半作为起始点。这是因为超线程Hyper-Threading带来的逻辑核心在密集计算任务中可能引发资源争用反而降低效率。例如一台 8 核 16 线程的 CPU可以尝试设置OMP_NUM_THREADS8。最佳值需要通过实际基准测试来确定。你可以写一个简单的脚本循环测试不同的线程数如 1, 2, 4, 8, 16并记录 token/s 的速度找到性能拐点。4.3 量化方案选择与内存估算deepseek.cpp支持多种量化格式在精度和内存/速度之间进行权衡。以下是支持矩阵的解读和选型建议模型 \ 量化Q2_KQ3_KQ4_KF8E5M2FP16FP32DeepSeek-V2-Lite✅✅WIP✅✅✅DeepSeek-V2✅✅WIP✅✅✅DeepSeek-V3✅✅WIP✅--Q2_K / Q3_K来自llama.cpp的 K 量化方案。它采用块状量化在极低的比特数2-bit, 3-bit下仍能保持相对较好的精度是内存极端受限情况下的首选。例如DeepSeek-V3 的 Q2_K 量化版本仅需约 206GB 内存。F8E5M2 / F8E4M38-bit 浮点量化。F8E5M2(1 位符号5 位指数2 位尾数) 和F8E4M3(1 位符号4 位指数3 位尾数) 是两种不同的 8-bit 浮点格式。它们比整数量化如 INT8对模型精度更友好速度也很快是平衡内存、速度和精度的不错选择。DeepSeek-V3 的 F8E5M2 版本需要约 650GB 内存。FP16 / BF16半精度浮点数。精度损失很小是追求高精度输出的标准选择但内存占用是 FP32 的一半。FP32单精度浮点数。最高精度用于调试或作为精度基准但内存占用最大速度最慢。注意事项量化与模型行为量化选择使用convert.py脚本时通过--quant参数指定如--quant q2_k。内存警告运行超大模型如 DeepSeek-V3前务必估算内存。例如FP16 的 V3 模型可能需要超过 1TB 内存。如果物理内存不足系统会使用交换空间Swap这将导致性能急剧下降可能从每秒几个 token 降到几分钟一个 token。强烈建议在拥有充足物理内存的机器上运行并配合-L参数。温度与重复如作者所述DeepSeek 模型在较低温度如 0.1下进行长文本生成时有较高概率陷入重复循环。如果你发现生成内容开始不断重复之前的句子尝试将温度-t提高到 0.8 或 1.0 通常可以缓解此问题。5. 项目内部机制探秘与 hack 指南5.1 代码结构速览deepseek.cpp的代码结构非常扁平核心文件不多易于导航deepseek.cpp/ ├── src/ │ ├── deepseek.cpp # 模型架构定义、前向传播核心逻辑 │ ├── gemm.cpp # 矩阵乘法相关实现可能调用 BLAS │ ├── quantize.cpp # 量化与反量化 kernels │ └── ... ├── convert.py # 模型转换脚本Python ├── main.cpp # 命令行入口、推理循环 └── CMakeLists.txt # 构建配置想要理解推理流程可以从main.cpp的main()函数开始看它如何加载配置、权重然后进入生成循环。生成循环的核心是调用deepseek.cpp中定义的forward函数。5.2 理解推理循环从 prompt 到 token一个简化的推理循环伪代码如下这有助于理解main.cpp中实际发生的事// 1. 加载模型和分词器 Model model load_model(“model_dir“); Tokenizer tokenizer load_tokenizer(“model_dir“); // 2. 将输入文本编码为 token IDs std::vectorint input_ids tokenizer.encode(prompt); // 3. 初始化推理状态K/V 缓存等 InferenceState state model.init_state(); // 4. 预填充阶段处理所有 prompt tokens-- deepseek.cpp 目前未实现优化版本 // 当前实现可能是在解码循环中逐个处理效率较低 for (int token_id : input_ids) { model.prefill_one_token(state, token_id); // 模拟逐个处理 } // 5. 解码生成阶段逐个生成新 token int next_token_id; for (int step 0; step max_new_tokens; step) { // 前向传播得到下一个 token 的 logits float* logits model.forward(state); // 从 logits 中采样下一个 token (根据温度、top-p等参数) next_token_id sample_from_logits(logits, temperature, top_p); // 将新生成的 token 加入序列并更新 K/V 缓存 state.update(next_token_id); // 解码并输出这个 token 对应的文本 std::string word tokenizer.decode(next_token_id); std::cout word std::flush; // 如果遇到结束符则停止 if (next_token_id tokenizer.eos_token_id) break; }在deepseek.cpp中model.forward的实现包含了 DeepSeek 特有的Multi-Head Latent Attention (MLA)和MoE (Mixture of Experts)层的处理逻辑。这是代码中最有趣也最复杂的部分。5.3 如何 hack以修改采样策略为例假设你觉得默认的采样方式不够好想尝试一种新的采样策略例如同时使用 temperature 和 top-k。由于代码精简你可以快速定位到采样相关的代码。定位代码在main.cpp中搜索sample或logits你可能会找到一个负责从 logits 数组中选择 token 的函数。理解接口该函数可能接收float* logits每个 token 的分数、int vocab_size、float temperature、float top_p等参数。实施修改例如添加 top-k 过滤// 伪代码展示修改思路 int sample_from_logits(float* logits, int vocab_size, float temp, float top_p, int top_k) { // 1. 应用温度缩放 for (int i0; ivocab_size; i) logits[i] / temp; // 2. 应用 softmax 得到概率 softmax(logits, vocab_size); // 3. 【新增】Top-k 过滤只保留概率最高的 k 个 token if (top_k 0 top_k vocab_size) { // 找到第 k 大的概率值作为阈值 float threshold find_topk_threshold(logits, vocab_size, top_k); for (int i0; ivocab_size; i) { if (logits[i] threshold) logits[i] 0.0f; } // 重新归一化概率 renomalize(logits, vocab_size); } // 4. 应用 top-p (nucleus) 采样 // ... 原有逻辑 ... // 5. 根据最终概率分布随机采样 return random_choice(logits, vocab_size); }编译测试修改后重新运行make编译并用你的测试 prompt 验证生成效果是否如预期变化。这种快速的“修改-编译-测试”循环正是deepseek.cpp作为学习工具的最大价值。6. 常见问题、故障排查与社区现状6.1 编译与运行问题问题现象可能原因解决方案fatal error: ‘omp.h‘ file not found未安装 OpenMP 开发库Ubuntu/Debian:sudo apt install libomp-devCentOS/RHEL:sudo yum install libomp-develerror: ‘stoi‘ is not a member of ‘std‘编译器未完全支持 C11确保使用较新版本的 g (如 g-11) 或 clang。在CMakeLists.txt中可尝试添加set(CMAKE_CXX_STANDARD 11)。convert.py运行时提示ModuleNotFoundError: No module named ‘torch‘Python 依赖未安装在项目根目录执行pip install .或手动安装pip install torch transformers。运行./build/main时提示Failed to open model file模型路径错误或转换未成功检查convert.py是否成功运行并生成了.dseek文件。确保命令行中指定的路径是转换输出的目录如v2-lite-f16而不是原始 Hugging Face 模型目录。推理速度极慢 0.1 tok/s内存不足大量使用交换空间1. 检查可用内存free -h。2. 换用更小的模型或更激进的量化如 Q2_K。3. 确保使用-L参数需 sudo锁定内存。4. 增加物理内存或减少系统其他内存占用。模型输出乱码或重复无意义内容1. 量化损坏2. 温度过低3. Tokenizer 问题1. 尝试使用更高精度的量化如 FP16或原始精度检查。2. 提高温度参数-t至 0.8 或 1.0。3. 这是一个已知问题可能与项目使用的简化 tokenizer 有关。关注项目 Issue。6.2 模型质量与已知限制deepseek.cpp作为一个实验性项目在模型生成质量上可能不如llama.cpp等成熟引擎稳定。作者在项目说明中明确指出了几个关键限制Tokenizer 差异项目使用的可能不是一个完整的 BPE tokenizer这可能导致在某些边缘情况下分词错误影响生成质量。位置编码目前使用了相对简单的注意力下沉attention sink方法而不是 DeepSeek 官方模型可能使用的更复杂的 YARN 或 NTK-aware 等位置编码扩展方法。这可能会影响模型处理超长上下文的能力。架构特性缺失DeepSeek V3 的一些可选新特性如noaux_tc专家选择方法尚未实现这可能导致模型精度略有下降。缺少预填充优化如前所述没有实现高效的预填充因此处理长提示词的开销较大。给开发者的建议如果你追求稳定的生产级推理llama.cpp是更安全的选择。但如果你想学习、研究或快速验证某个想法deepseek.cpp的简洁性无可替代。你可以定期查看项目的 Pull Requests 和 Issues 页面了解最新的质量评估如困惑度测试和已知问题的修复进展。6.3 性能瓶颈分析与优化方向通过简单的性能剖析你可以定位瓶颈。在 Linux 上可以使用perf工具# 记录 main 程序的 CPU 性能事件 sudo perf record -g -p $(pgrep -f “./build/main“) # 先运行 main 程序再获取其 PID # 或者直接运行并记录 sudo perf record -g ./build/main v2-lite-f16 -i “...” -m c -n 100 # 生成报告 sudo perf report报告可能会显示热点在ggml_vec_dot_q2_k之类的函数说明时间花在量化矩阵乘法上。这是计算密集型操作优化空间有限但可以检查是否使用了最优的线程数。memcpy或内存相关函数说明可能存在大量数据搬运可以检查 K/V 缓存的访问模式或者模型层与层之间是否有不必要的拷贝。OpenMP 同步开销如果热点在__kmp_barrier等函数说明线程同步开销大。可以尝试调整OMP_NUM_THREADS或者考虑将deepseek.cpp的 OpenMP 并行区域改为更细粒度或更粗粒度。项目的开源 Issue 中也提到了一些已知的性能问题例如 Multi-Latent Attention 的实现在某些场景下速度不如预期可能没有充分利用内存带宽。这为有兴趣的贡献者指明了潜在的优化方向。7. 扩展思考从 deepseek.cpp 出发玩转deepseek.cpp之后你可以沿着以下几个方向继续深入实现预填充Prefill当前解码循环中每个生成步骤都对整个序列进行前向传播效率低下。尝试实现一个真正的预填充阶段一次性处理完所有提示词 token并缓存其 K/V 值。这需要修改推理状态管理逻辑。集成更优的采样算法如前所述尝试实现 Top-k、Typical Sampling、Mirostat 等更先进的采样算法并比较它们对生成质量和多样性的影响。支持更多量化格式研究并实现如 AWQ、GPTQ 或作者提到的 1.58-bit 等更先进的量化方案在精度和压缩率之间寻找更好的平衡点。移植到其他硬件虽然项目聚焦 CPU但其清晰的结构使其成为向其他后端如使用 SYCL 的 Intel GPU或使用 Vulkan 的移动 GPU移植的良好基础。你可以尝试将核心计算 kernel 替换为针对特定硬件的实现。可视化与调试工具为项目添加简单的工具例如输出每一层注意力权重的分布、MoE 专家激活的直方图等这能帮助你更直观地理解模型内部的运作机制。这个项目的魅力在于它剥离了生产级框架的复杂性将 LLM 推理的核心骨架赤裸地呈现出来。它可能不是最快的也不是功能最全的但它无疑是最适合用来学习和动手改造的之一。每一次编译、每一次修改参数、每一次观察输出变化都是对 Transformer 模型如何工作的一次亲手验证。