轻松内网部署：llama.cpp量化大模型运行指南！

跑量化模型，LLama.cpp 还是方便，用 C/C++ 实现，性能很高，还支持的 CPU+GPU 做量化模型推理，命令行参数很精细，跑 GGUF 很方便。本文就详细介绍安装、运行全过程，中间踩坑无数，希望对大家有所帮助。

一、什么是 llama.cpp？为什么它如此重要？

llama.cpp 的核心思想是让大模型运行在普通人的消费级硬件上。它通过以下关键技术实现了这一目标：

• C/C++ 实现：没有复杂的 Python 依赖，编译后即是原生可执行文件，性能极高。
• 模型量化 (Quantization)：将模型权重从传统的 32 位或 16 位浮点数，压缩成更小的整数（如 4 位、5 位）。这使得模型文件大小和内存占用都减少数倍，而对模型性能的影响却很小。
• GGUF 格式：一种专为 llama.cpp 设计的模型文件格式，将模型结构和量化后的权重打包在一起，方便分发和加载。
• 硬件优化：充分利用现代 CPU 的向量指令集（如 AVX2）和 GPU 的并行计算能力（如 Apple Metal, NVIDIA CUDA），实现惊人的推理速度。

01.第一步：环境准备与基础编译

首先，我们需要安装编译 llama.cpp 所需的基础工具。

• macOS: 打开**终端 (Terminal)**，运行 xcode-select --install。
• Linux (Ubuntu/Debian): 运行 sudo apt update && sudo apt install build-essential git cmake。
• Windows: 安装 Git for Windows, CMake, 以及带有 "使用 C++ 的桌面开发" 工作负载的 Visual Studio Community Edition。

然后，克隆项目仓库：

git clone https://github.com/ggerganov/llama.cpp cd llama.cpp 

在进行下一步编译之前，我们先来了解如何开启 GPU 加速。

02.第二步：开启 GPU 加速（核心步骤）

默认情况下，llama.cpp 只使用 CPU。要发挥硬件的最大潜力，你需要在编译时明确告诉它使用哪个 GPU 后端。

编译命令详解

llama.cpp 使用 cmake 进行编译。开启 GPU 支持的关键是在 cmake 命令后附加 -D 标志。

对于 AMD/Intel GPU 用户 (使用 OpenCL 或 Vulkan):这是一个更通用的选项，但性能可能不如官方支持的 CUDA 和 Metal。

# 使用 OpenCL cmake -B build -DLLAMA_CLBLAST=ON cmake --build build --config Release -j 

对于 NVIDIA GPU 用户 (使用 CUDA):你需要先安装 NVIDIA CUDA Toolkit。安装后，执行：

cmake -B build -DLLAMA_CUDA=ON cmake --build build --config Release -j 

对于 Apple Silicon (M1/M2/M3/M4) 用户 (使用 Metal):

cmake -B build -DLLAMA_METAL=ON cmake --build build --config Release -j 

这会开启 Apple 的 Metal 图形和计算框架，性能极佳。

编译成功后，生成的 llama-cli 和 server 等工具就具备了 GPU 加速的能力。

如果运气好，上面即可编译成功，但是我运气不好

我在 RHEL 系统实操时，各种报错

走了 N 多弯路，尝试 N 多方法，最终在 10978 号 issue 中找到了答案

内网升级 gcc 有点麻烦，我用了编辑 CMakeLists.tx 的方法

我比较喜欢 unsloth 的玩法

在自己的大模型文件夹里：cp llama.cpp/build/bin/llama-* llama.cpp

这样可以非常方便滴使用 ./llama.cpp/llama-cli 直接拉起本地大模型

如何控制 CPU 和 GPU 的使用？

llama.cpp 通过一个核心参数来控制模型有多少层被“卸载”到 GPU 上运行：

• -ngl <层数> 或 --n-gpu-layers <层数>

这个参数告诉 llama.cpp 将模型的最后 N 层放到 GPU VRAM 中进行计算。因为模型的大部分计算量都集中在这些层，所以卸载的层数越多，速度越快。

• 纯 CPU 模式: 不加 -ngl 参数，或者设置为 -ngl 0。所有计算都在 CPU 上完成，内存占用在系统 RAM 中。
• 完全 GPU 加速模式: 设置一个非常大的数，如 -ngl 999。llama.cpp 会尝试将所有能卸载的层都放入 GPU。这是最快的模式，前提是你的 GPU VRAM 足够大，能装下所有被卸载的层。
• 混合模式 (CPU + GPU): 当你的 VRAM 不足以容纳整个模型时，这是最佳选择。你可以设置一个具体的层数，如 -ngl 20。这样，模型的 20 层会在 GPU 上飞速计算，而其余层和计算任务则由 CPU 和系统 RAM 承担。这是一种用有限 VRAM 撬动最大性能的有效方式。

03.第三步：获取 GGUF 模型

获取模型主要有两种方式：手动下载或直接从 Hugging Face 加载。

