llama.cpp

llama.cpp 是一个用纯 C/C++ 编写的大语言模型推理框架，由 Georgi Gerganov 创建。它最大的特点是无需 Python 环境即可运行，支持 CPU 和 GPU 推理，能够高效运行 GGUF 格式的量化模型。对于资源有限的服务器或需要极致性能的场景，llama.cpp 是非常好的选择。

系统要求

CentOS Stream 9 / AlmaLinux 9 / Rocky Linux 9
GCC 11+ 或 Clang 14+
CMake 3.21+
至少 4 GB 内存（运行 7B 量化模型）
可选：NVIDIA GPU + CUDA（用于 GPU 加速）

安装编译依赖

sudo dnf install -y git gcc gcc-c++ make cmake

如果需要 CUDA 支持，确保已安装 NVIDIA 驱动和 CUDA 工具包（参考 NVIDIA 驱动与 CUDA）。

从源码编译

克隆代码

cd /opt
sudo mkdir -p llama-cpp && sudo chown $(whoami):$(whoami) llama-cpp
git clone https://github.com/ggerganov/llama.cpp.git /opt/llama-cpp
cd /opt/llama-cpp

纯 CPU 编译

cd /opt/llama-cpp
cmake -B build
cmake --build build --config Release -j$(nproc)

编译完成后，二进制文件位于 build/bin/ 目录。

启用 CUDA GPU 加速编译

cd /opt/llama-cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

验证 CUDA 编译成功：

./build/bin/llama-cli --version

其他编译选项

# 启用 OpenBLAS 加速（CPU 矩阵运算优化）
sudo dnf install -y openblas-devel
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j$(nproc)

# 启用 Vulkan（AMD GPU 或无 CUDA 的 NVIDIA GPU）
sudo dnf install -y vulkan-headers vulkan-loader-devel
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release -j$(nproc)

GGUF 模型格式

GGUF（GPT-Generated Unified Format）是 llama.cpp 使用的模型格式，支持多种量化精度，在模型体积和推理质量之间取得平衡。

下载 GGUF 模型

从 Hugging Face 下载预量化的 GGUF 模型：

mkdir -p /opt/llama-cpp/models

# 下载 Qwen2.5-7B-Instruct GGUF（Q4_K_M 量化，约 4.7 GB）
cd /opt/llama-cpp/models
wget https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf

# 下载 Llama 3.1 8B GGUF
wget https://huggingface.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF/resolve/main/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf

量化级别说明

量化类型	大小（7B 模型）	质量	速度
Q2_K	~2.7 GB	较低	最快
Q3_K_M	~3.3 GB	一般	快
Q4_K_M	~4.7 GB	良好（推荐）	较快
Q5_K_M	~5.3 GB	很好	中等
Q6_K	~5.9 GB	优秀	较慢
Q8_0	~7.2 GB	接近原始	慢
F16	~14 GB	原始精度	最慢

一般推荐使用 Q4_K_M，在质量和体积之间有很好的平衡。

运行推理

交互式对话

cd /opt/llama-cpp

./build/bin/llama-cli \
  -m models/qwen2.5-7b-instruct-q4_k_m.gguf \
  -c 4096 \
  -n 512 \
  --chat-template chatml \
  -cnv

参数说明：

参数	说明
`-m`	模型文件路径
`-c`	上下文长度
`-n`	最大生成 token 数
`--chat-template`	聊天模板格式
`-cnv`	启用对话模式
`-t`	线程数（默认自动检测）
`-ngl`	卸载到 GPU 的层数（CUDA 编译时可用）

GPU 卸载

如果使用 CUDA 编译，可以将部分或全部模型层卸载到 GPU：

# 将全部层卸载到 GPU（需要足够的 GPU 显存）
./build/bin/llama-cli \
  -m models/qwen2.5-7b-instruct-q4_k_m.gguf \
  -c 4096 \
  -ngl 99 \
  -cnv

