llama.cpp

llama.cpp作为C++库

开始之前，让我们先谈谈什么是llama.cpp，您应该期待什么，以及为什么我们说带引号“使用”llama.cpp。本质上，llama.cpp是一个不同的生态系统，具有不同的设计理念，旨在实现轻量级、最小外部依赖、多平台以及广泛灵活的硬件支持：

  • 纯粹的C/C++实现，没有外部依赖

  • 支持广泛的硬件：

    • x86_64 CPU的AVX、AVX2和AVX512支持

    • 通过Metal和Accelerate支持Apple Silicon（CPU和GPU）

    • NVIDIA GPU（通过CUDA）、AMD GPU（通过hipBLAS）、Intel GPU（通过SYCL）、昇腾NPU（通过CANN）和摩尔线程GPU（通过MUSA）

    • GPU的Vulkan后端

  • 多种量化方案以加快推理速度并减少内存占用

  • CPU+GPU混合推理，以加速超过总VRAM容量的模型

它就像 Python 框架 torch+transformers 或 torch+vllm 的组合，但用的是 C++。然而，这一差异至关重要：

  • Python 是一种解释型语言：编写的代码会被解释器逐行实时执行。你可以使用解释器或原生交互式解释器终端来运行示例代码片段或脚本。此外，Python 对学习者非常友好，即使你之前了解不多，也可能修改源代码。

  • C++ 是一种编译型语言：你编写的源代码需要预先编译，由编译器将其转换为机器码和可执行程序，来自语言层面的开销微乎其微。llama.cpp也提供了示例程序的源代码，展示了如何使用该库。但是，如果你不精通 C++ 或 C 语言，修改源代码并不容易。

真正使用 llama.cpp 意味着在自己的程序中使用 llama.cpp 库，就像编写 Ollama、LM Studio、GPT4ALL、llamafile 等的源代码。但这并不是本指南的目的或所能做的。相反，这里我们介绍如何使用 llama-cli 示例程序，希望你能了解到 llama.cpp 支持 Qwen2.5 模型以及 llama.cpp 生态系统的一般工作原理。

在这份指南中，我们将讨论如何“使用” llama.cpp 在您的本地机器上运行模型，特别是随库提供的 llama-cli 和 llama-server 示例程序。

主要步骤如下：

  1. 获取程序

  2. 获取 GGUF[1] 格式的 Qwen3 模型

  3. 使用模型运行程序

备注

llama.cpp 自版本 b5092 支持 Qwen3 和 Qwen3MoE 。

获取程序

你可以通过多种方式获得 llama.cpp 中的程序。为了达到最佳效率，我们建议你本地编译程序，这样可以零成本享受CPU优化。但是，如果你的本地环境没有C++编译器，也可以使用包管理器安装或者下载预编译的二进制文件。虽然它们可能效率较低，但对于非生产用途的例子来说，它们已经足够好用了。

这里，我们将展示在 macOS 或 Linux 上本地编译 llama-cli 的基本命令。对于 Windows 用户或 GPU 用户，请参考llama.cpp的指南。

安装构建工具

要进行本地构建，你需要一个C++编译器和一个构建系统工具。在终端窗口中输入cc --version或cmake --version，看看这些工具是否已经安装好了。

  • 如果已安装，工具的构建配置信息将被打印到终端，那么你就可以开始了！

  • 如果出现错误，说明你需要先安装相关工具：

    • 在macOS上，使用命令xcode-select --install来安装。

    • 在Ubuntu上，使用命令sudo apt install build-essential来安装。对于其他Linux发行版，命令可能会有所不同；本指南所需的基本包是gcc和cmake。

编译程序

第一步是克隆仓库并进入该目录：

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

随后，使用 CMake 执行 llama.cpp 构建：

cmake -B build
cmake --build build --config Release

第一条命令将检查本地环境并确定需要包含的推理后端与特性。第二条命令将实际构建程序文件。

为了缩短时间，你还可以根据你的CPU核心数开启并行编译，例如：

cmake --build build --config Release -j 8

这将以8个并行编译任务来构建程序。

结果将存于 ./build/bin/ 。

对于macOS和Linux用户，llama-cli 和 llama-server 可以通过包括 Homebrew、Nix 和 Flox 在内的软件包管理器进行安装。

在这里，我们展示如何使用 Homebrew 安装 llama-cli 和 llama-server 。对于其他软件包管理器的安装，请查阅这里的指南。

