llama.cpp：纯 C/C++ 高效本地大模型推理引擎｜部署与使用全指南

llama.cpp（llama-server / llama-cli / llama-quantize）—— 纯 C/C++ 的高效本地 LLM 推理引擎

适用环境：Windows 10/11 原生、Windows 10/11 + WSL2（Ubuntu 24.04）、NVIDIA RTX 3070 8GB / RTX 4090 24GB，以及 Linux 云服务器。 信息口径：本章命令、编译参数、工具名、参数与端点均来自 llama.cpp 官方仓库 README、docs/build.md、docs/models.md、tools/server/README.md、tools/cli/README.md、tools/quantize/README.md 与官方 release 资产清单；核验日期 2026-10-25。

项目定位与基本信息

官方图片

下图为官方 README 内嵌的两张官方截图（非 AI 生成、非第三方图）：左为 llama cli 的 VLM 会话界面，右为 llama serve 内置 Web UI。

图 1：llama cli 命令行会话（官方 README 截图）

• 图片来源 URL：https://github.com/user-attachments/assets/88726b48-1713-48aa-a525-95a02e78afc4（README 原文 alt：VLM session with 'llama cli'，2026-10-25 curl -L 下载）。
• 本地路径：https://zhouruolin.cn/upload/02_llamacpp_cli_screenshot.png；file 校验：PNG image data, 2782 x 2014, 8-bit/color RGBA，317,242 字节（>20KB）。

图 2：llama serve 内置 Web UI（官方 README 截图）

• 图片来源 URL：https://github.com/user-attachments/assets/b402f972-2e32-4def-8771-8d849f08cf2e（README 原文 alt：Built-in web UI against 'llama serve' running Qwen 3.6，2026-10-25 curl -L 下载）。
• 本地路径：https://zhouruolin.cn/upload/02_llamacpp_webui_screenshot.png；file 校验：PNG image data, 2784 x 1916, 8-bit/color RGBA，688,668 字节（>20KB）。

环境要求

来源：docs/build.md（CPU/CUDA 构建与计算能力表）、README.md（支持后端、量化档位、CPU+GPU 混合推理）、tools/quantize/README.md（量化工具内存/磁盘要求）、tools/server/README.md（默认端口与后端能力）。

RTX 3070 8GB 与 RTX 4090 24GB 编译参数对照（来源：docs/build.md “Override Compute Capability Specifications”，官方示例即列出 RTX 3070=8.6、RTX 4090=8.9）：

最详细部署步骤（Windows 预编译 与 WSL2 源码编译 两种视角）

依赖安装

A. Windows 10/11 原生（预编译 CUDA 包路线）

1. 安装 NVIDIA 显卡最新驱动，设备管理器 / nvidia-smi 确认显卡被识别。
2. 无需安装 Visual Studio、CMake 或 CUDA Toolkit（预编译包自带后端运行时）。
3. 准备模型目录，例如 D:\llm\models\，用于存放 GGUF 文件。

B. WSL2（Ubuntu 24.04）源码编译路线

1. Windows 侧安装 NVIDIA 驱动；进入 WSL2 执行 nvidia-smi，确认能看到显卡与 CUDA Version（WSL2 直通由 Windows 驱动提供，不要在 Windows 上装 CUDA Toolkit 来给 WSL2 编译用，编译工具链要装在 WSL2 内）。
2. 在 WSL2 内安装 CUDA Toolkit（含 nvcc，官方下载入口 https://developer.nvidia.com/cuda-toolkit），安装后 nvcc --version 可执行。
3. 安装编译基础工具（Git、CMake、C++ 工具链、Ninja；Debian/Ubuntu 常用命令）：

sudo apt-get update
sudo apt-get install -y git cmake g++ build-essential ninja-build libssl-dev

说明：上面的 apt-get 包名是 Ubuntu 通用开发工具链；llama.cpp 官方 docs/build.md 只规定了 git clone + CMake 构建流程与 CUDA Toolkit 前提，未直接给出该 apt-get 清单。

项目下载 / 安装（预编译包、一键脚本、源码三种官方方式）

方式一：Windows 官方预编译包（Nightly b11874，2026-10-25 资产清单核验）

• 发布页：https://github.com/ggml-org/llama.cpp/releases
• NVIDIA CUDA 12.4 x64 包直链（HTTP 200 已核验）： https://github.com/ggml-org/llama.cpp/releases/download/b11874/llama-b11874-bin-win-cuda-12.4-x64.zip
• 同清单备选：CPU 包 llama-b11874-bin-win-cpu-x64.zip、CUDA 13.4 包 llama-b11874-bin-win-cuda-13.4-x64.zip、Vulkan 包 llama-b11874-bin-win-vulkan-x64.zip。

