llama.cpp 本地部署配置¶

纯 C++ 实现的高性能 LLM 推理引擎，支持多种量化格式和硬件后端

GitHub：https://github.com/ggerganov/llama.cpp
语言：C/C++
许可证：MIT

系统要求¶

项目	最低要求	推荐
编译器	GCC 9+ / Clang 15+ / MSVC 2022	最新版
CMake	3.14+	最新版
CPU	AVX2 支持	AVX512 / ARM NEON
GPU (CUDA)	CUDA 11.6+	CUDA 12.x
GPU (Metal)	macOS 13+	Apple Silicon M1+

编译安装¶

基础编译（纯 CPU）¶

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

CUDA GPU 编译¶

Bash
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

Metal 后端 (macOS Apple Silicon)¶

Bash
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release -j$(nproc)

Vulkan 后端（跨平台 GPU）¶

Bash
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release -j$(nproc)

ROCm 后端 (AMD GPU)¶

Bash
cmake -B build -DGGML_HIPBLAS=ON
cmake --build build --config Release -j$(nproc)

Windows MSVC 编译¶

PowerShell
cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release

# CUDA
cmake -B build -G "Visual Studio 17 2022" -A x64 -DGGML_CUDA=ON
cmake --build build --config Release

可选编译选项¶

选项	说明
`-DGGML_CUDA=ON`	启用 CUDA 后端
`-DGGML_METAL=ON`	启用 Metal 后端
`-DGGML_VULKAN=ON`	启用 Vulkan 后端
`-DGGML_HIPBLAS=ON`	启用 ROCm 后端
`-DGGML_BLAS=ON`	启用 OpenBLAS
`-DGGML_RPC=ON`	启用 RPC 远端推理
`-DLLAMA_CURL=ON`	启用 URL 模型下载

模型获取与量化¶

方式一：从 HuggingFace 下载预量化 GGUF¶

Bash
# 使用 huggingface-cli
pip install huggingface-hub
huggingface-cli download TheBloke/Qwen2.5-7B-Instruct-GGUF qwen2.5-7b-instruct-q4_k_m.gguf --localdir .

# 或使用 wget
wget https://huggingface.co/TheBloke/Qwen2.5-7B-Instruct-GGUF/resolve/main/qwen2.5-7b-instruct-q4_k_m.gguf

方式二：从 HF 原始模型转换并量化¶

Bash
# 1. 下载原始模型
git lfs install
git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct

# 2. 转换为 GGUF FP16
python convert-hf-to-gguf.py ./Qwen2.5-7B-Instruct --outfile qwen2.5-7b-f16.gguf

# 3. 量化
./build/bin/llama-quantize qwen2.5-7b-f16.gguf qwen2.5-7b-q4_km.gguf Q4_K_M

量化等级详解¶

量化类型	比特率	模型大小（7B）	质量损失	速度	推荐场景
Q2_K	~2.7 bit	2.8 GB	明显	快	极端资源受限
Q3_K_M	~3.5 bit	3.5 GB	较大	快	低端设备
Q4_K_M	~4.8 bit	4.7 GB	小	较快	推荐默认
Q5_K_M	~5.7 bit	5.5 GB	很小	中	质量优先
Q6_K	~6.6 bit	6.3 GB	极小	中	高质量
Q8_0	8.5 bit	8.1 GB	几乎无损	较慢	接近原始质量
F16	16 bit	15 GB	无损	慢	基准测试

💡 建议：一般用途选 Q4_K_M，质量敏感选 Q5_K_M/Q6_K，极端省空间选 Q3_K_M

命令行推理¶

基本对话¶

Bash
./llama-cli -m model.gguf -p "你好，请自我介绍" -n 512

交互式对话¶

Bash
./llama-cli -m model.gguf -i -cnv

关键参数¶

参数	说明	示例
`-m`	模型文件路径	`-m qwen2.5-7b-q4_km.gguf`
`-p`	提示词	`-p "你好"`
`-n`	最大生成 Token 数	`-n 1024`
`-c`	上下文长度	`-c 4096`
`-ngl`	GPU 层数（0=纯CPU，99=全GPU）	`-ngl 99`
`-i`	交互模式	`-i`
`-cnv`	对话模式	`-cnv`
`--temp`	温度	`--temp 0.7`
`--top-p`	Top-P 采样	`--top-p 0.9`
`--top-k`	Top-K 采样	`--top-k 40`
`--repeat-penalty`	重复惩罚	`--repeat-penalty 1.1`
`--prompt-cache`	Prompt 缓存文件	`--prompt-cache cache.bin`
`-b`	Batch size	`-b 512`
`--mlock`	锁定内存	`--mlock`
`--no-mmap`	不使用内存映射	`--no-mmap`

