llama.cpp 安装与使用指南

优质文章学习记录

— 2 min read

llama.cpp 安装与使用指南

最新在使用llama.cpp的开源框架，所以简单写一下安装过程以及相关的介绍。

llama.cpp 是一个高性能的开源推理框架，用于在 CPU 和 GPU 上运行 LLaMA
系列及其他兼容的 Transformer 模型。
它的特点是轻量、跨平台、可在无显卡的设备上运行，同时对显卡显存利用率很高。

1. 项目介绍

llama.cpp 主要功能： - 支持多种量化格式（Q4, Q5, Q8, Q2
等），显著减少显存占用。 - 支持
CPU、GPU（CUDA、Metal、OpenCL、Vulkan）等多种后端。 - 提供简单易用的 CLI
和 HTTP 服务接口。 - 支持大多数 Hugging Face 上的
LLaMA、Qwen、Mistral、Baichuan、ChatGLM 等模型（需转换为 GGUF 格式）。

项目地址：https://github.com/ggerganov/llama.cpp

2. 安装方法

2.1 使用预编译版本（推荐新手）

  1. 从 Releases
    页面下载适配系统的二进制包（Windows/Linux/macOS）。
  2. 解压到目标目录。

测试是否可运行：

./llama-cli --help

2.2 从源代码构建（适合需要定制化）

依赖环境
  • Linux / macOS / Windows WSL
  • cmake（>= 3.20）
  • make
  • gcc / clang
  • CUDA Toolkit（如果需要 GPU 加速）
构建步骤（Linux / macOS）
# 克隆项目git clone https://github.com/ggerganov/llama.cpp.git cd llama.cpp # 创建构建目录mkdir build &&cd build # GPU 版本（CUDA） cmake ..-DLLAMA_CUBLAS=ON make -j$(nproc)# CPU 版本 cmake ..make -j$(nproc)

构建完成后会生成： - llama-cli：命令行推理工具 - llama-server：HTTP
API 服务 - quantize：模型量化工具

3. 模型准备

3.1 下载模型

可以从 Hugging Face 下载模型权重（需要科学上网），例如：

git lfs installgit clone https://huggingface.co/Qwen/Qwen2-7B

3.2 转换为 GGUF 格式

llama.cpp 只能加载 GGUF 格式模型，需要用官方脚本转换：

python3 convert.py /path/to/model --outfile model.gguf

3.3 量化模型（可选，减少显存）

./quantize model.gguf model-q4_0.gguf q4_0

4. 启动 HTTP 服务

./llama-server -m ./model-q4_0.gguf --port9558 --gpu-layers 40

参数说明： - -m：模型路径 - --port：HTTP 服务端口 -
--gpu-layers：加载到 GPU 的层数（越多显存占用越高，推理更快）

5. 常见问题

Q1: CUDA 版本报错 libcublas.so not found

原因：CUDA Toolkit 未正确安装或路径未添加。 解决：

exportLD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

Q2: 显存不足

  • 尝试使用更低精度的量化（如 q4_0, q3_k_m）。
  • 减少 --gpu-layers 数值。

Q3: 端口占用

修改 --port 参数，或释放对应端口：

sudolsof-i:9558sudokill-9<pid>

6. 总结

llama.cpp
是运行大模型的轻量高效方案，不依赖重型推理框架，可以在几乎任何设备上运行。
如果你的目标是本地部署、低延迟推理，且显存有限，那么它非常适合你。

Could not load content