（二十）32天GPU测试从入门到精通-llama.cpp CPU/GPU 混合推理day18

目录

1. 引言
2. llama.cpp 介绍与安装
3. GGUF 格式与量化
4. CPU 推理性能
5. GPU 加速配置
6. 混合推理优化
7. 生产部署
8. 常见问题排查

---

引言

llama.cpp 是最流行的 CPU 推理引擎，让大语言模型在无 GPU 设备上运行成为可能，是边缘部署、隐私保护、成本敏感场景的首选方案。2023 年初，当整个行业都在追求更大模型、更多 GPU 时，llama.cpp 的作者反其道而行之：如何让 7B 模型在普通笔记本上流畅运行？通过精心优化的量化技术和 CPU 指令集利用，llama.cpp 做到了这一点，并迅速成为 GitHub 上最热门的 AI 项目之一。

掌握 llama.cpp 是 LLM 普惠部署的关键。无论你是在笔记本上运行个人助手，还是在企业内网部署隐私敏感应用，llama.cpp 都提供了可行的方案。它的零依赖特性使得部署变得异常简单，跨平台支持让你可以在任何设备上运行。

• llama.cpp 为什么如此流行？ 纯 C++ 实现，无依赖，跨平台
• GGUF 格式有什么优势？ 高效量化，内存映射
• CPU 推理性能如何？ 20-50 tokens/s (单线程)
• 如何启用 GPU 加速？ CUDA/Metal/Vulkan 支持
• 适合哪些场景？ 边缘、本地、离线、隐私敏感

这些问题都指向一个核心主题：llama.cpp CPU/GPU 混合推理。

llama.cpp 的核心优势

┌─────────────────────────────────────────────────┐
│          llama.cpp 核心优势                      │
├─────────────────────────────────────────────────┤
│                                                 │
│  零门槛部署:                                    │
│  ├── 纯 C++ 实现：无 Python 依赖                  │
│  ├── 单文件：编译即可运行                      │
│  ├── 跨平台：Linux/macOS/Windows               │
│  └── 无 GPU：CPU 即可运行                       │
│                                                 │
│  量化领先:                                      │
│  ├── GGUF 格式：专为量化设计                   │
│  ├── 多种精度：INT4/INT5/INT8/FP16/FP32       │
│  ├── 精度损失小：INT4 仅~1-2% 损失               │
│  └── 显存需求低：7B INT4 仅需 4GB                │
│                                                 │
│  性能优秀:                                      │
│  ├── CPU 推理：20-50 tokens/s (单线程)         │
│  ├── GPU 加速：50-150 tokens/s (入门 GPU)      │
│  ├── 混合推理：CPU+GPU 协同                     │
│  └── 内存映射：大模型低内存运行                │
│                                                 │
│  生态丰富:                                      │
│  ├── 模型支持：50+ 模型架构                     │
│  ├── 工具链：转换/量化/推理工具                │
│  ├── 社区活跃：GitHub 20k+ stars               │
│  └── 应用广泛：本地聊天/边缘设备/隐私场景      │
│                                                 │
└─────────────────────────────────────────────────┘

适用场景

┌─────────────────────────────────────────────────┐
│          llama.cpp 适用场景                      │
├─────────────────────────────────────────────────┤
│                                                 │
│  边缘设备:                                      │
│  ├── 笔记本：本地运行，无网络依赖              │
│  ├── 手机：Android/iOS 支持                     │
│  ├── 嵌入式：树莓派/Jetson Nano                │
│  └── 示例：个人助手、离线翻译                  │
│                                                 │
│  隐私敏感:                                      │
│  ├── 数据不出域：本地处理                      │
│  ├── 无 API 调用：完全离线                      │
│  ├── 企业内网：私有化部署                      │
│  └── 示例：医疗/法律/金融文档处理              │
│                                                 │
│  成本敏感:                                      │
│  ├── 无 GPU 成本：利用现有 CPU                  │
│  ├── 低功耗：适合长期运行                      │
│  ├── 小规模：个人/小团队使用                   │
│  └── 示例：个人项目、初创公司 MVP              │
│                                                 │
│  离线场景:                                      │
│  ├── 无网络环境：船舶/飞机/偏远地区            │
│  ├── 网络受限：安全隔离环境                    │
│  ├── 移动场景：车载/野外作业                   │
│  └── 示例：离线知识库、应急通信                │
│                                                 │
│  开发测试:                                      │
│  ├── 快速原型：无需 GPU 环境                    │
│  ├── 模型测试：量化效果验证                    │
│  ├── 教学演示：低门槛展示                      │
│  └── 示例：课程实验、技术验证                  │
│                                                 │
└─────────────────────────────────────────────────┘

