如何在本地运行LLM？ llama.cpp 快速入门 – wiki基地

作者： /

解锁本地AI力量：LLaMA.cpp 快速入门与实践指南

随着大型语言模型（LLM）技术的飞速发展，AI不再是遥不可及的云端服务。许多开发者和爱好者渴望在自己的电脑上亲身体验LLM的强大能力，进行私密对话、代码生成、文本创作等，而无需依赖第三方API。然而，许多强大的LLM模型（如Llama、Mistral、Mixtral等）动辄数十亿甚至上千亿参数，运行它们通常需要昂贵的GPU集群。这似乎让本地运行LLM成为一个难以企及的梦想。

幸运的是，一个名为 llama.cpp 的开源项目彻底改变了这一局面。它由 Georgi Gerganov 创建，以其卓越的效率和跨平台兼容性，使得在普通消费级硬件上，甚至是仅依赖CPU，也能够流畅地运行这些大型语言模型。

本文将带你深入了解 llama.cpp，详细讲解如何在你的本地计算机上安装、配置并运行LLM模型，让你亲身体验本地AI的魅力。

什么是 llama.cpp？为什么选择它？

简单来说，llama.cpp 是一个使用 C/C++ 编写的、用于运行大型语言模型推理的库和工具集。它的核心目标是：

  1. 极致的效率: 利用 C/C++ 的低层级特性，充分榨干硬件性能，特别是在CPU上。
  2. 跨平台: 可以在 Windows, macOS, Linux 等多种操作系统上运行，支持 x86 和 ARM 架构。
  3. 硬件兼容性: 不仅支持高性能GPU（通过各种后端如cuBLAS, CLBlast, Metal），更重要的是，它在CPU上的表现异常出色，使得没有高端GPU的用户也能运行大型模型。
  4. 易用性: 提供简单的命令行工具，以及用于集成到其他应用程序的库。
  5. 模型格式支持: 主要支持专门为高效推理设计的 GGUF 格式模型。

为什么选择 llama.cpp 来运行本地LLM？

  • 降低硬件门槛: 即使只有中等的CPU和足够的内存，也能运行相当大的模型。
  • 隐私保护: 所有推理都在本地进行，你的数据不会上传到任何服务器。
  • 离线可用: 一旦模型下载完成，你可以断开网络连接运行模型。
  • 成本效益: 避免了云服务的使用费用。
  • 高度灵活: 可以方便地切换不同的模型、调整参数，进行实验。
  • 活跃的社区: llama.cpp 拥有庞大的开发者和用户社区，问题解决和功能更新都非常快。

如果你想在自己的电脑上运行各种流行的开源LLM模型，llama.cpp 无疑是当前最受欢迎、最实用的选择。

准备工作：软硬件要求与环境搭建

在开始安装和运行 llama.cpp 之前，你需要确认你的电脑满足一定的条件，并安装一些必要的工具。

硬件要求

llama.cpp 的一个主要优势是它对硬件的友好性，但运行大型模型仍然需要一定的资源：

  1. 内存 (RAM): 这是最重要的资源。你需要足够的内存来加载整个模型的权重。模型大小直接影响所需的内存。例如，一个 7B 参数的模型（GGUF Q4_K_M 量化）可能需要 4-5 GB 内存。一个 13B 模型可能需要 8-10 GB。30B 模型可能需要 20-25 GB。65B 模型可能需要 40-50+ GB。建议至少 16GB RAM，32GB 或更高更佳。 如果内存不足，模型可能无法加载，或者性能会非常差（因为它会大量使用虚拟内存，即硬盘）。
  2. CPU: llama.cpp 在CPU上表现出色，CPU 的核心数和主频会影响推理速度。现代多核CPU都能提供不错的性能。
  3. 显卡 (GPU – 可选但强烈推荐): 虽然 llama.cpp 可以在纯CPU上运行，但如果你的电脑有NVIDIA (CUDA)、AMD (ROCm) 或 Apple Silicon (Metal) 显卡，并且显存（VRAM）足够，可以将部分或全部模型层卸载到GPU上运行，这将显著提升推理速度。所需的VRAM量取决于模型大小和量化程度，以及你希望卸载多少层。例如，一个 7B Q4_K_M 模型完全卸载可能需要 5-6 GB VRAM。建议有 6GB 或更多 VRAM 的现代显卡。

