ik_llama.cpp：具有更好CPU性能的llama.cpp分支

简要说明

本仓库是llama.cpp的一个分支，针对CPU及混合GPU/CPU推理进行了优化，支持新的SOTA量化类型、一流的Bitnet模型、通过MLA、FlashMLA、融合MoE操作和张量覆盖实现更好的DeepSeek性能，以及行交错量化打包等功能。

[!注意] 目前唯一完全可用且性能良好的计算后端是CPU（AVX2或更高版本，ARM_NEON或更高版本）和CUDA（Turing架构或更高版本）。 请勿提交与ROCm、Vulkan、Metal、旧款Nvidia显卡、AVX CPU等相关的问题。除非您亲自参与并帮助提升您偏好的后端性能，否则这些问题将不会得到解决。鉴于当前的主要贡献者数量有限，本项目没有足够的资源来维护llama.cpp中所有可用的后端。

[!重要提示] 请勿使用Unsloth发布的名称中带有 _XL 的量化模型。这些模型很可能无法在 ik_llama.cpp 中正常工作。

上述内容引发了一些讨论，特此澄清：可能不兼容的Unsloth _XL 模型是指那些包含 f16 张量的模型（这本身并不是一个好主意）。其他模型则没有问题。

[!注意] 部分用户报告了图并行模式（即分片模式 graph）和部分GPU卸载（使用 --cpu-moe 或 --n-cpu-moe 选项或张量覆盖）时出现的问题。如果您正在使用或希望使用分片模式图，并观察到乱码或不连贯的响应，请尝试在命令行中添加 -cuda graphs=0。

快速入门

前置条件

git clone https://github.com/ikawrakow/ik_llama.cpp

cd ik_llama.cpp

在Debian/Ubuntu Linux系统上，安装所需软件包（如果使用其他Linux发行版，请找到相应的软件包并进行适配）：

apt-get update && apt-get install build-essential git libcurl4-openssl-dev curl libgomp1 cmake

为CPU构建

cmake -B build -DGGML_NATIVE=ON

cmake --build build --config Release -j$(nproc)

为GPU构建

请先安装Nvidia驱动程序和NVIDIA CUDA工具包。

cmake -B build -DGGML_NATIVE=ON -DGGML_CUDA=ON

cmake --build build --config Release -j$(nproc)

Windows成功构建的逐步指南

https://github.com/ikawrakow/ik_llama.cpp/blob/main/docs/build.md

运行

下载 .gguf 模型文件（例如 bartowski/Qwen_Qwen3-0.6B-IQ4_NL.gguf）到您喜欢的目录中（例如 /my_local_files/gguf）。

使用以下命令之一启动服务器（CPU或GPU）：

./build/bin/llama-server --model /my_local_files/gguf/Qwen_Qwen3-0.6B-IQ4_NL.gguf --ctx-size 4096

./build/bin/llama-server --model /my_local_files/gguf/Qwen_Qwen3-0.6B-IQ4_NL.gguf --ctx-size 4096 -ngl 999

就完成了！在浏览器中打开 http://127.0.0.1:8080，即可开始聊天。

在podman/docker容器中运行ik_llama.cpp的逐步指南（包括llama-swap）

步骤指南

常用参数与选项

文档链接

最新消息

模型支持

LlaMA-3-Nemotron PR 377, Qwen3 PR 355, GLM-4 PR 344, Command-A PR 341, bitnet-b1.58-2B-4T PR 337, LLaMA-4 PR 321, Gemma3 PR 276, DeepSeek-V3 PR 176, Kimi-2 PR 609, dots.llm1 PR 573, Hunyuan PR 565, GLM-4.5 PR 668（4.5/4.6/4.7/AIR），Ernie 4.5 MOE和0.3B PR 759, grok-2 PR 782, Ling/Ring (Bailing-MoE2) PR 833, Qwen3-VL PR 883, SmolLM3 PR 934, GigaChat3 PR 995, ministral3 PR 1030, Mimo-V2-Flash PR 1096, GLM-4.7-Flash PR 1168, Seed-OSS PR 1218, Step-3.5-Flash PR 1231, GLM-5 PR 1268, Qwen3-Next PR 1266, Qwen3.5-MoE PR 1288以及稠密版Qwen-3.5 1326, Mistral 4 PR 1450, Bonsai 1-bit PR 1570, Gemma4 PR 1581