使用 Homebrew 安装非常简单：

  1. 请确保您的操作系统上已安装有 Homebrew。如果没有，您可以按照官网上的指导进行安装。

  2. 其次，您只需一条命令即可安装预先编译好的二进制文件，其中包括 llama-cli 和 llama-server ：

    brew install llama.cpp

请注意，安装的二进制文件可能并未针对您的硬件优化编译选项，这可能导致性能不佳。此外，在 Linux 系统上它们也不支持 GPU。

您还可以从GitHub Release下载预构建的二进制文件。请注意，这些预构建的二进制文件是特定于架构、后端和操作系统的。如果您不确定这些意味着什么，可能您并不想使用它们。使用不兼容的版本很可能导致运行失败或性能不佳。

文件名类似于llama-<version>-bin-<os>-<feature>-<arch>.zip。

分为三个简单部分：

  • <version>：llama.cpp的版本。建议使用最新版本，但鉴于llama.cpp频繁更新和发布，最新版本可能包含bug。如果最新版本无法正常工作，请尝试之前的版本直到找到能正常工作的为止。

  • <os>：操作系统。win代表Windows；macos代表macOS；linux代表Linux。

  • <arch>：系统架构。x64对应x86_64，例如大多数Intel和AMD系统，包括Intel Mac；arm64对应arm64，例如Apple Silicon或基于Snapdragon的系统。

<feature>部分对于Windows来说有些复杂：

  • 在CPU上运行

    • x86_64 CPU：我们建议首先尝试avx2。

      • noavx：完全无AVX硬件加速。

      • avx2，avx，avx512：基于SIMD的加速。大多数现代桌面CPU应该支持AVX2，部分CPU支持AVX512。

      • openblas：依赖OpenBLAS加速提示词(prompt)处理，但不涉及生成过程。

    • arm64 CPU：我们建议首先尝试llvm。

  • 在GPU上运行：我们建议NVIDIA GPU先尝试cu<cuda_verison>，AMD GPU先尝试kompute，Intel GPU先尝试sycl。请确保已安装相关驱动程序。

    • vulcan：支持某些NVIDIA和AMD GPU

    • kompute：支持某些NVIDIA和AMD GPU

    • sycl：Intel GPU，包含oneAPI运行时

    • cu<cuda_verison>：NVIDIA GPU，未包含CUDA运行时。如果您没有安装相应的CUDA工具包，可以下载cudart-llama-bin-win-cu<cuda_version>-x64.zip并将其解压到同一目录中。

对于macOS或Linux，您的选择不多。

  • Linux：仅有一个预构建的二进制文件llama-<version>-bin-linux-x64.zip，支持CPU。

  • macOS：对于Intel Mac，使用llama-<version>-bin-macos-x64.zip（不支持GPU）；对于Apple Silicon，使用llama-<version>-bin-macos-arm64.zip（支持GPU）。

下载.zip文件后，将其解压到一个目录中，并在该目录下打开终端。

获取 GGUF

GGUF[1] 是一种文件格式，用于存储运行模型所需的信息，包括但不限于模型权重、模型超参数、默认生成配置和tokenzier。

您可以使用我们 Hugging Face Hub 上的官方 Qwen GGUF 文件，或者自己准备 GGUF 文件。

使用官方 Qwen3 GGUF

在我们的 Hugging Face 组织中，我们提供了一系列 GGUF 模型。要查找您需要的模型，可以在仓库名称中搜索 -GGUF。

使用 huggingface-cli 下载您想要的 GGUF 模型（首先需要通过 pip install huggingface_hub 进行安装）：

huggingface-cli download <model_repo> <gguf_file> --local-dir <local_dir>

比如：

huggingface-cli download Qwen/Qwen3-8B-GGUF qwen3-8b-q4_k_m.gguf --local-dir .

这将下载采用 Q4_K_M 方案量化的 GGUF 格式的 Qwen3-8B model 模型。

准备您自己的 GGUF

可以使用 convert-hf-to-gguf.py Python 脚本将来自 Hugging Face Hub 的模型文件转换为 GGUF。这确实需要您拥有一个工作中的 Python 环境，并至少安装了 transformers。

如果尚未获取，请先获取源文件：

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

假设您想使用 Qwen3-8B，可以按照以下方式为 fp16 模型制作 GGUF 文件：

python convert-hf-to-gguf.py Qwen/Qwen3-8B --outfile qwen3-8b-f16.gguf

脚本的第一个参数指的是 HF 模型目录或 HF 模型名称的路径，第二个参数指的是输出 GGUF 文件的路径。在运行命令前，请记得创建输出目录。