总结： 最低配置建议 16GB RAM + 现代CPU。推荐配置建议 32GB+ RAM + 现代CPU + 8GB+ VRAM 的 GPU。

软件要求

你需要安装以下基础软件：

  1. Git: 用于从 GitHub 克隆 llama.cpp 的源代码。
    • Windows: 下载安装 Git for Windows。
    • macOS: 通常已预装，或通过 Homebrew 安装 brew install git。
    • Linux: 使用包管理器安装，如 sudo apt update && sudo apt install git (Debian/Ubuntu) 或 sudo dnf install git (Fedora)。
  2. CMake: 一个跨平台的构建工具，llama.cpp 使用它来管理编译过程。
    • Windows: 下载安装 CMake。安装时选择添加到系统PATH。
    • macOS: 通过 Homebrew 安装 brew install cmake。
    • Linux: 使用包管理器安装，如 sudo apt install cmake 或 sudo dnf install cmake。
  3. C/C++ 编译器: llama.cpp 需要一个 C++11 兼容的编译器来编译源代码。
    • Windows:
      • 推荐: 安装 Visual Studio (选择带有 “Desktop development with C++” 工作负载) 或 Visual Studio Build Tools。CMake 会自动找到 MSVC 编译器。
      • 备选: 安装 MinGW-w64。
    • macOS: 安装 Xcode Command Line Tools (xcode-select --install)，它包含了 Clang 编译器。
    • Linux: 安装 GCC 或 Clang。通常已预装或通过包管理器安装，如 sudo apt install build-essential (包含了 GCC)。

对于 GPU 加速 (可选):

  • NVIDIA: 需要安装 CUDA Toolkit 和 cuDNN。确保版本兼容。
  • AMD: 需要安装 ROCm。
  • Apple Silicon (M系列芯片): Metal 支持是内置的，无需额外安装。

安装这些依赖可能会是过程中最复杂的部分，特别是GPU相关的库。请根据你的操作系统和硬件，参考官方文档或社区教程进行安装。

获取并编译 llama.cpp

一旦准备工作就绪，就可以获取并编译 llama.cpp 源代码了。

步骤 1: 克隆源代码

打开终端 (macOS/Linux) 或命令提示符/PowerShell (Windows)，导航到你希望存放 llama.cpp 项目的目录，然后执行以下命令：

bash
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

这会将 llama.cpp 的最新代码下载到当前目录下的 llama.cpp 文件夹中，并进入该文件夹。

步骤 2: 编译项目

llama.cpp 提供了多种编译方式，最常见的是使用 make (macOS/Linux) 或 CMake (Windows/跨平台)。

方法 A: 使用 make (macOS/Linux) – 简单快速

这是 macOS 和 Linux 上最推荐的方式。直接在 llama.cpp 目录下运行 make 命令即可：

bash
make

如果你的系统有多个CPU核心，可以指定并行编译的数量以加快速度，例如使用 8 个核心：

bash
make -j8

启用 GPU 加速 (macOS/Linux with make):

如果你希望使用 GPU 加速，需要在编译时指定相应的后端。

  • NVIDIA (cuBLAS):
    bash
    make clean # 先清理旧的编译文件
    make LLAMA_CUBLAS=1 -j8 # 启用 cuBLAS
  • AMD (CLBlast):
    bash
    make clean
    make LLAMA_CLBLAST=1 -j8 # 启用 CLBlast
  • Apple Metal (M系列芯片): Metal 支持通常是默认启用的，但你也可以显式指定：
    bash
    make clean
    make LLAMA_METAL=1 -j8 # 启用 Metal

你可以同时启用多个后端，llama.cpp 会尝试使用可用的那个。例如，同时支持cuBLAS和Metal：make LLAMA_CUBLAS=1 LLAMA_METAL=1 -j8。

编译成功后，你会在 llama.cpp 目录下看到一些可执行文件，比如 main, server, quantize 等。

方法 B: 使用 CMake (Windows 或跨平台)

