在家用Llama.cpp打造个人AI助手

快速阅读: Llama.cpp支持在普通PC上运行大型语言模型，如通义千问3和gpt-oss，提供高性能和灵活性，适用于研究和开发。

训练大型语言模型（LLM）可能需要数百万甚至数十亿美元的基础设施，但这些努力的成果往往比想象中更容易获取。许多近期发布的模型，如阿里巴巴的通义千问3和OpenAI的gpt-oss，可以在性能一般的PC硬件上运行。

如果你想深入了解LLM的工作原理，本地运行模型是必不可少的。这还让你可以无限次访问聊天机器人，无需支付额外费用或上传数据到云端。虽然有一些更简单的工具，但在命令行激活Llama.cpp可以提供最佳性能和最多选项，包括将工作负载分配给CPU或GPU以及压缩模型以加快输出速度。

许多流行的本地运行框架，如Ollama、Jan和LM Studio，实际上是基于Llama.cpp的开源基础构建的，旨在简化操作并提升用户体验。尽管这些工具使新手更容易上手，但在性能和功能方面仍有所欠缺。截至本文撰写时，Ollama仍不支持Llama.cpp的Vulkan后端，而LM Studio虽然支持Vulkan，但不支持英特尔的SYCL运行时和GGUF模型创建。

在本指南中，我们将探讨Llama.cpp，包括如何构建和安装应用程序、部署和运行跨GPU和CPU的LLM、生成量化模型、最大化性能以及启用工具调用。

**前提条件**：

Llama.cpp几乎可以在任何设备上运行，包括Raspberry Pi。但为了获得最佳体验，建议使用至少16GB内存的机器。虽然不是必需，但英特尔、AMD或英伟达的独立显卡将大幅提升性能。如果拥有这些显卡之一，请确保系统已安装最新驱动程序。

对于大多数用户来说，安装Llama.cpp就像下载ZIP文件一样简单。虽然Llama.cpp可能从包管理器如apt、snap或WinGet中获取，但由于更新频繁，最好从官方GitHub页面下载最新的预编译二进制文件。二进制文件适用于多种加速器和框架，包括macOS、Windows和Ubuntu，支持Arm64和x86-64架构的主机CPU。

如果你不确定选择哪个版本，这里有一个快速参考表：

– 英伟达：CUDA

– 英特尔Arc/Xe：Sycl

– AMD：Vulkan或HIP

– 高通：OpenCL-Adreno

– 苹果M系列：macOS-Arm64

如果没有支持的GPU，可以选择适合操作系统的“CPU”版本。请注意，集成显卡在Llama.cpp上的表现参差不齐，由于内存带宽限制，即使能够运行，其性能也可能不如基于CPU的推理。

下载Llama.cpp后，将其解压到主目录以便轻松访问。如果找不到适合的Linux发行版或加速器的预编译二进制文件，我们稍后会介绍如何从源代码构建Llama.cpp。请放心，这比听起来容易得多。

**macOS用户**：

虽然建议Windows和Linux用户从GitHub下载预编译二进制文件，但macOS的安全措施使得运行未签名代码较为麻烦。因此，建议macOS用户使用Homebrew包管理器安装Llama.cpp。需要注意的是，这可能不是最新版本。有关设置Homebrew的指南可以在这里找到。安装Homebrew后，可以通过以下命令获取Llama.cpp：

“`

brew install llama.cpp

“`

**部署第一个模型**：

与LM Studio或Ollama等其他应用程序不同，Llama.cpp是一个命令行工具。要使用它，需要打开终端并导航到刚刚下载的文件夹。在Linux上，二进制文件位于`build/bin`目录下。

“`

cd 文件夹名

“`

然后，可以运行以下命令，在设备上下载并运行4位量化的通义千问3-8B模型，并在命令行界面中与其交互。建议至少使用8GB系统内存或具有至少6GB显存的GPU。

“`

./llama-cli -hfr bartowski/Qwen_Qwen3-8B-GGUF:Q4_K_M

“`

如果通过Homebrew安装了Llama.cpp，则无需在`llama-cli`前加上`./`。

模型下载后只需几秒钟即可启动，随后会呈现一个简单的命令行聊天界面。

与Llama.cpp互动最简单的方式是通过命令行界面。点击放大查看。

除非你使用的是M系列芯片，否则Llama.cpp默认会将模型加载到系统内存并在CPU上运行。如果你的GPU有足够的内存，通常不建议这样做，因为DDR通常比GDDR慢得多。

