llama.cpp llama-completion 实战指南：命令行文本生成、对话模式与采样调优的完整解析

llama-completion 是 llama.cpp 官方提供的命令行文本生成工具，也是项目中最核心的示例程序之一。它既能做"一次性"的 prompt 续写，也能进入持续交互的对话模式，覆盖采样器调优、上下文管理、模型加载与多 GPU 分配等全部关键能力。本文基于 tools/completion/README.md 的完整内容展开，并深入 tools/completion/completion.cpp 源码，帮助你在真实项目中快速上手并理解其底层机制。

一、它是什么：从构建结构与入口说起

从 tools/completion/CMakeLists.txt 可以看出，该工具拆分为两部分：

• llama-completion-impl：由 tools/completion/completion.cpp 编译出的库，封装全部生成逻辑，可被其他工具复用（例如 app/llama.cpp 应用）；
• llama-completion：由 tools/completion/main.cpp 编译的可执行文件，入口仅 5 行，直接转发到 llama_completion(argc, argv)。

llama-completion-impl 链接了 llama-common 与 llama 两个库，因此它复用了 llama.cpp 统一的参数解析体系（common/arg.cpp）与公共参数结构。README 中标注 LLAMA_EXAMPLE_COMPLETION 的选项，正是 common/arg.cpp 中按示例类型分发注册的 completion 专属参数。

二、快速开始

首次使用需要下载一个模型。原文档以 Hugging Face 上 ggml-org 仓库提供的 Gemma 模型为例（gemma-1.1-7b-it.Q4_K_M.gguf），下载后放入 llama.cpp 的 models/ 目录，然后按场景选择命令。

Unix 系统（Linux、macOS 等）

一次性输入 prompt（One-and-done）：

./llama-completion -m models/gemma-1.1-7b-it.Q4_K_M.gguf -no-cnv --prompt "Once upon a time"

对话模式（与模型持续交互）：

./llama-completion -m models/gemma-1.1-7b-it.Q4_K_M.gguf --chat-template gemma

使用模型内置 jinja 聊天模板进入对话模式：

./llama-completion -m models/gemma-1.1-7b-it.Q4_K_M.gguf --jinja

jinja 单轮查询：自定义系统提示词 + 起始 prompt：

./llama-completion -m models/gemma-1.1-7b-it.Q4_K_M.gguf --jinja --single-turn -sys "You are a helpful assistant" -p "Hello"

从起始 prompt 无限生成文本（Ctrl-C 停止）：

./llama-completion -m models/gemma-1.1-7b-it.Q4_K_M.gguf --ignore-eos -n -1

Windows

# 一次性输入 prompt
./llama-completion.exe -m models\gemma-1.1-7b-it.Q4_K_M.gguf -no-cnv --prompt "Once upon a time"

# 对话模式
./llama-completion.exe -m models\gemma-1.1-7b-it.Q4_K_M.gguf --chat-template gemma

# 使用内置 jinja 聊天模板
./llama-completion.exe -m models\gemma-1.1-7b-it.Q4_K_M.gguf --jinja

# jinja 单轮查询
./llama-completion.exe -m models\gemma-1.1-7b-it.Q4_K_M.gguf --jinja --single-turn -sys "You are a helpful assistant" -p "Hello"

# 无限生成文本
llama-completion.exe -m models\gemma-1.1-7b-it.Q4_K_M.gguf --ignore-eos -n -1

提示：如果模型元数据里带有聊天模板，程序会自动启用对话模式；-no-cnv 可强制关闭。从源码 tools/completion/completion.cpp 可以看到这段自动判定逻辑：当 conversation_mode 为 AUTO 且检测到可用聊天模板时，打印 "chat template is available, enabling conversation mode" 并置为 ENABLED，否则置为 DISABLED；若用户用 -cnv 强行开启但模板不可用，会给出警告。

三、完整参数参考（Usage）

以下参数表由 llama-gen-docs（examples/gen-docs/gen-docs.cpp）自动生成，以 llama-completion --help 的实际输出为准。

通用参数（Common params）