方式一：手动下载 (推荐，更稳定)

你需要从 Hugging Face 下载 GGUF 格式的模型。搜索时加上 "GGUF" (例如 "Qwen2-7B-Instruct-GGUF")，然后在 "Files and versions" 中选择一个合适的量化版本（Q4_K_M 是平衡性最好的选择）。

将下载好的 .gguf 文件放入 llama.cpp/models 文件夹。

方式二：从 Hugging Face 直接加载 (方便快捷)

llama.cpp 支持直接从 Hugging Face Hub 下载并运行模型，无需手动下载。这需要你在命令中使用 -hf 或 --hf-repo 参数。

方式三：modelscope

也算是一种手动下载，毕竟 HF 国内网络不通，魔塔是个绝好的替代，下载速度很快

pip install modelscope 之后，即可使用 modelscope download 下载模型

下载完整模型库

modelscope download --model unsloth/gpt-oss-120b

下载单个文件到指定本地文件夹（以下载 README.md 到当前路径下“dir”目录为例）

modelscope download --model unsloth/gpt-oss-120b README.md --local_dir ./dir

04.第四步：运行模型与参数深度解析

现在，我们将结合 GPU 加速参数来运行模型，并深入了解其他重要的命令行选项。

1. 基础运行示例（GPU 加速）

假设你有一块 NVIDIA 显卡，VRAM 足够，想完全使用 GPU 加速：

./build/bin/llama-cli -m ./models/Qwen2-7B-Instruct.Q4_K_M.gguf -ngl 999 --color -c 4096 -n 1024 -p "你好，请详细介绍一下光合作用的过程。" 

如果你的 VRAM 有限，可以尝试混合模式：

./build/bin/llama-cli -m ./models/Qwen2-7B-Instruct.Q4_K_M.gguf -ngl 22 --color -c 4096 -n 1024 -p "你好，请详细介绍一下光合作用的过程。" 

(Qwen-7B 大约有 32 层，-ngl 22 会卸载大部分层到 GPU)

也可以多卡启动

2. 更多实用示例 (来自官方 README)

计算模型困惑度 (Perplexity)困惑度是衡量语言模型好坏的指标，越低越好。你可以用 llama-cli 来测试模型在某个文本文件上的困惑度。

# -f 指定要测试的文件，-c 指定上下文长度 ./build/bin/llama-cli -m ./models/your-model.gguf -f ./path/to/your/test-file.txt -c 2048 --perplexity 

创建带“人设”的交互式对话通过组合使用 -r (reverse prompt) 和 --in-prefix，可以创建一个更自然的对话机器人。

# -i 进入交互模式 # -r "User:" 当模型生成 "User:" 时，会停止并等待你的输入 # --in-prefix " " 在你的输入前加上一个空格，防止粘连 ./build/bin/llama-cli -m ./models/your-model.gguf -i -r "User:" --in-prefix " " -p "A chat between a user and an assistant.\nUser: Hello!\nAssistant:" 

直接从 Hugging Face 运行

# llama-cli 会自动下载并运行 ggml-org/gemma-2-9b-it-GGUF 模型 ./build/bin/llama-cli -hf ggml-org/gemma-2-9b-it-GGUF -p "你好，介绍一下自己。" -n 128 

3. Web UI 与 OpenAI 兼容 API (server)

llama.cpp 的服务器功能非常强大，不仅提供了一个图形聊天界面，还暴露了与 OpenAI API 完全兼容的接口。

1. 使用 Web UI:在浏览器中打开 http://127.0.0.1:8080，即可开始聊天。

启动服务器：

# -m 指定模型，-ngl 指定 GPU 层数，--host 0.0.0.0 允许局域网访问 ./build/bin/server -m ./models/your-model.gguf -ngl 35 -c 4096 --host 0.0.0.0 --port 3003 

1. 使用 OpenAI API:服务器启动后，它会在 http://127.0.0.1:8080/v1/chat/completions 提供一个 OpenAI 兼容的端点。这意味着，你可以将任何支持 OpenAI API 的客户端、脚本或应用（例如 curl, Python openai 库等）直接对接到你本地运行的模型上，只需将 API 的 base_url 指向你的本地服务器地址即可。

比如可以配置到 open-webui

4. llama-cli 核心参数深度解析

05.第五步：Python 集成（带 GPU 加速）

在 Python 中使用 llama-cpp-python 时，同样可以开启 GPU 加速。

1. 安装库: pip install llama-cpp-python

Python 代码示例:

from llama_cpp import Llama # 加载模型 llm = Llama(     model_path="./models/你的模型文件名.gguf",     n_ctx=4096,       # 上下文长度     n_threads=8,      # CPU 线程数     n_gpu_layers=-1   # -1 表示尝试将所有层都卸载到 GPU                       # 设为 0 表示纯 CPU                       # 设为正整数 N 表示卸载 N 层 ) # 创建对话 response = llm.create_chat_completion(     messages = [         {"role": "system", "content": "You are a helpful assistant."},         {             "role": "user",             "content": "你好，请介绍一下北京这座城市。"         }     ] ) print(response['choices'][0]['message']['content']) 