CMake 是一种更灵活的构建方式，特别适合 Windows 用户。

  1. 创建构建目录: 在 llama.cpp 目录下创建一个新的目录来存放编译生成的文件，这样可以保持源代码目录的干净。
    bash
    mkdir build
    cd build

  2. 配置 CMake 项目: 运行 cmake 命令来配置项目。这将检查你的系统环境和依赖，并生成用于构建的配置文件。

    • 基础配置 (纯CPU):
      bash
      cmake ..
    • 启用 GPU 加速 (Windows with CMake): 你需要在配置阶段指定相应的选项。
      • NVIDIA (cuBLAS):
        bash
        cmake .. -DLLAMA_CUBLAS=ON
      • AMD (CLBlast):
        bash
        cmake .. -DLLAMA_CLBLAST=ON
      • Apple Metal (M系列芯片):
        bash
        cmake .. -DLLAMA_METAL=ON
      • Intel GPU (oneAPI/SYCL):
        bash
        cmake .. -DLLAMA_SYCL=ON
    • 使用特定的编译器 (可选): 如果你有多个编译器，可以使用 -G 选项指定，例如 -G "Visual Studio 17 2022" 或 -G "MinGW Makefiles"。

  3. 构建项目: 配置成功后，使用 cmake --build 命令来执行编译。
    bash
    cmake --build . --config Release # 使用 . 表示当前目录 (build)，--config Release 表示构建 Release 版本
    你也可以指定并行编译的数量，例如 --parallel 8。

编译成功后，可执行文件通常会在 build/bin/Release 或 build/Release (取决于配置) 目录下找到。

故障排除:

  • 如果编译失败，仔细阅读错误信息。通常是缺少依赖库（如 CUDA、ROCm、OpenBLAS 等）或编译器问题。
  • 确保你的系统 PATH 环境变量包含了 CMake 和编译器的路径。
  • 在 Windows 上使用 Visual Studio 时，确保在 开发者命令提示符 或 Developer PowerShell 中运行命令，这样环境变量才能正确设置。

获取 LLM 模型 (GGUF 格式)

llama.cpp 主要使用 GGUF 格式的模型文件。GGUF 是一种专为 llama.cpp 设计的、用于存储模型权重和元数据的二进制格式，它支持量化（quantization），这是在消费级硬件上运行大型模型 Hydro 的关键。

什么是量化 (Quantization)？

大型语言模型的权重通常以 16 位浮点数 (FP16) 或 32 位浮点数 (FP32) 存储。量化是将这些权重转换为更低精度的整数格式（如 8 位、5 位、4 位甚至 2 位），从而显著减小模型文件大小和内存占用。

不同的量化级别 (如 Q8_0, Q5_1, Q4_0, Q4_K_M, Q3_K_L, Q2_K 等) 代表了不同的精度和压缩程度。

  • 精度越高 (如 Q8_0): 文件越大，内存占用越高，但模型性能损失越小。
  • 精度越低 (如 Q2_K): 文件越小，内存占用越低，对硬件更友好，但模型性能（生成文本的质量、遵循指令的能力等）可能有更大的损失。

通常，Q4_K_M 是一个在文件大小、内存占用和模型性能之间取得良好平衡的常用选择。对于内存或显存非常有限的用户，可以尝试 Q3 或 Q2 级别的量化。

从哪里获取 GGUF 模型？

最方便的方式是从社区成员分享的仓库下载。Hugging Face 是一个主要的模型分享平台，许多社区成员会将流行的开源模型转换为 GGUF 格式并上传。

推荐的 GGUF 模型来源:

  • TheBloke (on Hugging Face): 这是最著名和最活跃的 GGUF 模型提供者之一。他转换了大量流行的开源模型（如 Llama, Mistral, Mixtral, Guanaco 等）为 GGUF 格式，并提供不同量化级别的版本。
    • 访问 TheBloke 在 Hugging Face 的主页：https://huggingface.co/TheBloke
    • 在他的仓库中搜索你感兴趣的模型，例如 Mistral-7B-Instruct-v0.2-GGUF 或 Llama-2-7B-Chat-GGUF。
    • 进入模型页面后，点击 Files and versions 标签页。
    • 你会看到一系列 .gguf 文件，文件名通常包含量化级别信息，例如 mistral-7b-instruct-v0.2.Q4_K_M.gguf 或 llama-2-7b-chat.Q5_K_S.gguf。
    • 选择一个合适的量化级别下载。请注意文件大小，确保你有足够的磁盘空间。