完整对话示例¶

Bash
./llama-cli \
  -m qwen2.5-7b-q4_km.gguf \
  -ngl 99 \
  -c 4096 \
  --temp 0.7 \
  --top-p 0.9 \
  --repeat-penalty 1.1 \
  --in-prefix "<|im_start|>user\n" \
  --in-suffix "<|im_end|>\n<|im_start|>assistant\n" \
  -i -cnv

HTTP 服务（OpenAI 兼容 API）¶

启动服务¶

Bash
# 基本启动
./llama-server -m model.gguf -ngl 99 --port 8080

# 完整配置
./llama-server \
  -m qwen2.5-7b-q4_km.gguf \
  -ngl 99 \
  --port 8080 \
  --host 0.0.0.0 \
  -c 4096 \
  -b 512 \
  --parallel 4 \
  --metrics

服务参数¶

参数	说明	默认值
`--port`	端口	8080
`--host`	监听地址	127.0.0.1
`--parallel`	并行请求数	1
`--metrics`	启用 Prometheus 指标	—
`--n-predict`	默认最大生成数	512
`--threads-http`	HTTP 线程数	—

API 调用¶

Bash
# Chat Completions（OpenAI 兼容）
curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "qwen2.5-7b",
  "messages": [
    {"role": "system", "content": "你是Python助手"},
    {"role": "user", "content": "写一个快排"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": true
}'

# Completions
curl http://localhost:8080/v1/completions -d '{
  "model": "qwen2.5-7b",
  "prompt": "用Python写快排：",
  "max_tokens": 512
}'

# Embeddings
curl http://localhost:8080/v1/embeddings -d '{
  "model": "qwen2.5-7b",
  "input": "你好世界"
}'

Python 调用¶

Python
import openai

client = openai.OpenAI(base_url="http://localhost:8080/v1", api_key="none")

resp = client.chat.completions.create(
    model="qwen2.5-7b",
    messages=[{"role": "user", "content": "你好"}],
    stream=True
)
for chunk in resp:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

性能调优¶

GPU 相关¶

参数	说明	建议值
`-ngl`	GPU offload 层数	99（全 GPU）
`-ngl 20`	部分层 GPU + 剩余 CPU	显存不足时
`-mmq`	矩阵乘法量化类型	—

CPU 相关¶

参数	说明	建议值
`-t`	线程数	物理核心数
`-b`	Batch size	512
`-ub`	微批次大小	CPU 时设小（如 32）

内存相关¶

参数	说明	何时使用
`--mlock`	锁定内存防止换页	推荐始终开启
`--no-mmap`	不用 mmap	Windows 上有时更快
`--mmap`	使用 mmap	默认，Linux 推荐

性能测试¶

Bash
# Benchmark
./llama-bench -m model.gguf -p 512 -n 128 -ngl 99

# 多种配置对比
./llama-bench -m model.gguf -p 512 -n 128 -ngl 0    # 纯 CPU
./llama-bench -m model.gguf -p 512 -n 128 -ngl 99   # 全 GPU
./llama-bench -m model.gguf -p 512 -n 128 -ngl 20   # 部分混合

多 GPU 与分布式¶

多 GPU¶

Bash
# 自动使用所有 GPU
./llama-cli -m model.gguf -ngl 99 -i -cnv

# 指定 GPU
CUDA_VISIBLE_DEVICES=0,1 ./llama-cli -m model.gguf -ngl 99 -i -cnv

RPC 远程推理¶

Bash
# 在远程 GPU 机器上启动 RPC 服务
./llama-rpc-server -H 0.0.0.0 -p 50052

# 本地连接远程 GPU
./llama-cli -m model.gguf -ngl 99 --rpc 192.168.1.100:50052 -i -cnv

常见问题¶

Q: 编译时找不到 CUDA？¶

Bash
# 确保 CUDA_PATH 设置正确
export CUDA_PATH=/usr/local/cuda
cmake -B build -DGGML_CUDA=ON

Q: Windows 编译报错？¶

使用 Visual Studio 2022 + CMake，确保安装了 "C++ CMake Tools for Windows" 组件。

Q: 首次加载很慢？¶

使用 --mlock 锁定内存，后续加载会更快。也可用 --prompt-cache 缓存系统 Prompt。

Q: 如何查看 GPU 利用率？¶

Bash
nvidia-smi -l 1  # 每秒刷新

练习清单¶

编译 llama.cpp（CPU 版和 CUDA 版）
下载一个 GGUF 模型，运行交互式对话
将 HF 原始模型转换为 GGUF 并量化
启动 HTTP 服务，用 curl 和 Python 调用
对比不同量化等级的质量和速度
使用 llama-bench 做性能测试
配置 Prompt 缓存加速重复加载