llama.cpp — 纯 C/C++ 无依赖 LLM 推理引擎

GitHub: ggerganov/llama.cpp
Stars: 117,000+ | Language: C++ (56.6%), C (14.0%) | License: MIT
官网: 无独立官网，文档在 GitHub Repo

项目速览

llama.cpp 是由 Georgi Gerganov 创建的开源 LLM 推理引擎，其独一无二的特点是 纯 C/C++ 实现且零外部依赖。2023 年 3 月，在 Meta 发布 Llama 模型后不到一周，Gerganov 就发布了 llama.cpp 的第一个版本，允许在普通笔记本电脑的 CPU 上运行 7B 参数的 Llama 模型。这个项目的诞生标志着一个重要转折点：LLM 推理从”数据中心专属”走向了”无处不在”。

截至 2026 年 6 月，项目在 GitHub 上已获得 117,000+ Star，是整个 LLM 生态中被 fork 和依赖最多的项目之一。llama.cpp 不仅是一个独立工具，更是整个本地 LLM 推理生态的基石：Ollama、LM Studio、GPT4All、Jan、LMDeploy 等数十个项目都在底层使用了 llama.cpp 或其 GGML 张量库。

llama.cpp 的核心价值在于：最小化依赖 + 极致优化。它不依赖 Python、PyTorch、CUDA 库等重型依赖，单二进制文件即可运行。同时通过手写 SIMD 指令（ARM NEON、x86 AVX2/AVX512）、Metal Shader、CUDA Kernel 等手段，在各平台上都达到了接近硬件的极限性能。

功能概述

GGUF 格式 — 统一的模型文件标准

GGUF（GGML Universal Format）是 llama.cpp 定义的模型文件格式，已事实上成为开源 LLM 分发标准。一个 .gguf 文件是自包含的：包含模型权重、分词器、元数据（模型架构、量化类型、上下文长度）和 chat template 等全部信息。

GGUF 的核心优势：

单文件分发：一个文件 = 一个可运行的模型，无需拆分配置和权重
向后兼容：新版 llama.cpp 总能读取旧版 GGUF 文件
增量量化：同一基础模型可派生出从 Q2_K（2-bit）到 F16（16-bit）多种量化版本，用户按需选择
元数据丰富：文件头包含 chat template、tokenizer 配置等信息，加载即用

HuggingFace Hub 上托管了数万个 GGUF 格式模型（通常以 -GGUF 后缀命名），许多官方模型（如 Meta Llama、Microsoft Phi）也提供官方 GGUF 量化版本。

极致量化体系

llama.cpp 拥有最完整的量化方案矩阵，覆盖从极低精度到高质量的范围：

量化类型	每权重位数	特点	适用场景
Q2_K	~2.6 bit	最小体积，质量损失较大	存储受限的嵌入式场景
IQ3_XXS	~3.0 bit	重要性感知量化，3-bit 中质量最优	移动端、边缘设备
Q4_K_M	~4.8 bit	性能/质量最佳平衡点	推荐默认选择
Q5_K_M	~5.5 bit	接近原始质量	质量要求高的场景
Q8_0	8 bit	几乎无损	CPU 推理首选
F16	16 bit	无量化损失	GPU 推理，追求质量

此外还支持 1.5-bit（IQ1_S）等极端压缩类型。所有量化类型在质量和速度上都有详细的 benchmark 数据，用户可以精确权衡。

全平台后端支持

llama.cpp 为每种硬件编写了定制优化内核：

**Apple Silicon (M1/M2/M3/M4)**：通过 Metal Shader 实现 GPU 加速，同时利用 ARM NEON 和 Accelerate 框架优化 CPU 路径
NVIDIA GPU：手写 CUDA Kernel，支持从 GTX 1060 到 H100 的全系列 GPU
AMD GPU：通过 HIP 接口利用 ROCm 栈，也支持 Vulkan 后端
Intel GPU：通过 SYCL 后端支持 Arc 系列 GPU
x86 CPU：利用 AVX、AVX2、AVX512 和 Intel AMX 指令集
RISC-V：支持 RVV 向量扩展
其他：Vulkan（跨平台 GPU）、WebGPU（浏览器端）、CANN（华为昇腾 NPU）、MUSA（摩尔线程 GPU）等

