简介

llama.cpp 是ChatGPT火爆后最早也是最核心的LLM推理引擎。 配套的还有 ggml/gguf 等适用于个人电脑的量化LLM模型档案格式。 用C++实现，小巧高校，社区活跃，对新模型有很及时的支持，是很多LLM本地运行工具的上游引擎。

优势

• 体积小，占用磁盘空间少。
• 可控性强，基础引擎可以定义所有参数。
• 直接使用 gguf 格式模型档案，便于模型收录档案管理。

劣势

• 用户不够友好，毕竟是核心引擎，虽然出了WebUI但远没有其他集成软件用户友好。
• 配置门槛高，运行模型本身就是命令行执行，配套的 Agent/SCP/RAG 等都需要自行组装。

版本

项目的开发和分发都在Github进行。

引擎本身支持不同的硬件加速:

• cpu 最精简状态，纯CPU推理。
• cuda 支持 Nvidia GPU 加速。
• rocm 支持 AMD GPU 加速。
• vulkan 支持开源GPU驱动加速。
• opencl 支持开源GPU驱动加速。

docker镜像发行分三类方式:

• light 轻量级，仅仅核心推理引擎，llama-cli命令行交互对话。
• server 服务端，运行引擎搭配Web服务器，提供API接口，新推出的WebUI也是server的一部分。
• full 全功能，包含以上内容，以及量化转换等各种辅助工具。

衍生

日常用到的各种LLM本地运行的应用程序，几乎都是基于 llama.cpp 封装开发的。

• Jan
  • 曾经自研引擎，现在自研引擎项目 cortex 已停滞，就直接打包llama.cpp。
• Ollama
  • 重写了llama.cpp,提供了更集成的封装和配置，如今引擎越来越向llama.cpp靠拢。
  • 模型采用自己的存储格式，有官方模型库，可以从GGUF导入，但会有效果差异。
  • 更新不如llama.cpp及时，比如qwen的多模态暂无法支持gguf导入。
• LM Studio
  • 商业软件，就是对llama.cpp的封装，提供用户友好的操作界面和API服务。
• GPT4ALL
  • 早期基于llama.cpp的GUI,现在开源版本似乎停止更新了。

安装

• Docker/Podman
  • pull镜像即可，镜像在Github的托管发布，官方没有在DockerHub上发布，不便于查询版本和体积，这里列出来。
    • 目前项目更新非常频繁，没有大版本号，所以直接用 light/server/full 最新版即可。
    • light 不到100M,-cuda 需要额外约2GiB, full-cuda 最大约5GiB。
  • 官方的参考命令有些问题，比如交互后无限回车，运行容器时加上 -it 参数即可。
• Linux
  • 目前llama.cpp并没有收录进各发行版的仓库。
  • 从Github发布页根据自己硬件的情况下载最新的二进制包解压运行即可，没有额外依赖。
• MacOS
  • 可以借助包管理工具安装
    • brew install llama.cpp
    • sudo port install llama.cpp
    • nix profile install nixpkgs#llama-cpp
• Windows
  • 从Github发布页根据自己硬件的情况下载最新的二进制包解压运行即可。
  • 也可以选择 Jan 或 LM Studio 等集成应用。
• 自行编译/Android
  • llama.cpp 由C++编写，依赖几乎只有显卡加速驱动库，按照说明编译不难。
  • Android 可借助 Termux 类应用编译运行，这里不做详细介绍。
  • Android也有很多应用封装了 llama.cpp 如 Maid/PocketPal 。

使用

参数

• 通用参数
  • -ngl auto 多少层加载到GPU,默认auto即可，目前引擎自动分配已足够智能。
  • -c 0 上下文长度，默认0采用GGUF档案中自带的默认值。
  • -fa auto 是否启用 fast attention 加速，默认auto即可能启用就用。
  • --jinja 指定使用GGUF中包含的对话模板，省得自己拼装prompt。
  • -m path/to/gguf 指定模型权重档案位置。
  • -mm path/to/mmproj/file 指定配套的多模态权重档案位置。
  • --host 0.0.0.0 server/full版本指定服务监听的IP,目前有BUG仅监听 localhost/127.0.0.1 本机无法访问
  • --port 8033 server/full版本指定服务监听的端口，早期默认8080官方WebUI推荐8033,可任选一个空闲的自己喜欢的端口。
• 模型超参数参考官方建议或保持默认
  • unsloth 提供的使用指南中通常都包含 llama.cpp 的参数设置,通常和官方推荐一致，而且gguf档案目前也是这家的版本最受欢迎。
  • –temp 温度，控制模型的生成发散性，越高越发散。
  • –top-p 候选概率阈值，越低约发散。
  • –top-k 候选数量阈值，越高越发散。
  • –min-p 候选词最小概率。
  • –presence-penalty 存在惩罚，降低已生成的token再次出现的概率，越低越可能重复。
  • –repeat-penalty 重复惩罚，已生成的越多惩罚越强，越低越可能重复。
  • –chat-template-kwargs 为聊天模板设定参数，通常控制是否思考，传入json字符串

参考命令

这里给出通过 docker 运行 server-cuda 镜像的示例命令行，直接运行把 docker 的部分去掉即可。 容器也可以查看帮助 docker run --rm llama.cpp:server-cuda -h 运行命令启动容器后，访问 http://localhost:8033 即可看到 llama.cpp 的官方WebUI。

Qwen3.5-9B-unsloth

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

ARGS=''
ARGS+=' -p 8033:8033 -v /path/to/gguf/folder:/models:ro --gpus=all --name=LlamaCpp --rm '
ARGS+=' llama.cpp:server-cuda '
ARGS+=' -c 0 -fa auto --jinja --host 0.0.0.0 --port 8033 '
ARGS+=' -m /models/Qwen3.5-9B-Q4_K_M.gguf -mm /models/mmproj-BF16.gguf '
#ARGS+=' --temp 1.0 --top-p 0.95 --top-k 20 --min-p 0.0 --presence-penalty 1.5 --repeat-penalty 1.0 '	# 思考通用任务|非思考推理任务
#ARGS+=' --temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.0 --presence-penalty 0.0 --repeat-penalty 1.0 '	# 思考精确编码任务
ARGS+=' --temp 0.7 --top-p 0.8 --top-k 20 --min-p 0.0 --presence-penalty 1.5 --repeat-penalty 1.0 '	# 非思考通用任务
#ARGS+=' --chat-template-kwargs ''{"enable_thinking":true}'	# 思考
ARGS+=' --chat-template-kwargs ''{"enable_thinking":false}'	# 不思考
docker run $ARGS

gemma-4-26B-A4B-it-unsloth

1
2
3
4
5
6
7
8

ARGS=''
ARGS+=' -p 8033:8033 -v /path/to/gguf/folder:/models:ro --gpus=all --name=LlamaCpp --rm '
ARGS+=' llama.cpp:server-cuda '
ARGS+=' -c 0 -fa auto --jinja --host 0.0.0.0 --port 8033 '
ARGS+=' -m /models/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf -mm /models/mmproj-BF16.gguf '
ARGS+=' --temp 1.0 --top-p 0.95 --top-k 64 '
ARGS+=' --chat-template-kwargs ''{"enable_thinking":false}'	# 是否思考
docker run $ARGS

配套

llama.cpp 项目本身并没有集成方便的配套工具。 如果集成多了软件和镜像的体积也就大了，所以还是自行组装更好。 之后在新开博文介绍如何基于 llama.cpp 搭建智能体。