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

发布日期2026-08-12 | 数据来源llama.cpp 官方 GitHubggml-org/llama.cpp文档、官方 install.md / build.md / server 文档 | 话题llama.cpp · 本地大模型 · GGUF · llama-serverllama.cpp 是由 Georgi Gerganov 开发的高性能大模型推理框架以纯 C/C 实现、零外部依赖著称支持 1.5 到 8 位整数量化可在笔记本 CPU 上运行 7B 模型也可通过 CUDA / Metal / Vulkan 将推理卸载到 GPU 加速截至 2026 年 8 月最新版本 b10369123k 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 MLX2026 年 3 月提供更简单的模型管理命令ollama pull/ollama run适合快速上手但不需要调参的场景。关系学 llama.cpp 学底层理解量化、层卸载、KV Cache 等机制用 Ollama 黑盒使用两者都基于 GGUF 格式模型文件通用。安装三平台最快路径macOS推荐 Homebrewbrewinstallllama.cppHomebrew 版本随官方 Release 自动更新包含 Metal GPU 加速支持Apple Silicon 默认启用。验证安装llama-cli--versionllama-server--versionLinux# conda-forge包含 CUDA / Vulkan 版本condainstall-cconda-forge llama.cpp# 或 HomebrewLinux 同样支持brewinstallllama.cppWindows三种方式任选其一方式一Winget最简单winget install llama.cpp方式二GitHub Release 预编译包推荐按显卡选版本前往 https://github.com/ggml-org/llama.cpp/releases 下载对应版本你的显卡下载哪个包NVIDIA GPUllama-bXXXXX-bin-win-cuda-cu12.4-x64.zipAMD GPUllama-bXXXXX-bin-win-vulkan-x64.zipIntel Arcllama-bXXXXX-bin-win-vulkan-x64.zip仅 CPUllama-bXXXXX-bin-win-cpu-x64.zip下载后解压在解压目录直接运行llama-server.exe无需安装。方式三从源码编译需要 GPU 加速时从源码编译GPU 加速版本包管理器安装的版本已包含对应平台的 GPU 加速若需要手动编译NVIDIA CUDA 加速Linux / Windows前提安装 CUDA Toolkit12.x 推荐gitclone https://github.com/ggml-org/llama.cppcdllama.cpp cmake-Bbuild-DGGML_CUDAON cmake--buildbuild--configRelease-j8Apple Silicon Metal 加速macOSMetal 默认启用无需额外参数cmake-Bbuild cmake--buildbuild--configRelease-j8AMD GPUVulkan跨平台cmake-Bbuild-DGGML_VULKANON cmake--buildbuild--configRelease-j8编译完成后可执行文件在build/bin/目录下。获取模型GGUF 格式和量化选择llama.cpp 只能运行 GGUF 格式的量化模型。从 HuggingFace 下载命令行直接拉取# 直接运行 HuggingFace 上的 GGUF 模型自动下载llama-cli-hfggml-org/Qwen3.5-0.8B-GGUF也可以手动下载 GGUF 文件# 安装 huggingface_hubpipinstallhuggingface_hub# 下载指定量化版本huggingface-cli download\Qwen/Qwen3-8B-GGUF\qwen3-8b-q4_k_m.gguf\--local-dir ./models量化版本怎么选GGUF 文件名中的量化标识对应不同的精度和内存需求以 7B/8B 模型为例量化类型模型大小7B所需内存推荐场景Q2_K~3 GB4 GB内存极限质量较差Q4_K_S~4.5 GB6 GB内存受限但可接受质量Q4_K_M~5 GB6–8 GB日常使用推荐Q5_K_M~5.7 GB8 GB质量更好稍大Q8_0~8 GB10 GB接近原精度大内存可选F16~14 GB16 GB开发/评测不量化命名规则Q{位数}_K_{规格}中K表示 K-quant 方法比同位数的旧方法精度更高M是中等MediumS是小SmallL是大Large。通常首选 Q4_K_M在文件大小和输出质量之间平衡最优。各参数量对应内存需求Q4_K_M模型参数量GGUF 大小最低显存 / 内存1B–3B1–2 GB4 GB7B–8B4–5 GB6 GB14B8–9 GB10 GB27B–32B15–18 GB20 GB70B38–42 GB48 GB或多 GPU估算公式参数量B× 量化位数 / 8 × 1.2KV Cache 框架开销基础推理llama-cli# 单次问答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 所有层卸载到 GPUllama-cli-m./models/qwen3-8b-q4_k_m.gguf\-ngl999\-p写一个快速排序的 Python 实现常用参数说明参数含义-m 路径指定 GGUF 模型文件路径-ngl N将 N 层卸载到 GPU越大越快受显存限制-c N上下文长度默认 4096设越大占 KV Cache 越多-n N最大生成 token 数-t NCPU 线程数纯 CPU 推理时调整--flash-attn启用 Flash Attention降低 KV Cache 显存占用-i -ins进入交互式指令跟随模式llama-server一键启动 OpenAI 兼容 API这是 llama.cpp 最重要的功能之一启动一个完全兼容 OpenAI API 格式的本地 HTTP 服务现有接入 OpenAI 的代码只需改base_url即可指向本地。基础启动llama-server\-m./models/qwen3-8b-q4_k_m.gguf\--host0.0.0.0\--port8080\-ngl999启动后内置 Web UIhttp://localhost:8080API 端点http://localhost:8080/v1/chat/completions模型列表http://localhost:8080/v1/models生产配置多并发 Flash Attentionllama-server\-m./models/qwen3-8b-q4_k_m.gguf\--host0.0.0.0\--port8080\-ngl999\-c8192\--parallel4\--flash-attn\--api-keyyour-local-key参数说明-c 8192总上下文长度被并发 slot 均分--parallel 4并发推理槽数同时处理 4 个请求--flash-attnFlash Attention减少 KV Cache 显存 30–50%--api-key设置访问鉴权 Key对外暴露时必须设置用 OpenAI SDK 调用本地服务fromopenaiimportOpenAI clientOpenAI(api_keyyour-local-key,# 与 --api-key 一致不鉴权时填任意字符串base_urlhttp://localhost:8080/v1,)completionclient.chat.completions.create(modelqwen3-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 的核心优势之一是CPUGPU 混合推理当显存不够装下整个模型时可以通过-ngl控制卸载到 GPU 的层数剩余层在 CPU 内存中运行速度下降但不会崩溃。调参策略# 先试全量 GPU-ngl 999如果 OOMllama-server-mmodel.gguf-ngl999# OOM# 逐步降低 -ngl 值找到不 OOM 的最大值llama-server-mmodel.gguf-ngl32# 32 层到 GPU其余 CPUllama-server-mmodel.gguf-ngl20# 继续降低其他节省显存的手段选更低量化版本Q4_K_S 比 Q4_K_M 小约 10%缩减上下文-c 2048比-c 8192节省约 75% KV Cache 显存启用 Flash Attention--flash-attnKV Cache 显存减少约 30–50%使用更小参数量模型3B 量化版比 7B 显存需求减半多 GPU 配置多张 NVIDIA GPU 时llama.cpp 默认在全部可用 GPU 上均匀分层。可以通过CUDA_VISIBLE_DEVICES环境变量控制使用哪几张# 只使用 GPU 0 和 GPU 1CUDA_VISIBLE_DEVICES0,1llama-server-mmodel.gguf-ngl999多 GPU 拆分模式详见官方docs/multi-gpu.md。常见问题QGGUF 文件去哪里下载主要来源HuggingFacehuggingface.co搜索模型名 GGUF通常找ggml-org/、bartowski/或模型原始仓库下的 GGUF 分支国内可通过 ModelScopemodelscope.cn镜像下载速度更快。Q-ngl 999和-ngl 0有什么区别-ngl 999 尽可能多地把模型层卸载到 GPU受显存限制自动截断-ngl 0 全 CPU 推理完全不使用 GPU。通常设-ngl 999让 llama.cpp 自动决定能卸多少层。Qllama-server 启动后 Web UI 没有响应检查①--host是否写了0.0.0.0默认 127.0.0.1 不对外②端口是否被占用换--port 8081③设了--api-key但浏览器没有带 Token 访问。Q模型输出是乱码或者语言错误通常是-c上下文设置过小被截断或者系统提示词语言与用户语言不一致。另外部分模型有 chat_template使用-i -ins参数确保使用了正确的对话格式。Qllama.cpp 和 vLLM 怎么选llama.cpp单机本地部署、显存有限、需要量化、以 GGUF 为格式适合个人开发者和边缘设备vLLM高并发生产服务、A100/H100 级 GPU、需要 PagedAttention 提升吞吐量适合企业规模推理服务。两者定位不同llama.cpp 在资源受限场景下是首选。Q企业有 GPU 服务器但不想自己维护推理服务有什么替代方案可以选择支持多家国产开源模型的 API 平台统一 OpenAI 格式接入无需维护推理基础设施。代码调用方式与 llama-server 相同只需将base_url和api_key替换为平台提供的值如七牛云 Token Planqiniu.com/ai/plan覆盖 DeepSeek / Kimi / GLM / MiniMax 四家共 25 个模型。小结llama.cpp 是当前最成熟的本地大模型推理引擎安装方面macOS 用brew install llama.cppWindows 用 Winget 或 GitHub Release 预编译包10 分钟内可完成部署模型方面Q4_K_M 是性价比最高的量化选择6–8 GB 显存可流畅运行 7B 模型API 服务方面llama-server一行命令启动 OpenAI 兼容接口现有代码零改动接入本地性能不足时先用--flash-attn降 KV Cache 开销再用-ngl混合 CPU/GPU 推理几乎在所有硬件上都能找到可用配置。本文基于 llama.cpp b103692026-08-12项目更新活跃最新参数以官方 GitHub 文档为准。延伸阅读llama.cpp 官方仓库ggml-orghttps://github.com/ggml-org/llama.cppllama.cpp 安装文档install.mdhttps://github.com/ggml-org/llama.cpp/blob/master/docs/install.mdllama.cpp 编译文档build.mdhttps://github.com/ggml-org/llama.cpp/blob/master/docs/build.mdQwen 官方 llama.cpp 接入指南https://qwen.readthedocs.io/zh-cn/latest/run_locally/llama.cpp.html