下载解压后，在解压目录内查找以下官方 CMake 目标对应的可执行文件（来源：各 tools/*/CMakeLists.txt）：

方式二：官方一键脚本（README Quick start，https://llama.app）

# Linux / macOS（README 原文：curl -LsSf https://llama.app/install.sh | sh）
curl -LsSf https://llama.app/install.sh | sh

# Windows PowerShell（README 原文：irm https://llama.app/install.ps1 | iex）
irm https://llama.app/install.ps1 | iex

脚本安装的是统一命令 llama，子命令为 llama cli 与 llama serve（README 示例：llama cli -hf ggml-org/Qwen3.5-0.8B-GGUF、llama serve -hf ggml-org/Qwen3.5-0.8B-GGUF）。

方式三：WSL2 / Linux 源码编译（官方 docs/build.md）

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# CPU 构建（官方 CPU Build 命令）
cmake -B build
cmake --build build --config Release

# CUDA 构建（官方 CUDA 节命令）
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

RTX 3070 / 4090 指定架构（官方 “Override Compute Capability Specifications”）：

# 单卡 RTX 3070（86）
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="86"
cmake --build build --config Release -j"$(nproc)"

# 单卡 RTX 4090（89）
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="89"
cmake --build build --config Release -j"$(nproc)"

# 两机通用（86 + 89）
cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="86;89"
cmake --build build --config Release -j"$(nproc)"

只构建服务器目标（官方 tools/server/README.md Build 节）：

cmake -B build
cmake --build build --config Release -t llama-server
# 产物：./build/bin/llama-server

可选：为覆盖所有 CUDA GPU（非原生机器）禁用原生优化：cmake -B build -DGGML_CUDA=ON -DGGML_NATIVE=OFF（docs/build.md “Non-Native Builds”）。需要 OpenSSL/SSL 支持时：cmake -B build -DLLAMA_OPENSSL=ON（tools/server/README.md “Build with SSL”）。

产物位置（官方文档）：./build/bin/llama-server、./build/bin/llama-cli、./build/bin/llama-quantize。

模型 / 权重下载（官方链接 + 国内加速方案）

A. 官方 -hf 直连 Hugging Face（docs/models.md、tools/server/README.md -hf 参数）

# 官方 README Quick start 示例仓库；量化档大小写不敏感，默认 Q4_K_M
./build/bin/llama-cli -hf ggml-org/Qwen3.5-0.8B-GGUF
./build/bin/llama-server -hf ggml-org/Qwen3.5-0.8B-GGUF

B. 官方 MODEL_ENDPOINT 兼容端点（docs/models.md 原文：You can use the same CLI invocation to download from other sites, by pointing the MODEL_ENDPOINT environment variable to an endpoint compatible with the Hugging Face API.）

# 指向兼容 Hugging Face API 的镜像端点（端点需自行确认兼容性）
export MODEL_ENDPOINT=https://hf-mirror.com
./build/bin/llama-server -hf Qwen/Qwen3-8B-GGUF:Q4_K_M

说明：hf-mirror.com 为第三方国内镜像站（非 llama.cpp / Hugging Face 官方），MODEL_ENDPOINT 仅要求端点兼容 HF API；若镜像路径不兼容，改用下面的“手动下载 + 本地路径”方案最稳妥。

C. 手动下载 GGUF + 本地路径加载（离线 / 慢网络最稳妥方案）

1. 在可访问渠道（浏览器、huggingface-cli 或 ModelScope 镜像，见 03 章）下载目标 .gguf，例如 Qwen3-8B-Q4_K_M.gguf。
2. 用 -m/--model 指定本地文件（tools/server/README.md 参数表）：

# Linux / WSL2
./build/bin/llama-server -m /home/user/models/Qwen3-8B-Q4_K_M.gguf --host 0.0.0.0 --port 8080

# Windows 预编译包
llama-server.exe -m models\Qwen3-8B-Q4_K_M.gguf -c 4096

3. 走代理时，启动前导出 HTTPS_PROXY / HTTP_PROXY（tools/server/README.md “Running behind a proxy”：export HTTPS_PROXY=http://proxy.example.com:8080，NO_PROXY 与回环地址直连）。

D. 本地转 GGUF 与重新量化（官方 tools/quantize/README.md）

# 1) 安装 Python 依赖
python3 -m pip install -r requirements.txt

# 2) HF 模型转 BF16 GGUF（官方示例命令格式）
python convert_hf_to_gguf.py --outfile model-bf16.gguf --outtype bf16 --remote org/model

# 3) 量化为 Q4_K_M（官方新格式命令）
./build/bin/llama-quantize model-bf16.gguf model-Q4_K_M.gguf Q4_K_M

# 旧格式（官方 Quantization Examples 兼容写法，最后一位为线程数）
./llama-quantize input-model-f32.gguf q4_k_m 8

关键配置（参数 / 环境变量表）

下列参数全部来自 tools/server/README.md 与 tools/cli/README.md 自动生成的参数表；带 (env: ...) 的参数也可用同名 LLAMA_ARG_* 环境变量设置。命令行参数优先于环境变量（tools/server/README.md 注释：命令行与环境变量同时设置时，参数优先）。

启动

Windows 预编译包（在解压目录下，PowerShell）：

# 启动服务器，本地模型，监听 127.0.0.1:9931（默认）
.\llama-server.exe -m models\Qwen3-8B-Q4_K_M.gguf -c 4096

# 指定对外地址与端口、全层卸载到 GPU
.\llama-server.exe -m models\Qwen3-8B-Q4_K_M.gguf --host 0.0.0.0 --port 8080 -ngl 99 -c 4096

WSL2 / Linux 源码编译产物：

# 查看可用设备（官方 --list-devices）
./build/bin/llama-server --list-devices

# CUDA 服务器启动示例（官方 Docker 示例同参数族）
./build/bin/llama-server -m models/Qwen3-8B-Q4_K_M.gguf \
  --host 0.0.0.0 --port 8080 \
  --n-gpu-layers 99 -c 4096 -fa

# 命令行对话（官方 cli README 模式）
./build/bin/llama-cli -m models/Qwen3-8B-Q4_K_M.gguf --jinja --color -ngl 99 -c 4096

官方 Docker 路线（docs/docker.md、tools/server/README.md Docker 示例）：

# CPU 镜像：仅含 llama-server
docker run -p 8080:8080 -v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:server \
  -m models/7B/ggml-model.gguf -c 512 --host 0.0.0.0 --port 8080

# CUDA 镜像（CUDA 12 编译），需 --gpus all
docker run -p 8080:8080 -v /path/to/models:/models --gpus all \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/7B/ggml-model.gguf -c 512 --host 0.0.0.0 --port 8080 --n-gpu-layers 99

镜像清单（docs/docker.md）：full（cli + completion + 转换/量化工具）、light（cli + completion）、server（仅 llama-server）；后缀 -cuda（CUDA 12）、-cuda13、-rocm、-vulkan、-musa、-intel；基础镜像平台为 linux/amd64、linux/arm64，full/light/server 另提供 linux/s390x，部分后端镜像仅 linux/amd64，以 docs/docker.md 清单为准。

使用方法

启动方式

界面 / 命令行操作步骤（带示例）

A. llama-cli 命令行对话（tools/cli/README.md；参数表见 02.4.4）

# 本地模型 + Jinja 模板 + 着色 + 全层 GPU 卸载 + Flash Attention + 8K 上下文
./build/bin/llama-cli \
  -m models/Qwen3-8B-Q4_K_M.gguf \
  --jinja --color \
  -ngl 99 -fa \
  -sm row \
  -c 8192 \
  --system-prompt "You are a concise assistant."

交互常用开关：

B. llama-server 内置 Web UI 与 HTTP 接口（tools/server/README.md）

1. 启动服务器（见 02.4.5）。
2. 浏览器打开 http://127.0.0.1:9931/（自定义 --port 后用对应端口），使用内置 Web UI 对话。
3. 其他前端（如 Open WebUI）通过 OpenAI 兼容接口接入：Base URL 填 http://<服务器IP>:<端口>/v1，API Key 任意填写（未启用 --api-key 时不校验）。 - 对接依据：llama.cpp 服务器提供 OpenAI 兼容 chat/completions 等路由（tools/server/README.md Features 与 “OpenAI-compatible API Endpoints”）；Open WebUI README 明确支持接入任意 OpenAI 兼容 API：https://github.com/open-webui/open-webui。

服务端 API 端点表（tools/server/README.md “API Endpoints”）

端到端示例（输入 → 命令 → 输出）

场景：RTX 3070 8GB，WSL2 源码编译 CUDA 版，本地 GGUF Qwen3-8B-Q4_K_M.gguf（体积见 03 章），启动 OpenAI 兼容服务器并完成一次对话。

第 1 步：启动服务器

cd ~/llama.cpp
./build/bin/llama-server \
  -m ~/models/Qwen3-8B-Q4_K_M.gguf \
  --host 0.0.0.0 --port 8080 \
  -ngl 99 -c 8192 -fa \
  --jinja --alias qwen3-8b

启动日志关键行（结构示意，tools/server/README.md 默认参数）：监听 http://0.0.0.0:8080，模型全层卸载，上下文 8192，Web UI 开启。

第 2 步：健康检查

curl http://localhost:8080/health
# 就绪返回：{"status": "ok"}

第 3 步：OpenAI 兼容聊天请求（tools/server/README.md 官方 curl 示例格式）

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "qwen3-8b",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "用三句话介绍你自己。"}
    ]
  }'

返回（OpenAI 兼容结构，字段说明见 /v1/chat/completions 文档；content 为模型回答）：

{
  "object": "chat.completion",
  "model": "qwen3-8b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我是基于 Qwen3 系列的本地大模型，运行在 llama.cpp 推理引擎上。\n我的回答由本地显卡完成计算，不上传对话内容到云端。\n你可以直接在命令行或浏览器里向我提问。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 24, "completion_tokens": 66, "total_tokens": 90}
}

Python openai SDK 接入（官方 /v1/chat/completions 文档示例，Base URL 替换为本机地址）：

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required"
)

completion = client.chat.completions.create(
    model="qwen3-8b",
    messages=[{"role": "user", "content": "用三句话介绍你自己。"}]
)
print(completion.choices[0].message.content)

常见坑（现象 + 原因 + 解决）

1. 现象：CUDA 编译时报 nvcc warning : Cannot find valid GPU for '-arch=native', default arch is used，或编译产物只能用 CPU。 - 原因：docs/build.md “Override Compute Capability Specifications” 指出，nvcc 无法探测到本机 GPU 时会回退默认架构；非原生机器 / 多卡混合场景需要显式指定架构。 - 解决：按官方方式指定 -DCMAKE_CUDA_ARCHITECTURES="86;89"（RTX 3070=86、RTX 4090=89）；或 -DGGML_NATIVE=OFF 做覆盖全架构的非原生构建。

2. 现象：llama-server / llama-cli 启动后全程跑在 CPU，生成很慢。 - 原因：使用了 CPU 版压缩包；或 -ngl 未设置 / 被 -dev none 限制；CUDA 后端未编译进二进制；WSL2 内 nvidia-smi 不可用。 - 解决：核对下载的是 bin-win-cuda-12.4-x64.zip（或源码 -DGGML_CUDA=ON 编译）；先执行 --list-devices 查看设备；启动时加 -ngl 99（全部层卸载）；WSL2 先确认 nvidia-smi 正常。

3. 现象：对话输出乱码、角色标记错乱、系统提示词不生效。 - 原因：模型自带聊天模板未被正确使用；/v1/chat/completions 要求模型具备受支持的聊天模板（tools/server/README.md 提示：不支持的模型将默认使用 ChatML 模板）。 - 解决：保持 --jinja 默认启用；必要时用 --chat-template / --chat-template-file 指定模板；模板支持清单参考官方 Wiki：https://github.com/ggml-org/llama.cpp/wiki/Templates-supported-by-llama_chat_apply_template（tools/server/README.md 内链）。

4. 现象：端口 9931（或自定义端口）被占用，服务器启动失败。 - 原因：本机已有其他进程占用端口；或上一个 llama-server 实例未退出。 - 解决：--port 指定其他端口（如 8080）；排查占用进程；检查 --host 绑定地址是否与其他服务冲突。

5. 现象：-hf 拉取模型超时、中断或报网络错误。 - 原因：Hugging Face 在国内网络访问不稳定；代理未配置。 - 解决：优先“手动下载 GGUF + -m 本地路径”（02.4.3 方案 C）；或用 MODEL_ENDPOINT 指向兼容 HF API 的镜像；tools/server/README.md “Running behind a proxy” 要求下载模型前先导出 HTTP_PROXY 与 HTTPS_PROXY（NO_PROXY 与回环地址直连）。

6. 现象：llama-quantize 阶段内存不足、进程被杀，或磁盘写满。 - 原因：官方 “Memory/Disk Requirements” 说明：模型当前整体载入内存，内存与磁盘需求相同；原始 F32/BF16 体积很大（官方参考 Llama-3.1-8B 原始 32.1GB）。 - 解决：留出与原始模型相当的 RAM 与磁盘；优先从已有 16bit 模型量化；不要反复对已量化文件再量化（--allow-requantize 会明显损失质量，tools/quantize/README.md 已警告）；需要更优质量时配合 --imatrix 重要性矩阵。

本节来源清单

验证方式：curl 200 = 命令行 HTTP 状态码核验；web_fetch / 源码核对 = 已下载官方原始文件逐条核对；general_search = 搜索索引佐证。核验日期 2026-10-25。