部署教程｜llama.cpp 本地大模型推理全流程（CPU/GPU 通用）

1. 项目简介

llama.cpp 是用 C/C++ 实现的轻量大模型推理引擎，支持 CPU/Metal/CUDA/ROCm，多平台通吃。优势：安装轻、量化多、兼容 OpenAI API。

2. 环境准备

  • 系统：Linux/macOS/Windows 均可（建议 16GB 内存起步）。
  • 依赖：CMake、git、Python（可选）、编译链（gcc/clang 或 MSVC）。
  • GPU：如需 GPU，安装对应 CUDA/ROCm/Metal SDK。

3. 获取代码并编译

1
2
3
4
5
6
7
8
9
10
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# CPU 版
cmake -B build
cmake --build build --config Release

# CUDA 版（示例）
cmake -B build -DLLAMA_CUBLAS=ON
cmake --build build --config Release

生成的二进制在 ./build/bin。

4. 下载与量化权重

  1. 准备 GGUF 权重：从官方或社区仓库下载（如 Hugging Face）。
  2. 量化示例（可选，将 FP16 转成 Q4_0）：
    1
    2
    python convert_hf_to_gguf.py --model /path/hf-model --outfile model-f16.gguf
    ./build/bin/llama-quantize model-f16.gguf model-q4_0.gguf q4_0
    如已有 GGUF 量化文件，直接使用。

5. 本地推理（CLI）

1
2
3
4
./build/bin/llama-cli \
  -m ./models/model-q4_0.gguf \
  -p "用50字说明量化的好处" \
  -n 256

常用参数：-n 输出 tokens，-t 线程数，-c 上下文长度。

6. OpenAI 兼容 API 模式

1
2
3
4
./build/bin/llama-server \
  -m ./models/model-q4_0.gguf \
  --host 0.0.0.0 --port 8000 \
  --threads 8 --ctx-size 4096

调用示例：

1
2
3
4
5
6
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model":"local-llama",
    "messages":[{"role":"user","content":"写一段 Markdown 介绍 llama.cpp"}]
  }'

7. 桌面/Web 前端

  • text-generation-webui：指向 llama.cpp server 的 OpenAI 端点。
  • LM Studio / Jan：可加载 GGUF，本地 GUI 直接推理。
  • VSCode 插件：配置 OpenAI 兼容 API，即可代码补全。

8. 性能优化

  • 量化：Q4_0/Q4_K_M 减显存，Q5/Q6 质量更好；FP16 需高显存。
  • 线程：-t 设为物理核数或略低。
  • KV Cache：--ctx-size 与内存/显存平衡；长上下文慎重。
  • GPU offload：-ngl 20（示例）将部分层放 GPU。

9. 常见问题

  • 乱码/输出慢：检查模型 tokenizer，确认权重与 llama.cpp 版本匹配。
  • OOM：降低上下文、换更小量化；或改用分段生成。
  • Windows 编译失败：用 MSVC 或 WSL；更新 CMake 与编译链。

10. 总结

llama.cpp 是最快速的本地 LLM 入门方案：编译简单、量化丰富、支持 OpenAI 兼容接口。先用 Q4 量化跑通，按需再升级模型与硬件。