如何下载模型文件？

你可以直接通过浏览器下载，或者使用 git 命令行工具（但对于大文件可能需要特定的 Git LFS 支持或配置）或 wget 等工具。对于大型模型文件，推荐使用支持断点续传的下载工具。

将下载好的 .gguf 模型文件存放在你容易找到的位置，例如 llama.cpp 目录下的 models 子目录（如果不存在可以创建）。

运行你的第一个 LLM 模型

现在你已经编译了 llama.cpp 并下载了 GGUF 模型文件，是时候运行它了！我们将使用 llama.cpp 提供的 main 工具进行基本的文本生成。

打开终端或命令提示符，进入 llama.cpp 目录 (或者你的 build 目录下的可执行文件所在目录)。

基本运行命令

main 工具的最基本用法是指定模型文件路径和输入提示 (prompt)。

假设你的模型文件 your_model.gguf 放在 llama.cpp/models/ 目录下。

“`bash

如果你在 llama.cpp 根目录 (macOS/Linux)

./main -m ./models/your_model.gguf –prompt “请写一个关于人工智能的短故事。” -n 512

如果你在 llama.cpp/build/Release 目录 (Windows)

.\main.exe -m ….\models\your_model.gguf –prompt “请写一个关于人工智能的短故事。” -n 512
“`

命令解释:

  • ./main (或 .\main.exe): 执行编译好的 main 工具。
  • -m ./models/your_model.gguf: 使用 -m 参数指定模型文件的路径。请根据你实际的模型文件位置修改路径。
  • --prompt "请写一个关于人工智能的短故事。": 使用 --prompt 参数指定你希望模型继续或回答的文本。将双引号内的内容替换成你的问题或指令。
  • -n 512: 使用 -n 参数指定生成文本的最大 token 数量。例如 -n 512 表示最多生成 512 个 token。你可以根据需要调整这个值，更大的值意味着更长的生成内容。

运行命令后，llama.cpp 会加载模型，然后根据你的 prompt 开始生成文本。你会看到模型生成的内容，以及一些性能信息（如每秒生成多少 token）。

常用参数详解

main 工具提供了丰富的参数来控制模型的行为和性能。这里介绍一些最常用的：

  • -m <path>: 必须。 指定 GGUF 模型文件的路径。
  • --prompt <string>: 必须。 指定初始的 prompt 文本。
  • -n <int>: 生成文本的最大 token 数量 (default: 32)。 -1 表示无限生成直到遇到停止条件。
  • -c <int>: 上下文窗口大小 (default: 512)。模型能“记住”多少之前的 token。更大的上下文可以处理更长的文本，但会占用更多内存/显存，并可能降低速度。
  • -t <int>: 使用的线程数量 (default: 物理核心数)。增加线程数可以利用多核CPU，但超过物理核心数通常没有额外收益，有时甚至会因为线程切换开销而降低性能。
  • -ngl <int>: 将模型的前 <int> 层卸载到 GPU 运行 (Requires GPU build). -1 表示将所有层卸载到 GPU (如果 VRAM 足够)。0 表示完全在 CPU 上运行。这是提升速度的关键参数。
  • --temp <float>: 温度 (Temperature, default: 0.8)。控制输出的随机性。较高的温度 (如 1.0) 会使输出更随机、更有创造力；较低的温度 (如 0.2) 会使输出更确定、更聚焦。
  • --top-k <int>: Top-k 采样 (default: 40)。在生成下一个 token 时，只考虑概率最高的 k 个 token。
  • --top-p <float>: Top-p 采样 (default: 0.95)。在生成下一个 token 时，选择概率累计和超过 p 的最小集合中的 token。
  • --repeat_penalty <float>: 重复惩罚 (default: 1.1)。控制模型重复相同词语或短语的倾向。大于 1.0 会抑制重复。
  • --repeat_last_n <int>: 对最近 n 个 token 应用重复惩罚 (default: 64)。
  • -i: 启用交互模式。模型会在生成一段文本后等待你输入新的 prompt，形成对话。在交互模式下，可以使用 /save <file> 保存对话状态，/load <file> 加载状态，/reset 重置对话。
  • -is: 启用交互模式，但首先等待用户输入第一个 prompt。
  • -r <string>: 在交互模式下，指定一个或多个停止序列。当模型生成到这些序列时，就会停止生成并等待用户输入。例如 -r "User:" 可以让模型在遇到 “User:” 时停下。
  • --instruct: 使用指令模式，通常用于微调过的指令跟随模型。它会根据模型的特定格式封装 prompt。
  • -p <string>: 和 --prompt 类似，但也可以用于文件路径或多行输入。