参数	说明
-h, --help, --usage	打印用法并退出
--version	显示版本与构建信息
-cl, --cache-list	显示缓存中的模型列表
--completion-bash	打印可 source 的 bash 补全脚本
-t, --threads N	生成阶段使用的 CPU 线程数（默认 -1）（env: LLAMA_ARG_THREADS）
-tb, --threads-batch N	batch 与 prompt 处理阶段使用的线程数（默认同 --threads）
-C, --cpu-mask M	CPU 亲和掩码：任意长十六进制，与 cpu-range 互补
-Cr, --cpu-range lo-hi	CPU 亲和范围，与 --cpu-mask 互补
--cpu-strict <0|1>	是否使用严格 CPU 绑定（默认 0）
--prio N	进程/线程优先级：low(-1)、normal(0)、medium(1)、high(2)、realtime(3)（默认 0）
--poll <0...100>	等待工作时的轮询级别（0 表示不轮询，默认 50）
-Cb, --cpu-mask-batch M	batch 阶段的 CPU 亲和掩码（默认同 --cpu-mask）
-Crb, --cpu-range-batch lo-hi	batch 阶段的 CPU 亲和范围
--cpu-strict-batch <0|1>	batch 阶段严格 CPU 绑定（默认同 --cpu-strict）
--prio-batch N	batch 阶段优先级（默认 0）
--poll-batch <0|1>	batch 阶段轮询开关（默认同 --poll）
-c, --ctx-size N	prompt 上下文大小（默认 0，0 = 从模型加载）（env: LLAMA_ARG_CTX_SIZE）
-n, --predict, --n-predict N	预测 token 数（默认 -1，-1 = 无限，-2 = 直到上下文填满）（env: LLAMA_ARG_N_PREDICT）
-b, --batch-size N	逻辑最大 batch 大小（默认 2048）（env: LLAMA_ARG_BATCH）
-ub, --ubatch-size N	物理最大 batch 大小（默认 512）（env: LLAMA_ARG_UBATCH）
--keep N	上下文重置时保留的初始 prompt token 数（默认 0，-1 = 全部）
--swa-full	使用全尺寸 SWA 缓存（默认 false，env: LLAMA_ARG_SWA_FULL）
-fa, --flash-attn [on|off|auto]	Flash Attention 开关（默认 auto，env: LLAMA_ARG_FLASH_ATTN）
-p, --prompt PROMPT	起始生成 prompt；系统消息请用 -sys
--perf, --no-perf	是否启用 libllama 内部性能计时（默认 false）
-f, --file FNAME	包含 prompt 的文件
-bf, --binary-file FNAME	包含 prompt 的二进制文件
-e, --escape, --no-escape	是否处理转义序列（\n、\r、\t、'、"、\）（默认 true）
--rope-scaling {none,linear,yarn}	RoPE 频率缩放方法，除非指定否则默认 linear（env: LLAMA_ARG_ROPE_SCALING_TYPE）
--rope-scale N	RoPE 上下文缩放因子，将上下文扩展 N 倍
--rope-freq-base N	RoPE 基础频率，用于 NTK-aware scaling（默认从模型加载）
--rope-freq-scale N	RoPE 频率缩放因子，将上下文扩展 1/N 倍
--yarn-orig-ctx N	YaRN：模型原始上下文大小（默认 0 = 训练上下文）
--yarn-ext-factor N	YaRN：外推混合因子（默认 -1.00，0.0 = 完全内插）
--yarn-attn-factor N	YaRN：缩放 sqrt(t) 或注意力幅值（默认 -1.00）
--yarn-beta-slow N	YaRN：高维修正维度或 alpha（默认 -1.00）
--yarn-beta-fast N	YaRN：低维修正维度或 beta（默认 -1.00）
-kvo, --kv-offload, -nkvo, --no-kv-offload	是否启用 KV 缓存卸载（默认启用）
--repack, -nr, --no-repack	是否启用权重重打包（默认启用）
--no-host	绕过 host buffer，允许使用额外 buffer
-ctk, --cache-type-k TYPE	K 的 KV 缓存数据类型；可选 f32、f16、bf16、q8_0、q4_0、q4_1、iq4_nl、q5_0、q5_1（默认 f16）
-ctv, --cache-type-v TYPE	V 的 KV 缓存数据类型，取值同上（默认 f16）
-dt, --defrag-thold N	KV 缓存碎片整理阈值（已弃用）
-np, --parallel N	并行解码的序列数（默认 1）
--rpc SERVERS	逗号分隔的 RPC 服务器列表（host:port）
--mlock	已弃用，请用 --load-mode：强制系统保持模型常驻内存
--mmap, --no-mmap	已弃用，请用 --load-mode：是否内存映射加载模型
-dio, --direct-io, -ndio, --no-direct-io	已弃用，请用 --load-mode：可用时使用 DirectIO
-lm, --load-mode MODE	模型加载模式（默认 auto）：auto = 设备支持时 mmap；none = 无特殊模式；mmap = 内存映射；mlock = 锁定内存；mmap+mlock = 两者兼备；dio = 可用时 DirectIO（env: LLAMA_ARG_LOAD_MODE）
-lzm, --lazy-mode MODE	按需读取部分张量（如逐层 embedding）：on = 从磁盘按需读取（需 mmap）；auto = 仅对大于 4 GiB 的张量生效；off = 常驻内存（默认 auto）
--numa TYPE	NUMA 优化策略：distribute = 均匀分布在所有节点；isolate = 只在启动节点上创建线程；numactl = 使用 numactl 提供的 CPU 映射；建议使用前清理系统页缓存
-dev, --device <dev1,dev2,..>	用于卸载的逗号分隔设备列表（none = 不卸载）；配合 --list-devices 查看可用设备
--list-devices	打印可用设备列表并退出
-ot, --override-tensor <pattern>=<buffer type>,...	覆盖张量的 buffer 类型
-cmoe, --cpu-moe	将全部 MoE（专家混合）权重保留在 CPU
-ncmoe, --n-cpu-moe N	将前 N 层 MoE 权重保留在 CPU
-ncffn, --n-cpu-ffn N	将前 N 层稠密 FFN 权重保留在 CPU（MoE 专家权重请用 --n-cpu-moe）
-ngl, --gpu-layers, --n-gpu-layers N	放入 VRAM 的最大层数，可为具体数值、'auto' 或 'all'（默认 auto）
-sm, --split-mode {none,layer,row,tensor}	多 GPU 拆分方式：none = 单 GPU；layer（默认）= 按层拆分（流水线）；row = 按行拆权重（并行）；tensor = 拆权重与 KV（并行，实验性）
-ts, --tensor-split N0,N1,...	各 GPU 卸载的比例列表，如 3,1
-mg, --main-gpu INDEX	主 GPU 索引（默认 0）
-fit, --fit [on|off]	是否自动调整未设置参数以适配显存（默认 on）
-fitt, --fit-target MiB0,MiB1,...	--fit 的每设备目标余量 MiB，默认 1024
-fitc, --fit-ctx N	--fit 可设置的最小 ctx 大小，默认 4096
--check-tensors	检查模型张量数据中的非法值（默认 false）
--override-kv KEY=TYPE:VALUE,...	高级选项，按 key 覆盖模型元数据；类型 int/float/bool/str
--op-offload, --no-op-offload	是否将 host 张量运算卸载到设备（默认 true）
--lora FNAME	LoRA 适配器路径（逗号分隔可加载多个）
--lora-scaled FNAME:SCALE,...	带用户自定义缩放系数的 LoRA 适配器
--control-vector FNAME	添加控制向量（逗号分隔可加多个）
--control-vector-scaled FNAME:SCALE,...	带自定义缩放系数的控制向量
--control-vector-layer-range START END	控制向量作用的层范围（含端点）
-m, --model FNAME	要加载的模型路径
-mu, --model-url MODEL_URL	模型下载 URL
-dr, --docker-repo [<repo>/]<model>[:quant]	Docker Hub 模型仓库；repo 可选（默认 ai/），quant 可选（默认 :latest），例：gemma3
-hf, -hfr, --hf-repo <user>/<model>[:quant]	Hugging Face 模型仓库；quant 可选（大小写不敏感，默认 Q4_K_M，不存在则回退到仓库第一个文件）；mmproj 若存在也会自动下载，可用 --no-mmproj 禁用
-hff, --hf-file FILE	Hugging Face 模型文件，指定后覆盖 --hf-repo 的 quant
-hft, --hf-token TOKEN	Hugging Face 访问令牌（默认取 HF_TOKEN 环境变量）
--log-disable	关闭日志
--log-file FNAME	日志写入文件
--log-colors [on|off|auto]	彩色日志开关（默认 auto，输出到终端时启用颜色）
-v, --verbose, --log-verbose	日志级别设为无穷（记录所有消息，调试用）
--offline	离线模式：强制使用缓存，禁止网络访问
-lv, --verbosity, --log-verbosity N	日志阈值：0 通用输出 / 1 error / 2 warning / 3 info / 4 trace / 5 debug（默认 3）
--log-prefix, --no-log-prefix	日志消息前缀开关
--log-timestamps, --no-log-timestamps	日志时间戳开关
--spec-draft-type-k, -ctkd, --cache-type-k-draft TYPE	草稿模型 K 的 KV 缓存数据类型（默认 f16）
--spec-draft-type-v, -ctvd, --cache-type-v-draft TYPE	草稿模型 V 的 KV 缓存数据类型（默认 f16）