要使用GPU，需要指定要卸载到GPU上的层数，方法是在命令后加上`-ngl`标志。以Qwen3-8B为例，它有37层，但如果你不确定层数，可以将`-ngl`设置为999，确保模型完全在GPU上运行。当然，也可以调整这个值，将模型拆分到系统内存和GPU内存之间，如果内存不足的话。我们稍后会详细介绍这一点，包括一些高级方法。

“`bash

./llama-cli -hfr bartowski/Qwen_Qwen3-8B-GGUF:Q4_K_M -ngl 37

“`

### 处理多个设备

Llama.cpp会尝试使用所有可用的GPU，这可能会导致问题，特别是当你同时拥有独立显卡和集成显卡时。在我们的测试中，使用AMD W7900和Windows的HIP二进制文件时，模型尝试将某些层卸载到CPU的集成显卡上，导致错误。

为了避免这个问题，可以使用`–device`标志指定要使用的GPU。运行以下命令可以列出所有可用的设备：

“`bash

./llama-cli –list-devices

“`

你应该会看到类似以下的输出：

“`

可用设备：

ROCm0: AMD Radeon RX 7900 XT (20464 MiB, 20314 MiB 空闲)

ROCm1: AMD Radeon™ Graphics (12498 MiB, 12347 MiB 空闲)

“`

请注意，根据你使用的后端（HIP、Vulkan、CUDA或OpenCL），设备名称会有所不同。例如，使用CUDA时，你可能会看到CUDA0和CUDA1。

现在，可以通过运行以下命令来使用首选的GPU启动Llama.cpp：

“`bash

./llama-cli -hfr bartowski/Qwen_Qwen3-8B-GGUF:Q4_K_M -ngl 37 –device ROCm0

“`

### 提供模型服务

尽管基于CLI的聊天界面非常方便，但它可能不是与Llama.cpp交互的最便捷方式。相反，你可以将其连接到图形用户界面（GUI）。

幸运的是，Llama.cpp包含一个API服务器，可以连接到支持OpenAI兼容端点的应用程序，如Jan或Open WebUI。如果你只需要一个基本的GUI，无需做特殊设置，只需使用`llama-server`启动模型即可。

“`bash

./llama-server -hfr bartowski/Qwen_Qwen3-8B-GGUF:Q4_K_M -ngl 37

“`

几秒钟后，你可以在浏览器中访问`http://localhost:8080`打开web GUI。

默认情况下，使用`llama-server`启动模型会启动一个基本的web界面用于与模型聊天。

如果你想从其他设备访问服务器，需要将服务器暴露给网络，设置`–host`地址为`0.0.0.0`，如果需要使用不同的端口，可以附加`–port`标志。如果你打算将服务器公开给互联网或大型网络，我们还建议设置`–api-key`标志。

“`bash

./llama-server -hfr bartowski/Qwen_Qwen3-8B-GGUF:Q4_K_M -ngl 37 –host 0.0.0.0 –port 8000 –api-key top-secret

“`

现在，API将在以下地址可用：

API地址：

`http://ServerIP:8080/v1`

API密钥应作为承载令牌传递到URL中，如果你正在编写自己的工具。其他工具如OpenWeb UI有一个字段可以输入密钥，客户端应用程序会处理其余部分。

### 获取模型

Llama.cpp支持大多数使用GGUF格式量化的模型。这些模型可以在各种模型仓库中找到，Hugging Face是最受欢迎的之一。

如果你在寻找特定的模型，可以查看像Bartowski、Unsloth和GGML-Org这样的个人资料，他们通常是最早提供新模型GGUF量化版本的人。

如果你使用Hugging Face，可以直接从Llama.cpp下载模型。实际上，我们在前面的步骤中就是这样下载Qwen3-8B的，需要指定模型仓库和所需的量化级别。

例如，`-hfr bartowski/Qwen_Qwen3-8B-GGUF:Q8_0`会下载8位量化的模型，而`-hfr bartowski/Qwen_Qwen3-8B-GGUF:IQ3_XS`会下载3位i-量化模型。

一般来说，较小的量化需要较少的资源来运行，但质量也较低。

### 量化自己的模型

如果你需要的模型还没有GGUF格式，可以自己创建。Llama.cpp提供了将模型转换为GGUF格式并从16位量化到更低精度（通常为8-2位）的工具，以便在较低性能的硬件上运行。

用户需要克隆 Llama.cpp 仓库并安装最新版本的 Python。如果使用 Windows，建议在 Windows Subsystem for Linux (WSL) 中操作，而非直接处理 Python 包。微软提供了 WSL 的设置指南。

用户可以运行以下命令来克隆仓库：

“`

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

cd llama.cpp

“`

