llama.cpp 量化大模型内网部署与运行实战

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

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

注意：编译过程有时会遇到依赖问题。例如在 RHEL 系统上，GCC 版本可能不满足要求。如果遇到报错，可以尝试升级 GCC 或调整 CMakeLists.txt 配置。具体可参考相关 Issue 讨论。

为了方便调用，可以将编译好的二进制文件复制到模型目录：

cp llama.cpp/build/bin/llama-* ./models/

这样可以非常方便地使用 ./models/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 撬动最大性能的有效方式。

四、获取 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

五、运行模型与参数深度解析

现在，我们将结合 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

2. 使用 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 核心参数深度解析

六、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'])

七、常见问题排查 (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，确实省事。