llama.cpp 入门指南：在本地运行大语言模型

无需云服务，一台普通电脑就能跑 AI 模型

什么是 llama.cpp？

llama.cpp 是一个用 C/C++ 编写的大语言模型推理框架，目标是在消费级硬件上高效运行 LLM。它支持 macOS、Linux、Windows 以及各种 GPU 加速后端，是目前最流行的本地 AI 推理工具之一。

安装指南

方式一：包管理器（推荐新手）

macOS (Homebrew)

brew install llama.cpp

Windows (winget)

winget install llama.cpp

Nix/NixOS

nix-env -iA nixpkgs.llama-cpp

方式二：下载预编译二进制

访问 Releases 页面 下载对应系统的预编译版本，解压即可使用。

方式三：使用 Docker

docker run -it --gpus all ghcr.io/ggml-org/llama.cpp:latest

方式四：从源码编译

# 克隆仓库
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# macOS / Linux
make

# Windows (使用 CMake)
cmake -B build
cmake --build build --config Release

# 启用 GPU 加速（可选）
# NVIDIA CUDA
make LLAMA_CUDA=1

# Apple Metal
make LLAMA_METAL=1

# Vulkan
make LLAMA_VULKAN=1

获取模型

llama.cpp 使用 GGUF 格式的模型文件。获取模型有几种方式：

方式一：直接从 Hugging Face 下载

# 使用 llama-cli 直接下载并运行
llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

方式二：手动下载

访问 Hugging Face 搜索 GGUF 格式的模型，例如：

• https://huggingface.co/ggml-org
• https://huggingface.co/TheBloke (大量量化模型)

下载 .gguf 文件到本地。

方式三：自己转换

如果有原始模型（如 Hugging Face 上的 PyTorch 模型），可以使用 convert-hf-to-gguf.py 脚本转换：

python convert-hf-to-gguf.py path/to/model --outfile model.gguf

基本使用

命令行交互

# 使用本地模型文件
llama-cli -m path/to/model.gguf

# 指定更多参数
llama-cli -m model.gguf \
  -p "你好，请介绍一下自己" \
  -n 512 \
  --temp 0.7

常用参数：

• -m：模型文件路径
• -p：提示词（prompt）
• -n：生成最大 token 数
• --temp：温度（创造性，0-1）
• --ctx-size：上下文窗口大小

启动 API 服务器

llama.cpp 可以启动一个 OpenAI 兼容的 API 服务器：

llama-server -m model.gguf --host 0.0.0.0 --port 8080

启动后，可以用任何 OpenAI 客户端连接：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="local-model",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手"},
        {"role": "user", "content": "你好！"}
    ]
)

print(response.choices[0].message.content)

多模态使用（图像 + 文本）

llama-cli -m llava-model.gguf \
  --mmproj mmproj-model.gguf \
  -i image.jpg \
  -p "描述这张图片"

高级配置

GPU 加速

NVIDIA CUDA

llama-cli -m model.gguf -ngl 99

-ngl 指定卸载到 GPU 的层数，99 表示全部卸载。

Apple Metal

llama-cli -m model.gguf -ngl 99

Vulkan

llama-cli -m model.gguf -ngl 99 -vgpu 0

量化模型选择

量化可以在几乎不影响质量的情况下大幅降低显存占用：

量化格式	显存占用	质量损失	推荐场景
Q4_K_M	~5GB (7B 模型)	极小	日常使用
Q5_K_M	~6GB (7B 模型)	几乎无	高质量需求
Q8_0	~8GB (7B 模型)	无	追求极致质量

上下文窗口调整

llama-cli -m model.gguf --ctx-size 8192

更大的上下文窗口可以处理更长的文档，但会增加内存占用。

常见问题

显存不足怎么办？

1. 使用量化程度更高的模型（如 Q4 instead of Q8）
2. 减少 -ngl 参数，让部分层在 CPU 上运行
3. 选择更小的模型（7B instead of 70B）

推理速度太慢？

1. 确保启用了 GPU 加速（-ngl 99）
2. 使用量化模型
3. 减少 --ctx-size
4. 关闭不必要的后台程序

如何保存对话历史？

使用 --conversation 参数或自行管理对话历史：

llama-cli -m model.gguf \
  --conversation \
  --conversation-file chat.json

生态系统工具

桌面应用

• LM Studio：图形界面，适合新手
• Jan：开源的本地 AI 平台
• Ollama：简化的模型管理工具

编辑器插件

• VS Code: llama.vscode
• Vim/Neovim: llama.vim

编程语言绑定

• Python: pip install llama-cpp-python
• Node.js: npm install node-llama-cpp
• Rust: cargo add llama-cpp-rs

推荐的入门模型

新手推荐（显存 8GB 以下）

• Gemma 3 1B/4B
• Phi-3 Mini (3.8B)
• Qwen2.5 3B/7B (量化版)

中端配置（显存 12-16GB）

• LLaMA 3 8B
• Mistral 7B
• Gemma 2 9B

高端配置（显存 24GB+）

• LLaMA 3 70B (量化版)
• Mixtral 8x7B
• Qwen2.5 72B (量化版)

总结

llama.cpp 让本地运行大模型变得简单。无论你是想保护隐私、节省成本，还是单纯想学习 AI 技术，它都是一个优秀的起点。

快速开始三步：

1. 安装 llama.cpp
2. 下载一个 GGUF 模型
3. 运行 llama-cli -m model.gguf

开始你的本地 AI 之旅吧！

---

参考资源：

• 官方仓库：https://github.com/ggml-org/llama.cpp
• 文档：https://github.com/ggml-org/llama.cpp/tree/master/docs
• 模型下载：https://huggingface.co/ggml-org
• 社区讨论：https://github.com/ggml-org/llama.cpp/discussions

---