llama.cpp纯CPU部署指南

本文最后更新于 2026年8月7日 上午

llama.cpp纯CPU部署指南

llama.cpp 是一个高性能的 C/C++ 本地推理引擎，支持在各种硬件上高效运行 LLM 模型。本文将详细介绍如何在国内和通用环境下正确部署 llama.cpp。

为什么选择 llama.cpp

  • ⚡ 高性能：极致优化的推理引擎，支持多种硬件加速
  • 🔧 纯 C/C++ 实现：无 Python 依赖，编译后即可运行
  • 📱 多平台支持：支持 x86、ARM、Apple Silicon 等
  • 🧠 量化支持：支持 4-bit、5-bit、8-bit 等量化格式
  • 🔌 多种前端：支持命令行、服务器模式、嵌入式设备

官方链接

平台 链接 说明
GitHub 仓库 github.com/ggml-org/llama.cpp 源代码
官方文档 github.com/ggml-org/llama.cpp/blob/master/README.md 使用文档
模型下载 huggingface.co GGUF 格式模型
量化工具 github.com/ggml-org/llama.cpp/tree/master/convert 模型转换脚本

一、国内部署方式

前置条件

在开始之前，需要安装编译环境：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Windows 用户推荐使用 MSYS2 或 WSL2
# 安装 MSYS2 后执行：
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make cmake

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential cmake git

# Linux (CentOS/RHEL)
sudo yum groupinstall "Development Tools"
sudo yum install cmake git

# macOS
# 只需安装 Xcode Command Line Tools
xcode-select --install

方式一：获取源码

方法 1：使用 Gitee 镜像克隆（推荐）

1
2
3
# 使用 Gitee 国内镜像克隆
git clone https://gitee.com/mirrors/llama-cpp.git
cd llama-cpp

方法 2：GitHub 加速访问

1
2
3
4
5
6
# 使用 GitHub 代理加速克隆
git clone https://gh-proxy.com/https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

# 或者直接下载 ZIP 压缩包
# https://gh-proxy.com/https://github.com/ggml-org/llama.cpp/archive/master.zip

方法 3：从国内平台下载

1
2
3
4
5
# Gitee 镜像下载
# https://gitee.com/mirrors/llama-cpp

# 华为云代码托管
# https://repo.huaweicloud.com/

方式二：国内编译方法

1. 编译 llama.cpp

使用 CMake 编译（推荐）：

1
2
3
4
5
6
7
8
9
10
# 创建构建目录
mkdir build && cd build

# 配置编译选项
cmake .. -DCMAKE_BUILD_TYPE=Release

# 编译（-j 后面跟 CPU 核心数）
make -j$(nproc)

# 可执行文件在 build/bin/ 目录下

Makefile 方式：

1
2
3
4
5
# 简单编译
make

# 指定优化级别编译
make LLAMA_NATIVE=1

2. 国内下载模型

由于 HuggingFace 在国内访问较慢，可以使用以下方式下载模型：

方法一：使用 ModelScope（魔搭社区）

1
2
3
4
# 访问 ModelScope
# https://www.modelscope.cn/

# 搜索 GGUF 格式模型下载

方法二：使用国内 HuggingFace 镜像

1
2
3
4
5
# 设置 HuggingFace 镜像源
export HF_ENDPOINT=https://hf-mirror.com

# 使用 huggingface-cli 下载
hf download ggml-org/models llama2-7b.Q4_0.gguf

方法三：手动下载

  1. 访问 ModelScope 或其他国内模型站点
  2. 搜索 llama.cpp 支持的 GGUF 格式模型
  3. 下载后放入指定目录

方式三：Docker 部署（国内镜像）

1
2
3
4
5
6
7
8
9
10
11
12
13
# 使用国内 Docker 镜像源
# 修改 /etc/docker/daemon.json，添加：
{
  "registry-mirrors": [
    "https://docker.1ms.run",
  ]
}

# 拉取 llama.cpp Docker 镜像
docker pull registry.cn-hangzhou.aliyuncs.com/library/llama-cpp:latest

# 或者使用 NVIDIA 官方镜像（如有 GPU）
docker pull registry.cn-hangzhou.aliyuncs.com/nvidia/llama-cpp:latest

国内常见问题

下载源码慢怎么办？

使用国内 Gitee 镜像或 GitHub 加速代理：

模型下载慢怎么办？

使用 ModelScope 国内平台：

编译依赖下载失败？

可以提前下载依赖源码，或使用国内 npm/maven 镜像源。

二、通用部署方式

