适用场景
手里只有一台普通笔记本或一台没装 GPU 的云主机,可用内存只有 5GB 出头,想跑通一个本地小模型的完整推理链路。这套流程覆盖从权重下载、GGUF 转换、量化压缩到低内存推理参数调优的全过程,产出的模型文件可以直接在本机反复使用,不依赖任何在线 API。如果你正在做离线 Demo、内网工具原型,或者只是想在有限的机器上验证一个模型的效果,这套步骤可以照着抄一遍。
环境与前置条件
先说明一点:5.4GB 指的是“可用内存”,不是物理内存总量。物理内存 8GB 的机器,刨掉系统和其他进程占用,通常能剩下 5GB 左右,这才是有意义的预算。判断标准放在第一步。
| 项目 | 建议 |
|---|---|
| 操作系统 | Linux(Ubuntu/Debian 系最省事)、macOS;Windows 建议用 WSL2 |
| 内存 | 物理 8GB 起,可用 ≥ 5.4GB;低于这个值需要调小上下文或降量化档位 |
| 磁盘 | 空闲 15GB 以上(原始权重 + 中间 f16 文件 + 量化产物) |
| CPU | 4 核以上,支持 AVX2;ARM 平台也能跑,速度慢一些 |
| 运行时 | Python 3.10+;CMake、g++ 或 clang;git |
| 显存 | 非必需。有 GPU 可以加速,没有就走纯 CPU,本文按纯 CPU 写 |
磁盘空间要预留够,是因为转换过程会同时存在两份文件:一份原始的 Hugging Face 格式权重,一份 f16 的 GGUF 中间产物,最后才是量化后的小文件。中间产物在量化成功之后可以删掉。
分步骤部署
第一步:先检查可用内存
这一步决定后面选什么量化档位,不能跳过。
```bash
free -h
awk '/MemAvailable/ {printf "MemAvailable: %.2f GB\n", $2/1024/1024}' /proc/meminfo
```
关注 MemAvailable 这一行,它才是真正能给新进程用的内存。如果输出显示可用内存低于 5.4GB,先关掉浏览器、编辑器里的大项目、Docker 等占内存的东西,或者加一块 swap(见后面的报错处理)。
同时确认 CPU 指令集,决定了编译时能不能开加速:
```bash
grep -o 'avx2\|avx512f\|neon' /proc/cpuinfo | sort -u
```
输出里有 avx2 或 avx512f 说明可以用上向量化加速,编译时不用额外指定,llama.cpp 会自动识别。
第二步:准备目录与 Python 环境
把权重、中间文件、日志分开存放,后面清理和备份都方便。
```bash
mkdir -p ~/inkling2mini/{models,out,logs}
cd ~/inkling2mini
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -U "huggingface_hub[cli]" modelscope
```
huggingface_hub 用于从 Hugging Face 拉权重,modelscope 是国内网络环境下常用的备选渠道,两个都装上,哪个通用哪个。
第三步:拉取权重
模型仓库地址和是否需要申请访问权限,以官方文档当前版本为准。这里用变量占位,替换成实际的仓库 ID 即可。
```bash
export MODEL_REPO="<官方权重仓库 ID>"
export MODEL_DIR="$HOME/inkling2mini/models/inkling2mini-hf"
Hugging Face 渠道
hf download "$MODEL_REPO" --local-dir "$MODEL_DIR"
或者 ModelScope 渠道
modelscope download --model "$MODEL_REPO" --local_dir "$MODEL_DIR"
```
如果仓库是受限访问的,先登录:
```bash
hf auth login
```
成功标志:$MODEL_DIR 下出现 config.json、tokenizer 相关文件和若干 .safetensors 权重分片。
```bash
ls -lh "$MODEL_DIR" | head -20
du -sh "$MODEL_DIR"
```
顺便看一眼 config.json 里的 num_hidden_layers、hidden_size、num_attention_heads,后面估算 KV cache 要用到。
第四步:编译 llama.cpp
```bash
cd ~/inkling2mini
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
```
编译完成后确认二进制文件存在:
```bash
ls build/bin | grep -E 'llama-cli|llama-quantize|llama-server'
```
输出里有 llama-cli、llama-quantize、llama-server 三个就对了。不同版本的二进制文件名可能略有差异(老版本里量化工具叫 quantize),以编译产物为准。
如果只在 CPU 上跑,编译时不需要加任何 GPU 相关的开关,默认就是 CPU 后端。
第五步:转换成 GGUF 格式
GGUF 是 llama.cpp 的原生格式,支持内存映射,加载时不需要把整个文件读进 RAM,这对低内存机器至关重要。
```bash
cd ~/inkling2mini
source .venv/bin/activate
pip install -U -r llama.cpp/requirements.txt
python llama.cpp/convert_hf_to_gguf.py \
"$HOME/inkling2mini/models/inkling2mini-hf" \
--outfile "$HOME/inkling2mini/out/inkling2mini-f16.gguf" \
--outtype f16
```
这一步在做格式转换,把 safetensors 里的一堆张量打包成单个 GGUF 文件。成功标志是末尾输出类似 GGUF file successfully written,并且文件大小和原权重同量级(f16 一般是原始 fp16 权重的体积)。
```bash
ls -lh out/inkling2mini-f16.gguf
```
第六步:量化到可以塞进 5.4GB 的档位
量化就是用更少的比特表示每个权重。常见的几档:
Q8_0:接近无损,但体积大,5.4GB 预算下大概率放不下;Q5_K_M:质量好,体积中等;Q4_K_M:通用推荐档,质量和体积平衡点;Q3_K_M、Q2_K:更小,质量损失明显,只在内存极度紧张时用。
先跑 Q4_K_M,跑不起来再往下退。
```bash
./llama.cpp/build/bin/llama-quantize \
./out/inkling2mini-f16.gguf \
./out/inkling2mini-Q4_K_M.gguf \
Q4_K_M
```
成功标志是最后打印出 llama_model_quantize_internal: model size = ... MB 一类的统计行,并生成新文件。
```bash
ls -lh out/
```
粗略估算内存账:模型文件体积 + KV cache + 几百 MB 运行时开销 ≈ 峰值内存。其中 KV cache 大小约等于:
```
KV ≈ 2 × 层数 × KV头数 × 每头维度 × 上下文长度 × 2 字节(f16)
```
上下文设 2048 时,小模型这部分通常在几百 MB 到 1GB 之间浮动。模型文件体积 + KV cache 超过 5.4GB,就要么降上下文,要么降量化档位。
第七步:低内存参数组合跑推理
这是整套流程的核心。下面这条命令里每个参数都有省内存的意图:
```bash
./llama.cpp/build/bin/llama-cli \
-m ./out/inkling2mini-Q4_K_M.gguf \
-c 2048 \
-n 256 \
-t "$(nproc)" \
--n-gpu-layers 0 \
-ctk q8_0 -ctv q8_0 \
-p "用三句话解释什么是模型量化。"
```
逐个说明:
-c 2048:上下文长度。这是最直接的内存旋钮,从 4096 降到 2048,KV cache 直接减半。-n 256:最多生成 256 个 token,够做验证,避免一不留神跑很久。-t $(nproc):用满 CPU 线程。线程数过多反而会因为调度开销变慢,机器核多的话可以试nproc-1。--n-gpu-layers 0:强制全部放 CPU。没显卡时不加也可以,加上是为了避免某些环境下误判设备。-ctk q8_0 -ctv q8_0:把 KV cache 也量化成 8bit,再省一半左右。如果当前版本的 llama.cpp 不支持这个参数,删掉即可,不影响主流程。- 不要加
--mlock:加了会把整个模型锁进物理内存,在 5.4GB 预算下几乎必然 OOM。 - 不要加
--no-mmap:默认的 mmap 让模型按需从磁盘分页加载,是低内存场景的关键;关掉它会把模型全量读进 RAM。
第一次运行会看到模型加载日志,然后开始输出。想交互式对话就去掉 -p,进入 REPL。
如果这条命令还是被系统杀掉,按这个顺序降:-c 2048 → 1024,Q4_K_M → Q3_K_M,把 -ctk/-ctv 加上。
第八步:起一个本地 API 服务(可选)
需要给别的程序调用时,用 llama-server,参数思路和上面一致:
```bash
./llama.cpp/build/bin/llama-server \
-m ./out/inkling2mini-Q4_K_M.gguf \
--host 127.0.0.1 --port 8080 \
-c 2048 \
--n-gpu-layers 0 \
-ctk q8_0 -ctv q8_0
```
看到 server is listening on http://127.0.0.1:8080 就表示启动成功。默认只监听本地回环,需要外部访问再改 --host,同时注意加访问控制。
验证部署是否成功
验证一:命令行推理能出结果。
用第七步的 llama-cli 命令跑一次,预期看到:
1. 加载阶段打印模型参数量、文件大小、上下文长度等信息;
2. 出现 llama_perf_context_print 一类的性能统计,包含 eval time、tokens per second;
3. 最后正常输出中文回答,进程退出码为 0。
```bash
echo $? # 应为 0
```
验证二:内存占用确实在预算内。
跑推理的同时另开一个终端,或用 /usr/bin/time 包一层:
```bash
/usr/bin/time -v ./llama.cpp/build/bin/llama-cli \
-m ./out/inkling2mini-Q4_K_M.gguf -c 2048 -n 64 \
--n-gpu-layers 0 -p "你好"
```
看输出的 Maximum resident set size,换算成 MB 后应明显低于 5.4GB。也可以用:
```bash
ps -o pid,rss,vsz,cmd -p "$(pgrep -f llama-cli)"
```
RSS 单位是 KB,除以 1024 得到 MB。
验证三:API 服务可访问。
```bash
curl -s http://127.0.0.1:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "回复两个字:收到"}],
"max_tokens": 16
}'
```
预期返回一个 JSON,choices[0].message.content 里是模型的回答。返回 200 且结构完整,就说明服务链路通了。
验证四:换一个稍长的上下文,确认没有崩。
```bash
./llama.cpp/build/bin/llama-cli -m ./out/inkling2mini-Q4_K_M.gguf \
-c 2048 -n 128 --n-gpu-layers 0 \
-p "请写一段 200 字左右的产品说明,主题是便携咖啡机。"
```
能稳定输出而不被 kill,说明内存余量够用。
常见报错与解决
报错一:进程直接消失,终端只留下一行 Killed
→ 原因:被内核 OOM Killer 杀掉,通常是上下文太长或量化档位太大,峰值内存超过了物理内存。
→ 解决:先降上下文,再降量化档位,最后才考虑加 swap。
```bash
降上下文
./llama.cpp/build/bin/llama-cli -m ./out/inkling2mini-Q4_K_M.gguf -c 1024 -n 128 --n-gpu-layers 0 -p "你好"
还不够就重新量化到更小的档位
./llama.cpp/build/bin/llama-quantize ./out/inkling2mini-f16.gguf ./out/inkling2mini-Q3_K_M.gguf Q3_K_M
```
临时加 swap(会变慢,但能救急):
```bash
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
free -h # 确认 Swap 行有数值
```
报错二:convert_hf_to_gguf.py 报 Unsupported model architecture 或读取 config.json 失败
→ 原因:llama.cpp 版本比模型发布旧,还没收录这个架构;或者 --outfile 目录不存在。
→ 解决:更新 llama.cpp 后重新编译,并确认输出目录已创建。
```bash
cd ~/inkling2mini/llama.cpp
git pull
cmake --build build -j"$(nproc)"
mkdir -p ~/inkling2mini/out
```
报错三:CUDA error: out of memory 或 no CUDA-capable device is detected
→ 原因:程序尝试用 GPU,但显卡不存在或显存不足。
→ 解决:显式关掉 GPU 卸载,全部走 CPU。
```bash
./llama.cpp/build/bin/llama-cli -m ./out/inkling2mini-Q4_K_M.gguf \
--n-gpu-layers 0 -c 2048 -n 128 -p "你好"
```
如果编译时误开了 CUDA 后端,重新用纯 CPU 方式编译一次即可。
报错四:cmake: command not found 或编译到一半报缺少 g++
→ 原因:构建工具链没装。
→ 解决:按发行版安装。
```bash
sudo apt update
sudo apt install -y build-essential cmake git python3-venv python3-pip
```
macOS 上装 Xcode Command Line Tools 和 brew install cmake。
报错五:模型加载极慢,卡在 loading model 很久,或者生成速度只有个位数 token/s
→ 原因:模型放在机械硬盘或网络盘上,mmap 分页读盘成为瓶颈;或线程数设置不合理。
→ 解决:把 gguf 挪到本地 SSD,并调整线程数。
```bash
mv ./out/inkling2mini-Q4_K_M.gguf /本地SSD路径/
./llama.cpp/build/bin/llama-cli -m /本地SSD路径/inkling2mini-Q4_K_M.gguf \
-t 4 -c 1024 -n 128 --n-gpu-layers 0 -p "你好"
```
报错六:error while loading shared libraries: libllama.so
→ 原因:动态库搜索路径没包含编译产物目录。
→ 解决:指定库路径运行,或改用静态链接构建。
```bash
LD_LIBRARY_PATH=~/inkling2mini/llama.cpp/build/bin ./llama.cpp/build/bin/llama-cli -m ./out/inkling2mini-Q4_K_M.gguf -p "你好"
```
后续维护
备份。 真正需要长期保留的其实只有两样:量化好的 .gguf 文件和生成它时用的参数。原始 Hugging Face 权重和 f16 中间文件都可以删掉,能省出十几个 GB。建议在模型目录里放一个 build-notes.md,记下量化档位、上下文长度、当时的 llama.cpp 提交号:
```bash
cd ~/inkling2mini/llama.cpp && git rev-parse --short HEAD
du -sh ~/inkling2mini/out/*.gguf
```
升级。 llama.cpp 迭代很快,新版本经常带来推理速度提升和新模型支持。升级方式是拉代码重编译,模型文件不用动:
```bash
cd ~/inkling2mini/llama.cpp
git pull
cmake --build build -j"$(nproc)"
```
升级后重新跑一遍验证命令,重点确认同一份 gguf 在新版下仍能正常加载、输出质量没有异常。
日志与监控。 对外提供服务时,把 llama-server 的输出重定向到文件,并用简单的定时采样观察内存趋势:
```bash
nohup ./llama.cpp/build/bin/llama-server \
-m ./out/inkling2mini-Q4_K_M.gguf \
--host 127.0.0.1 --port 8080 -c 2048 --n-gpu-layers 0 \
> ~/inkling2mini/logs/server.log 2>&1 &
每分钟记录一次内存
while true; do
echo "$(date -Is) $(ps -o rss= -p "$(pgrep -f llama-server)")" >> ~/inkling2mini/logs/rss.log
sleep 60
done
```
日志涨到一定大小就切分,用 logrotate 或者简单的按日期重命名都行。
容量规划。 如果后面要在同一台机器上跑多个并发请求,注意 llama-server 默认按顺序处理,并发上来之后排队会变长,内存也会因为多份 KV cache 而吃紧。低内存机器的正确姿势是限制并发数、把上下文压到够用的最小值,而不是硬堆参数。模型仓库更新、量化工具参数变化,都以官方文档当前版本为准,动手前扫一眼 release notes 能省不少排查时间。
