llama.cpp 本地部署完全指南：从安装到 OpenAI 兼容 API 服务

七牛云行业应用2026-08-13 10:59

发布日期：2026-08-12 | 数据来源：llama.cpp 官方 GitHub（ggml-org/llama.cpp）文档、官方 install.md / build.md / server 文档 | 话题：llama.cpp · 本地大模型 · GGUF · llama-server

llama.cpp 是由 Georgi Gerganov 开发的高性能大模型推理框架，以纯 C/C++ 实现、零外部依赖著称，支持 1.5 到 8 位整数量化，可在笔记本 CPU 上运行 7B 模型，也可通过 CUDA / Metal / Vulkan 将推理卸载到 GPU 加速；截至 2026 年 8 月最新版本 b10369（123k+ Stars），项目已从早期仅支持 LLaMA 系列发展为覆盖 Qwen3、DeepSeek、Kimi K3、GLM 等主流开源模型的通用推理引擎，内置 llama-server 可一键暴露 OpenAI 兼容 REST API，让本地模型无缝替换云端 API；本文覆盖三平台（macOS / Linux / Windows）的安装方式、GPU 加速编译、GGUF 模型选择、llama-server 生产配置，以及常见显存不足场景的调参策略。

llama.cpp 是什么，和 Ollama 有什么区别

llama.cpp 是底层推理引擎，直接操作 GGUF 量化格式的模型文件，提供命令行工具和 REST API，适合需要精细控制推理参数、自行集成 API 服务的开发者。

Ollama 是对 llama.cpp 的高层封装（macOS 版已从 llama.cpp 迁移至 Apple MLX，2026 年 3 月），提供更简单的模型管理命令（ollama pull/ollama run），适合快速上手但不需要调参的场景。

关系：学 llama.cpp = 学底层，理解量化、层卸载、KV Cache 等机制；用 Ollama = 黑盒使用，两者都基于 GGUF 格式，模型文件通用。

安装：三平台最快路径

macOS（推荐 Homebrew）

bash 复制代码 
brew install llama.cpp

Homebrew 版本随官方 Release 自动更新，包含 Metal GPU 加速支持（Apple Silicon 默认启用）。

验证安装：

bash 复制代码 
llama-cli --version
llama-server --version

Linux

bash 复制代码 
# conda-forge（包含 CUDA / Vulkan 版本）
conda install -c conda-forge llama.cpp

# 或 Homebrew（Linux 同样支持）
brew install llama.cpp

Windows（三种方式，任选其一）

方式一：Winget（最简单）

powershell 复制代码 
winget install llama.cpp

方式二：GitHub Release 预编译包（推荐，按显卡选版本）

前往 https://github.com/ggml-org/llama.cpp/releases 下载对应版本：

你的显卡 下载哪个包
NVIDIA GPU llama-bXXXXX-bin-win-cuda-cu12.4-x64.zip
AMD GPU llama-bXXXXX-bin-win-vulkan-x64.zip
Intel Arc llama-bXXXXX-bin-win-vulkan-x64.zip
仅 CPU llama-bXXXXX-bin-win-cpu-x64.zip

下载后解压，在解压目录直接运行 llama-server.exe，无需安装。

方式三：从源码编译（需要 GPU 加速时）

从源码编译：GPU 加速版本

包管理器安装的版本已包含对应平台的 GPU 加速，若需要手动编译：

NVIDIA CUDA 加速（Linux / Windows）

前提：安装 CUDA Toolkit（12.x 推荐）

bash 复制代码 
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j 8

Apple Silicon Metal 加速（macOS）

Metal 默认启用，无需额外参数：

bash 复制代码 
cmake -B build
cmake --build build --config Release -j 8

AMD GPU（Vulkan，跨平台）

bash 复制代码 
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release -j 8

编译完成后，可执行文件在 build/bin/ 目录下。

获取模型：GGUF 格式和量化选择

llama.cpp 只能运行 GGUF 格式的量化模型。

从 HuggingFace 下载（命令行直接拉取）

bash 复制代码 
# 直接运行 HuggingFace 上的 GGUF 模型（自动下载）
llama-cli -hf ggml-org/Qwen3.5-0.8B-GGUF

也可以手动下载 GGUF 文件：

bash 复制代码 
# 安装 huggingface_hub
pip install huggingface_hub

# 下载指定量化版本
huggingface-cli download \
  Qwen/Qwen3-8B-GGUF \
  qwen3-8b-q4_k_m.gguf \
  --local-dir ./models

量化版本怎么选

GGUF 文件名中的量化标识对应不同的精度和内存需求，以 7B/8B 模型为例：

