llama.cpp：本地模型跑起来

前面#

本地跑大模型这事，网上教程一搜一大把，但也有 git clone 编译，看着就劝退
Windows 下有 LM Studio 这种无脑 GUI，双击就能跑，Linux 下 AUR 直接有包，想更无脑还有 Ollama（就是配置很局限）
这篇是从安装到日常命令写全的笔记，能跑起来（~~颓废ing~~）

环境：3060 12GB，llama.cpp 9093（CUDA 版）
日常用qwen3-vl-8b 给AI看图、bge-m3 做嵌入，全是本地推理，不增加API开销
（ComfyUI 跑的是 PyTorch 生图模型，跟 llama.cpp 是两码事）
合着就是给 AI 扩能力：qwen3-vl-8b 当眼睛、bge-m3 给 AstrBot 塞向量记忆，看得见还记性好，是免费的，目前就压力着显卡
写这篇的记录？帮朋友装的时候有点小坑，顺便回忆回忆，就记下来

llama.cpp 是啥#

C++ 写的本地推理引擎，支持 CPU、NVIDIA、AMD、Apple Silicon
模型用 GGUF 格式，一个文件一个模型，下载就能跑，不用装一堆依赖
仓库在github上

ggml-org

llama.cpp

Waiting for api.github.com...

00K

Waiting...

自带 OpenAI 兼容 API，起个服务后，任何能调 OpenAI 接口的程序直接改个 base_url 就能用本地模型（包括你的Agent）
省事，而且一个终端会话就可以是一个加载的模型，随用随关，有很多参数可以调整（我目前是konsole加拆分会话区域跑）

安装#

Arch 下 CUDA 版得从 AUR 装，官方仓库没有：

1
paru -S llama.cpp-cuda

llama.cpp-cuda 带 CUDA 支持，NVIDIA 显卡用这个，AUR 的包会自动带上 cuda 和 nvidia-utils 依赖
官方仓库里只有不带 CUDA 的 llama-cpp，纯 CPU 机器装那个就行
不想碰 AUR 也可以手动编译，或者直接用 archlinuxcn 仓库的 llama.cpp
其他平台：macOS 用 brew install llama.cpp，Windows 用 winget install ggml.llamacpp，或者去 GitHub Releases 下编译好的包
Releases 里没有 exe/msi 安装器，全是 zip，解压就能用（记得按上面说的挑版本）

装完有三个常用命令，够用了：

llama-cli：命令行聊天
llama-server：起 OpenAI 兼容服务
llama-bench：跑分测速

坑：llama-server 起不来，先查 CUDA
帮朋友装的时候又白给了一次，cuda 版二进制光有本体不行，还依赖 NVIDIA 驱动和 CUDA runtime
报错长这样：

1
error while loading shared libraries: libcuda.so.1: cannot open shared object file

或者启动时直接 CUDA 初始化失败：

1
CUDA error: no kernel image is available for execution on the device

Arch 下 paru -S llama.cpp-cuda 会自动带上 cuda 和 nvidia-utils 依赖，一般没这问题
手动下二进制（尤其 Windows 和 Ubuntu 这类）就得自己装好驱动和 CUDA，版本还要匹配
先跑 nvidia-smi，能正常输出显卡信息就说明驱动没问题

下载版本也有讲究，Releases 里的包名全是讲究，实际命名长这样：

1
llama-b10620-bin-win-cpu-x64.zip
2
llama-b10620-bin-win-cuda-12.4-x64.zip
3
llama-b10620-bin-win-cuda-13.3-x64.zip
4
llama-b10620-bin-win-rocm-7.14-x64.zip
5
llama-b10620-bin-win-vulkan-x64.zip

NVIDIA 卡认准带 cuda 的，别下 cpu 版，下错了就是 CPU 100%、GPU 0% 白干
cuda 版还分 12.4、13.3 等版本，选对应你自己装的 CUDA runtime 的，版本差太多会报 no kernel image
AMD 卡下 rocm 版，Intel 核显或者老卡下 vulkan 版，arm 设备选 arm64 后缀

模型从哪来#

llama.cpp 只能吃 GGUF 格式，别下 safetensors，那是原版权重，吃不了，吃过亏的都懂
HuggingFace 上搜「模型名 + GGUF」就行，优先 bartowski、unsloth、lmstudio-community 这几个组织发的
一个模型会有好几个量化版本，文件名里的 Q4_K_M、Q5_K_M、Q8_0 就是量化等级：

Q4_K_M：日常首选，体积小质量够
Q5_K_M / Q6_K：追求质量，显存够就上
Q8_0：接近原版精度，文件最大

选型口诀？显存紧张选 Q4_K_M，7B 模型大概 4.2GB，12GB 显卡随便跑
国内下载走镜像，比直连快，断了还能续：

1
HF_ENDPOINT=https://hf-mirror.com curl -L -o model.gguf 'https://hf-mirror.com/<仓库>/resolve/main/<文件>.gguf'

命令行聊天#

最直接的用法，跑起来就是交互式聊天：

1
llama-cli -m model.gguf -ngl 99

