微精选

大家好，我是 Ai 学习的老章。

跑量化模型，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），实现惊人的推理速度。

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

首先，我们需要安装编译 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 加速。

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

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

编译命令详解

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

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

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

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

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

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

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

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

编译成功后，生成的 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 撬动最大性能的有效方式。

第三步：获取 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)

• 直接从 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
  

• 创建带“人设”的交互式对话通过组合使用 -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:"
  

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

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

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

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

1. 启动服务器：

   # -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. 使用 Web UI:在浏览器中打开 http://127.0.0.1:8080，即可开始聊天。

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

分类	参数	解释
模型加载	-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 集成（带 GPU 加速）

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

1. 安装库: pip install llama-cpp-python
2. 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 库。

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

   sudo apt update
   sudo apt install libopenblas-dev
   

2. 清理并重新配置编译环境: 回到 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
   

3. 重新编译:

   cmake --build build --config Release -j
   

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

最后

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

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

后面我再写文章介绍全过程，也是踩坑无数。