# 仅卸载部分层（显存不足时）
./build/bin/llama-cli \
  -m models/qwen2.5-7b-instruct-q4_k_m.gguf \
  -c 4096 \
  -ngl 20 \
  -cnv

单次生成

./build/bin/llama-cli \
  -m models/qwen2.5-7b-instruct-q4_k_m.gguf \
  -p "用简洁的语言解释什么是 Linux 内核" \
  -n 256 \
  -c 2048

性能基准测试

./build/bin/llama-bench \
  -m models/qwen2.5-7b-instruct-q4_k_m.gguf \
  -t $(nproc)

Server 模式

llama.cpp 内置了 HTTP 服务器，提供兼容 OpenAI API 的接口。

启动服务器

cd /opt/llama-cpp

./build/bin/llama-server \
  -m models/qwen2.5-7b-instruct-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -c 4096 \
  -ngl 99 \
  --chat-template chatml

API 调用

服务器提供兼容 OpenAI 格式的 API：

# Chat Completions
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手。"},
      {"role": "user", "content": "什么是 SELinux？"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

# Text Completions
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Linux 操作系统的优点包括",
    "max_tokens": 256
  }'

# 健康检查
curl http://localhost:8080/health

服务器还自带一个简易的 Web 界面，直接在浏览器访问 http://your-server-ip:8080 即可使用。

systemd 服务

sudo tee /etc/systemd/system/llama-server.service > /dev/null <<'EOF'
[Unit]
Description=llama.cpp Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/llama-cpp
ExecStart=/opt/llama-cpp/build/bin/llama-server \
  -m /opt/llama-cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -c 4096 \
  -ngl 99 \
  --chat-template chatml
Restart=on-failure
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now llama-server

模型量化

如果你有原始的 Hugging Face 模型，可以用 llama.cpp 自行转换和量化。

转换模型为 GGUF

cd /opt/llama-cpp

# 安装 Python 依赖（仅转换时需要）
pip install -r requirements.txt

# 将 Hugging Face 模型转换为 GGUF（F16 精度）
python convert_hf_to_gguf.py /path/to/huggingface-model/ \
  --outfile models/my-model-f16.gguf \
  --outtype f16

量化模型

# 将 F16 模型量化为 Q4_K_M
./build/bin/llama-quantize \
  models/my-model-f16.gguf \
  models/my-model-q4_k_m.gguf \
  Q4_K_M

# 量化为 Q5_K_M（更高质量）
./build/bin/llama-quantize \
  models/my-model-f16.gguf \
  models/my-model-q5_k_m.gguf \
  Q5_K_M

验证量化模型

# 快速测试量化模型是否正常
./build/bin/llama-cli \
  -m models/my-model-q4_k_m.gguf \
  -p "Hello, how are you?" \
  -n 64

防火墙配置

sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

更新 llama.cpp

llama.cpp 更新非常频繁，建议定期更新以获取性能改进和新模型支持：

cd /opt/llama-cpp
git pull

# 清理旧的编译文件并重新编译
rm -rf build
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

# 重启服务
sudo systemctl restart llama-server

常见问题

编译报错：CMake 版本过低

# 安装较新版本的 CMake
sudo dnf install -y cmake3
# 或从源码编译 CMake

推理速度慢

# 检查是否使用了所有 CPU 核心
./build/bin/llama-cli -m model.gguf -t $(nproc) ...

# 如果有 GPU，确保使用了 CUDA 编译并设置 -ngl
./build/bin/llama-cli -m model.gguf -ngl 99 ...

# 使用更小的量化模型
# Q4_K_M 通常比 Q8_0 快 40-50%

内存不足

# 使用更小的量化版本
# Q2_K 约为 F16 的 1/5 大小

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

# 使用 mmap（默认启用）避免将整个模型加载到内存

CUDA 相关错误

# 确认 CUDA 工具包版本
nvcc --version

# 确认编译时启用了 CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

# 检查 GPU 是否被识别
nvidia-smi