llamacpp 怎么用 - llama.cpp llama-cli 参数速查表（含量化与 GPU）
llamacpp（即 llama.cpp）是用 C/C++ 重写的轻量推理引擎，能在纯 CPU、Apple Silicon 与各类 GPU 上跑 GGUF 量化模型。llama-cli 是它自带的命令行对话前端，适合在本地终端快速验证模型、做离线推理。本表以 llamacpp 命令为主线，覆盖模型加载、采样、上下文与性能调优的关键参数，读完即可在笔记本上跑起对话。
典型使用场景
面向想在本地跑大模型（尤其 llama.cpp 生态）的开发者。llama-cli 是 llama.cpp 的命令行入口，覆盖模型下载、交互对话、一次问答、embedding 与基准测试。多数人真正高频用的是两个：加 -p 做单次问答接脚本，以及 --hf-repo 直接从 Hugging Face 拉模型。本表按模型获取、推理模式、采样参数、性能调优、实用组合五组组织。
基础推理 8
llama-cli -m model.gguf -p "你好"llama-cli -m model.gguf --interactivellama-cli -m model.gguf -ngl 35llama-cli -m model.gguf -c 4096llama-cli -m model.gguf -t 8llama-cli -m model.gguf --temp 0.7llama-cli -m model.gguf --top-p 0.9llama-cli -m model.gguf --color采样与上下文 6
llama-cli -m model.gguf --repeat-penalty 1.1llama-cli -m model.gguf -s 42llama-cli -m model.gguf --system "你是一名助手"llama-cli -m model.gguf -cnvllama-cli -m model.gguf -f prompt.txtllama-cli -m model.gguf --flash-attn性能与高级 6
llama-cli -m model.gguf -ngl 99llama-cli -m model.gguf -t 16llama-cli -m model.gguf -c 8192llama-cli -m model.gguf --mlockllama-cli -m model.gguf -b 512llama-cli --help参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
-m <file> | 指定 GGUF 模型文件 | llama-cli -m model.gguf |
-hf <user/repo> | 直接从 Hugging Face 下载并运行 | llama-cli -hf ggml-org/gemma-3-4b-it-GGUF |
-p "问题" | 单次问答后退出，适合脚本 | llama-cli -m m.gguf -p "写个快排" |
--hf-file | 配合 -hf 指定仓库内的具体文件 | llama-cli -hf <repo> --hf-file q4.gguf |
-c | 上下文长度，显存不足时先降它 | llama-cli -m m.gguf -c 4096 |
-ngl | 卸载到 GPU 的层数，全卸载填 99 | llama-cli -m m.gguf -ngl 99 |
-t <threads> | CPU 线程数 | llama-cli -m m.gguf -t 8 |
--temp | 随机性，0 更确定 | --temp 0 |
--top-k / --top-p | 采样截断，控制候选范围 | --top-p 0.9 |
-n <tokens> | 最大生成 token 数 | -n 512 |
--embeddings | embedding 模式而非生成 | llama-cli -m m.gguf --embeddings |
--benchmark | 跑推理基准测试 | llama-cli -m m.gguf --benchmark |
易错点与避坑指南
现象加载模型时报 "not enough memory" 或被系统杀掉。
原因模型大小超过可用显存/内存，或上下文长度设得过大。
处置优先降 -c 上下文长度，其次换更小的量化版本（Q4 比 Q8 小得多），再用 --benchmark 确认能跑。
现象CPU 推理速度极慢，等待时间不可接受。
原因模型未卸载到 GPU，或层数设置过低。
处置-ngl 99 尽量全部卸载到 GPU；无 GPU 时增加 -t 线程数并选更小模型。
现象输出内容重复、卡在同一个循环里。
原因采样参数过于贪心，或未设置停止条件。
处置调 --temp 与 --top-p 引入随机性；脚本场景可加 --temp 0 换取确定性输出。
现象中文输出乱码或截断。
原因模型本身非中文模型，或上下文不足导致回答被截。
处置换多语言模型；增加 -c 长度并用 -n 放宽生成长度上限。
现象脚本里调用后进程不退出。
原因未使用 -p 单次问答模式，进入了交互循环。
处置脚本内一律加 -p "..." 让它问答一次后退出。
现象同一问题两次运行结果差异很大。
原因随机采样导致，且未固定种子。
处置需要可复现时用 --temp 0；批量测试对比时同时固定模型版本与量化。
排障路径
1确认当前配置能否正常推理
llama-cli -m model.gguf --benchmark跑基准测试能确认模型可加载并给出吞吐量数据。
2显存不足时先降上下文
llama-cli -m model.gguf -c 2048 -ngl 99上下文长度是显存占用大户，优先降它而不是换模型。
3脚本里的单次问答
llama-cli -m model.gguf -p "总结这段配置"-p 问答一次即退出；加 --temp 0 换取确定性结果。
4直接从 Hugging Face 取模型运行
llama-cli -hf ggml-org/gemma-3-4b-it-GGUF --hf-file gemma-3-4b-it-Q4_K_M.gguf免手动下载；仓库内文件多时用 --hf-file 指定量化版本。
5在纯 CPU 上提高吞吐
llama-cli -m model.gguf -ngl 0 -t 8无 GPU 时显式关掉 GPU 卸载并给足线程数。
命令示例
脚本里单次问答：加 -p 才会退出
llama-cli -m model.gguf -p "把下面这段需求整理成三条验收标准" --temp 0 -s 42不带 -p 时进程进入交互循环，脚本会一直挂着直到超时。--temp 0 换成贪心解码，同一问题每次得到同一份输出，适合被下游程序解析；-s 42 固定种子进一步消除采样层面的随机性。需要创造性的回答才把温度调回 0.7 一带。
性能基线组合：全量卸载 GPU + Flash Attention + 上下文
llama-cli -m model.gguf -ngl 99 --flash-attn -c 8192 -t 16 --top-p 0.9 --repeat-penalty 1.1-ngl 99 表示尽可能多的层卸载到 GPU，有显卡时这是最关键的一项；纯 CPU 机器上不卸载反而更稳。--flash-attn 降低长上下文的显存与算力开销。-c 8192 是上下文窗口，越大越吃显存，按模型实际支持长度设。-t 16 与采样参数按机器实际情况调。
交互式对话：系统提示 + 多轮上下文 + 彩色输出
llama-cli -m model.gguf --interactive --system "你是一名助手" -cnv --color--system 注入的系统提示在每一轮都生效，适合固定角色与输出格式。-cnv 开启多轮对话上下文，让模型记得前面的问答；上下文窗口按 -c 设定，超出就会被截断，表现为回答突然变短或答非所问。--color 只影响终端显示，抓取输出重定向到文件时通常不含颜色信息。
长提示从文件读：-f 配合分层卸载与批大小
# 提示词放在文件里，避免 shell 引号与超长参数的转义问题
llama-cli -m model.gguf -f prompt.txt -ngl 35 -b 512 -c 4096
# 确认当前构建实际支持哪些参数
llama-cli --help提示词一旦包含引号、换行或管道符，走 shell 传参就要层层转义，容易静默丢字符；写进文件用 -f 读取最稳。-ngl 35 适用于显存装不下整个模型但能放下部分层的场景。-b 512 是 prompt 批处理大小，批越大长提示的预填充越快，但也更吃内存。不同构建的参数集并不完全一致，--help 是唯一可靠的清单。
常见坑与注意事项
- 显存/内存被吃满时进程会被系统 OOM Killer 直接杀掉：没有堆栈、没有 Python/Java 式报错，只是运行中途消失（同机 dmesg 里才有 OOM 记录）。-ngl 99 加上过大的 -c 是最常见的组合，先降 -c 再换更小的量化版本。
- 模型文件来源不可信就是执行不可信代码：第三方仓库里的 GGUF 可以被替换或植入恶意内容，llama.cpp 在加载时会解析其中的元数据与张量。模型只从可信源或自己转换的权重取；--hf-repo 拉取后先校验来源。
- --system 的内容与 -f 指定的文件会把完整提示（含内部文档、账号信息、密钥片段）送进本地模型，并可能被 --color 之外的重定向、终端回滚缓冲或日志文件记录下来。提示词文件与模型输出都按敏感数据对待，不要放进会被同步的目录。
- 不固定种子与温度时，同一提示两次运行结果不同，批量回归、评分与断言会随机失败且难以复现。脚本与测试链路一律用 --temp 0 并配 -s 42，同时把模型文件与量化版本一起记录下来。
- -t 线程数设成物理核数以上会让进程与其他服务抢同一批 CPU，吞吐反而下降，还可能把同机的构建、测试任务拖到超时。CI 里要按并发数分配线程，而不是每个任务都按核数拉满。
提示
-ngl是性能关键：能全卸载到 GPU 就设大（如 99），纯 CPU 机器设 0。- 上下文
-c越大越吃显存，按模型实际支持长度设置，不必盲目拉满。 - GGUF 量化模型配合
-ngl+--flash-attn在 Apple Silicon / CUDA 上体验最佳。
常见问题
llama-cli 和 ollama 有什么区别？
llama-cli 是 llama.cpp 的原生推理前端，偏底层、参数细；ollama 是更上层的模型管理+服务封装，开箱即用但可调项少。
GPU 不生效怎么办？
确认用 -ngl 设置了卸载层数，且构建版本包含对应后端（CUDA / Metal / Vulkan）；纯 CPU 跑设 -ngl 0。
-ngl 到底该设多少？
原则是「显存够就全卸载」：整个模型放得下时设 99（或模型层数），把全部层交给 GPU；显存不足时从 99 逐步下调到刚好不 OOM 的层数，剩余层留给 CPU。纯 CPU 机器设 0。
上下文 -c 设多大合适？
按模型实际支持的上下文长度设置即可，不必盲目拉满：KV 缓存随 -c 线性增长，设得越大显存/内存占用越高，超出模型训练长度还会拉低输出质量。
-i 和 -cnv 有什么区别，该用哪个？
-i 是通用交互模式，适合连续给同一类提示词、每次独立生成；-cnv 是多轮对话模式，会保留对话上下文并按模型自带的对话模板组织消息，可配合 --system 设置系统提示，要「聊下去」时用 -cnv。
由 巧匠 维护
公开更新于 2026年9月10日，内容持续校对官方文档。