告别API费用！Llama.cpp本地部署大模型全攻略，你的电脑也能跑AI

llama.cpp 本地大模型部署实战教程

编写日期: 2026-06 适用平台: Linux (Ubuntu 22.04/24.04) & Windows 10/11 llama.cpp 仓库: https://github.com/ggml-org/llama.cpp 当前稳定版: b9601（2026-06-11）

目录

1. 概述与环境要求

llama.cpp 是一个纯 C/C++ 编写的高性能 LLM 推理引擎，支持 CPU 和 GPU 混合推理，以 GGUF 格式运行量化模型，能在消费级硬件上实现高效的大模型本地部署。

最低硬件要求

软件版本要求

2. 环境依赖准备

2.1 Linux 环境

以 Ubuntu 22.04/24.04 为例。

安装基础编译工具链

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装基础编译工具
sudo apt install -y build-essential cmake git wget curl

# 验证版本
gcc –version # 需要 >= 12
cmake –version # 需要 >= 3.21

# 如果 gcc 版本过低，安装更新版本
sudo apt install -y gcc-12 g++-12
sudo update-alternatives –install /usr/bin/gcc gcc /usr/bin/gcc-12 100
sudo update-alternatives –install /usr/bin/g++ g++ /usr/bin/g++-12 100

安装 CUDA Toolkit（NVIDIA GPU 用户）

# 确认 GPU 和驱动
nvidia-smi
# 输出示例：Driver Version: 550.x | CUDA Version: 12.4

# 安装 CUDA Toolkit 12.4（Ubuntu 24.04）
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get install -y cuda-toolkit-12-4

# 配置环境变量
echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
nvcc –version
# 输出示例：Cuda compilation tools, release 12.4, V12.4.xxx

注意: 若 CMake 版本过低（Ubuntu 22.04 默认 3.22 通常够用），可通过 Kitware PPA 安装新版：

wget -O – https://apt.kitware.com/keys/kitware-archive-latest.asc | sudo gpg –dearmor -o /usr/share/keyrings/kitware-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ jammy main' | sudo tee /etc/apt/sources.list.d/kitware.list
sudo apt update && sudo apt install cmake

安装 Python 环境（模型转换用）

sudo apt install -y python3 python3-pip python3-venv
python3 –version # 需要 >= 3.10

2.2 Windows 环境

安装 Visual Studio Build Tools

安装 Git

winget install —id Git.Git –e —source winget

安装 CMake

winget install —id Kitware.CMake –e —source winget

安装后重启终端，验证：

cmake —version
git —version

安装 CUDA Toolkit（NVIDIA GPU 用户）

nvcc —version
nvidia-smi

安装 Python（模型转换用）

winget install —id Python.Python.3.12 –e —source winget

3. 源码克隆与编译构建

⚠️ 2026 年重大更新：自 b9196 版本起，llama.cpp 官方 GitHub Releases 提供了 Windows 预构建二进制包（免编译），支持 CUDA/Vulkan/HIP/SYCL 多种后端。如果你用 Windows 且不想折腾编译环境，直接跳到 3.0 节 下载即用。

3.0 Windows 免编译方案（2026 年新增推荐）

自 2026 年 5 月发布的 b9196 版本起，llama.cpp 官方在 GitHub Releases 中提供预编译的 Windows 二进制包，省去安装 Visual Studio、CMake、CUDA Toolkit 的繁琐流程。

下载步骤

配置 CUDA DLL（CUDA 版本需要）

如果下载的是 CUDA 版本，还需要补充 CUDA 运行时 DLL：

# 方式一：安装 CUDA Toolkit 12.x（会自动配置好 DLL）
# 下载地址：https://developer.nvidia.com/cuda-downloads

# 方式二：手动下载 cudart DLL（轻量）
# 从 https://github.com/ggml-org/llama.cpp/releases 下载对应的 cudart-llama-bin-win-cu12.8-x64.7z
# 解压后将 DLL 放到解压目录根层级（和 llama-cli.exe 同级）

验证

# 进到解压目录
cd C:\\llama.cpp

# 查看版本
.\\llama-cli.exe —version