接下来，创建一个 Python 虚拟环境并安装依赖项。如果尚未安装 `python3-pip` 和 `python3-venv`，需先安装这些包：

“`

sudo apt install python3-pip python3-venv

“`

然后创建虚拟环境并激活：

“`

python3 -m venv llama-cpp

source llama-cpp/bin/activate

“`

安装 Python 依赖项：

“`

pip install -r requirements.txt

“`

接下来，使用 `convert_hf_to_gguf.py` 脚本将安全张量模型转换为 16 位 GGUF 文件。以 Microsoft 的 Phi4 为例：

“`

python3.12 convert_hf_to_gguf.py –remote microsoft/phi-4 –outfile phi4-14b-FP16.gguf

“`

下载过程可能需要几分钟，因为 Phi 4 在原精度下接近 30GB。如果下载 Llama 或 Gemma 等模型时遇到问题，需先在 Hugging Face 请求权限并登录：

“`

huggingface-cli login

“`

接下来，量化模型到所需的位宽。这里使用 `Q4_K_M` 量化，因为它能将模型大小减少近四分之三，而不会大幅牺牲质量。可用的量化选项列表可以通过运行 `llama-quantize –help` 查看：

“`

./llama-quantize phi4-14b-FP16.gguf phi4-14b-Q4_K_M.gguf q4_k_m

“`

测试模型时，可以启动 `llama-cli`，使用 `-m` 参数指向新量化后的模型：

“`

llama-cli -m phi4-14b-Q4_K_M.gguf -ngl 99

“`

关于量化技术的更多信息，可以在相关指南中找到。

如果 Llama.cpp 没有提供适用于特定硬件或操作系统的预编译二进制文件，用户需要从源代码构建应用。Llama.cpp 开发团队提供了详细的文档，涵盖各种操作系统和计算运行时，如 CUDA、HIP、SYCL、CANN、MUSA 等。无论构建目标为何，确保已安装并配置最新的驱动程序和运行时。

以 Raspberry Pi 5 和基于 x86 的 Linux 系统（配备 Nvidia GPU）为例，由于没有预编译的二进制文件，我们将在这两个平台上构建 Llama.cpp。操作系统使用 Ubuntu Server（Raspberry Pi 5 为 25.04，PC 为 24.04）。

首先，安装一些依赖项：

“`

sudo apt install git cmake build-essential libcurl4-openssl-dev

“`

然后克隆仓库并进入目录：

“`

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

cd llama.cpp

“`

对于 Raspberry Pi 5，使用标准构建标志，并通过 `-j 4` 标志并行化构建过程：

“`

cmake -B build

cmake –build build –config Release -j 4

“`

对于 x86 系统，需先安装 Nvidia 驱动和 CUDA 工具包：

“`

sudo apt install nvidia-driver-570-server nvidia-cuda-toolkit

sudo reboot

“`

系统重启后，打开 `llama.cpp` 目录并构建带有 CUDA 支持的版本：

“`

cd llama.cpp

cmake -B build -DGGML_CUDA=ON

cmake –build build –config Release

“`

如果在不同系统上构建或遇到问题，可参考 Llama.cpp 的文档。

构建完成后，二进制文件将保存在 `/build/bin/` 目录中。可以直接从该目录运行这些文件，或将其复制到 `/usr/bin/` 目录完成安装：

“`

sudo cp /build/bin/ /usr/bin/

“`

如果一切顺利，可以通过以下命令启动 Google 的小型语言模型 Gemma 3 270M：

“`

llama-cli -hfr bartowski/google_gemma-3-270m-it-qat-GGUF:bf16

“`

是否推荐在 Raspberry Pi 上运行大语言模型？不太推荐，但至少现在知道这是可行的。

性能调优方面，我们已经介绍了如何下载、安装、运行、服务和量化 Llama.cpp 中的模型，但这只是其能力的一部分。运行 `llama-cli –help` 可获得更多帮助信息。

Llama.cpp 配置运行 OpenAI 的 gpt-oss-20b 模型，并添加几个标志以提高性能。我们逐一解析这些标志。

Llama.cpp 运行命令如下：

“`

./llama-server -hf ggml-org/gpt-oss-20b-GGUF –jinja -fa -c 16384 -np 2 –cache-reuse 256 -ngl 99

“`

– `-fa` 启用支持平台上的 Flash Attention，可显著加快提示处理速度并减少内存需求。大多数情况下有益，但建议尝试启用和禁用的效果。

– `-c 16384` 设置模型上下文窗口为 16,384 个标记。默认值为 4,096 个标记，以减少内存需求，但超过此阈值时，模型会开始忘记细节。如果内存充足，建议设置为最高值，直至达到模型限制。对于 gpt-oss，上限为 131,072 个标记。