示例：使用更多参数运行

“`bash

在交互模式下，使用 8 线程，上下文窗口 2048，温度 0.7，重复惩罚 1.1

并将前 30 层卸载到 GPU (假设你的模型有足够多层且你编译时启用了 GPU)

./main -m ./models/your_model.gguf -i -t 8 -c 2048 –temp 0.7 –repeat_penalty 1.1 -ngl 30
“`

运行此命令后，llama.cpp 会启动，等待你在命令行输入 prompt。输入你的指令，按回车，模型就会生成回应。

观察输出

当你运行 main 工具时，除了模型生成的文本，你还会看到一些输出信息，这些信息很有用：

  • 模型加载信息: 显示加载的模型文件、模型类型、参数量、使用的量化级别等。
  • GPU 卸载信息: 如果使用了 -ngl 参数，会显示有多少层被卸载到 GPU (VRAM)。
  • 内存/显存使用估计: 在模型加载时可能会显示预计的内存和显存占用。
  • 性能指标: 在生成完成后，会报告加载时间、预填充时间 (处理 prompt 的时间) 和生成时间 (生成回应的时间)，以及每秒生成 token 的速度 (tokens/s)。tokens/s 是衡量推理速度的关键指标。

如果你使用了 -ngl 参数，观察输出确认是否成功卸载了层到 GPU。如果没有看到相关的 GPU 信息，或者 -ngl 参数似乎没有效果，可能是编译时未启用 GPU 支持，或者 CUDA/ROCm/Metal 环境有问题。

llama.cpp 的其他重要工具

除了 main，llama.cpp 提供了其他一些有用的工具：

  1. server: 运行一个本地 HTTP 服务器，提供与 OpenAI API 兼容的接口。这允许你使用各种前端 UI（如 LM Studio, Text Generation WebUI 等）或通过编程方式与 llama.cpp 进行交互，而无需直接使用命令行。
    • 基本用法: ./server -m ./models/your_model.gguf -c 4096 -ngl 30
    • 运行后，你可以在 http://localhost:8080 访问其 API。
    • 这是将 llama.cpp 集成到其他应用或使用更友好界面的主要方式。
  2. quantize: 用于将支持的 FP16 或 FP32 模型文件转换为不同量化级别的 GGUF 文件。
    • 用法: ./quantize <input_gguf_file> <output_gguf_file> <quantization_type>
    • 例如: ./quantize ./models/your_model.gguf ./models/your_model.Q4_K_M.gguf Q4_K_M
    • 这对于想要自定义量化级别或从非 GGUF FP16/FP32 文件开始的用户很有用。
  3. perplexity: 计算模型在给定文本上的困惑度（Perplexity），用于评估模型的语言建模能力。
  4. embedding: 用于从文本生成向量嵌入（embeddings），这在语义搜索、聚类等任务中非常有用。
    • 用法: ./embedding -m ./models/your_model.gguf -p "Your text here."
  5. bench: 运行基准测试，测试模型在不同硬件配置下的性能。

对于普通用户来说，最常用的是 main 和 server。如果你想自己量化模型，quantize 会很有用。

性能优化与故障排除