---

llama.cpp 介绍与安装

llama.cpp 的安装非常简单，只需克隆仓库并编译即可。它支持多种后端：纯 CPU、CUDA（NVIDIA GPU）、Metal（macOS）、以及 Vulkan（跨平台 GPU）。根据你的硬件配置，选择合适的后端进行编译。

基础安装

安装脚本展示了完整的编译流程。首先克隆 llama.cpp 仓库，然后根据硬件编译相应的版本。CPU 版本使用 make 命令直接编译。如果有 NVIDIA GPU，使用 LLAMA_CUDA=1 编译 CUDA 版本。如果是 macOS，使用 LLAMA_METAL=1 编译 Metal 版本。

Docker 部署提供了更简单的方案。llama.cpp 官方提供了预构建的 Docker 镜像，支持 CPU、CUDA、Metal 三种后端。只需指定模型和配置参数，即可快速启动服务。

Python 绑定使得在 Python 中使用 llama.cpp 变得简单。通过 llama-cpp-python 包，你可以用 Python API 加载模型、进行推理，而无需直接调用命令行工具。

echo "=========================================="
echo "  llama.cpp 安装"
echo "=========================================="

# 1. 克隆仓库
echo ""
echo "[1/5] 克隆仓库..."
git clone https://github.com/ggerganov/llama.cpp.git /opt/llama.cpp
cd /opt/llama.cpp

# 2. 编译 (CPU 版本)
echo ""
echo "[2/5] 编译 CPU 版本..."
make clean
make -j$(nproc)

# 3. 编译 CUDA 版本 (如有 NVIDIA GPU)
if nvidia-smi &>/dev/null; then
    echo ""
    echo "[3/5] 编译 CUDA 版本..."
    make clean
    LLAMA_CUDA=1 make -j$(nproc)
fi

# 4. 编译 Metal 版本 (macOS)
if [[ "$OSTYPE" == "darwin"* ]]; then
    echo ""
    echo "[4/5] 编译 Metal 版本..."
    make clean
    LLAMA_METAL=1 make -j$(nproc)
fi

# 5. 验证安装
echo ""
echo "[5/5] 验证安装..."
./main --version
./main --help | head -20

echo ""
echo "=========================================="
echo "  llama.cpp 安装完成"
echo "=========================================="
echo ""
echo "安装目录：/opt/llama.cpp"
echo "主程序：./main"
echo "服务端：./server"
echo "工具：./quantize, ./convert, ..."

Docker 部署

#!/bin/bash
# run_llama_cpp_docker.sh - Docker 部署 llama.cpp

echo "=========================================="
echo "  llama.cpp Docker 部署"
echo "=========================================="

# 配置
MODEL=${MODEL:-"qwen2.5-7b-instruct-q4_k_m.gguf"}
GPU=${GPU:-"cuda"}  # cuda/metal/cpu
PORT=${PORT:-8080}

echo ""
echo "部署配置:"
echo "  模型：$MODEL"
echo "  GPU 加速：$GPU"
echo "  端口：$PORT"
echo ""

# 拉取镜像
docker pull ghcr.io/ggerganov/llama.cpp:server

# 运行容器
if [ "$GPU" == "cuda" ]; then
    docker run --runtime nvidia --gpus all \
        -v ~/.cache/llama.cpp:/models \
        -p $PORT:8080 \
        --name llama-cpp-server \
        ghcr.io/ggerganov/llama.cpp:server \
        --model /models/$MODEL \
        --n-gpu-layers 35 \
        --ctx-size 4096 \
        --batch-size 512