# 查看可用后端
.\\llama-cli.exe —version 2>&1 | Select-String "ggml"
# 应看到 cuda=1 或 vulkan=1 字样

免编译方案的限制

结论：绝大多数用户（尤其是 Windows 新手）直接用免编译版即可，性能差距微乎其微。只有当你需要极致性能调优、裁剪特定功能、或运行在特殊硬件上时，才值得花时间从源码编译。

3.1 CPU 编译（双平台）

克隆仓库

# 务必包含子模块！
git clone –recurse-submodules https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

如果已克隆但忘记 –recurse-submodules：

git submodule update –init –recursive

Linux CPU 编译

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake –build build –config Release -j$(nproc)

编译产物在 build/bin/ 目录下：

• llama-cli — 命令行推理工具
• llama-server — HTTP API 服务
• llama-quantize — 模型量化工具
• llama-embedding — 嵌入向量提取
• llama-perplexity — 困惑度评估

验证编译成功：

./build/bin/llama-cli –version

Windows CPU 编译

必须在 “Developer PowerShell for VS 2022” 或 “x64 Native Tools Command Prompt for VS 2022” 中执行！

cmake –B build –DCMAKE_BUILD_TYPE=Release
cmake —build build —config Release –j $env:NUMBER_OF_PROCESSORS

编译产物在 build\\bin\\Release\\ 目录下（.exe 后缀）。

验证：

.\\build\\bin\\Release\\llama-cli.exe —version

3.2 CUDA GPU 加速编译

查询 GPU 计算能力

# 查计算能力代码
nvidia-smi –query-gpu=compute_cap –format=csv,noheader
# 示例输出：8.9 → 架构代码为 "89"

常用架构代码：

Linux CUDA 编译

# 标准 CUDA 编译
cmake -B build \\
-DCMAKE_BUILD_TYPE=Release \\
-DGGML_CUDA=ON \\
-DBUILD_SHARED_LIBS=OFF

cmake –build build –config Release -j$(nproc)

推荐：指定 GPU 架构优化编译

# 以 RTX 4090 (架构代码 89) 为例
cmake -B build \\
-DCMAKE_BUILD_TYPE=Release \\
-DGGML_CUDA=ON \\
-DGGML_CUDA_F16=ON \\
-DGGML_CUDA_ARCHITECTURES="89" \\
-DBUILD_SHARED_LIBS=OFF

cmake –build build –config Release -j$(nproc)

参数说明：

• -DGGML_CUDA=ON — 启用 CUDA 后端（新版统一标志，替代旧的 LLAMA_CUBLAS）
• -DGGML_CUDA_F16=ON — 使用 FP16 张量核心加速（RTX 20xx+ 支持）
• -DGGML_CUDA_ARCHITECTURES="89" — 指定目标 GPU 架构（强烈推荐，避免运行时崩溃）
• -DBUILD_SHARED_LIBS=OFF — 生成静态二进制（可独立分发）

Windows CUDA 编译