前置条件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Windows
# 安装 Visual Studio Build Tools 或 MSYS2
# 下载地址：https://visualstudio.microsoft.com/downloads/

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential cmake git

# Linux (Fedora)
sudo dnf groupinstall "Development Tools"
sudo dnf install cmake git

# macOS
xcode-select --install

方式一：从源码编译（推荐）

1. 克隆仓库

1
2
3
# 克隆 llama.cpp 仓库
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

2. 编译

基础编译：

1
2
3
4
# 使用 CMake（推荐）
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

带 GPU 加速编译（NVIDIA CUDA）：

1
2
3
4
5
mkdir build && cd build
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DGGML_CUDA=ON
make -j$(nproc)

带 Metal 加速编译（Apple Silicon）：

1
2
3
4
# macOS 默认支持 Metal，直接编译即可
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(sysctl -n hw.ncpu)

带 OpenCL 加速编译：

1
2
3
4
5
mkdir build && cd build
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DGGML_OPENCL=ON
make -j$(nproc)

编译选项说明：

选项 说明
-DGGML_CUDA=ON 启用 NVIDIA GPU 加速
-DGGML_OPENCL=ON 启用 OpenCL 加速
-DGGML_METAL=ON 启用 Apple Metal 加速（默认开启）
-DGGML_VULKAN=ON 启用 Vulkan 加速
-DCMAKE_BUILD_TYPE=Release Release 优化模式

3. 下载模型

从 HuggingFace 下载：

1
2
3
4
5
6
7
8
9
# 安装 huggingface-hub
pip install huggingface-hub

# 下载 GGUF 格式模型
hf download ggml-org/models llama2-7b.Q4_0.gguf

# 或者指定下载目录
hf download ggml-org/models llama2-7b.Q4_0.gguf \
  --local-dir ./models

从modelscope下载：

1
2
pip install modelscope
modelscope download --model unsloth/Qwen3.5-4B-GGUF Qwen3.5-4B-Q4_K_M.gguf --local_dir ./models

常用 GGUF 模型地址：

方式二：Docker 部署

使用官方 Docker 镜像

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 拉取官方镜像
docker pull ghcr.io/ggml-org/llama.cpp:latest

# 运行容器
docker run -d \
  --name llama-cpp \
  -v $(pwd)/models:/models \
  -p 8080:8080 \
  ghcr.io/ggml-org/llama.cpp:latest \
  --model /models/llama2-7b.Q4_0.gguf \
  --host 0.0.0.0 \
  --port 8080

# 查看日志
docker logs -f llama-cpp

使用 NVIDIA GPU 加速

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 确保已安装 NVIDIA Container Toolkit
# https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

# 运行带 GPU 的容器
docker run -d \
  --name llama-cpp-gpu \
  --gpus all \
  -v $(pwd)/models:/models \
  -p 8080:8080 \
  ghcr.io/ggml-org/llama.cpp:latest \
  --model /models/llama2-7b.Q4_0.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  --cuda

三、使用方法

命令行运行

1
2
3
4
5
6
7
8
9
10
11
12
13
# 运行模型（交互式）
./build/bin/llama-cli -m ./models/llama2-7b.Q4_0.gguf

# 指定参数运行
./build/bin/llama-cli \
  -m ./models/llama2-7b.Q4_0.gguf \
  -t 8 \                    # 使用 8 个线程
  -n 256 \                  # 最大生成 token 数
  -c 4096 \                 # 上下文窗口大小
  -p "你好，请介绍一下自己"  # 提示词

# 批量处理
echo "你好" | ./build/bin/llama-cli -m ./models/llama2-7b.Q4_0.gguf

服务器模式

1
2
3
4
5
6
7
8
9
10
11
12
# 启动 HTTP 服务器
./build/bin/llama-server \
  -m ./models/llama2-7b.Q4_0.gguf \
  --host 0.0.0.0 \
  --port 8080

# 使用 API 调用
curl http://localhost:8080/completion -d '{
  "prompt": "你好",
  "n_predict": 128,
  "temperature": 0.7
}'

模型量化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 安装量化工具依赖
pip install -r requirements.txt

# 下载原始模型（HuggingFace 格式）
# 从 huggingface.co 下载原始 HuggingFace 模型

# 转换为 F16 格式
python convert-hf-to-gguf.py /path/to/model \
  --output-dir ./models \
  --outtype f16

# 量化为 Q4_K_M 格式（推荐）
./build/bin/llama-quantize \
  ./models/model-f16.gguf \
  ./models/model-q4_k_m.gguf \
  Q4_K_M