– `-np 2` 允许 Llama.cpp 同时处理两个请求，适用于多用户或连接代码辅助工具，如 Cline 和 Continue。每个并行进程的上下文窗口为 8,192 个标记。

– `–cache-reuse 256` 设置此参数可避免重新计算键值缓存，加快多轮对话中的提示处理速度。推荐从 256 个标记块开始。

为了获得最佳性能和输出质量，许多模型构建者建议设置采样参数，如温度或最小概率。例如，阿里巴巴的 Qwen 团队推荐在运行 Qwen3-30B-A3B-Instruct-2507 模型时将温度设为 0.7，Top-P 设为 0.8，Top-K 设为 20，最小概率设为 0。这些推荐参数通常可以在 Hugging Face 等仓库的模型卡片上找到。

这些参数影响模型从概率曲线中选择的标记。温度较低时，输出更确定；温度较高时，输出更富有创意。许多应用程序，如 Open WebUI、LibreChat 和 Jan，允许通过 API 覆盖这些参数，API 地址为 localhost:8080。对于不支持的应用程序，在启动 Llama.cpp 模型时设置这些参数很有帮助。

例如，运行 Qwen 3 指令模型的命令如下：

“`

./llama-server -hfr bartowski/Qwen_Qwen3-30B-A3B-Instruct-2507-GGUF:Q4_K_M –temp 0.7 –top-p 0.8 –top-k 20 –min-p 0.0

“`

请注意，此模型需要超过 20GB 内存，测试时可能需要替换为较小的模型。

Llama.cpp 支持一种名为推测解码的功能，这在其他模型运行器中并不常见。该功能通过使用小型草稿模型预测大型准确模型的输出，加速重复工作负载中的标记生成，如代码生成。这需要一个与主模型同系列的兼容草稿模型。例如，使用 0.6B 版本作为草稿模型加速阿里巴巴的 Qwen3-14B 模型。

运行命令如下：

“`

./llama-server -hfr Qwen/Qwen3-14B-GGUF:Q4_K_M -hfrd Qwen/Qwen3-0.6B-GGUF:Q8_0 -c 4096 -cd 4096 -ngl 99 -ngld 99 –draft-max 32 –draft-min 2 –cache-reuse 256 -fa

“`

测试时，我们可以要求模型生成一段文本或代码。启用推测解码后，生成速率与单独运行 Qwen3-14B 相当。但在请求对文本或代码进行微小更改时，性能大约翻倍，从每秒 60 个标记增加到 117 个标记。

Llama.cpp 的另一大优势是能够将大型模型拆分到 CPU 和 GPU 之间运行。只要 DRAM 和 VRAM 总内存足够容纳模型权重和操作系统，就有可能运行这些模型。

我们之前提到，最简单的方法是逐步增加卸载到GPU的层数（-ngl），直到出现内存不足错误，然后稍微回退。例如，如果你有一块20GB显存和32GB DDR5内存的GPU，并希望以4位精度运行Meta的Llama 3.1 70B模型，该模型需要超过42GB的内存，可以将40层卸载到GPU上，其余部分在CPU上运行。

命令如下：

“`

./llama-server -hfr bartowski/Meta-Llama-3.1-70B-Instruct-GGUF -ngl 40

“`

在模型运行期间，性能不会很好——我们的测试结果显示每秒大约2个token。然而，由于混合专家（MoE）模型如gpt-oss具有相对较少的活动参数，即使运行更大规模的模型，也能获得不错的性能。

关于为什么MoE模型更容易运行，我们详细讨论了其架构优势。通过利用Llama.cpp的MoE专家卸载功能，我们成功地在20GB显存和64GB DDR4 3200 MT/s内存的系统上，以每秒20个token的速度运行了OpenAI的1200亿参数gpt-oss模型。

命令如下：

“`

./llama-server -hf ggml-org/gpt-oss-120b-GGU -fa -c 32768 –jinja -ngl 999 –n-cpu-moe 26

“`

在这个例子中，我们将`-ngl`设置为`999`，并使用`–n-cpu-moe`参数逐步将更多的专家层卸载到CPU上，直到Llama.cpp不再抛出内存不足错误。

如果工作负载需要，Llama.cpp还可以解析来自OpenAI兼容API端点（如Open WebUI或Cline）的工具调用。如果需要引入外部功能，如时钟、计算器或检查Proxmox集群状态，就需要这些工具。我们之前构建了一个工具，用于从Proxmox VE生成状态报告。