混合推理（CPU + GPU）

当模型超过显存时，llama.cpp 支持将部分层放在 GPU，其余层放在 CPU + 系统内存，实现超出硬件限制的推理：

# 将 30 层放在 GPU，其余放在 CPU
llama-cli -m model.gguf -ngl 30

这个功能在实际场景中极其实用：一块 8GB 显存的 GPU 可以加载 Q4_K_M 量化的 7B 模型全部到显存，但对于 70B 模型，可以将 40 层放在 GPU、40 层放在 CPU，虽然速度会下降，但至少能跑起来。

OpenAI 兼容服务器（llama-server）

llama.cpp 内置了一个轻量级的 HTTP 服务器 llama-server，完全兼容 OpenAI Chat Completions API：

# 启动服务器
llama-server -m model.gguf --port 8080

# 浏览器访问 Web UI
# http://localhost:8080

服务器支持的功能远超预期：

并发推理：通过 -np 4 支持 4 路并行解码
推测性解码：-md draft.gguf 使用草稿模型加速
Embedding 服务：--embedding 开关
语法约束：--grammar-file json.gbnf 强制输出 JSON 格式
HuggingFace 直连：llama-server -hf org/model-GGUF 自动下载并启动
Reranking：--reranking 支持重排序模型

语法约束生成（GBNF Grammar）

llama.cpp 支持通过 GBNF（GGML BNF）语法文件约束模型的输出格式，这是结构化生成的关键能力：

# 强制模型输出有效的 JSON
llama-cli -m model.gguf --grammar-file grammars/json.gbnf \
    -p '列出三个中国城市及其人口: '

# 更实用的例子：限制分类器输出
llama-cli -m model.gguf --grammar 'root ::= "正面" | "负面" | "中性"' \
    -p '评价: 这部电影非常精彩, 情绪: '

内置的 grammar 文件涵盖了 JSON、JSON Schema、CSV、列表、算术表达式等常见格式。这使得 llama.cpp 可以作为结构化提取管线中的可靠组件。

适用场景

边缘设备与嵌入式推理

llama.cpp 的零依赖特性使其成为树莓派、Jetson Nano、智能音箱、工业控制器等嵌入式 Linux 设备上运行小模型的唯一可行方案。配合 IQ3_XXS 等极致量化，2B 模型只需约 1GB 内存即可运行。

桌面端离线 AI 工具

Ollama、GPT4All、LM Studio、Jan 等本地 AI 应用都基于 llama.cpp 构建，为最终用户提供图形化的离线 AI 体验。如果你在构建需要内嵌 LLM 的桌面应用，直接集成 llama.cpp 是性能最优的选择。

CPU 推理与无 GPU 环境

许多企业的标准服务器只有 CPU 没有 GPU。llama.cpp 在 x86 CPU 上的推理速度经过极致优化，AVX512 指令集下 7B Q4_K_M 模型可达 15-20 token/s，足以应对离线批处理、数据分析等工作负载。

模型量化与格式转换

llama.cpp 提供的 convert_hf_to_gguf.py 和 llama-quantize 工具是将 PyTorch/HuggingFace 模型转换为 GGUF 格式并量化的标准工具链。即使最终使用其他推理引擎，许多团队也用 llama.cpp 完成格式转换。

CLI 管线中的文本处理

llama-cli 支持 Unix 管道输入输出，可以轻松集成到 shell 脚本和 CI/CD 管线中，用于代码审查总结、日志分类、文本翻译等自动化任务。

快速上手

编译安装

# 克隆仓库
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# CPU 版本（通用）
make -j$(nproc)