量化

量化新增内容

格状量化（IQ1_KT、IQ2_KT、IQ3_KT、IQ4_KT）

相关信息及原始 CUDA 实现参见 PR 113。其他实现：Metal PR 475、Neon PR 471、CPU PR 441。IQ1_KT 是近期在 PR 616 中添加的。注意：这些量化方法基于一种新颖的整数基格状量化方案，能够在 CPU 上获得较为理想的性能，详情请参阅 PR 529 及其中引用的相关 PR。

IQK 量化

相关信息可在 讨论 8 中找到。

初始实现（Zen4、AVX2、NEON）：IQ5_KS_R4 PR 426、IQ5_KS PR 422、IQ4_KS_R4 PR 150、IQ5_K_R4 PR 149、IQ2_K_R4 PR 146、IQ3_K_R4 PR 145、IQ4_K_R4 PR 138、IQ4_KSS PR 89、IQ2_KS PR 85、IQ4_KS PR 83、IQ6_K PR 14、IQ2_K、IQ3_K 和 IQ5_K PR 7、IQ4_K PR 6。

CUDA 实现：IQ4_KS_R4 和 IQ5_KS_R4 PR 493、IQ1_S_R4 PR 492、IQ1_M_R4 PR 494。IQ4_KS_R4 和 IQ5_KS_R4 PR 462、IQ2_K_R4、IQ3_K_R4、IQ4_K_R4、IQ5_K_R4 PR 461、IQ4_K、IQ5_K、IQ6_K PR 417、IQ2_KS、IQ2_K、IQ3_K PR 418。

IQ2_KL 是近期在 PR 602 中新增的。

K 缓存的哈达玛变换

CPU PR 1033 和 CUDA PR 1034。

V 缓存的哈达玛变换

PR 1527。

gpt-oss 模型中使用的 MXFP4

已在 Zen4、AVX2、ARM_NEON、Metal 和 CUDA 平台上实现 PR 682。

量化改进

• IQ1_M PR 327、IQ2_XS PR 312、Q2_K、Q4_K、Q5_K、Q4_1、Q5_1 PR 302、Q4_0、Q5_0、Q6_0、Q3_K、Q6_K、IQ4_XS、IQ4_NL PR 295。
• 低困惑度 Q4_0 KV 缓存 PR 1547 PR 1556。

量化性能提升

• 所有非交错量化类型的 CPU 提示处理速度大幅提升。最初的想法见 PR 515 和 PR 531，随后有多项 PR 将其应用于三种支持的 CPU 平台上的所有量化类型。
• 所有量化类型现在都配备了量化矩阵乘法的 CUDA 内核，详情参见 PR 557 及其他若干 PR。
• 格状量化和 MoE 模型的 CPU 提示处理速度进一步提升。PR 488。
• 格状量化：CPU 提示处理速度更快 PR 482。
• CUDA 上 iq2_ks 的 TG 性能小幅提升（约 2%）PR 468。
• IQ3_KT 和 IQ4_KT 处理速度更快 PR 453。
• Zen4：IQ2_KS、IQ4_KS、IQ5_KS 的 PP 处理速度更快 PR 428。
• IQ1_S 的 GEMM/GEMV 加速 PR 212。
• AVX-VNNI 优化 PR 1446、PR 1455、PR 1467、PR 1474、PR 1482。

功能特性

