llama.cpp 速查表
llama.cpp 是一个高性能的 C/C++ 本地 LLM 推理引擎，支持 GGUF 格式模型。它提供 `llama-cli`（命令行推理）和 `llama-server`（HTTP 服务器，兼容 OpenAI API）两种使用方式，支持 CPU/GPU/Metal 推理和模型量化。
快速开始
``bash
# 下载 GGUF 模型
huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF --include 'Q4_K_M/*' --local-dir ./models
# 命令行推理 llama-cli -m ./models/Llama-3.2-3B-Instruct-Q4_K_M.gguf -p "你好，最近怎么样？"
# HTTP 服务模式（兼容 OpenAI API） llama-server -m ./models/Llama-3.2-3B-Instruct-Q4_K_M.gguf --port 8080
# 通过 API 调用（另一个终端）
curl -s http://localhost:8080/v1/chat/completions \
-d '{"model":"model","messages":[{"role":"user","content":"你好"}]}'
`
CLI 推理（llama-cli）
llama-cli 用于终端直接推理。核心参数：-m（模型文件）、-p（提示词）、-n（最大 token 数）、--temp（温度）、-ngl（GPU 层数）、-t（线程数）。加 --no-display-prompt 只输出生成文本。
HTTP 服务器（llama-server）
llama-server 提供 OpenAI 兼容 API。支持聊天补全（/v1/chat/completions）、文本补全（/v1/completions）、嵌入向量（/v1/embeddings）、分词、模型管理等端点。
模型量化
llama-quantize 在不同 GGUF 量化等级间转换。典型用法：llama-quantize input.gguf output.gguf Q4_K_M。常用类型：Q4_0（最快）、Q4_K_M（推荐平衡）、Q5_K_M（更高质量）、Q8_0（近乎无损）。
嵌入向量
llama.cpp 支持 RAG 流水线的文本嵌入。服务器模式加 --embeddings 启用嵌入端点，或用 llama-embedding 命令行工具单独生成。
GPU 加速
用 -ngl N 控制 GPU 卸载层数。-ngl 99` 卸载全部层。Apple Silicon 自动使用 Metal，NVIDIA 使用 CUDA，AMD 使用 Vulkan 或 HIP。
启动模式(11)
| 命令 | 难度 | ||
|---|---|---|---|
llama-cli --help显示 llama.cpp CLI 帮助信息 | 基础 | llama-cli --help | |
llama-cli -m指定模型文件路径（GGUF 格式） | 基础 | llama-cli -m models/llama-3.2-3b-q4_k_m.gguf -p 'Hello' | |
llama-cli -p指定输入提示词 | 基础 | llama-cli -m model.gguf -p 'What is the capital of France?' | |
llama-cli -f从文件读取提示词 | 基础 | llama-cli -m model.gguf -f prompt.txt | |
llama-cli -n设置最大生成 token 数 | 基础 | llama-cli -m model.gguf -p 'Hello' -n 512 | |
llama-cli -t设置线程数（CPU 推理） | 中级 | llama-cli -m model.gguf -p 'Hello' -t 8 | |
llama-cli --temp设置温度参数（0-2） | 中级 | llama-cli -m model.gguf -p 'Poem' --temp 0.7 | |
llama-cli --top-p设置 top-p 采样参数 | 中级 | llama-cli -m model.gguf -p 'Story' --top-p 0.9 | |
llama-cli --ctx-size设置上下文窗口大小 | 中级 | llama-cli -m model.gguf --ctx-size 8192 -p 'Long context' | |
llama-cli -ngl指定 GPU 卸载层数（GPU 加速） | 中级 | llama-cli -m model.gguf -p 'Hello' -ngl 35 | |
llama-cli --no-display-prompt输出只包含生成的文本（不含提示词） | 基础 | llama-cli -m model.gguf -p 'Hello' --no-display-prompt |
ai-server(8)
| 命令 | 难度 | ||
|---|---|---|---|
llama-server --help显示 HTTP 服务器帮助 | 基础 | llama-server --help | |
llama-server -m以 HTTP 服务器模式启动模型 | 中级 | llama-server -m models/model.gguf --port 8080 | |
llama-server --port指定服务器监听端口 | 基础 | llama-server -m model.gguf --port 8080 | |
llama-server --host指定绑定的主机地址 | 中级 | llama-server -m model.gguf --host 0.0.0.0 | |
llama-server -ngl服务器模式下 GPU 卸载 | 中级 | llama-server -m model.gguf -ngl 99 --port 8080 | |
llama-server --embeddings启用嵌入向量端点 | 高级 | llama-server -m model.gguf --embeddings --port 8080 | |
llama-server --chat-template指定聊天模板文件 | 高级 | llama-server -m model.gguf --chat-template chatml.json | |
curl localhost:8080/v1/chat/completions向 llama-server 发送 OpenAI 兼容请求 | 中级 | curl -s http://localhost:8080/v1/chat/completions -d '{"model":"model","messages":[{"role":"user","content":"Hi"}]}'
|
ai-model(3)
| 命令 | 难度 | ||
|---|---|---|---|
llama-cli --hf-token使用 HuggingFace Token 下载模型 | 中级 | llama-cli --hf-token hf_xxx -m hf:bartowski/Llama-3.2-3B-Instruct-GGUF | |
llama-cli --hf从 HuggingFace 直接加载模型 | 中级 | llama-cli --hf bartowski/Meta-Llama-3.1-8B-Instruct-GGUF -p 'Hello' | |
llama-quantize量化模型到指定精度 | 高级 | llama-quantize model.gguf model-q4_k_m.gguf Q4_K_M |
ai-eval(1)
| 命令 | 难度 | ||
|---|---|---|---|
llama-perplexity -m评估模型的困惑度 | 高级 | llama-perplexity -m model.gguf -f test.txt |
ai-embedding(2)
| 命令 | 难度 | ||
|---|---|---|---|
llama-embedding生成文本嵌入向量 | 中级 | llama-embedding -m model.gguf -p 'Hello world' | |
curl -X POST http://localhost:8080/v1/embeddings通过 API 获取嵌入向量 | 中级 | curl -s http://localhost:8080/v1/embeddings -d '{"model":"model","input":"Hello"}'
|