# NVIDIA GPU 版本
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

# Apple Silicon Metal 版本
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release -j$(nproc)

# 所有二进制文件在 build/bin/ 下
ls build/bin/
# llama-cli  llama-server  llama-bench  llama-perplexity
# llama-quantize  llama-embedding  llama-simple

也可以使用包管理器：

# macOS
brew install llama.cpp

# 或直接下载预编译二进制
# https://github.com/ggerganov/llama.cpp/releases

获取 GGUF 模型

# 方法1：直接使用 HuggingFace 上的 GGUF 模型（无需手动下载）
llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

# 方法2：用 huggingface-cli 下载
huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF \
    --include "Llama-3.2-3B-Instruct-Q4_K_M.gguf" \
    --local-dir ./models/

# 方法3：从 PyTorch 模型自行转换
pip install -r requirements.txt
python convert_hf_to_gguf.py /path/to/hf-model --outtype q8_0
./build/bin/llama-quantize model-q8_0.gguf Q4_K_M

基本推理

# 单次问答
llama-cli -m model.gguf -p "用一句话解释什么是Transformer" -n 256

# 交互对话模式
llama-cli -m model.gguf -cnv --chat-template llama3

# 语法约束输出
llama-cli -m model.gguf --grammar-file grammars/json.gbnf \
    -p '输出一个包含name和age字段的JSON: ' -n 128

启动 OpenAI 兼容服务器

# 基础服务器
llama-server -m model.gguf --port 8080

# 并发 + 长上下文
llama-server -m model.gguf --port 8080 -c 16384 -np 4

# 直接使用 huggingface 模型
llama-server -hf bartowski/Qwen2.5-7B-Instruct-GGUF \
    -hf-file Qwen2.5-7B-Instruct-Q4_K_M.gguf --port 8080

启动后访问 http://localhost:8080 使用 Web UI，或调用 OpenAI 协议 API：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",  # model 名在 llama.cpp 中不校验
    messages=[{"role": "user", "content": "你好!"}],
)
print(response.choices[0].message.content)

源码架构

llama.cpp 的代码组织清晰，核心是 ggml 张量计算库 + llama 模型加载器 + 应用层工具：

llama.cpp/
├── ggml/                        # GGML 核心张量计算库
│   ├── include/ggml.h           # GGML C API 头文件（公开接口）
│   ├── src/ggml.c               # GGML 核心实现（~50k 行 C 代码）
│   ├── src/ggml-cpu/            # CPU 后端（NEON/AVX/AVX2/AVX512/RISC-V）
│   ├── src/ggml-cuda/           # CUDA GPU 后端
│   ├── src/ggml-metal/          # Apple Metal GPU 后端
│   ├── src/ggml-vulkan/         # Vulkan GPU 后端
│   ├── src/ggml-sycl/           # Intel SYCL GPU 后端
│   └── src/ggml-webgpu/         # WebGPU 浏览器后端
├── src/                         # llama 模型层
│   ├── llama.cpp                # 核心：模型加载、推理图构建、token 生成
│   ├── llama.h                  # llama 公共 API
│   ├── llama-model.cpp          # 模型文件加载（GGUF 解析）
│   ├── llama-model.h
│   ├── llama-grammar.cpp        # GBNF 语法解析与约束采样
│   ├── llama-sampling.cpp       # 采样策略（top-k/top-p/min-p/temperature）
│   └── llama-vocab.cpp          # 分词器（BPE/SentencePiece）
├── common/                      # 公共工具层
│   ├── common.h                 # 参数解析、日志、模型加载通用逻辑
│   └── sampling.h               # 采样器配置
├── tools/                       # CLI 工具
│   ├── llama-cli/               # 命令行对话工具（原 main 示例）
│   ├── llama-server/            # HTTP 服务器 + Web UI
│   ├── llama-bench/             # 性能基准测试
│   ├── llama-perplexity/        # 困惑度计算
│   ├── llama-quantize/          # 模型量化工具
│   ├── llama-embedding/         # 文本嵌入生成
│   └── llama-simple/            # 最小化推理示例
├── examples/                    # 高级示例
│   ├── server/                  # 旧版 server（遗留）
│   └── speculative/             # 推测性解码示例
├── convert_hf_to_gguf.py        # HF PyTorch 模型 → GGUF 转换
├── gguf-py/                     # Python GGUF 读写库
├── grammars/                    # 内置 GBNF 语法文件（json/ csv/ list/ ...）
├── models/                      # 模型架构定义（llama/falcon/gemma/qwen/...）
├── scripts/                     # 辅助脚本
├── tests/                       # 测试套件
└── CMakeLists.txt               # 构建系统