# 量化格式说明：
# Q2_K, Q3_K_S, Q3_K_M, Q3_K_L, Q4_0, Q4_K_S, Q4_K_M, Q5_0, Q5_K_S, Q5_K_M, Q8_0

Python API 调用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import requests

# llama.cpp 服务器 API
BASE_URL = "http://localhost:8080"

# 发送请求
response = requests.post(f"{BASE_URL}/completion", json={
    "prompt": "Hello, introduce yourself",
    "n_predict": 128,
    "temperature": 0.7,
    "top_p": 0.9,
    "stop": ["\n"]
})

# 处理响应
result = response.json()
print(result["content"])

使用 llama-cpp-python

1
2
3
4
5
# 安装 Python 绑定
pip install llama-cpp-python

# 如果需要从源码编译
CMAKE_ARGS="-DGGML_CUDA=ON" pip install llama-cpp-python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from llama_cpp import Llama

# 加载模型
llm = Llama(
    model_path="./models/llama2-7b.Q4_0.gguf",
    n_ctx=4096,
    n_gpu_layers=-1  # -1 表示使用所有 GPU 层
)

# 生成文本
output = llm(
    "Q: 你好，请介绍一下自己\nA: ",
    max_tokens=128,
    stop=["\n"]
)

print(output["choices"][0]["text"])

# 聊天模式
output = llm.create_chat_completion(
    messages=[
        {"role": "user", "content": "你好"}
    ],
    max_tokens=128
)

print(output["choices"][0]["message"]["content"])

四、常见问题

编译错误怎么办？

1
2
3
4
5
6
7
8
9
# 确保编译环境完整
# Ubuntu/Debian
sudo apt install build-essential cmake git python3

# 清理后重新编译
rm -rf build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

显存/内存不足？

1
2
3
4
5
6
7
8
# 使用更小的模型
# Q2_K < Q3_K < Q4_K < Q5_K < Q8_0 < F16

# 减小上下文窗口
./build/bin/llama-cli -m model.gguf -c 2048

# 使用更少的线程
./build/bin/llama-cli -m model.gguf -t 4

如何选择量化级别？

量化类型 大小 质量 推荐场景
Q2_K ~1.5GB 较低 测试、极小设备
Q3_K_M ~2GB 一般 嵌入式使用
Q4_K_M ~2.5GB 良好 日常使用（推荐）
Q5_K_M ~3GB 很好 质量优先
Q8_0 ~5GB 优秀 高质量需求
F16 ~7GB 原始 研究、精度要求高

模型不支持怎么办？

  1. 检查模型格式是否为 GGUF
  2. 参考 llama.cpp 的 README.md 查看支持的模型列表
  3. 某些新模型可能需要最新版本的 llama.cpp

性能优化建议

1
2
3
4
5
6
7
8
9
10
# 使用 GPU 加速（如有）
# NVIDIA CUDA: 编译时加 -DGGML_CUDA=ON
# Apple Silicon: 默认启用 Metal
# AMD: 编译时加 -DGGML_VULKAN=ON

# 使用适当的线程数
./build/bin/llama-cli -m model.gguf -t $(nproc)

# 启用 KV Cache（默认开启）
# 可以提升长文本处理速度

五、进阶配置

环境变量

变量名 说明 默认值
GGML_THREADS 线程数 CPU 核心数
LLAMA_MAX_LOADED_MODELS 最大加载模型数 1

配置开机自启（Linux 服务器）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 创建 systemd 服务
sudo nano /etc/systemd/system/llama-cpp.service

# 添加以下内容
[Unit]
Description=llama.cpp Server
After=network.target

[Service]
ExecStart=/path/to/llama-server \
  -m /path/to/model.gguf \
  --host 0.0.0.0 \
  --port 8080
User=your_username
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable llama-cpp
sudo systemctl start llama-cpp

多模型服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 创建 systemd 服务
sudo nano /etc/systemd/system/llama-cpp.service

# 添加以下内容
[Unit]
Description=llama.cpp Server
After=network.target

[Service]
ExecStart=/root/llama.cpp/build/bin/llama-server \
  --models-dir /root/llama.cpp/models \
  --host 0.0.0.0 \
  --port 8080
User=root
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable llama-cpp
sudo systemctl start llama-cpp

适用场景

  • 💻 高性能本地推理
  • 📱 嵌入式设备 AI
  • 🔧 模型转换与量化
  • 🏢 私有化部署
  • 🎓 AI 研究与教学
  • ⚙️ 定制化 AI 应用
llama.cpp纯CPU部署指南
https://blog.quickso.cn/2026/08/07/llama-cpp纯CPU部署指南/
作者
木子欢儿
发布于
2026年8月7日
许可协议