fp16 模型对于本地运行可能有些重，您可以根据需要对模型进行量化。我们在 这份指南 中介绍了创建和量化 GGUF 文件的方法。您可以参考该文档获取更多信息。

使用 llama.cpp 运行 Qwen

备注

关于在思考模式和非思考模式之间切换，虽然软开关始终可用，但在聊天模板中实现的硬开关并未在 llama.cpp 中暴露。快速的解决方法是通过 --chat-template-file 传递一个等效于始终设置 enable_thinking=False 的自定义聊天模板。

llama-cli

llama-cli 是一个可用于与大型语言模型聊天的控制台程序。只需在放置 llama.cpp 程序的位置运行以下命令：

./llama-cli -hf Qwen/Qwen3-8B-GGUF:Q8_0 --jinja --color -ngl 99 -fa -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 -c 40960 -n 32768 --no-context-shift

以下是对上述命令的一些解释：

  • 模型：llama-cli 支持从本地路径、远程 URL 或 Hugging Face Hub 使用模型文件。

    • 上面的 -hf Qwen/Qwen3-8B-GGUF:Q8_0 表示我们使用的是来自 Hugging Face Hub 的模型文件。

    • 要使用本地路径，传递 -m qwen3-8b-q8_0.gguf 即可。

    • 要使用远程 URL，传递 -mu https://hf.co/Qwen/Qwen3-8B-GGUF/resolve/main/qwen3-8b-Q8_0.gguf?download=true 即可。

  • 速度优化：

    • CPU：llama-cli 默认会使用 CPU，您可以通过更改 -t 来指定希望使用的线程数，例如 -t 8 表示使用 8 个线程。

    • GPU：如果程序包含 GPU 支持，您可以使用 -ngl，它允许将一些层卸载到 GPU 进行计算。如果有多个 GPU，它会卸载到所有 GPU 上。您可以使用 -dev 控制使用的设备，并使用 -sm 控制使用的并行类型。例如，-ngl 99 -dev cuda0,cuda1 -sm row 表示使用 row 切分将所有层卸载到 GPU 0 和 GPU 1。添加 -fa 也可能加速生成。

  • 采样参数：llama.cpp 支持多种采样方法，并对其中许多方法有默认配置。建议根据实际情况调整这些参数，Qwen3 模型卡片中推荐的参数可作为参考。如果您遇到重复和无尽生成的情况，建议额外传递 --presence-penalty，最大值为 2.0。

  • 上下文管理：llama.cpp 默认采用“轮换”上下文管理方式。-c 控制最大上下文长度（默认值 4096，0 表示从模型加载），-n 控制每次生成的最大长度（默认值 -1 表示无限生成直到结束，-2 表示直到上下文满）。当上下文已满但生成未结束时，初始提示中的前 --keep 个 token（默认值 0，-1 表示全部）会被保留，其余部分的前半部分会被丢弃。然后，模型基于新的上下文 token 继续生成。您可以设置 --no-context-shift 来防止这种轮换行为，一旦达到 -c，生成就会停止。

    llama.cpp 支持 YaRN，可以通过 -c 131072 --rope-scaling yarn --rope-scale 4 --yarn-orig-ctx 32768 启用。

  • 聊天：--jinja 表示使用嵌入在 GGUF 中的聊天模板（推荐），--color 表示对文本进行着色，以便更好地区分用户输入和模型输出。如果有聊天模板（如 Qwen3 模型中），llama-cli 将自动进入聊天模式。要停止生成或退出，请按 “Ctrl+C”。您可以使用 -sys 添加系统提示。

llama-server

llama-server 是一个简单的 HTTP 服务器，包含一组 LLM REST API 和一个简单的 Web 前端，用于通过 llama.cpp 与大型语言模型交互。

其核心命令与 llama-cli 类似。此外，它还支持思考内容解析和工具调用解析。

./llama-server -hf Qwen/Qwen3-8B-GGUF:Q8_0 --jinja --reasoning-format deepseek -ngl 99 -fa -sm row --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0 -c 40960 -n 32768 --no-context-shift

默认情况下，服务器将在 http://localhost:8080 监听，可以通过传递 --host 和 --port 更改。Web 前端可以通过浏览器访问 http://localhost:8080/。兼容 OpenAI 的 API 位于 http://localhost:8080/v1/。

还有更多

如果你仍然觉得使用llama-cli有困难，别担心，可以尝试其他基于llama.cpp的应用程序。例如，Qwen3已经成为Ollama和LM Studio的官方组成部分，它们是用于搜索和运行本地LLM的平台。

玩得开心！