轻松内网部署：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 完全兼容的接口。
- 使用 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 
- 使用 OpenAI API:服务器启动后，它会在
http://127.0.0.1:8080/v1/chat/completions提供一个 OpenAI 兼容的端点。这意味着，你可以将任何支持 OpenAI API 的客户端、脚本或应用（例如curl, Pythonopenai库等）直接对接到你本地运行的模型上，只需将 API 的base_url指向你的本地服务器地址即可。
比如可以配置到 open-webui
4. llama-cli 核心参数深度解析
分类 | 参数 | 解释 |
|---|---|---|
| 模型加载 | -m, --model <path> | (必需) 指定本地 GGUF 模型文件路径。 |
-hf, --hf-repo <repo> | 从 Hugging Face Hub 加载模型，例如 | |
| 硬件与性能 | -ngl, --n-gpu-layers <N> | (最重要) 将模型的 N 层卸载到 GPU。 |
-t, --threads <N> | 使用的 CPU 线程数。 | |
-b, --batch-size <N> | 提示词处理的批处理大小，可以影响速度。 | |
--mlock | 将模型锁定在内存中，防止被交换到硬盘，对性能有益。 | |
| 上下文管理 | -c, --ctx-size <N> | 上下文窗口大小（单位：token）。模型能“记住”的对话长度。 |
--prompt-cache <file> | 将处理过的提示词缓存到文件，下次加载相同提示词时会更快。 | |
| 生成控制 | -n, --n-predict <N> | 模型一次最多生成的 token 数量。设为 |
--temp <value> | 温度 。控制随机性。值越低（如 0.2）回答越确定；越高（如 1.2）越有创意。 | |
--top-k <N> | Top-K 采样 。在每一步，模型只从概率最高的 K 个词中选择。 | |
--top-p <value> | Top-P (Nucleus) 采样 。从累积概率超过 P 的最小词集中选择。通常比 Top-K 效果更好。 | |
--repeat-penalty <value> | 重复惩罚 。大于 1 的值会惩罚重复出现的词，有效减少复读。常用 | |
| 交互与提示词 | -p, --prompt <text> | 初始提示词。 |
-f, --file <path> | 从文件加载初始提示词。 | |
-i, --interactive | 进入交互模式，可以持续对话。 | |
-r, --reverse-prompt <text> | 在交互模式下，指定用户的输入提示符，例如 | |
--color | 让输出带上颜色，区分用户和模型的输入。 |
05.第五步：Python 集成（带 GPU 加速）
在 Python 中使用 llama-cpp-python 时，同样可以开启 GPU 加速。
- 安装库:
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%免费】🆓
