C++AI算法
llama.cpp 量化大模型内网部署与运行指南
介绍 llama.cpp 在本地内网环境下的部署与运行方法。涵盖 C/C++ 编译配置（支持 CPU/GPU 加速）、GGUF 模型获取方式、命令行参数详解及 Python 集成方案。包含常见问题排查（如 BLAS 库缺失）及 OpenAI API 兼容接口使用，旨在帮助用户在消费级硬件上高效运行量化大语言模型。
介绍 llama.cpp 在本地内网环境下的部署与运行方法。涵盖 C/C++ 编译配置（支持 CPU/GPU 加速）、GGUF 模型获取方式、命令行参数详解及 Python 集成方案。包含常见问题排查（如 BLAS 库缺失）及 OpenAI API 兼容接口使用，旨在帮助用户在消费级硬件上高效运行量化大语言模型。
跑量化模型，LLama.cpp 还是方便，用 C/C++ 实现，性能很高，还支持 CPU+GPU 做量化模型推理，命令行参数很精细，跑 GGUF 很方便。本文详细介绍安装、运行全过程。
llama.cpp？为什么它如此重要？llama.cpp 的核心思想是让大模型运行在普通人的消费级硬件上。它通过以下关键技术实现了这一目标：
llama.cpp 设计的模型文件格式，将模型结构和量化后的权重打包在一起，方便分发和加载。首先，我们需要安装编译 llama.cpp 所需的基础工具。
xcode-select --install。sudo apt update && sudo apt install build-essential git cmake。然后，克隆项目仓库：
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
在进行下一步编译之前，我们先来了解如何开启 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 系统实操时报错，可能需要升级 GCC。可以通过编辑 CMakeLists.txt 的方法解决。
为了方便使用，可以将编译好的二进制文件复制到模型文件夹中：
cp llama.cpp/build/bin/llama-* ./models/
这样可以非常方便地使用 ./llama-cli 直接拉起本地大模型。
llama.cpp 通过一个核心参数来控制模型有多少层被'卸载'到 GPU 上运行：
-ngl <层数> 或 --n-gpu-layers <层数>这个参数告诉 llama.cpp 将模型的最后 N 层放到 GPU VRAM 中进行计算。因为模型的大部分计算量都集中在这些层，所以卸载的层数越多，速度越快。
-ngl 参数，或者设置为 -ngl 0。所有计算都在 CPU 上完成，内存占用在系统 RAM 中。-ngl 999。llama.cpp 会尝试将所有能卸载的层都放入 GPU。这是最快的模式，前提是你的 GPU VRAM 足够大，能装下所有被卸载的层。-ngl 20。这样，模型的 20 层会在 GPU 上飞速计算，而其余层和计算任务则由 CPU 和系统 RAM 承担。这是一种用有限 VRAM 撬动最大性能的有效方式。获取模型主要有两种方式：手动下载或直接从 Hugging Face 加载。
你需要从 Hugging Face 下载 GGUF 格式的模型。搜索时加上 "GGUF" (例如 "Qwen2-7B-Instruct-GGUF")，然后在 "Files and versions" 中选择一个合适的量化版本（Q4_K_M 是平衡性最好的选择）。
将下载好的 .gguf 文件放入 llama.cpp/models 文件夹。
llama.cpp 支持直接从 Hugging Face Hub 下载并运行模型，无需手动下载。这需要你在命令中使用 -hf 或 --hf-repo 参数。
国内网络环境下，魔塔社区 (ModelScope) 是个绝好的替代，下载速度很快。
安装后，即可使用 modelscope download 下载模型。
下载完整模型库：
modelscope download --model unsloth/gpt-oss-120b
下载单个文件到指定本地文件夹：
modelscope download --model unsloth/gpt-oss-120b README.md --local_dir ./dir
现在，我们将结合 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)
也可以多卡启动。
**计算模型困惑度 (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
server)llama.cpp 的服务器功能非常强大，不仅提供了一个图形聊天界面，还暴露了与 OpenAI API 完全兼容的接口。
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
http://127.0.0.1:8080/v1/chat/completions 提供一个 OpenAI 兼容的端点。这意味着，你可以将任何支持 OpenAI API 的客户端、脚本或应用（例如 curl, Python openai 库等）直接对接到你本地运行的模型上，只需将 API 的 base_url 指向你的本地服务器地址即可。比如可以配置到 open-webui。
llama-cli 核心参数深度解析| 分类 | 参数 | 解释 |
|---|---|---|
| 模型加载 | -m, --model <path> | (必需) 指定本地 GGUF 模型文件路径。 |
-hf, --hf-repo <repo> | 从 Hugging Face Hub 加载模型，例如 ggml-org/gemma-2-9b-it-GGUF。 | |
| 硬件与性能 | -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 数量。设为 -1 表示无限生成。 |
--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 的值会惩罚重复出现的词，有效减少复读。常用 1.1。 | |
| 交互与提示词 | -p, --prompt <text> | 初始提示词。 |
-f, --file <path> | 从文件加载初始提示词。 | |
-i, --interactive | 进入交互模式，可以持续对话。 | |
-r, --reverse-prompt <text> | 在交互模式下，指定用户的输入提示符，例如 -r "User:"。 | |
--color | 让输出带上颜色，区分用户和模型的输入。 |
在 Python 中使用 llama-cpp-python 时，同样可以开启 GPU 加速。
pip install llama-cpp-pythonPython 代码示例:
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'])
这是一个在编译 llama.cpp 时非常常见的情况。当您在运行 cmake 时看到 BLAS not found 的提示，这不是一个致命错误，而是一个可选的性能提示。
1. 它是什么意思？
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 性能。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online