量化类型 模型大小（7B） 所需内存 推荐场景
Q2_K ~3 GB 4 GB+ 内存极限，质量较差
Q4_K_S ~4.5 GB 6 GB+ 内存受限但可接受质量
Q4_K_M ~5 GB 6--8 GB+ 日常使用推荐
Q5_K_M ~5.7 GB 8 GB+ 质量更好，稍大
Q8_0 ~8 GB 10 GB+ 接近原精度，大内存可选
F16 ~14 GB 16 GB+ 开发/评测，不量化

命名规则：Q{位数}_K_{规格} 中，K 表示 K-quant 方法（比同位数的旧方法精度更高），M 是中等（Medium），S 是小（Small），L 是大（Large）。通常首选 Q4_K_M，在文件大小和输出质量之间平衡最优。

各参数量对应内存需求（Q4_K_M）

模型参数量 GGUF 大小 最低显存 / 内存
1B--3B 1--2 GB 4 GB
7B--8B 4--5 GB 6 GB
14B 8--9 GB 10 GB
27B--32B 15--18 GB 20 GB
70B 38--42 GB 48 GB（或多 GPU）

估算公式：参数量（B）× 量化位数 / 8 × 1.2（KV Cache + 框架开销）

基础推理：llama-cli

bash 复制代码 
# 单次问答
llama-cli -m ./models/qwen3-8b-q4_k_m.gguf \
  -p "用一句话解释什么是量化"

# 交互式对话模式
llama-cli -m ./models/qwen3-8b-q4_k_m.gguf \
  -i -ins

# 全 GPU 推理（-ngl 999 = 所有层卸载到 GPU）
llama-cli -m ./models/qwen3-8b-q4_k_m.gguf \
  -ngl 999 \
  -p "写一个快速排序的 Python 实现"

常用参数说明：

参数 含义
-m <路径> 指定 GGUF 模型文件路径
-ngl N 将 N 层卸载到 GPU（越大越快，受显存限制）
-c N 上下文长度（默认 4096，设越大占 KV Cache 越多）
-n N 最大生成 token 数
-t N CPU 线程数（纯 CPU 推理时调整）
--flash-attn 启用 Flash Attention（降低 KV Cache 显存占用）
-i -ins 进入交互式指令跟随模式

llama-server：一键启动 OpenAI 兼容 API

这是 llama.cpp 最重要的功能之一：启动一个完全兼容 OpenAI API 格式的本地 HTTP 服务，现有接入 OpenAI 的代码只需改 base_url 即可指向本地。

基础启动

bash 复制代码 
llama-server \
  -m ./models/qwen3-8b-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 999

启动后：

  • 内置 Web UI：http://localhost:8080
  • API 端点：http://localhost:8080/v1/chat/completions
  • 模型列表：http://localhost:8080/v1/models

生产配置（多并发 + Flash Attention）

bash 复制代码 
llama-server \
  -m ./models/qwen3-8b-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 999 \
  -c 8192 \
  --parallel 4 \
  --flash-attn \
  --api-key "your-local-key"
参数 说明
-c 8192 总上下文长度（被并发 slot 均分）
--parallel 4 并发推理槽数（同时处理 4 个请求）
--flash-attn Flash Attention，减少 KV Cache 显存 30--50%
--api-key 设置访问鉴权 Key（对外暴露时必须设置）

用 OpenAI SDK 调用本地服务

python 复制代码 
from openai import OpenAI

client = OpenAI(
    api_key="your-local-key",        # 与 --api-key 一致，不鉴权时填任意字符串
    base_url="http://localhost:8080/v1",
)

completion = client.chat.completions.create(
    model="qwen3-8b-q4_k_m",        # 填 model 名（llama-server 自动识别）
    messages=[
        {"role": "system", "content": "你是一位专业的代码审查工程师。"},
        {"role": "user", "content": "帮我审查这段 Python 代码：..."},
    ],
)
print(completion.choices[0].message.content)

Node.js 同样适用，只需将 baseURL 指向 http://localhost:8080/v1。

显存不足怎么办：层卸载调参

llama.cpp 的核心优势之一是 CPU+GPU 混合推理 ：当显存不够装下整个模型时，可以通过 -ngl 控制卸载到 GPU 的层数，剩余层在 CPU 内存中运行，速度下降但不会崩溃。

调参策略：

bash 复制代码 
# 先试全量 GPU（-ngl 999），如果 OOM：
llama-server -m model.gguf -ngl 999    # OOM？

# 逐步降低 -ngl 值，找到不 OOM 的最大值
llama-server -m model.gguf -ngl 32     # 32 层到 GPU，其余 CPU
llama-server -m model.gguf -ngl 20     # 继续降低

其他节省显存的手段：

  1. 选更低量化版本：Q4_K_S 比 Q4_K_M 小约 10%
  2. 缩减上下文 ：-c 2048 比 -c 8192 节省约 75% KV Cache 显存
  3. 启用 Flash Attention ：--flash-attn，KV Cache 显存减少约 30--50%
  4. 使用更小参数量模型：3B 量化版比 7B 显存需求减半