• 新增多 GPU 设置下的“graph”拆分模式 PR 1022
• 针对 Qwen3-Next 和 Qwen3.5-MoE 的融合 delta-net PR 1315 PR 1333 PR 1362 PR 1373
• K 缓存和 V 缓存的 Hadamard 变换 PR 1033 PR 1034 PR 1527
• 自动调整卸载张量以适应可用显存（MoE 和密集模型）PR 1501 PR 1504
• 循环模型的检查点 PR 1310 PR 1398
• 用于所有补全的字符串屏蔽功能 PR 1185 PR 1243
• OpenAI /v1/responses API 端点 PR 1184
• 函数调用支持 PR 628
• Jinja 模板支持 PR 677
• WebUI：对话、设置和聊天消息的新功能 PR 618
• GLM-4.x MoE 的 MTP 解码支持 PR 1270
• 自我推测解码，n 元语法 PR 1261
• 动态控制向量管理端点 PR 1223
• convert_hf_to_gguf.py 中的旧版量化转换方案 PR 449，以及 PR 483 中的 Q6_0
• Adaptive-P 采样器 PR 1100，由其作者按设计实现；WebUI 支持
• llama-mtmd-cli 中的多模态视觉支持 PR 798 和 llama-server 中的多模态支持 PR 901
• mikupad 作为替代 WebUI PR 558
• 2025 年 6 月 8 日：WebUI 更新（当传递 --path ./examples/server/public_legacy 时，仍可使用旧版）PR 481
• 2025 年 6 月 8 日：RPC 改进 PR 480
• 2025 年 6 月 7 日：为服务器添加一个列出所有已保存提示缓存的端点 PR 502
• 2025 年 6 月 6 日：使提示缓存的保存和恢复具备 MLA 意识 PR 497
• 2025 年 6 月 3 日：新增采样器，XTC PR 486，top-n σ PR 489。
• 2025 年 5 月 22 日：重构 iqk_mul_mat.cpp，显著加快编译速度。PR 435
• 2025 年 5 月 17 日：可选择启用或禁用 CPU FA 核心 PR 429。
• 2025 年 5 月 12 日：用户现在可以控制是否或将 RAM 中的哪些张量操作卸载到 GPU。详见 PR 405
• 2025 年 5 月 12 日：在 PR 394 中解决了启用 MLA 的 DeepSeek 模型与主干 llama.cpp GGUF 文件之间的兼容性问题。由于使用 llama.cpp 风格的 MLA GGUF 文件导致的较低提示处理性能，在 PR 409 中得以恢复。
• 2025 年 4 月 21 日：ik_llama.cpp 在 Android 上成功构建并运行（使用 Termux），详见 PR 336
• 2025 年 3 月 1 日：智能专家约简，加速 DeepSeek 推理 PR 239
• 2025 年 2 月 25 日：张量覆盖，更好地控制模型权重存储位置（GPU 或 CPU）PR 232
• 2025 年 2 月 23 日：sweep-bench——更优的性能基准测试 PR 225
• 2025 年 2 月 19 日：Q8_KV——一种新的 8 位 KV 缓存量化类型 PR 208
• 2025 年 3 月 7 日：使用正则表达式自定义量化组合 PR 244

性能改进

• 使用混合 HPU/CPU 推理时，MoE 模型的更好 GPU 卸载策略，详见 PR 520
• 更快的随机数采样 PR 1187
• 2025 年 5 月 13 日：DeepSeek-Lite 的 CPU FA 性能提升。PR 410
• 2025 年 5 月 11 日：CUDA 上 DeepSeek 模型的 Flash Attention 略有提速，并将兼容性扩展至 Turing 或更新的 GPU。PR 408
• 2025 年 5 月 4 日：在 CUDA 上使用 Flash Attention 时，GQA 模型的标记生成性能显著提升。详情及基准测试见 PR 370
• 2025 年 4 月 17 日：CPU Flash Attention 标记生成性能提升。PR 332
• 2025 年 4 月 3 日：Metal 上的 MoE 实现速度大幅提升。PR 307
• 2025 年 3 月 25 日：CUDA 上的 MoE 性能提升 PR 283
• 2025 年 3 月 23 日：DeepSeek 模型的批处理速度提升 PR 282
• 2025 年 3 月 18 日：减少计算缓冲区大小 PR 237
• 2025 年 3 月 10 日：CUDA 上 MoE 模型的 TG 性能提升 PR 248
• 2025 年 2 月 23 日：融合 FFN 操作，加速 MoE 推理 PR 229