采样参数（Sampling params）

参数	说明
--samplers SAMPLERS	按顺序使用的采样器，分号分隔（默认 penalties;dry;top_n_sigma;top_k;typ_p;top_p;min_p;xtc;temperature）
-s, --seed SEED	随机数种子（默认 -1，使用随机种子）
--sampler-seq, --sampling-seq SEQUENCE	简化采样器序列（默认 edskypmxt）
--ignore-eos	忽略 EOS token 继续生成（隐含 --logit-bias EOS-inf）
--temp, --temperature N	温度（默认 0.80）
--top-k N	top-k 采样（默认 40，0 = 禁用）
--top-p N	top-p 采样（默认 0.95，1.0 = 禁用）
--min-p N	min-p 采样（默认 0.05，0.0 = 禁用）
--top-nsigma, --top-n-sigma N	top-n-sigma 采样（默认 -1.00，-1.0 = 禁用）
--xtc-probability N	XTC 概率（默认 0.00，0.0 = 禁用）
--xtc-threshold N	XTC 阈值（默认 0.10，1.0 = 禁用）
--typical, --typical-p N	局部典型采样参数 p（默认 1.00，1.0 = 禁用）
--repeat-last-n N	惩罚重复时考虑的最后 n 个 token（默认 64，0 = 禁用）
--repeat-penalty N	重复序列惩罚（默认 1.00，1.0 = 禁用）
--presence-penalty N	存在惩罚 alpha（默认 0.00，0.0 = 禁用）
--frequency-penalty N	频率惩罚 alpha（默认 0.00，0.0 = 禁用）
--dry-multiplier N	DRY 采样乘数（默认 0.00，0.0 = 禁用）
--dry-base N	DRY 采样底数（默认 1.75）
--dry-allowed-length N	DRY 允许长度（默认 2）
--dry-penalty-last-n N	DRY 惩罚考虑的最后 n 个 token（默认 64，0 = 禁用）
--dry-sequence-breaker STRING	添加 DRY 序列分隔符，会清掉默认分隔符（'\n'、':'、'"'、'*'）；"none" 表示不用任何分隔符
--adaptive-target N	adaptive-p：选择接近该概率的 token（0.0~1.0，负数 = 禁用，默认 -1.00）
--adaptive-decay N	adaptive-p：目标随时间自适应的衰减率，值越小越灵敏（0.0~0.99，默认 0.90）
--dynatemp-range N	动态温度范围（默认 0.00，0.0 = 禁用）
--dynatemp-exp N	动态温度指数（默认 1.00）
--mirostat N	Mirostat 采样；与之一并使用时 Top K、Nucleus 与 Locally Typical 采样器会被忽略（默认 0 禁用，1 = Mirostat，2 = Mirostat 2.0）
--mirostat-lr N	Mirostat 学习率 eta（默认 0.10）
--mirostat-ent N	Mirostat 目标熵 tau（默认 5.00）
-l, --logit-bias TOKEN_ID(+/-)BIAS	修改 token 出现的可能性，如 --logit-bias 15043+1 提高 ' Hello' 出现概率，15043-1 降低
--grammar GRAMMAR	BNF 风格语法约束生成（示例见 grammars/ 目录）
--grammar-file FNAME	从文件读取语法
-j, --json-schema SCHEMA	用 JSON Schema 约束生成，如 {} 表示任意 JSON 对象；含外部 $ref 的 schema 请改用 --grammar 配合 examples/json_schema_to_grammar.py
-jf, --json-schema-file FILE	从文件读取 JSON Schema，用法同上
-bs, --backend-sampling	启用后端采样（实验性，默认禁用）