elif [ "$GPU" == "metal" ]; then
    docker run \
        -v ~/.cache/llama.cpp:/models \
        -p $PORT:8080 \
        --name llama-cpp-server \
        ghcr.io/ggerganov/llama.cpp:server-metal \
        --model /models/$MODEL \
        --n-gpu-layers 35
else
    docker run \
        -v ~/.cache/llama.cpp:/models \
        -p $PORT:8080 \
        --name llama-cpp-server \
        ghcr.io/ggerganov/llama.cpp:server \
        --model /models/$MODEL \
        --ctx-size 4096
fi

echo ""
echo "=========================================="
echo "  llama.cpp 服务已启动"
echo "=========================================="
echo ""
echo "API 端点：http://localhost:$PORT"
echo "健康检查：curl http://localhost:$PORT/health"

Python 绑定

#!/bin/bash
# install_llama_cpp_python.sh - 安装 Python 绑定

echo "=========================================="
echo "  llama.cpp Python 绑定安装"
echo "=========================================="

# 创建虚拟环境
python3 -m venv /opt/llama-cpp-env
source /opt/llama-cpp-env/bin/activate

# 安装 llama-cpp-python
echo ""
echo "安装 llama-cpp-python..."
CMAKE_ARGS="-DLLAMA_CUDA=on" pip install llama-cpp-python

# 安装依赖
pip install numpy torch

# 验证安装
python3 -c "
from llama_cpp import Llama
print(f'llama-cpp-python 已安装')
print(f'支持后端：CPU + CUDA')
"

echo ""
echo "=========================================="
echo "  Python 绑定安装完成"
echo "=========================================="

---

GGUF 格式与量化

GGUF 是 llama.cpp 专为量化模型设计的二进制格式，是 llama.cpp 能够在 CPU 上高效运行的关键。理解 GGUF 格式和量化技术，对于选择合适的模型配置至关重要。

GGUF 格式介绍

GGUF（GGML Unified Format）是 ggerganov 开发的统一模型格式，专为量化模型设计。它替代了旧的 GGML 格式，支持元数据、多模型架构、以及内存映射优化。

文件结构包括：文件头（魔法数、版本、张量数量）、元数据（模型信息、词汇表、配置）、张量数据（量化权重）、以及对齐（内存映射优化）。这种结构使得 GGUF 模型可以快速加载，无需反序列化，支持大模型在低内存设备上运行。

量化类型对比显示了不同量化等级的权衡。Q2_K 最小（2.8GB），但精度损失较大（5-8%）。Q4_K_M 是推荐的平衡选择（4.4GB，精度损失 1-2%）。Q5_K_M 提供更高精度（5.2GB，精度损失 0.5-1%）。Q8_0 接近 FP16 精度（7.5GB，精度损失 0.1-0.5%）。FP16 无精度损失，但需要 14GB。

模型量化可以使用 llama.cpp 的 quantize 工具完成。指定输入模型、输出模型、以及量化类型，工具会自动执行量化。量化后的大小和压缩比可以通过脚本计算。

下载预量化模型是更简单的选择。HuggingFace 上有许多预量化的 GGUF 模型，使用 huggingface-cli 可以直接下载，无需自己量化。

├─────────────────────────────────────────────────┤
│                                                 │
│  什么是 GGUF:                                   │
│  ├── GGML Unified Format (ggerganov)           │
│  ├── 专为量化模型设计的二进制格式              │
│  ├── 替代旧的 GGML 格式                         │
│  └── 支持元数据、多模型架构                    │
│                                                 │
│  文件结构:                                      │
│  ├── 文件头：魔法数、版本、张量数量            │
│  ├── 元数据：模型信息、词汇表、配置            │
│  ├── 张量数据：量化权重                        │
│  └── 对齐：内存映射优化                        │
│                                                 │
│  优势:                                          │
│  ├── 高效量化：多种精度支持                    │
│  ├── 内存映射：大模型低内存运行                │
│  ├── 快速加载：无需反序列化                    │
│  └── 跨平台：统一格式                          │
│                                                 │
└─────────────────────────────────────────────────┘

量化类型对比

