llama.cpp：纯C/C++本地大模型推理引擎安装与使用指南
一、官方信息
| 项目名称 | llama.cpp |
| 仓库地址 | https://github.com/ggerganov/llama.cpp |
| 官方网站 | GitHub 主页（无独立官网） |
| 最新更新 | 持续高频迭代（2026-10-28） |
| Star 数 | 8万+（GitHub 最热门的本地推理项目之一） |
| 项目定位 | 纯 C/C++ 实现的 LLaMA 及衍生模型本地推理框架，CPU/GPU 全平台跑量化模型 |
二、项目背景
llama.cpp 由 Georgi Gerganov（简称 ggerganov）于 2023 年 3 月开源，初衷是用纯 C/C++ 复现 Meta 发布的 LLaMA 推理过程，让开发者在没有高端 GPU 的笔记本电脑上也能跑起大语言模型。它不依赖 PyTorch、CUDA 等重型框架，仅凭一块普通 CPU 就能完成推理，开启了"个人本地跑大模型"的浪潮。
经过三年多发展，llama.cpp 已经支持 LLaMA、Qwen、DeepSeek、Mistral、Gemma、Phi、Yi、Baichuan、ChatGLM、GLM-4 等几乎所有主流开源模型，并衍生出 GGUF 量化格式、llama-server 本地 OpenAI 兼容 API、llama-bench 性能测试工具等完整生态。Ollama、LM Studio、LocalAI 等知名项目底层都调用了 llama.cpp。
三、核心特性
- 极致轻量化：纯 C/C++ 编写，无 Python 依赖，单二进制文件即可运行，内存占用极低。
- GGUF 量化格式：原生支持 Q4_K_M、Q5_K_M、Q8_0 等多种量化精度，7B 模型 4-bit 量化后仅需 4GB 内存即可运行。
- 全平台支持：Linux、macOS、Windows、Android、iOS、Raspberry Pi、WebAssembly 均可运行。
- 多后端加速：支持 CPU、CUDA、Metal（Apple Silicon）、Vulkan、ROCm、Hexagon 等多种推理后端自动切换。
- OpenAI 兼容服务：内置 llama-server，一键启动后即提供 /v1/chat/completions 接口，可直接对接 NextChat、Open-WebUI 等前端。
- 工具调用 / 函数调用：原生支持 Function Calling、JSON Schema 输出、Grammar 约束解码。
- 活跃社区：GitHub 8 万+ Star，每天合并大量 PR，新模型适配速度极快。
四、环境要求
- 操作系统：Ubuntu 20.04+ / Debian 11+ / CentOS 8+ / macOS 12+ / Windows 10+（推荐 Linux）
- CPU：支持 AVX2 指令集的 x86_64 处理器（Apple Silicon M1/M2/M3/M4 原生支持）
- 内存：7B Q4 模型 ≥ 8GB；14B Q4 ≥ 12GB；70B Q4 ≥ 40GB
- GPU（可选）：NVIDIA 显卡 ≥ 4GB 显存（CUDA 11.7+）；Apple Silicon 统一内存自动利用
- 编译依赖：CMake ≥ 3.14、gcc/g++ ≥ 11、Git；如启用 CUDA 需安装 CUDA Toolkit
五、详细部署步骤
方式一：预编译二进制（最快，推荐新手）
官方在 GitHub Releases 提供了各平台预编译包，无需编译，下载即用：
# 1. 访问 Releases 页面
# https://github.com/ggerganov/llama.cpp/releases
# 2. 下载对应平台包（以 Linux x64 为例）
wget https://github.com/ggerganov/llama.cpp/releases/latest/download/llama-bXXXX-bin-ubuntu-x64.zip
unzip llama-bXXXX-bin-ubuntu-x64.zip -d llama.cpp
cd llama.cpp
# 3. 验证版本
./llama-cli --version方式二：Docker 部署（最省心）
# 1. 拉取官方镜像（CPU 版）
docker pull ghcr.io/ggml-org/llama.cpp:latest
# 2. 准备模型目录
mkdir -p ~/models
# 把下载好的 GGUF 模型放到 ~/models 目录
# 3. 启动 OpenAI 兼容 API 服务
docker run -d \
--name llama-server \
-p 8080:8080 \
-v ~/models:/models \
ghcr.io/ggml-org/llama.cpp:latest \
-m /models/qwen2.5-7b-instruct-q4_k_m.gguf \
--host 0.0.0.0 \
--port 8080 \
-c 4096 \
-ngl 99
# 4. 查看日志
docker logs -f llama-server方式三：源码编译（性能最佳，推荐生产）
# 1. 安装编译依赖（Ubuntu/Debian）
sudo apt update
sudo apt install -y build-essential cmake git libcurl4-openssl-dev
# 2. 克隆源码（--recursive 拉取子模块）
git clone --recursive https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
# 3a. CPU 版本编译
cmake -B build
cmake --build build --config Release -j $(nproc)
# 3b. 启用 CUDA 加速（NVIDIA 显卡用户）
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="native"
cmake --build build --config Release -j $(nproc)
# 3c. 启用 Metal 加速（macOS Apple Silicon 用户）
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release -j $(sysctl -n hw.ncpu)
# 4. 编译产物位于 build/bin/ 目录
ls build/bin/
# 关键可执行文件：
# llama-cli 命令行对话
# llama-server HTTP API 服务
# llama-bench 性能测试
# llama-quantize 模型量化工具
# llama-convert-hf-to-gguf HuggingFace 模型转 GGUF下载模型（GGUF 格式）
# 推荐从 ModelScope（国内快）或 HuggingFace 下载
# 以 Qwen2.5-7B-Instruct Q4_K_M 为例
# 方法 A：直接 wget
mkdir -p models
wget -O models/qwen2.5-7b-instruct-q4_k_m.gguf \
"https://modelscope.cn/models/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/master/qwen2.5-7b-instruct-q4_k_m.gguf"
# 方法 B：使用 huggingface-cli
pip install -U huggingface_hub
huggingface-cli download Qwen/Qwen2.5-7B-Instruct-GGUF \
qwen2.5-7b-instruct-q4_k_m.gguf \
--local-dir ./models启动命令行对话
./build/bin/llama-cli \
-m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \
-p "你是谁？请用中文介绍自己。" \
-n 512 \
--interactive \
-c 4096 \
-ngl 99 # 把所有层offload到GPU；纯CPU则去掉此参数启动 HTTP API 服务（推荐生产使用）
./build/bin/llama-server \
-m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \
--host 0.0.0.0 \
--port 8080 \
-c 8192 \ # 上下文长度
-ngl 99 \ # GPU offload 层数
--n-gpu-layers 99 \
--flash-attn on \ # 开启 Flash Attention 省显存
--jinja # 使用模型自带 chat template
# 启动后访问：
# Web UI: http://服务器IP:8080/
# OpenAI API: http://服务器IP:8080/v1/chat/completions
# 健康检查: http://服务器IP:8080/healthAPI 调用示例
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "qwen2.5-7b",
"messages": [
{"role": "system", "content": "你是一个 helpful 助手"},
{"role": "user", "content": "写一首关于秋天的五言绝句"}
],
"max_tokens": 512,
"temperature": 0.7
}'六、常见问题（FAQ）
Q1：启动报 "error: loading model: unexpected token found"？
A：模型文件下载不完整或损坏，重新下载并校验文件大小（应约 4.7GB）。建议用 wget -c 断点续传。
Q2：CPU 推理很慢怎么加速？
A：① 确认编译时启用了 AVX2（CMake 自动检测）；② 选用 Q4_K_M 量化而非 Q8；③ 增大 -t 参数指定线程数（如 -t 8）；④ 有 N 卡务必加 -ngl 99 offload 到 GPU。
Q3：如何把 HuggingFace 原版模型转成 GGUF？
A：先 pip install -r requirements.txt，然后：
python3 llama-convert-hf-to-gguf.py /path/to/hf-model --outfile model-f16.gguf
再量化：./build/bin/llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M
Q4：上下文长度爆显存？
A：减小 -c 参数（如 2048），启用 Flash Attention（--flash-attn on），或换用更小量化等级（Q4_0）。
Q5：Windows 下如何部署？
A：直接从 Releases 下载 win64 预编译 zip，解压后在 cmd/PowerShell 中运行 llama-server.exe 即可，无需编译。
七、跳转链接
- GitHub 仓库：https://github.com/ggerganov/llama.cpp
- Releases 下载：https://github.com/ggerganov/llama.cpp/releases
- GGUF 模型仓库：HuggingFace GGUF 模型列表
- ModelScope 镜像：ModelScope GGUF 搜索
- 官方文档：docs 目录