多 GPU 配置

多张 NVIDIA GPU 时，llama.cpp 默认在全部可用 GPU 上均匀分层。可以通过 CUDA_VISIBLE_DEVICES 环境变量控制使用哪几张：

bash 复制代码 
# 只使用 GPU 0 和 GPU 1
CUDA_VISIBLE_DEVICES=0,1 llama-server -m model.gguf -ngl 999

多 GPU 拆分模式详见官方 docs/multi-gpu.md。

常见问题

Q：GGUF 文件去哪里下载？

主要来源：HuggingFace（huggingface.co）搜索模型名 + GGUF，通常找 ggml-org/、bartowski/ 或模型原始仓库下的 GGUF 分支；国内可通过 ModelScope（modelscope.cn）镜像下载，速度更快。

Q：-ngl 999 和 -ngl 0 有什么区别？

-ngl 999 = 尽可能多地把模型层卸载到 GPU（受显存限制自动截断）；-ngl 0 = 全 CPU 推理，完全不使用 GPU。通常设 -ngl 999 让 llama.cpp 自动决定能卸多少层。

Q：llama-server 启动后 Web UI 没有响应？

检查：①--host 是否写了 0.0.0.0（默认 127.0.0.1 不对外）；②端口是否被占用（换 --port 8081）；③设了 --api-key 但浏览器没有带 Token 访问。

Q：模型输出是乱码或者语言错误？

通常是 -c 上下文设置过小（被截断）或者系统提示词语言与用户语言不一致。另外部分模型有 chat_template，使用 -i -ins 参数确保使用了正确的对话格式。

Q：llama.cpp 和 vLLM 怎么选？

llama.cpp：单机本地部署、显存有限、需要量化、以 GGUF 为格式，适合个人开发者和边缘设备；vLLM：高并发生产服务、A100/H100 级 GPU、需要 PagedAttention 提升吞吐量，适合企业规模推理服务。两者定位不同，llama.cpp 在资源受限场景下是首选。

Q：企业有 GPU 服务器但不想自己维护推理服务，有什么替代方案？

可以选择支持多家国产开源模型的 API 平台，统一 OpenAI 格式接入，无需维护推理基础设施。代码调用方式与 llama-server 相同，只需将 base_url 和 api_key 替换为平台提供的值（如七牛云 Token Plan，qiniu.com/ai/plan，覆盖 DeepSeek / Kimi / GLM / MiniMax 四家共 25 个模型）。

小结

llama.cpp 是当前最成熟的本地大模型推理引擎：安装方面，macOS 用 brew install llama.cpp，Windows 用 Winget 或 GitHub Release 预编译包，10 分钟内可完成部署；模型方面，Q4_K_M 是性价比最高的量化选择，6--8 GB 显存可流畅运行 7B 模型；API 服务方面，llama-server 一行命令启动 OpenAI 兼容接口，现有代码零改动接入本地；性能不足时，先用 --flash-attn 降 KV Cache 开销，再用 -ngl 混合 CPU/GPU 推理，几乎在所有硬件上都能找到可用配置。

本文基于 llama.cpp b10369（2026-08-12），项目更新活跃，最新参数以官方 GitHub 文档为准。

延伸阅读

相关推荐
星马梦缘1 小时前
人工智能学院科协 · 2026秋季学期工作安排说明
人工智能·智能硬件
赵庆明老师1 小时前
RH7.6安装 llama.cpp（普通用户，无sudo权限）
llama
zhangfeng11331 小时前
CodeBuddy 切换账号后对话历史“消失“解决办法。找回历史记录
人工智能
AI服务老曹1 小时前
AI视频分析API完整流程：设备、算法与告警接口接入指南
人工智能·算法·音视频
watersink1 小时前
机器学习LDA
人工智能·机器学习
蓝狐社2 小时前
AI这艘船，谁在划桨，谁在凿洞？
人工智能
GlobalInfo2 小时前
AI与另类数据融合，市场研究正在从“经验驱动”走向“数据智能”
大数据·网络·人工智能·ai
AImoon11.12 小时前
MiniMax H3开源引发视频赛道变局，客易云关注AI模型从生成工具迈向生产力工具
人工智能·音视频
XMAIPC_Robot2 小时前
RK3588+STM32：高性能机器人运动控制解决方案，兼顾实时性与AI算力
人工智能·stm32·嵌入式硬件·算法·fpga开发·机器人·arm+fpga
vivo互联网技术2 小时前
MagicBokeh：单步统一生成式框架实现真实感长焦虚化渲染 | CVPR 2026 Oral
人工智能·算法
热门推荐
01GitHub 镜像站点02VSCode+CodeX扩展，无法启动03国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）042026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路07历年考研数学一、数学二、数学三真题试卷及答案PDF08Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费09如何新建文件夹？ 电脑新建文件夹的4种方法102026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片