┌────────────────────────────────────────────────────────────────────┐
│                    GGUF 量化类型对比                                │
├──────────────┬─────────────┬─────────────┬─────────────┬──────────┤
│   量化类型    │   7B 大小     │   精度损失   │   CPU 速度   │   推荐场景 │
│              │   (GB)      │   (%)       │   (tok/s)   │          │
├──────────────┼─────────────┼─────────────┼─────────────┼──────────┤
│   Q2_K       │   2.8       │   5-8%      │   40-50     │   极低内存 │
│   Q3_K_S     │   3.2       │   3-5%      │   35-45     │   资源受限 │
│   Q3_K_M     │   3.5       │   2-4%      │   30-40     │   平衡     │
│   Q4_0       │   3.8       │   2-3%      │   35-45     │   速度优先 │
│   Q4_K_M     │   4.4       │   1-2%      │   30-40     │   推荐     │
│   Q5_0       │   4.7       │   1-1.5%    │   25-35     │   精度优先 │
│   Q5_K_M     │   5.2       │   0.5-1%    │   25-35     │   推荐     │
│   Q6_K       │   6.0       │   0.5%      │   20-30     │   高精度   │
│   Q8_0       │   7.5       │   0.1-0.5%  │   18-25     │   接近 FP16│
│   FP16       │   14.0      │   0%        │   15-20     │   最高精度 │
└──────────────┴─────────────┴─────────────┴─────────────┴──────────┘

推荐：Q4_K_M (平衡) 或 Q5_K_M (精度)

模型量化

#!/bin/bash
# quantize_model.sh - 模型量化脚本

echo "=========================================="
echo "  GGUF 模型量化"
echo "=========================================="

# 配置
INPUT_MODEL=${1:-"llama-2-7b-fp16.gguf"}
OUTPUT_MODEL=${2:-"llama-2-7b-q4_k_m.gguf"}
QUANT_TYPE=${3:-"Q4_K_M"}

echo ""
echo "量化配置:"
echo "  输入：$INPUT_MODEL"
echo "  输出：$OUTPUT_MODEL"
echo "  类型：$QUANT_TYPE"
echo ""

# 执行量化
cd /opt/llama.cpp
./quantize $INPUT_MODEL $OUTPUT_MODEL $QUANT_TYPE

echo ""
echo "=========================================="
echo "  量化完成"
echo "=========================================="
echo ""
echo "原大小：$(ls -lh $INPUT_MODEL | awk '{print $5}')"
echo "量化后：$(ls -lh $OUTPUT_MODEL | awk '{print $5}')"
echo "压缩比：$(python3 -c "
import os
orig = os.path.getsize('$INPUT_MODEL')
quant = os.path.getsize('$OUTPUT_MODEL')
print(f'{(1-quant/orig)*100:.1f}%')
")"

下载预量化模型

#!/bin/bash
# download_gguf_model.sh - 下载预量化 GGUF 模型

echo "=========================================="
echo "  下载 GGUF 模型"
echo "=========================================="

# 配置
MODEL_REPO=${1:-"Qwen/Qwen2.5-7B-Instruct-GGUF"}
QUANTIZATION=${2:-"q4_k_m"}

echo ""
echo "下载配置:"
echo "  仓库：$MODEL_REPO"
echo "  量化：$QUANTIZATION"
echo ""

# 使用 huggingface-cli 下载
huggingface-cli download $MODEL_REPO \
    --include "*${QUANTIZATION}*.gguf" \
    --local-dir ~/.cache/llama.cpp/models

