ggml-org/llama.cpp · 上手攻略

仓库：ggml-org/llama.cpp
链接：https://github.com/ggml-org/llama.cpp
分类：ai
作者：Tom
更新：2026-08-16

是什么

llama.cpp 是一个纯 C/C++ 实现的高性能 LLM 推理框架，核心目标是在各种硬件上以最小化依赖和最优性能跑本地大模型。它基于底层的 ggml 库构建，支持 FP16 和 GGUF 量化格式，Star 122,572（无周增，长期稳定），是本地 LLM 推理领域最活跃的开源项目之一。

核心特点： - 纯 C/C++ 实现，无外部依赖（除少量单文件 HTTP/JSON 库） - Apple Silicon 一等公民（Metal GPU 加速、NEON、Accelerate 框架） - 支持 CUDA、HIP（AMD）、Vulkan、SYCL、WebGPU 等多种 GPU 后端 - 支持 CPU + GPU 混合推理（模型大于显存时自动 offload） - 量化支持：Q8_0、Q6_K、Q5_K、Q4_K、Q3_K、Q2_K 等（1.5-bit 到 8-bit） - 内置 OpenAI 兼容 API Server（llama serve）

解决什么问题

想在本地（笔记本、服务器、Mac）跑大模型，但不想装 PyTorch 环境、占用大量显存？llama.cpp 解决了三个核心问题：

最小化部署：纯 C/C++，无 Python 依赖，单二进制文件即可运行
跨硬件推理：从树莓派（ARM）到 H100（CUDA），同一套代码均可编译运行
量化压缩：INT2/INT4 量化后 7B 模型可压缩到 4GB，MacBook M 系列 CPU 即可流畅推理

快速安装

方式一：下载预编译二进制（最简单）

访问 https://github.com/ggml-org/llama.cpp/releases 下载对应平台最新 release，解压即用。

方式二：Docker（跨平台）

# 见 docs/docker.md
docker run ...

方式三：从源码编译（推荐，了解硬件加速）

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build
cmake --build build --config Release

不同硬件加不同参数：

# CUDA（NVIDIA GPU）
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Metal（Apple Silicon）
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release

# Vulkan（通用 GPU）
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

# CPU + OpenBLAS
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release

⚠️ 编译提示： - 加 -j 8 加速编译：cmake --build build --config Release -j 8 - 安装 ccache 加速重复编译 - Debian/Ubuntu 需要 libssl-dev

核心用法

下载并运行模型（Hugging Face 直接拉取）

# CLI 交互式对话
llama cli -hf ggml-org/Qwen3.5-0.8B-GGUF

# 下载指定量化版本（: 后指定）
llama cli -hf ggml-org/Qwen3.5-0.8B-GGUF:Q8_0

启动 OpenAI 兼容 API Server

llama serve -hf ggml-org/Qwen3.5-0.8B-GGUF
# 默认监听 http://localhost:8080

调用示例：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ggml-org/Qwen3.5-0.8B-GGUF",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

llama server 还支持： - Anthropic Messages API 兼容路由 - Function calling / Tool use（任意模型） - JSON schema 约束输出 - 连续批处理（Continuous batching）+ 多用户并发 - 多模态（见 docs/multimodal.md） - 推测解码（Speculative decoding） - 监控端点

关键参数说明

参数	说明	默认值
`-c, --ctx-size N`	上下文窗口大小	模型自带
`-n, --n-predict N`	最大生成长度	无穷大
`-t N`	CPU 线程数	自动检测
`-tb N`	批处理线程数	同 `-t`
`-b N`	逻辑最大 batch size	2048
`--ubatch-size N`	物理最大 batch size	512
`-fa, --flash-attn`	Flash Attention（auto/on/off）	auto
`-mg i`	GPU offload 层数（i=0 表示全 CPU）	全部 GPU

模型量化

模型需要是 GGUF 格式。Hugging Face 上已有数千个 GGUF 模型：https://huggingface.co/models?library=gguf&sort=trending

在线转换工具： - GGUF-my-repo space：普通模型转 GGUF + 量化 - GGUF-my-LoRA space：LoRA 适配器转 GGUF - GGUF-editor space：浏览器编辑 GGUF 元数据

本地量化（需 llama.cpp 源码）：

# 见 tools/quantize/README.md

典型适用场景

场景	推荐后端
MacBook M1/M2/M3 本地推理	Metal
NVIDIA GPU 服务器推理	CUDA
AMD GPU（ROCm）推理	HIP
通用 GPU（Intel/国产卡）	Vulkan / SYCL
CPU only（轻量推理）	CPU + OpenBLAS
量化压缩（低显存场景）	CPU+GPU offload + Q4_K
快速部署 API 服务	llama serve
手机/嵌入式	ARM NEON / Android

坑与注意

模型必须是 GGUF 格式：其他格式（Safetensors、PyTorch .bin）需先转换，用仓库里的 convert_*.py 脚本。
量化精度 vs 速度权衡：Q8_0 质量最高但体积大；Q4_K / Q3_K 在 4-8GB 内存/MacBook 上体验好；INT2/INT3 仅适合极度受限环境。
GPU 选型：NVIDIA 用 CUDA；AMD 用 HIP；Mac 全系列用 Metal（无需额外配置）；国产 GPU 尝试 Vulkan 或 SYCL。
上下文窗口：-c 参数决定能处理的上下文长度，8K 模型用 -c 8192，超过会报错。
CPU 线程数：-t 参数在超售服务器上建议明确设置，否则可能绑定过多线程影响性能。
Flash Attention：需特定硬件支持，GPU 后端下默认 auto 即可提升首 token 速度。
llama serve 并发：支持 continuous batching 和多用户，API 参数与 OpenAI Chat Completions 高度兼容，但某些字段映射需对照文档。

与同类对比

工具	依赖	量化	GPU 支持	API 兼容
llama.cpp	无（纯 C++）	全面（Q2-Q8）	CUDA/Metal/Vulkan/HIP/SYCL	OpenAI + Anthropic
Ollama	Docker/Kubernetes	内置	CUDA/Metal/Vulkan	OpenAI 兼容
vLLM	PyTorch	PagedAttention	CUDA 为主	OpenAI
text-generation-webui	Python	GPTQ/AWQ/GGUF	多种	OpenAI
lmstudio	闭源 App	内置	CUDA/Metal	OpenAI 兼容

llama.cpp 的独特优势：无依赖 + 最广硬件覆盖 + GGUF 量化生态成熟，是本地推理的底层基础设施；Ollama/lmstudio 等工具实际上也是在 llama.cpp 之上封装。

一句话推荐结论

本地 LLM 推理的底层基础设施首选：纯 C/C++ 无依赖、多硬件最优覆盖、GGUF 量化生态成熟，llama serve 直接提供 OpenAI 兼容 API，从 7B 到 405B 都能在各种硬件上跑起来。