llama-cpp

llama.cpp -- C/C++ 大模型推理框架指南

官方文档

来源	URL
GitHub 仓库	https://github.com/ggml-org/llama.cpp
C API 头文件（llama.h）	https://github.com/ggml-org/llama.cpp/blob/master/include/llama.h
C++ RAII 封装	https://github.com/ggml-org/llama.cpp/blob/master/include/llama-cpp.h
构建说明	https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md
服务文档	https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md
量化工具	https://github.com/ggml-org/llama.cpp/blob/master/tools/quantize/README.md
GGUF 规范	https://github.com/ggml-org/llama.cpp/blob/master/docs/gguf.md
函数调用文档	https://github.com/ggml-org/llama.cpp/blob/master/docs/function-calling.md
多模态文档	https://github.com/ggml-org/llama.cpp/blob/master/docs/multimodal.md
示例目录	https://github.com/ggml-org/llama.cpp/tree/master/examples
HuggingFace GGUF Hub	https://huggingface.co/docs/hub/gguf-llamacpp
Llama-Unreal 插件	https://github.com/getnamo/Llama-Unreal

什么是 llama.cpp？

llama.cpp 是一个纯 C/C++ 大模型推理引擎，依赖极少，专为 CPU 和 GPU 上的高性能本地推理而设计。主要特性：

• 采用 MIT 许可证，开发极为活跃（几乎每日发布，目前为 b8766+）
• 硬件支持最广泛：NVIDIA（CUDA）、AMD（ROCm/Vulkan）、Apple（Metal）、Intel（SYCL/Vulkan）、Qualcomm（OpenCL）、ARM、WebGPU
• GGUF 模型格式：单文件、兼容 mmap，支持 40 多种量化类型，范围从 1.5 位到 16 位
• 内置 HTTP 服务：兼容 OpenAI API、Anthropic Messages API，支持流式传输、函数调用和多模态
• 语言绑定：Python（llama-cpp-python）、Go、Rust、C#、Node.js、Java、Swift 等

快速开始

通过服务运行模型（最快方式）

# Install
brew install llama.cpp    # macOS/Linux
winget install llama.cpp  # Windows

# Start server with a HuggingFace model
llama-server -hf bartowski/Llama-3.3-70B-Instruct-GGUF:Q4_K_M -ngl 99

# Query via curl
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"temperature":0.8}'

嵌入 C++ 项目（库用法）

#include "llama.h"

// 1. Init backends and load model
ggml_backend_load_all();
auto params = llama_model_default_params();
params.n_gpu_layers = 99;
llama_model * model = llama_model_load_from_file("model.gguf", params);

// 2. Create context
auto ctx_params = llama_context_default_params();
ctx_params.n_ctx = 4096;
llama_context * ctx = llama_init_from_model(model, ctx_params);

// 3. Tokenize, decode, sample (see C API reference for full pattern)

从源代码构建并启用 GPU

git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
cmake -B build -DGGML_CUDA=ON      # or GGML_VULKAN=ON, GGML_METAL=ON
cmake --build build --config Release -j

核心架构

llama.cpp/
  include/
    llama.h          # C API (primary interface)
    llama-cpp.h      # C++ RAII wrappers (unique_ptr aliases)
    ggml.h           # Tensor computation library
  common/
    common.h         # High-level convenience layer
  tools/
    server/          # HTTP server (llama-server)
    quantize/        # Model quantization tool
  examples/
    simple/          # Minimal inference example
    simple-chat/     # Multi-turn chat example

推理流程：

Model (GGUF file)
  -> llama_model_load_from_file()  [load + mmap weights]
  -> llama_init_from_model()       [create context with KV cache]
  -> llama_tokenize()              [text -> tokens]
  -> llama_decode()                [run transformer, fill KV cache]
  -> llama_get_logits()            [get output probabilities]
  -> llama_sampler_sample()        [select next token]
  -> llama_token_to_piece()        [token -> text]
  -> repeat decode/sample loop until EOS

量化速查表

类型	位数	质量	推荐用途
Q4_K_M	~4.5	良好	默认选择 -- 质量与体积的最佳平衡
Q5_K_M	~5.5	非常好	可接受约 20% 更多空间时
Q8_0	8	接近无损	验证、对质量要求高的任务
IQ4_XS	~4.25	4 位量化中最佳	配合 imatrix 使用，比 Q4_K_M 略小
Q3_K_M	~3.5	可接受	RAM 受限的场景
IQ2_XS	~2.3	有所降低	极限压缩（需要 imatrix）
F16	16	参考	全精度基准

# Quantize a model
llama-quantize model-f16.gguf model-q4km.gguf Q4_K_M

# Convert from HuggingFace
python convert_hf_to_gguf.py /path/to/hf_model --outfile model.gguf

GPU 后端

后端	标志	硬件
CUDA	GGML_CUDA=ON	NVIDIA GPU
Metal	macOS 上自动启用	Apple Silicon
Vulkan	GGML_VULKAN=ON	跨平台（NVIDIA/AMD/Intel）
HIP	GGML_HIP=ON	AMD GPU（ROCm）
SYCL	GGML_SYCL=ON	Intel GPU

GPU 卸载（-ngl 99）是对性能影响最大的单项设置。

服务 API

内置服务提供兼容 OpenAI 的端点：

端点	用途
POST /v1/chat/completions	聊天（支持流式传输）
POST /v1/completions	文本补全
POST /v1/embeddings	嵌入
POST /v1/messages	Anthropic Messages API
POST /completion	可完整控制参数的原生 API
GET /health	健康检查
GET /metrics	Prometheus 指标

功能：函数调用（--jinja）、语法约束（--grammar/--json-schema）、多模态（视觉+音频）、并行解码、推测解码、路由器模式、LoRA 热切换、内置 Web UI。

CMake 集成

# Method 1: Subdirectory (embedding)
add_subdirectory(vendor/llama.cpp)
target_link_libraries(myapp PRIVATE llama ggml)

# Method 2: Installed package
find_package(llama REQUIRED)
target_link_libraries(myapp PRIVATE llama)

详细参考文档

• C/C++ API 参考：请参阅 references/c-api-reference.md，了解完整的 llama.h 函数签名、类型、枚举、结构体、采样链 API 和完整的可运行示例
• 构建系统与集成：请参阅 references/build-and-integration.md，了解所有 CMake 选项、GPU 后端构建、库链接方法、Docker 和包管理器
• 服务端 REST API：请参阅 references/server-api.md，了解所有 HTTP 端点、CLI 标志、环境变量、curl 示例、函数调用、语法约束和 Python 客户端用法
• GGUF 与量化：请参阅 references/quantization-guide.md，了解 GGUF 格式规范、40 多种量化类型、imatrix 生成、模型转换、硬件要求和支持的架构
• 性能与 GPU 后端：请参阅 references/performance-and-backends.md，了解后端对比、CUDA/Vulkan/Metal 优化、内存管理、推测解码和硬件建议
• Unreal Engine 集成：请参阅 references/unreal-engine-integration.md，了解 Llama-Unreal 插件、使用 Build.cs 的自定义 C++ 集成、HTTP 服务端方案、游戏内性能和常见的 UE 易踩问题