Completion 专属参数（Completion-specific params）

参数	说明
--verbose-prompt	生成前打印详细 prompt（默认 false）
--display-prompt, --no-display-prompt	生成时是否打印 prompt（默认 true）
-co, --color [on|off|auto]	彩色输出以区分 prompt/用户输入与生成内容（默认 auto）
--context-shift, --no-context-shift	无限文本生成时是否使用上下文移位（默认禁用）
-sys, --system-prompt PROMPT	系统提示词（若聊天模板支持）
-sysf, --system-prompt-file FNAME	包含系统提示词的文件
-ptc, --print-token-count N	每 N 个 token 打印一次 token 计数（默认 -1）
--prompt-cache FNAME	缓存 prompt 状态的文件，加速启动（默认无）
--prompt-cache-all	同时将用户输入与生成内容写入缓存
--prompt-cache-ro	只读使用 prompt 缓存，不更新
-r, --reverse-prompt PROMPT	遇到 PROMPT 时停止生成，交互模式下交还控制权
-sp, --special	启用特殊 token 输出（默认 false）
-cnv, --conversation, -no-cnv, --no-conversation	是否启用对话模式：不打印特殊 token 与前后缀，同时启用交互模式（默认：有聊天模板时自动启用）
-st, --single-turn	只跑一轮对话即退出；若首轮已由 --prompt 定义则不进入交互
-i, --interactive	交互模式（默认 false）
-if, --interactive-first	交互模式并立即等待输入（默认 false）
-mli, --multiline-input	允许书写/粘贴多行而无需每行以 \ 结尾
--in-prefix-bos	在 --in-prefix 字符串前再加 BOS
--in-prefix STRING	用户输入前缀（默认空）
--in-suffix STRING	用户输入后缀（默认空）
--warmup, --no-warmup	是否用空跑预热（默认启用）
-gan, --grp-attn-n N	分组注意力因子（默认 1）
-gaw, --grp-attn-w N	分组注意力宽度（默认 512）
--jinja, --no-jinja	是否使用 jinja 模板引擎处理聊天（默认禁用）
--reasoning-format FORMAT	控制思考标签的解析与返回形式：none = 保留在 content；deepseek = 放入 reasoning_content；deepseek-legacy = 两者都保留（默认 auto）
-rea, --reasoning [on|off|auto]	聊天中是否启用推理/思考（默认 auto，从模板检测）
--reasoning-effort LEVEL	传给聊天模板的推理力度：default / minimal / low / medium / high / xhigh / max（默认 default）
--reasoning-budget N	思考 token 预算：-1 不限制、0 立即结束、N>0 指定预算（默认 -1）
--reasoning-budget-message MESSAGE	思考预算耗尽时、结束思考标签前注入的消息
--reasoning-preserve, --no-reasoning-preserve	在完整历史中保留推理轨迹而非仅最后一条 assistant 消息（需模板支持 supports_preserve_reasoning 能力）
--chat-template JINJA_TEMPLATE	设置自定义 jinja 聊天模板（默认取模型元数据）；指定了前缀/后缀时模板失效；默认只接受常用内置模板（在 --jinja 之后指定可放开），内置模板包括：bailing、bailing-think、bailing2、chatglm3、chatglm4、chatml、command-r、deepseek、deepseek-ocr、deepseek2、deepseek3、exaone-moe、exaone3、exaone4、falcon3、gemma、gigachat、glmedge、gpt-oss、granite、granite-4.0、granite-4.1、grok-2、hunyuan-dense、hunyuan-moe、hunyuan-vl、kimi-k2、llama2、llama2-sys、llama2-sys-bos、llama2-sys-strip、llama3、llama4、megrez、minicpm、mistral-v1、mistral-v3、mistral-v3-tekken、mistral-v7、mistral-v7-tekken、monarch、openchat、orion、pangu-embedded、phi3、phi4、rwkv-world、seed_oss、smolvlm、solar-open、vicuna、vicuna-orca、yandex、zephyr
--chat-template-file JINJA_TEMPLATE_FILE	从外部文件加载自定义 jinja 聊天模板，规则同 --chat-template
--skip-chat-parsing, --no-skip-chat-parsing	即使指定了 Jinja 模板也强制使用纯内容解析器，模型的一切输出（含推理/工具调用）都放进 content（默认禁用）
--simple-io	使用基础 IO，提升子进程与受限控制台的兼容性

四、最常用选项详解

• -m FNAME, --model FNAME：指定模型文件路径（如 models/gemma-1.1-7b-it.Q4_K_M.gguf）；若设置了 --model-url 则可从远程 URL 下载。
• -i, --interactive：进入交互模式，直接输入并获得实时响应。
• -n N, --n-predict N：设定预测 token 数，直接影响生成文本长度。
• -c N, --ctx-size N：设定 prompt 上下文大小。默认 0（从模型加载）；若模型以更长上下文训练，调大可提升长输入/长推理的效果。
• -mli, --multiline-input：允许书写或粘贴多行而无需每行以 \ 结尾。
• -t N, --threads N：生成阶段线程数。建议设为物理 CPU 核心数而非逻辑核心数。
• -ngl N, --n-gpu-layers N：编译了 GPU 支持时，把部分层卸载到 GPU 计算，通常可提升性能。