核心模块说明：

ggml：GGML 是整个项目的基石，一个用纯 C 写的张量计算库，实现了矩阵乘法、注意力、归一化等深度学习基础运算，并为每种硬件平台编写了手动的 SIMD/CUDA/Metal 优化实现。它不依赖 BLAS、cuBLAS 等外部库，实现了真正的零依赖。
src/llama.cpp：约 20,000 行的核心文件，负责解析 GGUF 文件头、构建 Transformer 计算图（embedding → attention block × N → lm_head → sampling）、管理 KV Cache、执行 token 生成循环。支持 50+ 种模型架构。
llama-server：基于 C++ 内置的 HTTP 库实现，提供了一个完整的 OpenAI 兼容 API 服务器。源码在 tools/llama-server/ 目录，包含了 Web UI 的 HTML/CSS/JS 资源。
llama-quantize：提供 20+ 种量化类型（从 IQ1_S 到 Q8_0），支持对已转换的 GGUF 文件进行量化。量化过程包括统计权重分布、选择量化策略、计算 scale 参数等步骤。
convert_hf_to_gguf.py：将 HuggingFace 格式（safetensors/pytorch bin）模型转换为 GGUF 格式的 Python 脚本。它会遍历模型权重，写入 GGUF magic header、metadata 键值对、张量信息和原始权重数据。

实操 Demo

完整流程：从编译到部署量化模型

1. 编译 CUDA 版本

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

export PATH="$PWD/build/bin:$PATH"

2. 下载并量化模型

# 下载 Qwen2.5-7B 原始模型（HuggingFace）
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen-7b-hf

# 转换为 GGUF F16 格式
pip install -r requirements.txt
python convert_hf_to_gguf.py ./qwen-7b-hf --outtype f16 --outfile qwen-7b-f16.gguf

# 量化为 Q4_K_M（性能/质量最佳平衡）
llama-quantize qwen-7b-f16.gguf Q4_K_M
# 输出: qwen-7b-f16-Q4_K_M.gguf（约 4.4GB）

# 也可以量化为其他类型做对比
llama-quantize qwen-7b-f16.gguf Q8_0
llama-quantize qwen-7b-f16.gguf IQ3_XXS

3. 基准测试

# 测试不同量化类型的推理速度
llama-bench -m qwen-7b-f16-Q4_K_M.gguf -n 128 -t 8
llama-bench -m qwen-7b-f16-Q8_0.gguf -n 128 -t 8
llama-bench -m qwen-7b-f16-IQ3_XXS.gguf -n 128 -t 8

# 输出示例：
# | model          | size     | backend | ngl | test       | t/s    |
# | qwen 7B Q4_K_M | 4.37 GiB | CUDA    | 99  | pp 512     | 243.81 |
# | qwen 7B Q4_K_M | 4.37 GiB | CUDA    | 99  | tg 128     | 62.15  |

4. 交互式对话

llama-cli -m qwen-7b-f16-Q4_K_M.gguf \
    -cnv \
    --chat-template qwen \
    --system-prompt "你是一个精通 Python 的编程助手。" \
    -ngl 99 \
    -c 4096 \
    --temp 0.7