提升性能的建议：

  • 使用 GPU 加速: 如果你有兼容的显卡，务必在编译时启用相应的后端 (LLAMA_CUBLAS=1, LLAMA_METAL=1 等)，并在运行时使用 -ngl 参数将尽可能多的层卸载到 GPU。这是提升速度最有效的方法。
  • 选择合适的量化级别: 更低的量化级别 (如 Q4_K_M vs Q8_0) 会减小模型大小和内存/显存占用，从而可能在内存/显存受限的情况下提高速度。但注意，过低的量化可能会影响模型质量。
  • 调整线程数 (-t): 尝试不同的线程数，通常接近你CPU的物理核心数能获得最佳性能。
  • 增加上下文 (-c) 会消耗更多资源: 如果你不需要处理很长的文本，使用默认或较小的上下文窗口可能会更快。
  • 使用最新的 llama.cpp 版本: 项目更新频繁，新版本通常包含性能优化。定期 git pull 更新代码并重新编译。

常见问题与故障排除：

  1. 编译失败:
    • 错误信息: 仔细阅读错误输出。
    • 缺少依赖: 检查是否安装了 CMake, 编译器。如果启用 GPU，检查是否安装了 CUDA/ROCm/Metal SDK，并确保路径正确。
    • Windows MSVC: 确保在 Visual Studio 的 开发者命令提示符 或 Developer PowerShell 中运行 CMake 和编译命令。
    • 清理: 尝试运行 make clean (如果使用 make) 或删除 build 目录重新开始 CMake 配置和构建。
  2. 模型加载失败:
    • 文件路径错误: 检查 -m 参数后的模型文件路径是否正确。使用绝对路径或相对于可执行文件的相对路径。
    • GGUF 格式问题: 确保你下载的是 .gguf 文件，并且文件没有损坏。有时特定版本的 llama.cpp 对 GGUF 版本有要求，可以尝试更新 llama.cpp 或下载另一个 GGUF 文件源。
    • 内存不足: 如果模型文件大小接近或超过你的物理内存，可能会加载失败或非常慢。尝试下载一个更小参数量或更高量化级别（文件更小）的模型。
  3. 运行缓慢:
    • 纯 CPU 运行: 这是正常的，纯 CPU 运行速度远不如 GPU。确保你已经启用了 GPU 加速（如果硬件支持），并使用了 -ngl 参数。
    • -ngl 参数无效: 检查编译时是否成功启用了 GPU 后端。查看运行时的输出，确认层是否真的被卸载到了 GPU。检查 GPU 驱动和 CUDA/ROCm/Metal 安装是否正确。
    • 线程数 (-t) 不合适: 尝试调整线程数。
    • 量化级别过低: 如果使用了 Q2 等极低量化，虽然文件小，但计算可能效率反而降低，或者模型质量差强人意。尝试 Q4_K_M 或 Q5_K_M。
    • 硬盘速度慢: 如果内存不足导致大量使用虚拟内存，或模型文件放在慢速硬盘上，加载和运行都会变慢。
  4. 输出质量差:
    • 模型选择: 不是所有模型都适合所有任务。聊天用 Chat 模型，写代码用 Code 模型。
    • 量化级别: 过低的量化可能会显著影响模型性能。尝试更高量化级别的模型（如果硬件允许）。
    • Prompt 工程: 尝试更清晰、更具体的 prompt。
    • 参数调整: 调整 --temp, --top-k, --top-p, --repeat_penalty 等参数。

总结与展望

llama.cpp 是一个令人惊叹的项目，它极大地降低了在本地运行大型语言模型的门槛。通过本文的介绍，你应该已经掌握了如何在自己的计算机上编译 llama.cpp，获取 GGUF 格式的模型，并使用 main 工具进行基本的文本生成。

从简单的命令行交互到搭建本地 API 服务（使用 server），llama.cpp 为我们打开了在个人硬件上探索 LLM 的大门。你可以尝试运行不同的模型、不同的量化版本，体验它们各自的特点和能力。

本地运行 LLM 不仅提供了隐私和离线使用的便利，更是深入理解 LLM 工作原理、进行个性化实验和开发的绝佳途径。随着 llama.cpp 的不断发展，以及更多高效模型和量化技术的出现，本地 AI 的能力边界将不断拓展。

现在，就开始你的本地 LLM 之旅吧！克隆 llama.cpp 仓库，下载你的第一个 GGUF 模型，然后在终端中敲下命令，亲手解锁属于你的本地 AI 力量！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部