Flash-MLA

• 2025年5月7日：🚀 在CUDA上为DeepSeek模型推出FlashMLA-3。PR 386 注意事项：需要Ampere或更新的Nvidia GPU。
• 2025年3月21日：🚀 FlashMLA-3：为DeepSeek模型提供最快的纯CPU推理性能 PR 273
• 2025年3月17日：🚀 FlashMLA-2性能改进 PR 253
• 2025年3月12日：允许在CUDA上使用FlashMLA-2时启用Q8_0 KV缓存 PR 265
• 2025年3月9日：🚀 在CUDA上实现FlashMLA PR 247
• 2025年3月8日：🚀 更快的FlashMLA CPU实现 PR 243
• 2025年3月3日：🚀 引入FlashMLA——结合Flash Attention的MLA PR 240
• 2025年2月27日：无需转置缓存的MLA PR 235
• 2025年2月13日：允许MLA使用Q8_0量化缓存 PR 206
• 2025年2月11日：🚀 DeepSeek模型支持Flash Attention PR 200
• 2025年2月9日：🚀 DeepSeek模型的MLA PR 188

修复

• 修复MMVQ内核中的错误 PR 446
• 修复AVX2对IQ4_K、IQ4_KS、IQ5_K、IQ6_K的实现 PR 427
• 修复CPU上的标准注意力机制 PR 421
• 修复MLA模型的imatrix计算 PR 411
• 修复Touring架构上的新CUDA FA PR 413
• 修复SER问题。CPU版：PR 415，CUDA版：PR 416

资源

目前没有一个统一的参考文档能够全面描述ik_llama.cpp的所有新特性。Pull请求通常包含详细信息，因此浏览这些PR往往是了解新功能及其使用方法的最佳途径。此外：

• 维基页面提供了与主线llama.cpp的性能对比；
• 本指南是如果你因为DeepSeek模型而来到这里的好起点；
• 此讨论讨论的是如何在16张3090显卡的配置上运行DeepSeek-V3/R1；
• 此讨论介绍了ik_llama.cpp中可用的新量化类型。

测试

函数调用测试

要运行函数调用测试套件：

cd build
cmake --build . --target test-function-calls
./bin/test-function-calls

该测试套件涵盖了解析器功能、流式传输、错误处理、内容清理以及服务器集成等方面。所有测试都应通过，以确保产品已准备好投入生产。

贡献

欢迎以pull请求、提交问题（包括bug报告和功能请求）或一般讨论的形式进行贡献。

许可证

• subprocess.h —— C和C++的单头进程启动解决方案 —— 公有领域
• server
• GBNF语法

开发文档

• 如何构建
• 在Docker上运行
• 性能故障排除
• GGML技巧与窍门

基础论文及模型背景

如果你的问题与模型生成质量有关，请至少浏览以下链接和论文，以了解LLaMA模型的局限性。这一点在选择合适的模型规模以及理解LLaMA模型与ChatGPT之间的重要和细微差异时尤为重要：

• LLaMA：
  • 介绍LLaMA：一个基础性的650亿参数大型语言模型
  • LLaMA：开放且高效的底层语言模型
• GPT-3
  • 语言模型是少样本学习者
• GPT-3.5 / InstructGPT / ChatGPT：
  • 使语言模型遵循指令
  • 通过人类反馈训练语言模型遵循指令

补全功能