# 在 Developer PowerShell for VS 2022 中执行
# 以 RTX 4090 (架构代码 89) 为例
cmake –B build `
–DCMAKE_BUILD_TYPE=Release `
–DGGML_CUDA=ON `
–DGGML_CUDA_F16=ON `
–DGGML_CUDA_ARCHITECTURES="89" `
–DBUILD_SHARED_LIBS=OFF

cmake —build build —config Release –j $env:NUMBER_OF_PROCESSORS

编译产物在 build\\bin\\Release\\。

验证 CUDA 是否正确启用

# Linux
./build/bin/llama-cli -m ./models/test.gguf -p "Hello" -n 10 –n-gpu-layers 99 2>&1 | grep -i "offload\\|cuda\\|VRAM"

# Windows
.\\build\\bin\\Release\\llama-cli.exe -m models\\test.gguf -p "Hello" -n 10 –n-gpu-layers 99

成功标志（输出中应看到类似内容）：

llm_load_tensors: offloaded 32/33 layers to GPU
llm_load_tensors: VRAM used: 4782 MiB

如果看到 offloaded 0/33 layers，说明 CUDA 未生效，需要：

rm -rf build # 清理构建缓存
# 重新执行 cmake 编译命令

3.3 其他 GPU 后端（Vulkan/Metal/HIP）

Vulkan（AMD/Intel GPU，跨平台）

cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_VULKAN=ON
cmake –build build –config Release -j$(nproc)

Metal（Apple Silicon / macOS）

cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_METAL=ON
cmake –build build –config Release -j $(sysctl -n hw.ncpu)

HIP（AMD GPU，Linux）

cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_HIP=ON
cmake –build build –config Release -j$(nproc)

4. 模型下载与转换指南

4.1 直接下载 GGUF 模型（推荐）

GGUF 是 llama.cpp 的原生格式，无需转换，下载即用。

方式一：从 HuggingFace 手动下载

访问 HuggingFace 搜索 GGUF 模型，知名发布者：

方式二：使用 huggingface-cli 下载

# 安装 huggingface_hub
pip install huggingface_hub

# 下载指定 GGUF 文件
huggingface-cli download bartowski/Qwen2.5-7B-Instruct-GGUF \\
Qwen2.5-7B-Instruct-Q4_K_M.gguf \\
–local-dir ./models \\
–local-dir-use-symlinks False

方式三：llama.cpp 内置下载

# 新版 llama.cpp 支持直接指定 HuggingFace 仓库路径
./build/bin/llama-cli \\
-m "hf:repo=bartowski/Qwen2.5-7B-Instruct-GGUF:file=Qwen2.5-7B-Instruct-Q4_K_M.gguf" \\
-p "Hello"

# 或使用环境变量设置缓存目录
export LLAMA_CACHE=/path/to/model/cache

推荐的开源 GGUF 模型

4.2 HuggingFace 模型转 GGUF

如果只有 HuggingFace 格式（safetensors/pytorch）的模型，需要先转换为 GGUF。

安装转换依赖

cd llama.cpp
pip install -r requirements.txt

执行转换

# 方式一：本地模型目录
python convert_hf_to_gguf.py /path/to/huggingface-model \\
–outfile ./models/my-model-f16.gguf \\
–outtype f16

# 方式二：直接从 HuggingFace 下载并转换
python convert_hf_to_gguf.py Qwen/Qwen2.5-7B-Instruct \\
–outfile ./models/qwen2.5-7b-f16.gguf \\
–outtype f16

# 支持的输出类型：f32, f16, bf16, q8_0

注意：转换大模型（70B+）需要大量内存，建议在有足够 RAM 的机器上执行。

4.3 GGUF 模型量化

使用 llama-quantize 工具将 FP16/BF16 GGUF 模型量化为更小的版本。

量化命令

# 基本用法
./build/bin/llama-quantize \\
./models/model-f16.gguf \\
./models/model-Q4_K_M.gguf \\
Q4_K_M

# 推荐：使用重要性矩阵优化量化效果
./build/bin/llama-quantize \\
–imatrix ./calibration-data.dat \\
./models/model-f16.gguf \\
./models/model-Q4_K_M.gguf \\
Q4_K_M

量化等级选择

建议：优先从 Q4_K_M 开始，如果质量不够再升级到 Q5_K_M 或 Q6_K；如果显存不够则降级到 Q3_K_M。

常用优化参数

# 允许对已量化模型再次量化（不推荐，可能损失质量）
–allow-requantize

# 保留输出层不量化（体积稍大，可能提升质量）
–leave-output-tensor

# 关闭混合量化
–pure

# 使用重要性矩阵
–imatrix calibration.dat

# 保留分片结构
–keep-split

5. 关键参数配置与启动命令

5.1 核心参数速查表

模型加载参数

上下文与性能参数

采样参数

服务器参数

5.2 llama-cli 命令行推理

单轮对话

./build/bin/llama-cli \\
-m ./models/qwen2.5-7b-Q4_K_M.gguf \\
-p "请用中文介绍一下人工智能的发展历史" \\
-n 512 \\
–n-gpu-layers 99 \\
–ctx-size 4096 \\
–temp 0.7

交互式多轮对话

./build/bin/llama-cli \\
-m ./models/qwen2.5-7b-Q4_K_M.gguf \\
-cnv \\
–chat-template chatml \\
-ngl 99 \\
-c 8192 \\
-t 8 \\
–temp 0.7 \\
–top-p 0.9

参数说明：

• -cnv — 启用交互式对话模式
• –chat-template chatml — 指定聊天模板格式
• -ngl 99 — 将 99 层卸载到 GPU（实际层数由模型决定）
• -c 8192 — 上下文窗口 8192 Token

多模态模型推理

./build/bin/llama-cli \\
-m ./models/qwen2.5-vl-7b.gguf \\
–mmproj ./models/qwen2.5-vl-7b-mmproj.gguf \\
–image ./photo.jpg \\
-p "描述这张图片的内容" \\
-ngl 99

5.3 llama-server HTTP 服务

基本启动

./build/bin/llama-server \\
-m ./models/qwen2.5-7b-Q4_K_M.gguf \\
–n-gpu-layers 99 \\
–ctx-size 8192 \\
–threads 8 \\
–host 0.0.0.0 \\
–port 8080

启动后访问 http://127.0.0.1:8080 即可使用内置 Web 聊天界面。

API 调用示例

# 补全 API (Completion)
curl http://127.0.0.1:8080/completion \\
-H "Content-Type: application/json" \\
-d '{
"prompt": "请用中文写一首关于春天的诗",
"n_predict": 256,
"temperature": 0.7
}'

# 对话 API (Chat Completion) — OpenAI 兼容
curl http://127.0.0.1:8080/v1/chat/completions \\
-H "Content-Type: application/json" \\
-d '{
"model": "local-model",
"messages": [
{"role": "user", "content": "你好，请介绍一下自己"}
],
"temperature": 0.7,
"max_tokens": 512
}'

# 健康检查
curl http://127.0.0.1:8080/health

# 模型信息
curl http://127.0.0.1:8080/v1/models

生产级启动配置

./build/bin/llama-server \\
-m ./models/qwen2.5-14b-Q5_K_M.gguf \\
–n-gpu-layers -1 \\
–ctx-size 16384 \\
–threads 16 \\
–threads-batch 16 \\
–batch-size 2048 \\
–ubatch-size 512 \\
–flash-attn \\
–host 127.0.0.1 \\
–port 8080 \\
–api-key my-secret-key \\
–slots-endpoint-disable \\
–metrics

参数详解：

• –n-gpu-layers -1 — 自动检测最优 GPU 层数
• –flash-attn — 启用 Flash Attention 降低显存占用
• –api-key — 设置 API 密钥保护服务
• –metrics — 启用 Prometheus 格式指标

5.4 生产级启动脚本示例

Linux 启动脚本 (start-server.sh)

#!/bin/bash
set -e

# ===== 配置区域 =====
MODEL_PATH="./models/qwen2.5-14b-Q5_K_M.gguf"
HOST="127.0.0.1"
PORT="8080"
CTX_SIZE="16384"
THREADS="16"
API_KEY="change-me-to-a-secure-key"
# ===================

LLAMA_DIR="/opt/llama.cpp"
SERVER_BIN="${LLAMA_DIR}/build/bin/llama-server"

if [ ! -f "$SERVER_BIN" ]; then
echo "错误：找不到 llama-server，请先编译 llama.cpp"
exit 1
fi

if [ ! -f "$MODEL_PATH" ]; then
echo "错误：找不到模型文件 $MODEL_PATH"
exit 1
fi

echo "启动 llama-server…"
echo " 模型: $MODEL_PATH"
echo " 地址: http://${HOST}:${PORT}"
echo " 上下文: ${CTX_SIZE} tokens"

exec "$SERVER_BIN" \\
-m "$MODEL_PATH" \\
–n-gpu-layers -1 \\
–ctx-size "$CTX_SIZE" \\
–threads "$THREADS" \\
–threads-batch "$THREADS" \\
–batch-size 2048 \\
–ubatch-size 512 \\
–flash-attn \\
–host "$HOST" \\
–port "$PORT" \\
–api-key "$API_KEY" \\
–metrics

chmod +x start-server.sh
./start-server.sh

Windows 启动脚本 (start-server.bat)

@echo off
setlocal

REM ===== 配置区域 =====
set MODEL_PATH=models\\qwen2.5-14b-Q5_K_M.gguf
set HOST=127.0.0.1
set PORT=8080
set CTX_SIZE=16384
set THREADS=16
set API_KEY=change-me-to-a-secure-key
REM ===================

set SERVER_BIN=build\\bin\\Release\\llama-server.exe

if not exist "%SERVER_BIN%" (
echo 错误：找不到 llama-server.exe，请先编译 llama.cpp
pause
exit /b 1
)

if not exist "%MODEL_PATH%" (
echo 错误：找不到模型文件 %MODEL_PATH%
pause
exit /b 1
)

echo 启动 llama-server…
echo 模型: %MODEL_PATH%
echo 地址: http://%HOST%:%PORT%
echo 上下文: %CTX_SIZE% tokens

"%SERVER_BIN%" ^
-m "%MODEL_PATH%" ^
–n-gpu-layers -1 ^
–ctx-size %CTX_SIZE% ^
–threads %THREADS% ^
–threads-batch %THREADS% ^
–batch-size 2048 ^
–ubatch-size 512 ^
–flash-attn ^
–host %HOST% ^
–port %PORT% ^
–api-key %API_KEY% ^
–metrics

pause

6. 常见报错排查

6.1 编译阶段

6.2 运行时阶段

6.3 性能问题

6.4 诊断命令

# 查看编译时启用的特性
./build/bin/llama-cli –version

# 查看模型元数据
./build/bin/llama-cli -m model.gguf –verbose 2>&1 | head -50

# 查看 GPU 信息
nvidia-smi

# 监控 GPU 使用
watch -n 1 nvidia-smi

# Linux 查看进程内存
htop -p $(pgrep llama-server)

# Windows 查看进程
tasklist | findstr llama

7. 性能优化建议

GPU 推理优化

CPU 推理优化

通用优化

8. 附录：GPU 架构代码对照表

NVIDIA GPU

多 GPU 编译

# 同时支持多种架构
cmake -B build \\
-DGGML_CUDA=ON \\
-DCMAKE_CUDA_ARCHITECTURES="75;86;89"

9. llama.cpp vs Ollama 对比选型指南

看完上面的教程，你可能会有一个疑问：“说了那么多，到底该用 llama.cpp 还是 Ollama？”

这个问题确实值得认真讨论，因为它直接关系到你后续的使用体验。下面从定位、安装、性能、灵活性等多个维度做一次系统性对比。

9.1 一句话定位

打个比方：Ollama 像自动挡汽车，踩油门就走；llama.cpp 像手动挡赛车，起步要学，但弯道极限更高。

9.2 多维度对比

安装与上手

结论：易用性上 Ollama 完胜，尤其适合 Windows 新手。

模型管理

结论：Ollama 模型管理更方便；llama.cpp 更自由但需自己操心。

性能

根据 2026 年 5 月第三方 benchmark（Llama 3.1 8B Q4_K_M，RTX 4090）：

性能差距分析：

llama.cpp 略微领先的原因在于：

• 编译时可针对特定 GPU 架构优化（GGML_CUDA_ARCHITECTURES），Ollama 用的是通用编译
• 更细粒度的线程控制和 batch size 调节空间
• Flash Attention 等特性在编译期就确定了最优实现

但说实话：对普通用户的日常使用来说，这个 9-11% 的性能差距几乎感知不到。除非你在做批处理、高并发、或对延迟极度敏感的场景。

灵活性与可控性

结论：llama.cpp 在灵活性和底层控制上远超 Ollama。如果你是开发者、需要精细化调参、或者跑非标准 GPU（AMD/Intel），llama.cpp 是更好的选择。

生态与社区

结论：Ollama 生态更繁荣；llama.cpp 是其底层依赖，技术深度更深。

9.3 性能实测对比

在同一台机器（RTX 4090 24GB，64GB RAM）上的实测数据：

# 测试模型：Qwen2.5-7B-Instruct-Q4_K_M.gguf
# 测试方式：每次运行生成 512 tokens，"请用中文介绍人工智能" × 3 取均值

# Ollama
ollama run qwen2.5:7b
# 结果：42.3 tok/s（生成阶段），3.8s 首 token 延迟

# llama.cpp (CUDA 编译，指定 ARCH=89)
./llama-cli -m qwen2.5-7b-Q4_K_M.gguf -p "请用中文介绍人工智能" -n 512 -ngl 99 -fa
# 结果：46.1 tok/s（生成阶段），3.5s 首 token 延迟

实测差约 9%，符合社区报告的 8-12% 区间。 注意：这个差距在低端硬件（如 8G 显卡）上会更小，因为瓶颈更多在显存容量而非计算速度。

9.4 选型决策树

用下面这个决策树，30 秒决定该用哪一个：

你的主要需求是什么？
│
├─ "我就想赶紧用上 AI，别让我折腾"
│ └─ → 选 Ollama ✅
│
├─ "我是开发者，想要最大控制权"
│ └─ → 选 llama.cpp ✅
│
├─ "我要在 AMD / Intel 显卡上跑"
│ └─ → 选 llama.cpp（Vulkan 后端）✅
│
├─ "我要做性能 Benchmark / 横向对比"
│ └─ → 选 llama.cpp（llama-bench 工具）✅
│
├─ "我要集成到现有应用，需要 OpenAI 兼容 API"
│ └─ → 两个都可以，Ollama 稍微省事 ✅
│
├─ "我是纯新手 + Windows + 不想学命令行"
│ └─ → 选 Ollama ✅
│
├─ "我要做模型量化、格式转换、自定义推理管线"
│ └─ → 选 llama.cpp ✅
│
└─ "我既想省事又想极致性能"
└─ → 选 Ollama 入门，熟悉后用 llama.cpp 进阶 ✅

9.5 终极建议：两个都用

其实 Ollama 和 llama.cpp 不是"你死我活"的关系。事实上：

Ollama 底层用的就是 llama.cpp 引擎。

它们是同一技术栈的不同封装层级：

• Ollama 封装了 llama.cpp，给它套上了易用的外壳
• llama.cpp 是更底层、更自由的原始引擎

推荐的使用策略：

具体分工建议：

• 日常聊天、写作、翻译 → 用 Ollama，省心省力
• 代码开发、嵌入向量提取、批量处理 → 用 llama.cpp，性能更高
• 模型评测、量化实验、格式转换 → 必须用 llama.cpp，这是它独有的能力
• 搭建团队共享 AI 服务 → 用 llama.cpp 的 llama-server，部署更灵活

小结：

一句话总结：Ollama 让你快速起步，llama.cpp 让你走得更远。如果你有时间，先学 Ollama 建立信心，再学 llama.cpp 拓展能力边界——两把刀都磨，才是本地 AI 玩家的完全体。

快速上手 Checklist

• 安装编译工具链（gcc/msvc + cmake + git）
• （GPU 用户）安装 NVIDIA 驱动 + CUDA Toolkit 12.x
• git clone –recurse-submodules https://github.com/ggml-org/llama.cpp
• cd llama.cpp
• cmake -B build -DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=ON -DGGML_CUDA_ARCHITECTURES="你的架构代码"
• cmake –build build –config Release -j$(nproc)
• 下载 GGUF 模型到 ./models/ 目录
• 测试：./build/bin/llama-cli -m ./models/model.gguf -p "Hello" -n 50 -ngl 99
• 启动服务：./build/bin/llama-server -m ./models/model.gguf -ngl -1 -c 8192 –host 0.0.0.0
• 浏览器访问 http://127.0.0.1:8080

参考资源：

• 官方仓库：https://github.com/ggml-org/llama.cpp
• 参数文档：https://github.com/ggml-org/llama.cpp/blob/master/examples/server/README.md
• HuggingFace GGUF 文档：https://huggingface.co/docs/hub/gguf-llamacpp
• CUDA 下载：https://developer.nvidia.com/cuda-downloads