llama.cpp 是一个极受欢迎的 C/C++ 实现，旨在让大语言模型 (LLM) 能够在各种硬件上（从树莓派到高性能服务器）高效运行。它的核心优势是无需复杂依赖，性能出色，且支持广泛的量化格式。

本教程将指导你通过多种方式部署和使用 llama.cpp。

1. 部署前准备

硬件要求

  • 最低配置：4GB RAM，任意 CPU。
  • 推荐配置：
    • CPU：支持 AVX2/AVX512 的现代 x86 处理器，或 Apple Silicon (M系列)。
    • GPU (可选)：NVIDIA (CUDA)、AMD (HIP)、Intel (SYCL) 或 Apple (Metal)。
    • 内存：根据模型大小，建议至少 8GB (7B 模型) 或 32GB (70B 模型)。

软件要求

  • 操作系统：Windows、Linux、macOS。
  • 基础工具：git、cmake、C/C++ 编译器 (如 gcc、clang 或 Visual Studio)。
  • 可选：Python (用于模型转换和下载脚本)。

2. 部署方式

llama.cpp 提供多种部署路径，以适应不同用户。

方式一：使用预编译二进制文件 (最简单)

这是最快捷的方式，适合大多数用户。

  1. 下载：访问 llama.cpp Releases 页面，下载适用于你操作系统的最新预编译包。

    • Windows：下载 llama-bin-win-avx2-*.zip 等文件。
    • macOS：下载 llama-bin-macos-*.tar.gz。
    • Linux：下载 llama-bin-ubuntu-*.tar.gz。

  2. 解压：将压缩包解压到你选择的目录。

  3. 运行模型：打开终端，进入解压目录，执行以下命令直接下载并运行一个 GGUF 模型：

    1
    2
    3
    4
    5
    # 下载并运行一个来自 Hugging Face 的小模型
    ./llama cli -hf ggml-org/Qwen3.5-0.8B-GGUF

    # 启动一个 OpenAI 兼容的 API 服务器
    ./llama serve -hf ggml-org/Qwen3.5-0.8B-GGUF

    其中 -hf 参数会自动从 Hugging Face 下载指定的 GGUF 模型文件。

方式二：从源码编译 (推荐高级用户)

从源码编译能让你获得最佳性能，并启用特定硬件加速。

Linux / macOS

  1. 克隆仓库：

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

  2. 使用 CMake 构建：

    1
    2
    3
    mkdir build && cd build
    cmake ..   # 添加 -DGGML_METAL=ON 以启用 Apple Metal 加速
    cmake --build . --config Release -j $(nproc)  # Linux 下使用 $(nproc)

    构建完成后，可执行文件 (如 llama-cli) 会在 build/bin/ 目录下。

Windows (使用 Visual Studio)

  1. 克隆仓库。
  2. 在 Visual Studio 中打开项目文件夹，或使用 CMake GUI 生成 Visual Studio 解决方案。
  3. 选择 Release 配置并构建。
  4. 构建成功后，可执行文件位于 build/bin/Release。

方式三：使用 Docker (适合服务器)

Docker 提供了良好的环境隔离和便捷的部署。

请参考官方 Docker 文档 获取详细命令。基本用法是拉取镜像并运行容器，将模型文件挂载到容器内。

3. 核心工具使用

安装完成后，你会获得几个主要命令行工具：

  • llama cli：这是主要的交互式命令行工具，用于与模型进行对话。

    1
    2
    # 运行一个本地 GGUF 模型文件
    ./llama cli -m ./models/llama-2-7b.Q4_K_M.gguf -p "你好，请问你是谁？"

  • llama serve：启动一个兼容 OpenAI API 的 HTTP 服务器，方便其他应用 (如 Web UI) 调用。

    1
    2
    ./llama serve -m ./models/llama-2-7b.Q4_K_M.gguf
    # 服务默认运行在 http://localhost:8080

    启动后，你可以使用 curl 或任何 OpenAI 客户端库来发送请求。

  • 内置 Web UI：当使用 llama serve 启动服务器后，你可以在浏览器中访问 http://localhost:8080，使用一个简洁的 Web 聊天界面与模型交互。

4. 获取和转换模型

llama.cpp 使用 GGUF 格式的模型文件。

  • 直接下载：从 Hugging Face 等平台搜索并下载 GGUF 格式的模型文件。许多热门模型都有社区转换好的版本。

  • 使用 -hf 参数：如快速开始所示，llama cli 和 llama serve 支持 -hf 参数，可以直接从 Hugging Face 下载并运行模型。

  • 自行转换：如果你有 PyTorch 格式的模型，可以使用项目提供的 convert_hf_to_gguf.py 脚本将其转换为 GGUF 格式。

    1
    python convert_hf_to_gguf.py /path/to/pytorch/model --outfile model.gguf

5. 性能优化建议

  • 启用硬件加速：在编译时启用对应的后端（如 -DGGML_METAL=ON for Apple, -DGGML_CUDA=ON for NVIDIA）。
  • 选择合适的量化版本：模型文件名中的 Q4_K_M、Q5_K 等表示量化级别。较低的比特数（如 Q4）占用更少内存但精度稍低；较高的比特数（如 Q8）精度更高但更耗内存。根据你的硬件选择平衡点。
  • 调整上下文长度：使用 -c 2048 等参数设置上下文窗口大小，影响内存占用和处理速度。
  • 使用批处理：在 llama-server 中，可以通过 -np 参数设置并行处理的请求数，提高吞吐量。

6. 故障排查

  • llama: command not found：确保你在终端中位于包含 llama 可执行文件的目录，或者已将其路径添加到 PATH 环境变量中。
  • 内存不足 (OOM)：选择更小的模型或使用更低的量化版本 (如 Q4)。也可以通过 -ngl 0 强制完全使用 CPU，避免 GPU 显存不足。
  • GPU 加速未生效：确认在编译时正确启用了对应的后端 (如 -DGGML_METAL=ON)。运行时，llama 命令应该会输出加载了哪些后端。

总结

llama.cpp 是部署和运行 LLM 最强大、最灵活的工具之一。通过本教程，你应该已经掌握了安装、基础使用和性能调优的方法。

  • 初学者：建议从使用预编译二进制文件开始，通过 llama cli -hf 快速体验。
  • 进阶用户：可以尝试从源码编译，并根据自己的硬件启用特定的优化（如 Metal 或 CUDA）。
  • 生产部署：使用 Docker 结合 llama serve 是可靠的选择。

在实际使用中，可以根据你的具体硬件和模型需求，灵活调整编译选项和运行参数，以获得最佳的性能和体验。如果在具体环节遇到问题，可以查阅项目根目录下的 docs/ 文件夹中更详细的指南。