五、输入 prompt 的多种方式

• --prompt PROMPT：直接以命令行选项提供 prompt。
• --file FNAME：提供包含单个或多个 prompt 的文件。
• --system-prompt PROMPT：提供系统提示词（否则使用聊天模板中的默认系统提示词）。
• --system-prompt-file FNAME：提供包含系统提示词的文件。
• --interactive-first：交互模式并立即等待输入。

在 tools/completion/completion.cpp 中可以看到 prompt 的组装逻辑：对话模式下 system_prompt 与 prompt 会分别以 system、user 角色加入 chat_msgs，再经 common_chat_templates_apply 渲染成最终 prompt；非对话模式下则直接使用原始 prompt。之后统一经 common_tokenize 分词，若长度超过 n_ctx - 4 会直接报错退出。

六、交互模式与反向 prompt

llama-completion 的交互模式支持在生成过程中注入输入：任意时刻按 Ctrl+C 插入你的输入，再按 Return 提交给模型；若想继续输入而不提交，在当前行末尾加反斜杠（\）续行。

交互选项

• -i, --interactive：实时对话或下达指令。
• --interactive-first：启动即等待用户输入，然后才开始生成。
• -cnv, --conversation：对话模式（不打印特殊 token 与前后缀，使用默认或指定聊天模板；发现聊天模板时默认启用）。
• -no-cnv：关闭对话模式。
• -st, --single-turn：只处理一轮对话（一次用户输入）后退出。
• --jinja：启用 jinja 聊天模板解析器，使用模型内置模板或用户提供的模板。
• --color：彩色输出，直观区分 prompt、用户输入与生成文本。

反向 prompt（Reverse Prompts）

-r PROMPT, --reverse-prompt PROMPT：指定一个或多个反向 prompt，当生成文本中出现该字符串时暂停生成并切换到交互模式。例如 -r "User:" 可在模型轮到"用户发言"时自动交还控制权，从而构造类聊天体验。注意：以空格结尾的反向 prompt 不生效，可用 --in-prefix 在其后补一个空格或任意字符绕过。

源码中反向 prompt 的检测在 tools/completion/completion.cpp：每轮取最近 32 个输出 token 解码为字符串（n_prev = 32），检查是否以某个反向 prompt 结尾；非交互模式下额外放宽 2 个 token 的搜索窗口以补偿分词边界问题。此外还支持"单 token 反向 prompt"的快速路径——当反向 prompt 恰好只分出一个 token 时，直接与最后一个采样 token 比较（见 completion.cpp 的 antiprompt_token 预处理）。

In-Prefix / In-Suffix

--in-prefix 为用户输入添加前缀，主要用于在反向 prompt 后补空格。示例：

./llama-completion -r "User:" --in-prefix " "

--in-suffix 为用户输入添加后缀，常用于在输入末尾自动附加 "Assistant:"（加在程序自动追加的换行符 \n 之后）。示例：

./llama-completion -r "User:" --in-prefix " " --in-suffix "Assistant:"

注意：一旦启用 --in-prefix 或 --in-suffix，聊天模板（--chat-template）会被禁用。 从 completion.cpp 可以验证：前缀/后缀只在非对话模式下打印与拼接（!params.conversation_mode 判断），且参数解析阶段就据此关闭了 enable_chat_template。

聊天模板

• --chat-template JINJA_TEMPLATE：设置自定义 jinja 聊天模板，接受的是字符串而非文件名。默认取模型元数据中的模板。llama.cpp 只支持一批预定义模板（即上表列出的内置列表），例如 --chat-template gemma。启用 --in-prefix/--in-suffix 后模板失效。
• --chat-template-file JINJA_TEMPLATE_FILE：从外部文件加载模板，适用于模型自带模板过时或不兼容的场景，仓库内 models/templates/ 提供了一批现成模板示例；最新的聊天模板可用 scripts/get_chat_template.py 从 Hugging Face 获取。

七、上下文管理

LLaMA 模型的上下文长度有限，只能"看见"一定数量的 token。上下文填满后模型内部会重置，可能丢失开头信息。相关选项用于在这种场景下维持连贯性。

上下文大小

-c N, --ctx-size N：设定 prompt 上下文大小（默认 0 = 从模型加载）。若模型以更长上下文训练，调大此值可改善长输入/长推理效果。

扩展上下文

部分微调模型通过缩放 RoPE 扩展了上下文。例如原模型上下文为 4096（4k），微调后为 32k，则缩放因子为 8：将 --ctx-size 设为 32768，并将 --rope-scale 设为 8。--rope-scale N 中的 N 即微调模型使用的线性缩放因子。

保留 prompt

--keep N：模型重置上下文时保留初始 prompt 的 token 数，确保与最初指令/主题的关联。默认 0（不保留），-1 表示保留全部初始 prompt token。

从 completion.cpp 可以看到实现细节：n_keep 小于 0 或超过 prompt 长度时会被钳制为 prompt 总长度，否则再加 1（n_keep += add_bos）——因为 BOS token 始终会被保留。

无限生成与上下文移位（context shift）

--predict 的取值为 -1 时会启用无限文本生成。虽然上下文窗口有限，当窗口填满时，程序会丢弃较早的部分 token（--keep 之后的 token 的一半），然后必须重新求值上下文，才能继续生成。大模型或大上下文窗口下这一步会造成明显停顿。若不想停顿，可用 -2 在上下文填满时立即停止生成。--no-context-shift 选项则允许在有限上下文窗口填满时直接停止无限生成。

