llama-cpp

llama.cpp

纯 C/C++ 大模型推理，依赖极少，并针对 CPU 和非 NVIDIA 硬件进行了优化。

何时使用 llama.cpp

在以下情况下使用 llama.cpp：

• 在仅配备 CPU 的机器上运行
• 部署在 Apple Silicon（M1/M2/M3/M4）上
• 使用 AMD 或 Intel GPU（无 CUDA）
• 边缘部署（Raspberry Pi、嵌入式系统）
• 需要简单部署，无需 Docker/Python

在以下情况下改用 TensorRT-LLM：

• 配备 NVIDIA GPU（A100/H100）
• 需要最大吞吐量（100K+ tok/s）
• 在使用 CUDA 的数据中心中运行

在以下情况下改用 vLLM：

• 配备 NVIDIA GPU
• 需要以 Python 为先的 API
• 需要 PagedAttention

快速开始

安装

# macOS/Linux
brew install llama.cpp

# Or build from source
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make

# With Metal (Apple Silicon)
make LLAMA_METAL=1

# With CUDA (NVIDIA)
make LLAMA_CUDA=1

# With ROCm (AMD)
make LLAMA_HIP=1

下载模型

# Download from HuggingFace (GGUF format)
huggingface-cli download \
    TheBloke/Llama-2-7B-Chat-GGUF \
    llama-2-7b-chat.Q4_K_M.gguf \
    --local-dir models/

# Or convert from HuggingFace
python convert_hf_to_gguf.py models/llama-2-7b-chat/

运行推理

# Simple chat
./llama-cli \
    -m models/llama-2-7b-chat.Q4_K_M.gguf \
    -p "Explain quantum computing" \
    -n 256  # Max tokens

# Interactive chat
./llama-cli \
    -m models/llama-2-7b-chat.Q4_K_M.gguf \
    --interactive

服务模式

# Start OpenAI-compatible server
./llama-server \
    -m models/llama-2-7b-chat.Q4_K_M.gguf \
    --host 0.0.0.0 \
    --port 8080 \
    -ngl 32  # Offload 32 layers to GPU

# Client request
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-2-7b-chat",
    "messages": [{"role": "user", "content": "Hello!"}],
    "temperature": 0.7,
    "max_tokens": 100
  }'

量化格式

GGUF 格式概览

格式	位数	大小（7B）	速度	质量	使用场景
Q4_K_M	4.5	4.1 GB	快	良好	推荐默认选项
Q4_K_S	4.3	3.9 GB	更快	较低	速度至关重要
Q5_K_M	5.5	4.8 GB	中等	更好	质量至关重要
Q6_K	6.5	5.5 GB	较慢	最佳	追求最高质量
Q8_0	8.0	7.0 GB	慢	极佳	尽量减少性能损失
Q2_K	2.5	2.7 GB	最快	较差	仅用于测试

选择量化格式

# General use (balanced)
Q4_K_M  # 4-bit, medium quality

# Maximum speed (more degradation)
Q2_K or Q3_K_M

# Maximum quality (slower)
Q6_K or Q8_0

# Very large models (70B, 405B)
Q3_K_M or Q4_K_S  # Lower bits to fit in memory

硬件加速

Apple Silicon（Metal）

# Build with Metal
make LLAMA_METAL=1

# Run with GPU acceleration (automatic)
./llama-cli -m model.gguf -ngl 999  # Offload all layers

# Performance: M3 Max 40-60 tokens/sec (Llama 2-7B Q4_K_M)

NVIDIA GPU（CUDA）

# Build with CUDA
make LLAMA_CUDA=1

# Offload layers to GPU
./llama-cli -m model.gguf -ngl 35  # Offload 35/40 layers

# Hybrid CPU+GPU for large models
./llama-cli -m llama-70b.Q4_K_M.gguf -ngl 20  # GPU: 20 layers, CPU: rest

AMD GPU（ROCm）

# Build with ROCm
make LLAMA_HIP=1

# Run with AMD GPU
./llama-cli -m model.gguf -ngl 999

常见模式

批处理

# Process multiple prompts from file
cat prompts.txt | ./llama-cli \
    -m model.gguf \
    --batch-size 512 \
    -n 100

受约束生成

# JSON output with grammar
./llama-cli \
    -m model.gguf \
    -p "Generate a person: " \
    --grammar-file grammars/json.gbnf

# Outputs valid JSON only

上下文长度

# Increase context (default 512)
./llama-cli \
    -m model.gguf \
    -c 4096  # 4K context window

# Very long context (if model supports)
./llama-cli -m model.gguf -c 32768  # 32K context

性能基准测试

CPU 性能（Llama 2-7B Q4_K_M）

CPU	线程数	速度	成本
Apple M3 Max	16	50 tok/s	$0（本地）
AMD Ryzen 9 7950X	32	35 tok/s	$0.50/小时
Intel i9-13900K	32	30 tok/s	$0.40/小时
AWS c7i.16xlarge	64	40 tok/s	$2.88/小时

GPU 加速（Llama 2-7B Q4_K_M）

GPU	速度	相比 CPU	成本
NVIDIA RTX 4090	120 tok/s	3-4×	$0（本地）
NVIDIA A10	80 tok/s	2-3×	$1.00/小时
AMD MI250	70 tok/s	2×	$2.00/小时
Apple M3 Max（Metal）	50 tok/s	~相同	$0（本地）

支持的模型

LLaMA 系列：

• Llama 2（7B、13B、70B）
• Llama 3（8B、70B、405B）
• Code Llama

Mistral 系列：

• Mistral 7B
• Mixtral 8x7B、8x22B

其他：

• Falcon、BLOOM、GPT-J
• Phi-3、Gemma、Qwen
• LLaVA（视觉）、Whisper（音频）

查找模型：https://huggingface.co/models?library=gguf

参考资料

• 量化指南 - GGUF 格式、转换、质量比较
• 服务部署 - API 端点、Docker、监控
• 优化 - 性能调优、CPU+GPU 混合方案

资源

• GitHub：https://github.com/ggerganov/llama.cpp
• 模型：https://huggingface.co/models?library=gguf
• Discord：https://discord.gg/llama-cpp

Agent 操作流程

1. 检查环境。 确认硬件、框架和服务版本、模型格式以及预期负载。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会影响结果的值都应询问，而非猜测。
3. 先运行小规模版本。 扩大规模前，先服务或记录单个请求，或端到端运行一次。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 对照参考结果测量延迟、吞吐量和输出正确性；检查资源使用情况和成本。
6. 汇报。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些事项仍不确定。

如果发生这种情况	请执行以下操作
服务无法启动或发生 OOM	检查模型大小与内存是否匹配，以及量化和并行设置。
已安装版本中缺少这些说明里的函数、标志或端点	查看已安装版本自己的文档（help()、--help、官方文档），进行调整，并告知用户。切勿捏造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，应如实说明。
• 不要公开暴露服务或凭据；配置云资源前确认相关成本。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须事先征求同意。

相关技能

• gguf-quantization：GGUF 格式和 llama.cpp 量化，用于高效 CPU/GPU 推理。
• tensorrt-llm：使用 NVIDIA TensorRT 优化 LLM 推理，以实现最高吞吐量和最低延迟。
• gptq：通过 AutoGPTQ 和 transformers，使用分组量化（默认组大小为 128）将 LLM 量化为 4 位（也支持 3 位）。