部分环境下支持命令行补全。

Bash补全

$ build/bin/llama-cli --completion-bash > ~/.llama-completion.bash
$ source ~/.llama-completion.bash

你也可以将其添加到.bashrc或.bash_profile中，以便自动加载。例如：

$ echo "source ~/.llama-completion.bash" >> ~/.bashrc

依赖项

• yhirose/cpp-httplib —— 单头HTTP服务器，由llama-server使用 —— MIT许可证
• stb-image —— 单头图像格式解码器，用于多模态子系统 —— 公有领域
• nlohmann/json —— 单头JSON库，被各种工具和示例使用 —— MIT许可证
• miniaudio.h —— 单头音频格式解码器，用于多模态子系统 —— 公有领域
• subprocess.h —— C和C++的单头进程启动解决方案 —— 公有领域

ik_llama.cpp 快速上手指南

ik_llama.cpp 是 llama.cpp 的高性能分支，专注于提升 CPU 及混合 GPU/CPU 推理速度。它支持最新的量化格式（如 IQK、Trellis）、Bitnet 模型、DeepSeek MLA 架构以及多种最新大模型（如 Qwen3、GLM-4、Llama-3-Nemotron 等）。

注意：本项目主要优化了 CPU (AVX2/ARM_NEON) 和 CUDA (Turing 架构及以上) 后端。暂不建议在 ROCm、Vulkan、Metal 或旧款硬件上尝试，除非您愿意自行贡献代码进行适配。

1. 环境准备

系统要求

• 操作系统: Linux (推荐 Debian/Ubuntu), Windows, macOS
• CPU: 支持 AVX2 (x86) 或 NEON (ARM) 指令集
• GPU (可选): NVIDIA GPU (Turing 架构或更新，如 RTX 20 系列及以上)，需安装 CUDA Toolkit
• 内存: 根据模型大小而定，建议至少 8GB

前置依赖

在 Debian/Ubuntu 系统上，运行以下命令安装构建工具：

apt-get update && apt-get install build-essential git libcurl4-openssl-dev curl libgomp1 cmake

注：国内用户可使用清华或阿里镜像源加速 apt 更新。

2. 安装步骤

第一步：克隆仓库

git clone https://github.com/ikawrakow/ik_llama.cpp
cd ik_llama.cpp

第二步：编译构建

方案 A：仅 CPU 版本

适用于无独立显卡或仅需 CPU 推理的场景。

cmake -B build -DGGML_NATIVE=ON
cmake --build build --config Release -j$(nproc)

方案 B：GPU 加速版本 (CUDA)

需先安装 NVIDIA 驱动 和 CUDA Toolkit。

cmake -B build -DGGML_NATIVE=ON -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

Windows 用户若遇到构建问题，可参考项目文档中的 Windows 构建指南。

3. 基本使用

下载模型

从 HuggingFace 下载 .gguf 格式的模型文件。 示例：下载 Qwen3-0.6B 模型到本地目录 /my_local_files/gguf。

提示：请勿使用名称中包含 _XL 的 Unsloth 量化模型（通常包含 f16 张量），这些模型可能无法在此项目中正常运行。

启动服务

模式一：CPU 推理

./build/bin/llama-server --model /my_local_files/gguf/Qwen_Qwen3-0.6B-IQ4_NL.gguf --ctx-size 4096

模式二：GPU 加速推理

使用 -ngl 999 参数将尽可能多的层卸载到 GPU。

./build/bin/llama-server --model /my_local_files/gguf/Qwen_Qwen3-0.6B-IQ4_NL.gguf --ctx-size 4096 -ngl 999

故障排除：如果您使用了多卡分割模式（graph split mode）或部分 GPU 卸载，且发现输出乱码，请尝试在命令中添加 -cuda graphs=0。

开始对话

终端显示服务启动后，打开浏览器访问： http://127.0.0.1:8080

即可在网页界面中与模型进行对话。