tools/completion/completion.cpp 中的实现印证了这一描述：当 n_past + embd.size() >= n_ctx 时，若 ctx_shift 关闭则打印 "context full and context shift is disabled => stopping" 并退出；n_predict == -2 同样直接停止。否则计算 n_left = n_past - n_keep、n_discard = n_left / 2，通过 llama_memory_seq_rm 删除 [n_keep, n_keep + n_discard) 区间、再用 llama_memory_seq_add 把后半段整体左移 n_discard，完成一次"换血"式的上下文移位；同时清空 session 缓存路径。

另外需要注意：即使指定了 --predict 数量，生成也可能提前结束——遇到 EOS token 或反向 prompt 时即会停止。交互模式下生成会暂停并交还控制权给用户；非交互模式下程序直接结束。若希望模型永远不主动产生 EOS，可用 --ignore-eos（它隐含 --logit-bias EOS-inf，把 EOS 的概率直接置零）。

八、生成标志与采样调优

预测 token 数

-n N, --predict N：控制生成 token 数（默认 -1：-1 = 无限，-2 = 直到上下文填满）。更高的值生成更长文本，更低的值更短。关于 -1 / -2 的行为差异与上下文移位的代价，见上文第七节。

温度（Temperature）

--temp N：控制生成随机性（默认 0.8）。温度作用于输出 token 的概率分布：高温（如 1.5）更随机、更有创造性；低温（如 0.5）更聚焦、更确定、更保守。默认 0.8 在随机性与确定性之间取得平衡。极端情况下温度为 0 总是选择最可能的下一个 token，每次运行输出完全相同。示例：--temp 0

重复惩罚

• --repeat-penalty N：控制 token 序列的重复惩罚（默认 1.0，1.0 = 禁用）。值越高惩罚越强（如 1.5），越低越宽松（如 0.9）。
• --repeat-last-n N：惩罚时回看的 token 历史长度（默认 64，0 = 禁用）。值越大回看越远，越小只看近期 token。

DRY 重复惩罚

DRY（Don't Repeat Yourself）采样基于 token 近期使用模式施加惩罚，即使在长上下文中也能有效减少重复。它源自开源社区的 DRY 采样方案，在 llama.cpp 中通过以下参数控制：

• --dry-multiplier N：DRY 效果强度（默认 0.0 = 禁用，典型推荐值 0.8）。
• --dry-base N：指数惩罚计算的底数（默认 1.75），值越高惩罚越激进。
• --dry-allowed-length N：不被惩罚的重复序列最大长度（默认 2），更短的重复视为自然重复而不加惩罚。
• --dry-penalty-last-n N：应用惩罚时考虑多少近期 token（默认 64，0 = 禁用）。
• --dry-sequence-breaker STRING：添加序列分隔符，可重复使用加多个；一旦使用即清空默认分隔符（\n、:、"、*）；传 "none" 表示不使用任何分隔符。分隔符会打断序列匹配，把输入切分成可分别匹配的子段。

示例：--dry-multiplier 0.8 --dry-base 1.75 --dry-allowed-length 2 --dry-penalty-last-n 64 --dry-sequence-breaker "—" --dry-sequence-breaker "##"

DRY 采样为文本生成提供了更精细的控制，尤其擅长减少长距离重复、维持全局连贯性。

Top-K 采样

--top-k N：只从概率最高的 K 个 token 中选择（默认 40）。可降低生成低概率/无意义 token 的风险，但可能限制多样性。值越大（如 100）文本越多样，值越小（如 10）越保守。示例：--top-k 30

Top-P 采样

--top-p N：从累计概率达到阈值 P 的最小 token 集合中采样（核采样，默认 0.9）。它在多样性与质量之间取得平衡：值越大（如 0.95）文本越多样，值越小（如 0.5）越聚焦。示例：--top-p 0.95

Min-P 采样

--min-p N：token 选择的最低概率阈值，相对最可能 token 的概率而言（默认 0.1，即 0.05）。Min-P 是 Top-P 的替代方案，旨在平衡质量与多样性。例如 p=0.05、最可能 token 概率为 0.9 时，概率低于 0.045 的 logit 会被过滤。示例：--min-p 0.05

Adaptive-P 采样

• --adaptive-target N：选择接近该概率的 token（0.0~1.0，负数 = 禁用）。
• --adaptive-decay N：自适应的 EMA 衰减；历史窗口约 1/(1-decay) 个 token（0.0~0.99）。

adaptive-p 采样器把 token 概率分布变形，使采样偏向落在用户设定目标概率附近的 token。它在每一步对"被选中 token 的原始概率"维护一个指数移动平均，并据此动态计算当前步骤的目标概率，从而在长时间生成中维持目标概率。建议在该采样器前只做轻度截断，推荐仅搭配 min-p 作为唯一前置采样器。推荐起始值：--adaptive-target 0.55 --adaptive-decay 0.9

局部典型采样（Locally Typical）

--typical N：以参数 p 启用局部典型采样（默认 1.0，1.0 = 禁用）。它从上下文中"典型/预期"的 token 中采样，兼顾局部连贯与多样性：p 接近 1 时更偏连贯，接近 0 时更偏多样。示例：--typical 0.9

Mirostat 采样

• --mirostat N：启用 Mirostat 采样，在生成过程中控制困惑度（默认 0 = 禁用，1 = Mirostat，2 = Mirostat 2.0）。
• --mirostat-lr N：学习率 eta（默认 0.1），影响算法对生成文本反馈的响应速度。
• --mirostat-ent N：目标熵 tau（默认 5.0），代表期望困惑度。值越低文本越聚焦连贯，越高越多样但可能不够连贯。