-m 指定模型文件
-ngl 99 把层全塞进显卡，99 就是全部（CPU 机器不写这个参数）
还能直接从 HuggingFace 拉模型，不用先下载：

1
llama-cli -hf bartowski/Llama-3.2-3B-Instruct-GGUF:Q4_K_M

-hf 直接写仓库名加量化版本，模型自动下载缓存，懒人福音

起来~#

用llama-server 起一个 OpenAI 兼容 API：

1
llama-server -m model.gguf -ngl 99 -c 8192 --port 8080

-c 8192 上下文长度，默认 0 = 用模型自带的，很多模型不够长，按需调大
--port 8080 监听端口，默认就是 8080
--host 127.0.0.1 只允许本机访问，局域网要用就绑 0.0.0.0 加 --api-key

测试一下：

1
curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"你好"}]}'

返回的 JSON 结构和 OpenAI 一模一样，本地当 OpenAI 用，香得很
浏览器打开 http://localhost:8080 还有个内置 Web 聊天界面，不想开就加 --no-webui

常用参数速查#

参数	作用
`-m`	模型文件路径
`-ngl`	显卡加载层数，99 全量
`-c`	上下文长度
`-t`	CPU 线程数
`-ub`	批大小，默认 512，嵌入长文本报 500 就调大
`-fa`	开启 Flash Attention，提速省显存
`--port` / `--host`	监听端口和地址
`--api-key`	给 API 加个密钥
`--no-warmup`	跳过启动预热，显存紧张时防 OOM

视觉模型#

llama.cpp 支持多模态，跑视觉模型要挂一个投影文件 mmproj：

1
llama-server -m qwen3-vl-8b-q4.gguf --mmproj mmproj-qwen3-vl-8b-f16.gguf -ngl 99 -c 8192 --port 8087

--mmproj 指定视觉编码器文件，和模型放一起下载
用 -hf 的话投影文件会自动一起拉，省事：

1
llama-server -hf unsloth/Qwen3-VL-8B-Instruct-GGUF:Q4_K_M -ngl 99 --port 8087

传图走 OpenAI 的 image_url 格式：

1
curl http://localhost:8087/v1/chat/completions -H "Content-Type: application/json" -d '{
2
  "messages": [{
3
    "role": "user",
4
    "content": [
5
      {"type": "text", "text": "这张图里有什么"},
6
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,<base64内容>"}}
7
    ]
8
  }]
9
}'

嵌入模型#

RAG 和语义搜索用的嵌入模型也能跑：

1
llama-server -m bge-m3-q8.gguf --embedding --pooling mean -c 8192 --port 8084

--embedding 切嵌入模式
--pooling mean 用 mean 池化，bge-m3 需要这个
调用接口是 /v1/embeddings：

1
curl http://localhost:8084/v1/embeddings -H "Content-Type: application/json" -d '{"input":"你好世界"}'

坑：嵌入长文本报 500 说 batch size 不够，是默认 -ub 512 太小，加 -ub 2048 重启就行，又是白给的教训

显存管理#

一张卡要跑生图又跑模型？是个头疼玩意
视觉模型加载后一直占着显存，生图（ComfyUI）一来，两个一起吃显存直接 OOM 撑爆，然后 OOM 就肘飞了视觉模型
当时还专门写了个 180 行的 relay 脚本，有请求才拉起 llama-server、空闲 300 秒杀进程释放显存
后来一查才发现 llama-server 内置了现成参数，一行搞定，感觉是白写了

1
llama-server -m model.gguf -ngl 99 --sleep-idle-seconds 30

--sleep-idle-seconds 30 空闲 30 秒自动把模型从显存卸载，有请求再加载
实测：推理时占 6.4GB，空闲 30 秒后掉到 960MB，唤醒约 1.4 秒
跟 ComfyUI 共用一张卡互不打架，从 180 行 relay 缩到一行参数的折腾记录见从 Ollama 到 llama.cpp：VS后续（仅供参考）

偷懒选项#

不想敲命令的话有现成的，懒人专用：

Ollama：装完 ollama run qwen3 就能用，模型管理方便，但多一层 overhead，自定义 GGUF 支持一般
LM Studio：图形界面，下载模型点鼠标就行，适合完全不想碰命令行的人

我最后选了纯 llama.cpp，原因写在本地跑vl模型用什么？llama.cpp vs Ollama？，一句话：少一层不透明，参数全在自己手里
Ollama 也不是当年那个纯本地了，出了 Cloud models 要登录账号才能跑云端大模型，本地用倒是没毛病，但路子感觉越来越臃肿
而且它本地推理底层本来就是 llama.cpp，等于套了层壳，官方 README 自己写的：

就这一行：Supported backends: llama.cpp project founded by Georgi Gerganov

模型还锁在自家 blob 仓库里，底层虽是 GGUF，想搬出来给 llama.cpp 跑还得手动倒腾，干脆一开始就用纯的
不过图省事、不想碰命令行的小白，Ollama 装完 ollama run 就能跑，也完全够用

最后#

显卡闲着也是闲着，不如让它上班，给点压力
管它白给多少次，能用就行