06.第六步：常见问题排查 (Troubleshooting)

问题：编译时提示“BLAS not found”

这是一个在编译 llama.cpp 时非常常见的情况。当您在运行 cmake 时看到 BLAS not found 的提示，这不是一个致命错误，而是一个可选的性能提示。

1. 它是什么意思？

• 核心计算是矩阵乘法：大语言模型推理过程最耗时的计算就是大量的矩阵与向量相乘。
• BLAS 作为“外挂加速引擎”：llama.cpp 允许调用系统上已安装的高性能 BLAS 库（如 OpenBLAS）来执行这些矩阵运算，以获得更好的 CPU 性能，尤其是在处理长提示词（Prompt Ingestion）的阶段。
• BLAS not found 的含义：cmake 在你的系统中搜索可用的 BLAS 库但没有找到。因此，它会回退使用 llama.cpp 自带的标准数学运算代码。你的程序依然可以编译和运行，只是可能没有达到最理想的 CPU 性能。

2. 如何解决并开启 BLAS 加速？

解决方案非常简单，就是为系统安装一个高性能的 BLAS 库。

重新编译:

cmake --build build --config Release -j 

清理并重新配置编译环境: 回到 llama.cpp 的根目录，清理掉旧的配置，然后重新运行 cmake，并明确地告诉它使用 BLAS。

# 清理旧的 build 目录 rm -rf build # 重新配置，并开启 BLAS 支持 cmake -B build -DLLAMA_BLAS=ON # 如果你同时需要 GPU 加速，可以将标志合并 # 例如，对于 NVIDIA GPU: # cmake -B build -DLLAMA_CUDA=ON -DLLAMA_BLAS=ON 

安装 OpenBLAS 开发库 (以 Debian/Ubuntu 为例):

sudo apt update sudo apt install libopenblas-dev 

完成这些步骤后，你编译出的 llama.cpp 版本就会链接到 OpenBLAS，从而在处理提示词时获得更强的 CPU 性能。

最后

源码编译其实蛮看运气的，比如我生产环境的一台 RHEL 系统的服务器，yum 源很不给力，仅仅是升级 GCC 都费老大劲，各种依赖安装到吐血。

最后还是选择了 Docker 运行 llama.cpp，确实省事。

二、AI大模型学习路线

如果你对AI大模型入门感兴趣，那么你需要的话可以点击这里大模型重磅福利：入门进阶全套104G学习资源包免费分享！

这份完整版的大模型 AI 学习和面试资料已经上传ZEEKLOG，朋友们如果需要可以微信扫描下方ZEEKLOG官方认证二维码免费领取【保证100%免费】

这是一份大模型从零基础到进阶的学习路线大纲全览，小伙伴们记得点个收藏！

第一阶段： 从大模型系统设计入手，讲解大模型的主要方法；

第二阶段： 在通过大模型提示词工程从Prompts角度入手更好发挥模型的作用；

第三阶段： 大模型平台应用开发借助阿里云PAI平台构建电商领域虚拟试衣系统；

第四阶段： 大模型知识库应用开发以LangChain框架为例，构建物流行业咨询智能问答系统；

第五阶段： 大模型微调开发借助以大健康、新零售、新媒体领域构建适合当前领域大模型；

第六阶段： 以SD多模态大模型为主，搭建了文生图小程序案例；

第七阶段： 以大模型平台应用与开发为主，通过星火大模型，文心大模型等成熟大模型构建大模型行业应用。

100套AI大模型商业化落地方案

大模型全套视频教程

200本大模型PDF书籍

👉学会后的收获：👈

• 基于大模型全栈工程实现（前端、后端、产品经理、设计、数据分析等），通过这门课可获得不同能力；

• 能够利用大模型解决相关实际项目需求： 大数据时代，越来越多的企业和机构需要处理海量数据，利用大模型技术可以更好地处理这些数据，提高数据分析和决策的准确性。因此，掌握大模型应用开发技能，可以让程序员更好地应对实际项目需求；

• 基于大模型和企业数据AI应用开发，实现大模型理论、掌握GPU算力、硬件、LangChain开发框架和项目实战技能， 学会Fine-tuning垂直训练大模型（数据准备、数据蒸馏、大模型部署）一站式掌握；

• 能够完成时下热门大模型垂直领域模型训练能力，提高程序员的编码能力： 大模型应用开发需要掌握机器学习算法、深度学习框架等技术，这些技术的掌握可以提高程序员的编码能力和分析能力，让程序员更加熟练地编写高质量的代码。

LLM面试题合集

大模型产品经理资源合集

大模型项目实战合集

👉获取方式：
😝有需要的小伙伴，可以保存图片到wx扫描二v码免费领取【保证100%免费】🆓