Mirostat 主动把生成质量维持在一个期望区间，平衡连贯与多样，避免"无聊陷阱"（过度重复）与"混乱陷阱"（不连贯）。示例：--mirostat 2 --mirostat-lr 0.05 --mirostat-ent 3.0

XTC 采样

• --xtc-probability N：移除 token 的概率（采样器启动时检查一次，默认 0.0）。
• --xtc-threshold N：被移除 token 的最低概率阈值（默认 0.1）。

Exclude Top Choices（XTC）是一种实验性采样器：以 xtc-probability 的概率找出概率 ≥ xtc-threshold 的 token，然后移除其中除最不可能者之外的全部 token。由于陈词滥调与重复短语往往概率更高，移除 top token 可以提升回答多样性、打破写作套路并抑制重复；保留最后一个达标 token 则保证回答仍有连贯性。XTC 适合创意任务。推荐组合为 Min-P 后接默认设置的 XTC：--sampling-seq mx --min-p 0.02 --xtc-probability 0.5。示例：--xtc-probability 0.5 --xtc-threshold 0.1

Top-nσ 采样

--top-nsigma N：只保留 pre-softmax logits 落在最大 logit 之下 n·σ 以内的 token（默认 -1 = 禁用）。它直接在 pre-softmax logits 上做统计阈值过滤，无需复杂的概率变换，采样空间在温度缩放下保持稳定，因此高温推理任务表现良好。值越大（如 5）纳入越多噪声 token，值越小（如 1）越聚焦信息量高的区域。示例：--top-nsigma 1

Logit Bias

-l TOKEN_ID(+/-)BIAS, --logit-bias TOKEN_ID(+/-)BIAS：手动调整特定 token 的出现可能性。例如 --logit-bias 15043+1 提高 token 'Hello' 的概率，15043-1 降低；取负无穷 --logit-bias 15043-inf 可保证该 token 永不出现。一个实用场景：抑制模型输出 LaTeX 的 \begin/\end，把 \ token（29905）设为负无穷：-l 29905-inf。

RNG 种子

-s SEED, --seed SEED：随机数种子（默认 -1 = 随机）。固定种子可在相同输入与设置下得到可复现的结果，便于测试、调试或对比不同选项的影响、观察从何处开始分叉。种子小于 0 时每次运行使用不同随机种子。

九、性能调优与内存选项

线程数

• -t N, --threads N：生成阶段线程数。建议设为物理 CPU 核心数（而非逻辑核心数），用对线程数可显著提升性能。
• -tb N, --threads-batch N：batch 与 prompt 处理阶段线程数。部分系统在 batch 处理中使用更多线程更优；未指定时与 --threads 相同。

模型加载模式

-lm MODE, --load-mode MODE（默认 auto）：

• auto：设备支持时内存映射加载模型。
• none：无特殊加载模式。关闭 mmap 会拖慢加载，但不使用 mlock 时可能减少 pageout；注意若模型大于总内存，关闭 mmap 会导致完全无法加载。
• mmap：内存映射加载。
• mlock：把模型锁定在内存中，防止被换出。可提升性能，但牺牲了部分 mmap 优势：占用更多内存、加载更慢。
• mmap+mlock：映射并锁定。
• dio：可用时使用 DirectIO。

NUMA 支持

• --numa distribute：把等比例线程固定到每个 NUMA 节点的核上，负载摊平到所有核心、利用全部内存通道，代价是内存可能跨慢速节点间链路访问。
• --numa isolate：所有线程固定在程序启动所在节点。限制了可用核心与内存数量，但保证所有内存访问都在本地节点。
• --numa numactl：使用 numactl 工具传入的 CPUMAP 固定线程。最灵活，可实现任意核心使用模式，例如占满一个节点的全部核心、再在第二节点上取刚好够打满节点间内存总线的核心数。

这些标志针对非均匀内存访问（NUMA）系统尝试优化，当前包括上述策略之一，以及对 mmap 关闭预取与预读。后者使映射页在首次访问时才缺页载入，配合把线程固定到 NUMA 节点，更多页面会落在实际使用的节点上。注意：若模型已在系统页缓存中（例如之前未带该选项运行过），这些优化几乎没有效果，除非先清理页缓存——重启系统，或在 Linux 上以 root 身份向 /proc/sys/vm/drop_caches 写入 3。

Batch 大小

• -ub N, --ubatch-size N：物理 batch 大小，即一次最多处理的 token 数。调大可能提升 prompt 处理性能，代价是更高内存占用。默认 512。
• -b N, --batch-size N：逻辑 batch 大小。在多 GPU 流水线并行场景下，把逻辑 batch 调到物理 batch 之上可能提升 prompt 处理性能。默认 2048。

Prompt 缓存

--prompt-cache FNAME：指定文件缓存初始 prompt 之后的模型状态。对长 prompt 可显著加快启动：首次运行创建文件，后续运行复用并更新。注意：恢复缓存的 prompt 并不等于恢复保存那一刻的精确会话状态——即使指定固定种子，也不保证得到与原始生成完全一致的 token 序列。

