llama.cpp 配置模型实战：把开源模型跑在自己电脑上

① 小白第一课怎么学（4 步走，约 90 分钟）

这是"动手落地"页，建议边读边在终端跟着敲。没有 Mac 也没关系，Windows/Linux 命令几乎一样，照抄即可。

② 一图看懂：llama.cpp 跑模型的完整流水线

③ 本质直觉：llama.cpp 就是一个"能读懂 GGUF 的本地小服务器"

一句话：llama.cpp 是 Georgi Gerganov 用纯 C/C++ 写的推理引擎，它的本事是——不依赖 CUDA、不依赖 PyTorch，光靠 CPU（或 Apple Metal / Vulkan）就能把一个 GGUF 格式的模型文件跑起来。它不是训练框架，只做"推理"这一件事。

为什么它这么火？因为它把"跑大模型"的门槛从"租 A100"降到了"一台 MacBook"。量化后的 7B 模型才 4GB 出头，MacBook Air 都能跑。

④ 完整体系：关键参数 / 接口 / 精度对照表

llama-cli 核心参数速查（必背）

GGUF 量化精度对比（第7课已讲，这里对照体积）

⑤ 用法场景：本地跑模型能干什么

⑥ 高频错误诊断（5 条 box.err）

⑦ 考点真题演练（4 题）

考点分布

⑧ 必背知识点卡

⑨ 应用输出：从 0 到跑通，完整照做

9.1 选模型去哪下：Hugging Face 搜 GGUF

打开 huggingface.co，搜索框输 Qwen3.8-7B-Instruct GGUF。你会看到一堆仓库，优先选 bartowski/Qwen3.8-7B-Instruct-GGUF（社区最常用、更新及时、量化版本齐全）。点进去在 Files 标签里找文件名：

# 认准这个文件名（HF 上真实存在）：
qwen3.8-7b-instruct-q4_k_m.gguf      # ≈ 4.4 GB，这就是我们要下的
qwen3.8-7b-instruct-q5_k_m.gguf      # ≈ 5.2 GB，质量略高
qwen3.8-7b-instruct-q8_0.gguf        # ≈ 7.0 GB，几乎无损

下载可以直接浏览器点文件名，也可以用 huggingface-cli：

pip install -U "huggingface_hub[cli]"
hf download bartowski/Qwen3.8-7B-Instruct-GGUF qwen3.8-7b-instruct-q4_k_m.gguf \
  --local-dir ./models

9.2 安装 llama.cpp：git clone + cmake（Mac Metal 后端）

# 1. 拉源码
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

# 2. 编译（macOS 自动用 Metal，Apple Silicon 速度起飞）
cmake -B build
cmake --build build --config Release -j

# 3. 编译完后，二进制在 build/bin/ 下：
ls build/bin/llama-cli      # 命令行推理
ls build/bin/llama-server   # HTTP 服务

9.3 命令行一次推理（逐参数解释）

把上一步下的 .gguf 放进 ./models/，然后敲这一条（整条可直接复制）：

./build/bin/llama-cli \
  -m ./models/qwen3.8-7b-instruct-q4_k_m.gguf \
  -c 4096 \
  -ngl 99 \
  -t 8 \
  -p "你好，请用三句话介绍你自己" \
  -n 256 \
  --temp 0.7 \
  --top-p 0.9 \
  --repeat-penalty 1.1 \
  --color

9.4 多模态投影：跑 Qwen2-VL 要加 --mmproj

如果跑的是视觉语言模型（如 Qwen3.8-VL），你需要两个文件：主模型 .gguf + 投影文件 mmproj。投影文件把图片编码器输出对齐到语言模型的嵌入空间（原理见第18课）。

# 两个文件：
qwen3.8-vl-7b-instruct-q4_k_m.gguf     # 主权重
mmproj-f16.gguf                       # 投影层，单独下

# 命令里多两个参数：
./build/bin/llama-cli \
  -m ./models/qwen3.8-vl-7b-instruct-q4_k_m.gguf \
  --mmproj ./models/mmproj-f16.gguf \
  -c 4096 -ngl 99 -t 8 \
  --image ./path/to/cat.jpg \
  -p "描述这张图里有什么" -n 256

9.5 服务模式：起 llama-server

一次性跑 cli 每次都要重新加载模型（5~15 秒）。要反复调用，就起常驻服务：

./build/bin/llama-server \
  -m ./models/qwen3.8-7b-instruct-q4_k_m.gguf \
  -ngl 99 \
  -c 8192 \
  --port 8080 \
  --host 127.0.0.1 \
  --chat-template qwen3.8

看到 main: server is listening on 127.0.0.1:8080 就成功了。浏览器打开 http://127.0.0.1:8080 还有一个自带的网页聊天框可以先玩。

9.6 API 调用示例（完整 curl + JSON）

① 原生补全接口 POST /completion

curl http://127.0.0.1:8080/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "用三句话解释什么是量化",
    "n_predict": 256,
    "temperature": 0.7,
    "top_p": 0.9,
    "repeat_penalty": 1.1,
    "stream": false
  }'

返回 JSON 里关键字段是 content（模型生成的文本）和 timings（速度统计，含 prompt eval / eval 每秒 token 数）。

② OpenAI 兼容接口 POST /v1/chat/completions

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-7b-instruct",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手，回答不超过三句话。"},
      {"role": "user", "content": "什么是 KV Cache？"}
    ],
    "n_predict": 256,
    "temperature": 0.3,
    "stream": false
  }'

这个接口的请求体和 OpenAI 官方 /v1/chat/completions 几乎一样——意味着你把 OpenAI SDK 的 base_url 改成 http://127.0.0.1:8080/v1、api_key 随便填，原有代码一行不改就能跑本地模型。

③ stream=true 的 SSE 流式返回长什么样

把上面请求体里 "stream": false 改成 true，服务器不再一次性返回完整 JSON，而是以 SSE（Server-Sent Events）格式逐块吐：

data: {"choices":[{"delta":{"content":"K"}}]}

data: {"choices":[{"delta":{"content":"V"}}]}

data: {"choices":[{"delta":{"content":" "}}]}

data: {"choices":[{"delta":{"content":"Cache"}}]}

data: {"choices":[{"delta":{"content":" 是"}}]}

data: [DONE]

前端每收到一段 data: 就把 choices[0].delta.content 追加到页面上——这就是"打字机效果"的来源（第22课专门讲流式）。

9.7 显存 / 内存测算公式与算例

算例（7B Q4_K_M，-c 4096）：权重 ≈ 4.4GB；KV Cache 在 FP16 下大约几百 MB（7B 大约 0.5~1GB），合计 ≈5~5.5GB。Mac 16G 跑它还剩一半内存给系统，很舒服。

9.8 效果调优表：温度 / top_p / repeat-penalty 怎么配

⑪ 记忆口诀 + 7 天复习计划