进入交互模式后：

> 用 Python 写一个 HTTP GET 请求的示例

（模型生成代码...）

> 加上错误处理

（模型补充 try/except...）

5. 部署 OpenAI 兼容 API 服务器

# 启动服务器（全 GPU 加载 7B Q4_K_M 模型需要约 5GB 显存）
llama-server -m qwen-7b-f16-Q4_K_M.gguf \
    --host 0.0.0.0 \
    --port 8080 \
    -ngl 99 \
    -c 8192 \
    -np 4 \
    --alias qwen7b

启动后访问 http://localhost:8080 可以看到内置的 Web 聊天界面。

6. 客户端调用演示

import json
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")

# 基本对话
response = client.chat.completions.create(
    model="qwen7b",
    messages=[
        {"role": "user", "content": "用 Java 写一个单例模式，要求线程安全。"},
    ],
    temperature=0.3,
    max_tokens=512,
)
print(response.choices[0].message.content)

# 流式 + JSON 约束
response = client.chat.completions.create(
    model="qwen7b",
    messages=[
        {"role": "user", "content": "生成3个程序员笑话，作为JSON数组返回。"}
    ],
    response_format={"type": "json_object"},
    stream=True,
)
for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()

# Embedding
embed_resp = client.embeddings.create(
    model="qwen7b",
    input=["hello world", "你好世界"],
)
print(f"Embedding 维度: {len(embed_resp.data[0].embedding)}")

# 并发压力测试
import concurrent.futures
import time

def make_request(i):
    return client.chat.completions.create(
        model="qwen7b",
        messages=[{"role": "user", "content": f"用{i+1}句话介绍Python"}],
        max_tokens=128,
    )

start = time.time()
with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(make_request, range(8)))
print(f"8请求/4并发 总耗时: {time.time()-start:.2f}s")

7. curl 测试

# Chat Completions
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen7b",
    "messages": [{"role": "user", "content": "How to reverse a linked list in C?"}],
    "temperature": 0.7,
    "max_tokens": 256
  }' | jq '.choices[0].message.content'

# 查看服务器健康状态
curl http://localhost:8080/health
# {"status": "ok"}

# 获取服务器 slot 信息
curl http://localhost:8080/slots | jq

特性	llama.cpp	Ollama	vLLM	MLX
语言	C/C++	Go + llama.cpp	Python	Python + C++
依赖	零外部依赖	系统级依赖	Python + CUDA	macOS 专有
安装	make/cmake 编译	一条 curl 命令	pip install	pip install
模型格式	GGUF（原生）	GGUF（自动拉取）	HF Hub 直接加载	safetensors/GGUF
量化类型	20+ 种（最丰富）	自动 Q4_0	10+ 种	4/8 bit
GPU 支持	CUDA/Metal/Vulkan/SYCL	自动检测	CUDA/ROCm/TPU	Apple Silicon
吞吐量	中等（单请求）	中等	极高（continuous batching）	高（Apple Silicon）
并发	支持（-np）	有限	极高	有限
API	OpenAI 兼容	REST（非标准）	OpenAI 兼容	无内置 API 服务
边缘设备	极佳	一般	不适合	仅 Apple Silicon
部署复杂度	低（单二进制）	极低	中等	低
Star	117k	174k	82.9k	18.4k
适合	嵌入/边缘/CLI 管线	开发者本地使用	生产环境服务	Mac 本地开发

参考资源

GitHub 仓库: https://github.com/ggerganov/llama.cpp
GGUF 格式规范: https://github.com/ggerganov/ggml/blob/master/docs/gguf.md
GGML 张量库: https://github.com/ggerganov/ggml
HuggingFace GGUF 模型: https://huggingface.co/models?library=gguf
在线 GGUF 量化工具: https://huggingface.co/spaces/ggml-org/gguf-my-repo
GBNF 语法指南: https://github.com/ggerganov/llama.cpp/blob/master/grammars/README.md