配套开关 --prompt-cache-all（同时缓存用户输入与生成内容）与 --prompt-cache-ro（只读缓存、不更新）。从源码看（tools/completion/completion.cpp），启动时通过 llama_state_load_file 载入会话 token，与当前 prompt 做前缀比对：完全匹配则直接复用（"using full prompt from session file"），相似度低于一半时警告"will mostly be reevaluated"；会话 token 中超出匹配长度的"未来"部分会被 llama_memory_seq_rm 清除。由于 logit 不作为会话状态保存，若完全命中还要 common_replay_last_token 重放最后一个 token 以取得采样所需 logit。另据 common/arg.cpp，--prompt-cache-all 目前尚不支持在交互模式下使用（会直接抛错）。

语法与 JSON Schema

• --grammar GRAMMAR / --grammar-file FILE：用内联或文件中的语法（GBNF）把模型输出约束到指定格式，例如强制输出 JSON 或只用 emoji 说话。语法细节见 GBNF 指南，示例见 grammars/ 目录（如 grammars/json.gbnf、grammars/c.gbnf）。
• --json-schema SCHEMA：用 JSON Schema 约束输出（如 {} 表示任意 JSON 对象，或 {"items": {"type": "string", "minLength": 10, "maxLength": 100}, "minItems": 10} 表示带长度约束的字符串数组）。若 schema 含外部 $ref，请改用 --grammar "$(python examples/json_schema_to_grammar.py myschema.json)"，转换脚本为 examples/json_schema_to_grammar.py；仓库内还配套实现了 C++ 侧的 common/json-schema-to-grammar.cpp，并有对应测试 tests/test-json-schema-to-grammar.cpp。

量化

关于 4-bit 量化如何显著改善性能并降低内存占用的完整说明，参见项目主文档 README.md 的 "Prepare and Quantize" 部分。

LoRA 适配器

• --lora FNAME：以缩放 1.0 使用 LoRA 适配器，可与 --lora-scaled 混用、可重复指定多个。
• --lora-scaled FNAME:SCALE,...：带自定义缩放系数的 LoRA 适配器。

例如：--lora my_adapter_1.gguf --lora my_adapter_2.gguf ... 或 --lora-scaled lora_task_A.gguf:0.5 --lora-scaled lora_task_B.gguf:0.5。

LoRA 适配器须为 GGUF 格式，从 Hugging Face 格式转换可用 convert_lora_to_gguf.py 脚本。适配器独立加载并在推理时应用，不会与主模型合并，因此使用 LoRA 时完全支持 mmap 模型加载；旧版 --lora-base 标志已随合并流程一并移除。

十、附加选项与源码流程纵览

附加选项：

• -h, --help：显示全部选项与默认值。选项与默认值经常变化，建议以 --help 最新输出为准。
• --verbose-prompt：生成前打印 prompt（completion.cpp 中会逐 token 打印 id -> 'piece'，并打印基于 n_keep 的静态 prompt）。
• --no-display-prompt：生成时不打印 prompt。
• -mg i, --main-gpu i：多 GPU 时指定处理"小张量"的主 GPU——对这些张量跨卡拆分的开销不值得，主 GPU 会多占一些 VRAM 存放临时结果的 scratch buffer。默认 GPU 0。
• -ts SPLIT, --tensor-split SPLIT：多设备时控制张量如何拆分。逗号分隔的非负值表示各设备应得的数据份额，如 "3,2" 表示设备 0 得 60%、设备 1 得 40%。默认按 VRAM 比例拆分，但这未必是性能最优。实际使用的设备列表会在启动时打印，可能与 --list-devices 或 nvidia-smi 给出的设备列表不同。
• -hfr URL, --hf-repo URL：Hugging Face 模型仓库 URL，配合 --hf-file/-hff 使用，模型下载后保存到 -m 指定路径；未提供 -m 时自动存入 LLAMA_CACHE 环境变量指定路径或操作系统本地缓存。

源码级运行流程

从 tools/completion/completion.cpp 的 llama_completion 主函数可以梳理出完整调用链：

1. common_params_parse 解析全部命令行参数（含 completion 专属选项）；
2. llama_backend_init + llama_numa_init 初始化后端与 NUMA 策略；
3. common_init_from_params 一次性完成模型加载、上下文创建与采样器构建（含 LoRA 应用）；
4. common_chat_templates_init 初始化聊天模板，随后自动判定对话模式；
5. 若指定 --prompt-cache，尝试加载会话文件并做前缀匹配复用；
6. prompt 分词、长度校验（超过 n_ctx - 4 报错）；
7. 注册 SIGINT 处理器后进入主生成循环。

其中值得注意的两个实现细节：

Ctrl+C 的双重语义。sigint_handler 中，若当前不在交互状态且开启了 --interactive，第一次 Ctrl+C 只是把 is_interacting 置真并标记 need_insert_eot（等待用户插入输入）；否则执行清理、打印性能统计（common_perf_print）并以退出码 130 结束。这也解释了交互式下"按 Ctrl+C 打断生成、按回车交还控制"的体验。

对话模式的回合闭环。主循环中每次采样出的 token 会被追加进 assistant_ss 流；当遇到 EOG（生成结束）token 且处于交互模式时，助手消息通过 chat_add_and_format("assistant", ...) 写回聊天历史（见 completion.cpp），下一轮用户输入即基于完整的多轮历史经聊天模板重新渲染。而 --single-turn 在 completion.cpp 中会关闭交互标志，实现"一轮即走"。

结语

llama-completion 以单一可执行程序覆盖了 llama.cpp 推理链路中"参数 → 模型加载 → 聊天模板渲染 → 分词 → 批量解码 → 采样链 → 交互循环"的全部关键环节。掌握本文的参数体系与源码流程后，你可以直接用它做快速实验、对比采样器效果、调试上下文管理与加载策略，并为进一步阅读 common/arg.cpp、common/sampling.cpp 等公共库实现打下基础。