echo ""
echo "=========================================="
echo "  下载完成"
echo "=========================================="
echo ""
echo "模型位置：~/.cache/llama.cpp/models/"
ls -lh ~/.cache/llama.cpp/models/*.gguf

---

CPU 推理性能

llama.cpp 的核心价值在于让 CPU 推理变得实用。虽然 CPU 推理速度无法与 GPU 相比，但对于个人使用、离线场景、隐私敏感应用来说，已经足够好用。

基准测试

CPU 推理基准测试脚本使用 llama-cpp-python 包加载模型并进行推理测试。通过测量不同提示的推理时间和生成 token 数，可以计算出平均推理速度（tokens/s）。

性能参考表显示了不同 CPU 的预期性能。高端 CPU 如 M3 Max 可以达到 45-55 tokens/s（8 线程），i9-13900K 达到 35-45 tokens/s。中端 CPU 如 i7-12700K 达到 25-35 tokens/s。入门 CPU 如 i5-11400 达到 15-20 tokens/s。即使是树莓派 4B 这样的嵌入式设备，也能达到 2-3 tokens/s，虽然慢但可以用。

这些性能数据表明，对于阅读速度（约 3-5 tokens/s）来说，CPU 推理已经完全够用。这使得在笔记本、台式机、甚至嵌入式设备上运行 LLM 成为可能。

from llama_cpp import Llama
import time
import statistics

def benchmark_cpu_inference(model_path: str):
    """CPU 推理基准测试"""
    
    print("="*60)
    print("llama.cpp CPU 推理性能测试")
    print("="*60)
    
    # 加载模型
    print(f"\n加载模型：{model_path}")
    llm = Llama(
        model_path=model_path,
        n_ctx=2048,
        n_threads=8,
        n_batch=512,
        verbose=False
    )
    
    # 测试提示
    prompts = [
        "请介绍一下人工智能。",
        "什么是机器学习？",
        "深度学习有哪些应用？",
    ]
    
    results = []
    
    print(f"\n{'Prompt':<30} {'Tokens':<10} {'Time (s)':<12} {'Tokens/s':<12}")
    print("-"*60)
    
    for prompt in prompts:
        start = time.perf_counter()
        output = llm(prompt, max_tokens=100, temperature=0.7)
        elapsed = time.perf_counter() - start
        
        tokens = len(output['choices'][0]['text'].split())
        tokens_per_sec = tokens / elapsed
        
        results.append({
            'prompt': prompt[:20],
            'tokens': tokens,
            'time': elapsed,
            'tokens_per_sec': tokens_per_sec
        })
        
        print(f"{prompt[:30]:<30} {tokens:<10} {elapsed:<12.2f} {tokens_per_sec:<12.1f}")
    
    # 统计
    avg_tps = statistics.mean([r['tokens_per_sec'] for r in results])
    print("-"*60)
    print(f"平均速度：{avg_tps:.1f} tokens/s")
    
    return results

if __name__ == "__main__":
    import sys
    model_path = sys.argv[1] if len(sys.argv) > 1 else "~/.cache/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf"
    benchmark_cpu_inference(model_path)

性能参考值

┌────────────────────────────────────────────────────────────────────┐
│                llama.cpp CPU 推理性能参考                            │
├──────────────┬─────────────┬─────────────┬─────────────┬──────────┤
│   CPU 型号     │   单线程    │   8 线程     │   16 线程    │   内存    │
│              │   (tok/s)   │   (tok/s)   │   (tok/s)   │   (GB)    │
├──────────────┼─────────────┼─────────────┼─────────────┼──────────┤
│ M3 Max       │   18-22     │   45-55     │   60-70     │   16      │
│ M2 Ultra     │   15-18     │   40-50     │   55-65     │   32      │
│ i9-13900K    │   12-15     │   35-45     │   50-60     │   32      │
│ Ryzen 9 7950X│   10-13     │   30-40     │   45-55     │   32      │
│ i7-12700K    │   10-12     │   25-35     │   40-50     │   16      │
│ Ryzen 7 5800X│   8-10      │   20-28     │   30-40     │   16      │
│ i5-11400     │   6-8       │   15-20     │   22-28     │   16      │
│ 树莓派 4B     │   2-3       │   2-3       │   2-3       │   8       │
└──────────────┴─────────────┴─────────────┴─────────────┴──────────┘

注：测试条件 Q4_K_M 量化，7B 模型，实际性能受配置影响

---

GPU 加速配置

虽然 llama.cpp 主打 CPU 推理，但它也支持 GPU 加速。通过卸载部分计算到 GPU，可以显著提升推理速度。llama.cpp 支持三种 GPU 后端：CUDA（NVIDIA）、Metal（macOS）、以及 Vulkan（跨平台）。

CUDA 加速

CUDA 加速配置脚本展示了如何编译和使用 CUDA 版本。首先检查 CUDA 和 GPU 状态，然后使用 LLAMA_CUDA=1 重新编译，最后测试 GPU 加速效果。

GPU 层数配置（-ngl 参数）决定了多少层模型卸载到 GPU。-ngl 0 是纯 CPU，显存占用 0GB，速度 20-40 tok/s。-ngl 10 是部分 GPU，显存占用约 2GB，速度 40-60 tok/s。-ngl 35 是大部分 GPU，显存占用约 4GB，速度 60-100 tok/s。-ngl 99 是全 GPU，显存占用 6-8GB，速度 80-150 tok/s。

Metal 加速（macOS）配置类似，使用 LLAMA_METAL=1 编译，可以在 Mac 上获得更好的性能。M 系列芯片的 Mac 通过 Metal 加速，推理速度可以接近入门级 NVIDIA GPU。

echo "=========================================="
echo "  llama.cpp CUDA 加速配置"
echo "=========================================="

# 检查 CUDA
echo ""
echo "[1/3] CUDA 检查..."
nvcc --version
nvidia-smi

# 编译 CUDA 版本
echo ""
echo "[2/3] 重新编译 CUDA 版本..."
cd /opt/llama.cpp
make clean
LLAMA_CUDA=1 make -j$(nproc)

# 测试 GPU 加速
echo ""
echo "[3/3] 测试 GPU 加速..."
./main -m ~/.cache/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \
    -p "Hello" -n 100 \
    -ngl 35 \
    -t 8

echo ""
echo "=========================================="
echo "  CUDA 加速配置完成"
echo "=========================================="

GPU 层数配置

┌─────────────────────────────────────────────────┐
│          GPU 层数配置指南                        │
├─────────────────────────────────────────────────┤
│                                                 │
│  -ngl 0 (纯 CPU):                               │
│  ├── 显存占用：0GB                             │
│  ├── 速度：20-40 tok/s (8 核 CPU)                │
│  └── 适用：无 GPU 场景                           │
│                                                 │
│  -ngl 10 (部分 GPU):                            │
│  ├── 显存占用：~2GB                            │
│  ├── 速度：40-60 tok/s                         │
│  └── 适用：小显存 GPU (4GB)                     │
│                                                 │
│  -ngl 35 (大部分 GPU):                          │
│  ├── 显存占用：~4GB                            │
│  ├── 速度：60-100 tok/s                        │
│  └── 适用：中等显存 GPU (8GB)                   │
│                                                 │
│  -ngl 99 (全 GPU):                              │
│  ├── 显存占用：~6-8GB                          │
│  ├── 速度：80-150 tok/s                        │
│  └── 适用：大显存 GPU (12GB+)                   │
│                                                 │
└─────────────────────────────────────────────────┘

Metal 加速 (macOS)

#!/bin/bash
# llama_cpp_metal_config.sh - Metal 加速配置 (macOS)

echo "=========================================="
echo "  llama.cpp Metal 加速配置 (macOS)"
echo "=========================================="

# 编译 Metal 版本
echo ""
echo "[1/2] 编译 Metal 版本..."
cd /opt/llama.cpp
make clean
LLAMA_METAL=1 make -j$(nproc)

# 测试
echo ""
echo "[2/2] 测试 Metal 加速..."
./main -m ~/.cache/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf \
    -p "Hello" -n 100 \
    -ngl 35

echo ""
echo "=========================================="
echo "  Metal 加速配置完成"
echo "=========================================="

---

混合推理优化

llama.cpp 的混合推理能力使得 CPU 和 GPU 可以协同工作，根据硬件条件灵活配置。通过调整 GPU 层数，你可以在显存占用和推理速度之间找到最佳平衡点。

CPU+GPU 协同

混合推理测试脚本对比了纯 CPU、CPU+GPU 混合、以及全 GPU 三种配置的性能。通过实际测试，你可以找到最适合你硬件的配置。

内存优化技巧包括：内存映射（mmap）使得大模型可以在低内存设备上运行，70B 模型甚至可以在 16GB 内存的笔记本上运行。上下文优化通过调整 n_ctx 参数平衡内存占用和长文本处理能力。批处理优化通过调整 n_batch 参数平衡吞吐量和内存占用。线程优化通过调整 n_threads 参数平衡速度和 CPU 占用。

from llama_cpp import Llama

def setup_hybrid_inference(model_path: str, n_gpu_layers: int = 35):
    """设置混合推理"""
    
    llm = Llama(
        model_path=model_path,
        n_ctx=4096,
        n_threads=8,          # CPU 线程数
        n_batch=512,          # 批处理大小
        n_gpu_layers=n_gpu_layers,  # GPU 层数
        verbose=True
    )
    
    return llm

def benchmark_hybrid(model_path: str):
    """混合推理性能测试"""
    
    print("="*60)
    print("llama.cpp CPU+GPU 混合推理测试")
    print("="*60)
    
    # 纯 CPU
    print("\n[1/3] 纯 CPU 测试...")
    llm_cpu = Llama(model_path=model_path, n_gpu_layers=0, n_threads=8)
    output = llm_cpu("请介绍一下人工智能。", max_tokens=100)
    print(f"  纯 CPU: 完成")
    
    # 部分 GPU
    print("\n[2/3] CPU+GPU 混合测试...")
    llm_hybrid = Llama(model_path=model_path, n_gpu_layers=35, n_threads=8)
    output = llm_hybrid("请介绍一下人工智能。", max_tokens=100)
    print(f"  混合：完成")
    
    # 全 GPU
    print("\n[3/3] 全 GPU 测试...")
    llm_gpu = Llama(model_path=model_path, n_gpu_layers=99, n_threads=8)
    output = llm_gpu("请介绍一下人工智能。", max_tokens=100)
    print(f"  全 GPU: 完成")
    
    print("\n" + "="*60)
    print("推荐配置：n_gpu_layers=35 (平衡显存和速度)")

if __name__ == "__main__":
    import sys
    model_path = sys.argv[1] if len(sys.argv) > 1 else "~/.cache/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf"
    benchmark_hybrid(model_path)

内存优化

┌─────────────────────────────────────────────────┐
│          内存优化技巧                            │
├─────────────────────────────────────────────────┤
│                                                 │
│  内存映射 (mmap):                               │
│  ├── 优势：大模型低内存运行                    │
│  ├── 配置：--mmap (默认启用)                   │
│  └── 效果：70B 模型可在 16GB 内存运行            │
│                                                 │
│  上下文优化:                                    │
│  ├── 减小 n_ctx: 降低内存占用                   │
│  ├── 默认：2048-4096                           │
│  └── 长文本：8192-16384 (需要更多内存)         │
│                                                 │
│  批处理优化:                                    │
│  ├── n_batch: 512-2048                         │
│  ├── 调高：吞吐量提升                          │
│  └── 调低：内存占用减少                        │
│                                                 │
│  线程优化:                                      │
│  ├── n_threads: CPU 核心数                      │
│  ├── 调高：速度提升 (有上限)                   │
│  └── 调低：降低 CPU 占用                         │
│                                                 │
└─────────────────────────────────────────────────┘

---

生产部署

llama.cpp 提供了简单的 API 服务部署方案，支持命令行启动和 Docker Compose 部署。这使得 llama.cpp 可以快速集成到生产环境中。

API 服务部署

服务启动脚本展示了如何启动 llama.cpp API 服务。配置包括模型路径、主机地址、端口、GPU 层数、上下文大小、批处理大小、以及线程数。启动后，服务提供 OpenAI API 兼容接口。

Docker Compose 部署提供了更好的隔离性和可重复性。配置包括 llama.cpp 服务器、GPU 资源配置、端口映射、模型缓存卷、以及健康检查。

echo "=========================================="
echo "  启动 llama.cpp API 服务"
echo "=========================================="

# 配置
MODEL=${MODEL:-"~/.cache/llama.cpp/models/qwen2.5-7b-instruct-q4_k_m.gguf"}
HOST=${HOST:-"0.0.0.0"}
PORT=${PORT:-8080}
N_GPU_LAYERS=${N_GPU_LAYERS:-35}
CTX_SIZE=${CTX_SIZE:-4096}

echo ""
echo "启动配置:"
echo "  模型：$MODEL"
echo "  主机：$HOST:$PORT"
echo "  GPU 层数：$N_GPU_LAYERS"
echo "  上下文：$CTX_SIZE"
echo ""

# 启动服务
cd /opt/llama.cpp
./server \
    -m $MODEL \
    --host $HOST \
    --port $PORT \
    -ngl $N_GPU_LAYERS \
    -c $CTX_SIZE \
    --batch-size 512 \
    --threads 8 \
    --parallel 4

echo ""
echo "=========================================="
echo "  llama.cpp 服务已启动"
echo "=========================================="

Docker Compose 部署

# docker-compose.llama-cpp.yaml

version: '3.8'

services:
  llama-cpp-server:
    image: ghcr.io/ggerganov/llama.cpp:server
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    ports:
      - "8080:8080"
    volumes:
      - ~/.cache/llama.cpp:/models
    command: >
      --model /models/qwen2.5-7b-instruct-q4_k_m.gguf
      --n-gpu-layers 35
      --ctx-size 4096
      --batch-size 512
      --threads 8
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

---

常见问题排查

在使用 llama.cpp 过程中，可能会遇到加载失败、性能低下、显存不足等问题。下面的排查指南可以帮助你快速定位和解决问题。

加载失败

模型加载失败可能由以下原因引起：模型文件不存在或损坏，检查模型文件路径和大小；内存不足，使用 free -h 检查可用内存；上下文太大，减小--ctx-size 参数；量化等级太高，尝试更小的量化（Q4_K_M → Q3_K_M → Q2_K）；GGUF 版本不兼容，检查 llama.cpp 版本是否支持该 GGUF 格式。

性能低下

推理速度慢可能由以下原因引起：GPU 加速未启用，检查 nvidia-smi 确认 GPU 可用；GPU 层数太低，增加-ngl 参数；线程数不足，增加--threads 参数；批处理太小，增加--batch-size 参数；量化等级太低，使用更快的量化（Q5_K_M → Q4_K_M → Q4_0）。

显存不足

CUDA out of memory 可能由以下原因引起：GPU 层数太高，减少-ngl 参数；上下文太大，减小--ctx-size 参数；批处理太大，减小--batch-size 参数；量化等级太高，使用更小的量化；切换到纯 CPU，设置-ngl 0。

# 2. 检查内存
free -h

# 3. 减小上下文
--ctx-size 1024

# 4. 使用更小量化
# Q4_K_M → Q3_K_M → Q2_K

# 5. 检查 GGUF 版本
./main -m model.gguf --version

性能低下

# 问题：推理速度慢

# 1. 检查 GPU 加速
nvidia-smi

# 2. 增加 GPU 层数
-ngl 99

# 3. 增加线程
--threads 16

# 4. 增加批处理
--batch-size 1024

# 5. 使用更快量化
# Q5_K_M → Q4_K_M → Q4_0

显存不足

# 问题：CUDA out of memory

# 1. 减少 GPU 层数
-ngl 20

# 2. 减小上下文
--ctx-size 2048

# 3. 减小批处理
--batch-size 256

# 4. 使用更大量化
# Q4_K_M → Q3_K_M → Q2_K

# 5. 切换到纯 CPU
-ngl 0

---

总结

今天学到的内容

1. ✅ llama.cpp 介绍与安装：编译、Docker、Python 绑定
2. ✅ GGUF 格式与量化：格式详解、量化对比、模型下载
3. ✅ CPU 推理性能：基准测试、性能参考
4. ✅ GPU 加速配置：CUDA、Metal、层数配置
5. ✅ 混合推理优化：CPU+GPU 协同、内存优化
6. ✅ 生产部署：API 服务、Docker Compose
7. ✅ 问题排查：加载、性能、显存问题

下一步

明天我们将学习 Day 19 - LLaMA 系列模型测试，深入了解：

• LLaMA 2/3 模型介绍
• 不同参数量模型性能对比
• 推理引擎适配情况
• 实战部署案例