使用 llama.cpp 运行 LLM

简介

llama.cpp 是一个轻量级、高性能的 C/C++ 实现，用于运行 LLM。它能够在消费级硬件（包括 NVIDIA Jetson 等 ARM64 设备）上进行高效的 LLM 推理。由于其高效率和广泛的格式支持，它已成为本地 LLM 推理的默认标准。

虽然 Ollama 为 llama.cpp 提供了用户友好的包装，但直接了解 llama.cpp 可以让你：

最大限度地控制推理参数
更好地理解 LLM 的底层工作原理
能够针对特定用例进行优化
支持自定义量化格式

llama-cpp

为什么选择 llama.cpp？

特性	描述
纯 C/C++	无重型依赖，占用空间小
多后端支持	CPU、CUDA、Metal、OpenCL、Vulkan
GGUF 格式	原生支持量化模型
可嵌入	易于集成到应用程序中
CPU 回退	即使没有 GPU 也能工作
流式输出	实时 token 流式传输

Jetson 上的安装

前置要求

确保已安装构建工具：

bash

# 更新软件包列表
sudo apt-get update

# 安装构建 essentials
sudo apt-get install -y build-essential git cmake

# 将 CUDA 环境变量添加到 .bashrc
echo '
# CUDA Environment
export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
export CUDACXX=$CUDA_HOME/bin/nvcc
' >> ~/.bashrc

# 重新加载 shell 配置
source ~/.bashrc

# 验证 CUDA 安装
nvcc --version

克隆并构建 llama.cpp

bash

# 克隆仓库
cd ~
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# 使用 CUDA 支持构建（适用于 Jetson）
#make -j$(nproc) GGML_CUDA=1

# 备选方案：使用 CMake
mkdir build && cd build
cmake .. -DGGML_CUDA=ON
cmake --build . --config Release -j$(nproc)

builded_llamacpp

验证安装

bash

# 检查二进制文件是否已构建
ls ~/llama.cpp/build/bin/llama-cli

# 测试版本
~/llama.cpp/build/bin/llama-cli --version

llama_v

获取你的第一个模型

llama.cpp 使用 GGUF 格式（GGML Universal Format）—— 一种用于存储量化模型的高效二进制格式。

下载模型

bash

# 创建 models 目录
mkdir -p ~/llama.cpp/models
cd ~/llama.cpp/models

# 下载 Llama 3.2 3B（Q4_K_M 量化 - 4 位）
wget https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF/resolve/main/Llama-3.2-3B-Instruct-Q4_K_M.gguf

# 或使用 curl 从 Hugging Face 下载
huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF Llama-3.2-3B-Instruct-Q4_K_M.gguf --local-dir ./models

了解 GGUF 量化

量化方式	位数	文件大小	质量	速度
Q2_K	2位	非常小	较低	最快
Q3_K_M	3位	小	可接受	非常快
Q4_K_M	4位	中等	良好	快
Q5_K_M	5位	中等偏大	非常好	中等
Q6_K	6位	大	优秀	较慢
Q8_0	8位	非常大	接近原始	最慢

对于 Jetson 设备：

Orin Nano 4GB：使用 Q2_K 或 Q3_K_M
Orin Nano 8GB：使用 Q3_K_M 或 Q4_K_M
Orin NX 16GB+：使用 Q4_K_M 或 Q5_K_M

Jetson 推荐模型

bash

# 下载 Qwen3 4B（出色的多语言支持）
wget https://huggingface.co/bartowski/Qwen3-4B-Instruct-GGUF/resolve/main/Qwen3-4B-Instruct-Q4_K_M.gguf

# 下载 DeepSeek-R1 1.5B（蒸馏推理模型）
wget https://huggingface.co/bartowski/DeepSeek-R1-Distill-Qwen-1.5B-GGUF/resolve/main/DeepSeek-R1-Distill-Qwen-1.5B-Q4_K_M.gguf

# 下载 Gemma3 4B
wget https://huggingface.co/bartowski/gemma-3-4b-it-GGUF/resolve/main/gemma-3-4b-it-Q4_K_M.gguf

基本用法

简单文本生成

bash

cd ~/llama.cpp

# 基本推理
./build/bin/llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "The future of edge AI is"

聊天模式（对话）

bash

# 启动交互式聊天会话
./build/bin/llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -cnv \
  --chat-template llama3

注意：-cnv 标志启用对话模式，--chat-template 指定如何格式化对话。

常用 llama-cli 参数

参数	描述	示例
`-m, --model`	模型文件路径	`-m models/model.gguf`
`-p, --prompt`	初始提示	`-p "Hello world"`
`-cnv`	对话模式	`-cnv`
`-n, --n-predict`	要生成的 token 数量	`-n 256`
`-c, --ctx-size`	上下文大小（以 token 为单位）	`-c 4096`
`--temp`	温度（创造性）	`--temp 0.7`
`--top-p`	Nucleus 采样	`--top-p 0.9`
`-ngl, --n-gpu-layers`	要卸载的 GPU 层数	`-ngl 35`
`-t, --threads`	CPU 线程数	`-t 4`

针对 Jetson GPU 优化

GPU 卸载

将模型层卸载到 GPU 可以显著提高性能：

bash

# 确定最佳 GPU 层数
# 从 -ngl 999 开始（卸载所有层）
./build/bin/llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "Explain quantum computing" \
  -ngl 35 \
  -n 256

提示：使用 -ngl 999 自动将所有可能的层卸载到 GPU。

测量性能

bash

# 运行性能统计
./build/bin/llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "What is the capital of France?" \
  -n 50 \
  -ngl 35 \
  --perf

llamacpp_test

关键指标：每 token 评估时间应低于 100ms 才能获得良好的实时性能。

高级功能

运行 API 服务器

llama.cpp 包含用于 REST API 访问的服务器模式：

bash

# 启动服务器
./llama-server \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  --host 0.0.0.0 \
  --port 8000 \
  -ngl 35 \
  -c 4096

访问服务器：

bash

# 简单查询
curl -X POST http://localhost:8000/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Once upon a time",
    "n_predict": 100
  }'

# 聊天补全
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is machine learning?"}
    ],
    "max_tokens": 256
  }'

系统提示

使用系统提示设置模型行为：

bash

./llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "You are a helpful coding assistant. Explain Python list comprehensions." \
  --system "You are an expert Python programmer. Provide concise, practical code examples."

批处理

高效处理多个提示：

python

# batch_inference.py
import subprocess
import json

prompts = [
    "Explain neural networks",
    "What is GPU acceleration?",
    "Describe edge computing"
]

model_path = "~/llama.cpp/models/Llama-3.2-3B-Instruct-Q4_K_M.gguf"

for prompt in prompts:
    result = subprocess.run(
        ["./llama-cli", "-m", model_path, "-p", prompt, "-n", "100", "--temp", "0.7"],
        capture_output=True,
        text=True
    )
    print(f"Prompt: {prompt}")
    print(f"Response: {result.stdout}\n")

将模型转换为 GGUF

如果你有 Hugging Face 格式的模型（PyTorch/SafeTensors），可以将其转换为 GGUF：

bash

cd ~/llama.cpp

# 安装 Python 依赖
pip install -r requirements.txt

# 将 Hugging Face 模型转换为 GGUF
python convert_hf_to_gguf.py \
  /path/to/model \
  --outfile output-model.gguf \
  --outtype q4_k_m

可用的输出类型：

f16：16 位浮点（无量化）
q8_0：8 位量化
q6_k：6 位量化
q5_k_m：5 位量化
q4_k_m：4 位量化（推荐平衡）
q3_k_m：3 位量化
q2_k：2 位量化（最高压缩）

集成示例

Python 绑定

bash

# 安装 Python 绑定
pip install llama-cpp-python

# 启用 CUDA 支持（Jetson）
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir

python

from llama_cpp import Llama

# 加载模型
llm = Llama(
    model_path="/path/to/model-Q4_K_M.gguf",
    n_gpu_layers=35,
    n_ctx=4096
)

# 生成文本
output = llm(
    "Q: What is the capital of France?\nA:",
    max_tokens=50,
    temperature=0.7
)
print(output["choices"][0]["text"])

# 聊天补全
output = llm.create_chat_completion(
    messages=[
        {"role": "user", "content": "Tell me a joke"}
    ],
    max_tokens=100
)
print(output["choices"][0]["message"]["content"])

性能基准测试

Jetson 特定优化

bash

# Jetson Orin Nano 8GB 的最佳设置
./llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "Explain transformers in machine learning" \
  -ngl 35 \
  -t 6 \
  -c 4096 \
  -n 200 \
  --temp 0.7

基准测试脚本

bash

#!/bin/bash
# benchmark.sh

MODEL="models/Llama-3.2-3B-Instruct-Q4_K_M.gguf"
PROMPT="Explain the concept of artificial intelligence and its applications."

echo "Benchmarking llama.cpp on Jetson"
echo "Model: $MODEL"
echo "Prompt: $PROMPT"
echo ""

for gpu_layers in 0 10 20 30 35; do
    echo "Testing with $gpu_layers GPU layers..."
    timeout 120 ./llama-cli \
        -m $MODEL \
        -p "$PROMPT" \
        -ngl $gpu_layers \
        -n 100 \
        --per-test 2>&1 | grep "eval time"
done

常见问题及解决方案

问题 1：未检测到 CUDA

问题：GPU 卸载不工作

解决方案：

bash

# 使用 CUDA 重新构建
make clean
make -j$(nproc) GGML_CUDA=1

# 验证 CUDA 安装
nvidia-smi
nvcc --version

问题 2：内存不足

问题：模型加载失败（OOM）

解决方案：

bash

# 减少 GPU 层数
./llama-cli -m model.gguf -ngl 10  # 代替 -ngl 35

# 使用更小的上下文
./llama-cli -m model.gguf -c 2048  # 代替默认的 4096

# 使用更激进的量化
# 从 Q5_K_M 切换到 Q4_K_M 或 Q3_K_M

问题 3：纯 CPU 性能慢

问题：没有 GPU 时生成太慢

解决方案：

bash

# 启用更多线程
./llama-cli -m model.gguf -t 8  # 使用 8 个 CPU 线程

# 使用更小的模型或更激进的量化

# 确保 CPU 调速器设置为性能模式
sudo apt-get install cpufrequtils
sudo cpufreq-set -g performance

实践练习

完成以下任务：

构建 llama.cpp 并启用 CUDA 支持
下载 3 个不同的模型 并比较它们的大小
对每个模型运行推理 并使用 -ngl 35
测量性能 使用 --perf 标志
启动服务器 并测试 API 请求
创建一个 Python 脚本 来批处理 5 个不同的提示

参考资料

llama.cpp GitHub
GGUF 格式规范
TheBloke 的 GGUF 模型 - 预转换模型
bartowski 的 GGUF 模型 - 更新后的模型转换
Jetson AI Lab - NVIDIA 的 Jetson 资源

下一步：继续学习模块 5.4：高吞吐量推理与 vLLM，了解生产级 LLM 服务！

PreviousOllama 快速入门

Next使用 vLLM 实现高性能推理