下载：https://github.com/ggml-org/llama.cpp/releases

llama-cli 参数详解与部署推荐指南

基于 llama.cpp llama-cli -h 整理。

每个参数包含： - - 适用场景 - 推荐配置（CPU / RTX 4090 / 多
GPU）

---

1. 通用参数（common params）

-m, --model FNAME

指定加载的模型文件路径。

作用

告诉 llama-cli 使用哪个 GGUF 模型。

适用场景

• 本地运行 Llama、Qwen、DeepSeek 等 GGUF 模型。
• 多模型切换。

推荐值

CPU:

-m model.gguf

RTX 4090:

-m Qwen3-32B-Q4_K_M.gguf

多 GPU:

-m DeepSeek-R1-70B-Q4_K_M.gguf

---

-ngl, --gpu-layers N

设置放入 GPU 显存中的模型层数量。

作用

控制 GPU 加速比例。

适用场景

显存不足时降低； 显存充足时提高速度。

推荐值

CPU:

-ngl 0

RTX 4090 24GB:

-ngl auto

70B 多 GPU:

-ngl all

---

-c, --ctx-size N

设置上下文长度。

作用

决定模型一次能记忆多少 token。

适用场景

长文本分析、代码、大文档。

推荐值

普通聊天:

-c 4096

RTX 4090:

-c 32768

长文本:

-c 131072

注意： 上下文越大，KV Cache 占用越高。

---

-t, --threads N

CPU 推理线程数量。

适用场景

纯 CPU 推理。

推荐值

8核CPU:

-t 8

16核CPU:

-t 16

服务器: 设置为物理核心数。

---

-b, --batch-size N

批处理大小。

作用

影响 prompt 处理速度。

推荐值

CPU:

-b 256

RTX 4090:

-b 2048

大显存:

-b 4096

---

--flash-attn

启用 Flash Attention。

作用

降低显存占用，提高注意力计算速度。

推荐值

RTX 4090:

--flash-attn on

CPU:

--flash-attn off

多 GPU:

--flash-attn auto

---

2. 采样参数（sampling params）

--temperature

温度参数，控制随机性。

推荐值

严谨回答:

--temp 0.2

代码:

--temp 0.3

聊天创作:

--temp 0.8

---

--top-k

限制候选 token 数量。

推荐值

通用:

--top-k 40

代码:

--top-k 20

---

--top-p

核采样概率范围。

推荐值

通用:

--top-p 0.95

稳定输出:

--top-p 0.8

---

--repeat-penalty

重复惩罚。

推荐值

默认:

--repeat-penalty 1.1

长文本:

1.15

---

3. KV Cache 参数

--cache-type-k / --cache-type-v

设置 KV Cache 精度。

推荐值

RTX 4090:

节省显存:

--cache-type-k q8_0
--cache-type-v q8_0

高质量:

f16

---

4. 多 GPU 参数

--split-mode

多 GPU 模型切分方式。

类型

none: 单 GPU

layer: 按层切分（推荐）

row: 按权重切分

tensor: 张量并行（实验）

推荐

双 RTX 4090:

--split-mode layer

---

--tensor-split

指定 GPU 显存比例。

示例

两张 4090:

--tensor-split 1,1

48GB+24GB:

--tensor-split 2,1

---

5. 推测解码（Speculative Decoding）

--model-draft

指定草稿模型。

作用

使用小模型预测，大模型验证。

适用

例如:

主模型: 70B

Draft: 7B

可以明显提升速度。

---

6. 多模态参数

--mmproj

加载视觉投影模型。

用途

图片理解模型。

例如:

--mmproj mmproj-model.gguf

---

--image

输入图片。

示例

--image test.jpg

---

推荐配置模板

RTX 4090 24GB 单卡

llama-cli \
-m model.gguf \
-ngl auto \
--flash-attn on \
-c 32768 \
-b 2048 \
--temp 0.7

---

CPU服务器

llama-cli \
-m model.gguf \
-ngl 0 \
-t 32 \
-c 8192 \
-b 512

---

双 RTX 4090

llama-cli \
-m model.gguf \
-ngl all \
--split-mode layer \
--tensor-split 1,1 \
--flash-attn on \
-c 65536

---

调优原则

目标 主要调整参数

---

提高速度 增加 -ngl、batch、开启 flash-attn
降低显存 降低 ctx、KV cache 量化
提高输出质量 降低 temperature
长文本 增加 ctx-size
多GPU split-mode + tensor-split
减少重复 repeat-penalty

llama-cli 命令行手册

本文档翻译自 llama-cli -h 的输出，涵盖了所有可用参数。
版本信息与编译细节请使用 --version 查看。

---

一、通用参数（common params）

参数	说明
-h, --help, --usage	打印用法信息并退出
--version	显示版本和编译信息
-cl, --cache-list	显示缓存中的模型列表
--completion-bash	打印可 source 的 bash 补全脚本（用于 llama.cpp）
-t, --threads N	生成期间使用的 CPU 线程数（默认：-1）<br>环境变量：LLAMA_ARG_THREADS
-tb, --threads-batch N	批处理和提示处理期间使用的线程数（默认：同 --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	批处理时的 CPU 亲和性掩码，与 --cpu-range-batch 互补（默认：同 --cpu-mask）
-Crb, --cpu-range-batch lo-hi	批处理时的 CPU 亲和性范围，与 --cpu-mask-batch 互补（默认：同 --cpu-mask）
--cpu-strict-batch <0\|1>	批处理时是否使用严格的 CPU 绑定（默认：同 --cpu-strict）
--prio-batch N	批处理时设置进程/线程优先级：0-normal, 1-medium, 2-high, 3-realtime（默认：0）
--poll-batch <0\|1>	批处理时是否使用轮询等待工作（默认：同 --poll）
-c, --ctx-size N	提示上下文大小（默认：0，0 表示从模型加载）<br>环境变量：LLAMA_ARG_CTX_SIZE
-n, --predict, --n-predict N	预测的 token 数量（默认：-1，-1 表示无限）<br>环境变量：LLAMA_ARG_N_PREDICT
-b, --batch-size N	逻辑最大批大小（默认：2048）<br>环境变量：LLAMA_ARG_BATCH
-ub, --ubatch-size N	物理最大批大小（默认：512）<br>环境变量：LLAMA_ARG_UBATCH
--keep N	从初始提示中保留的 token 数量（默认：0，-1 表示全部保留）
--swa-full	是否使用全尺寸 SWA 缓存（默认：false）<br>更多信息参见文档，环境变量：LLAMA_ARG_SWA_FULL
-fa, --flash-attn [on\|off\|auto]	设置 Flash Attention 使用模式（'on', 'off' 或 'auto'，默认：'auto'）<br>环境变量：LLAMA_ARG_FLASH_ATTN
-p, --prompt PROMPT	启动生成的提示文本；系统消息请使用 -sys
--perf, --no-perf	是否启用内部 libllama 性能计时（默认：false）<br>环境变量：LLAMA_ARG_PERF
-f, --file FNAME	包含提示的文件（默认：无）
-bf, --binary-file FNAME	包含提示的二进制文件（默认：无）
-e, --escape, --no-escape	是否处理转义序列（\n, \r, \t, ', ", \）（默认：true）
--rope-scaling {none,linear,yarn}	RoPE 频率缩放方法，默认为 linear，除非模型指定<br>环境变量：LLAMA_ARG_ROPE_SCALING_TYPE
--rope-scale N	RoPE 上下文缩放因子，将上下文扩大 N 倍<br>环境变量：LLAMA_ARG_ROPE_SCALE
--rope-freq-base N	RoPE 基础频率，用于 NTK 感知缩放（默认：从模型加载）<br>环境变量：LLAMA_ARG_ROPE_FREQ_BASE
--rope-freq-scale N	RoPE 频率缩放因子，将上下文扩大 1/N 倍<br>环境变量：LLAMA_ARG_ROPE_FREQ_SCALE
--yarn-orig-ctx N	YaRN：模型的原始上下文大小（默认：0 = 模型训练上下文大小）<br>环境变量：LLAMA_ARG_YARN_ORIG_CTX
--yarn-ext-factor N	YaRN：外推混合因子（默认：-1.00，0.0 = 完全内插）<br>环境变量：LLAMA_ARG_YARN_EXT_FACTOR
--yarn-attn-factor N	YaRN：缩放 sqrt(t) 或注意力幅度（默认：-1.00）<br>环境变量：LLAMA_ARG_YARN_ATTN_FACTOR
--yarn-beta-slow N	YaRN：高校正维度或 alpha（默认：-1.00）<br>环境变量：LLAMA_ARG_YARN_BETA_SLOW
--yarn-beta-fast N	YaRN：低校正维度或 beta（默认：-1.00）<br>环境变量：LLAMA_ARG_YARN_BETA_FAST
-kvo, --kv-offload, -nkvo, --no-kv-offload	是否启用 KV 缓存卸载（默认：启用）<br>环境变量：LLAMA_ARG_KV_OFFLOAD
--repack, -nr, --no-repack	是否启用权重重打包（默认：启用）<br>环境变量：LLAMA_ARG_REPACK
--no-host	绕过主机缓冲区，允许使用额外缓冲区<br>环境变量：LLAMA_ARG_NO_HOST
-ctk, --cache-type-k TYPE	KV 缓存中 K 的数据类型<br>允许值：f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1（默认：f16）<br>环境变量：LLAMA_ARG_CACHE_TYPE_K
-ctv, --cache-type-v TYPE	KV 缓存中 V 的数据类型<br>允许值同上（默认：f16）<br>环境变量：LLAMA_ARG_CACHE_TYPE_V
-dt, --defrag-thold N	KV 缓存碎片整理阈值（已弃用）<br>环境变量：LLAMA_ARG_DEFRAG_THOLD
-np, --parallel N	并行解码的序列数量（默认：1）<br>环境变量：LLAMA_ARG_N_PARALLEL
--rpc SERVERS	逗号分隔的 RPC 服务器列表（主机）<br>环境变量：LLAMA_ARG_RPC
--mlock	强制系统将模型保留在 RAM 中，避免交换或压缩<br>环境变量：LLAMA_ARG_MLOCK
--mmap, --no-mmap	是否内存映射模型（如果禁用，加载更慢但可能减少页面交换，若未使用 mlock）<br>默认：启用<br>环境变量：LLAMA_ARG_MMAP
-dio, --direct-io, -ndio, --no-direct-io	如果可用，使用 Direct I/O（默认：禁用）<br>环境变量：LLAMA_ARG_DIO
--numa TYPE	尝试优化 NUMA 系统的帮助<br>- distribute: 均匀分布执行到所有节点<br>- isolate: 只在执行开始的节点上的 CPU 上生成线程<br>- numactl: 使用 numactl 提供的 CPU 映射<br>如果之前没有使用此选项，建议在使用前清除系统页缓存<br>参见 https://github.com/ggml-org/llama.cpp/issues/1437<br>环境变量：LLAMA_ARG_NUMA
-dev, --device <dev1,dev2,..>	逗号分隔的设备列表，用于卸载（none = 不卸载）<br>使用 --list-devices 查看可用设备<br>环境变量：LLAMA_ARG_DEVICE
--list-devices	打印可用设备列表并退出
-ot, --override-tensor <KEY=TYPE,...>	覆盖张量缓冲区类型<br>环境变量：LLAMA_ARG_OVERRIDE_TENSOR
-cmoe, --cpu-moe	将所有专家混合（MoE）权重保留在 CPU 中<br>环境变量：LLAMA_ARG_CPU_MOE
-ncmoe, --n-cpu-moe N	将前 N 层的 MoE 权重保留在 CPU 中<br>环境变量：LLAMA_ARG_N_CPU_MOE
-ngl, --gpu-layers, --n-gpu-layers N	存储在 VRAM 中的最大层数，可以是精确数字、'auto' 或 'all'（默认：auto）<br>环境变量：LLAMA_ARG_N_GPU_LAYERS
-sm, --split-mode {none,layer,row,tensor}	如何在多个 GPU 之间分割模型：<br>- none: 只使用一个 GPU<br>- layer（默认）：按层分割并跨 GPU 流水线<br>- row: 按行跨 GPU 分割权重（并行）<br>- tensor: 分割权重和 KV（并行，实验性）<br>环境变量：LLAMA_ARG_SPLIT_MODE
-ts, --tensor-split N0,N1,N2,...	每 GPU 卸载模型的比例，逗号分隔的比例列表，例如 3,1<br>环境变量：LLAMA_ARG_TENSOR_SPLIT
-mg, --main-gpu INDEX	用于模型的 GPU（split-mode = none 时），或用于中间结果和 KV（split-mode = row 时），默认：0<br>环境变量：LLAMA_ARG_MAIN_GPU
-fit, --fit [on\|off]	是否调整未设置参数以适应设备内存（'on' 或 'off'，默认：'on'）<br>环境变量：LLAMA_ARG_FIT
-fitt, --fit-target MiB0,MiB1,MiB2,...	每设备的 --fit 目标余量（MiB），逗号分隔列表，单个值广播到所有设备，默认：1024<br>环境变量：LLAMA_ARG_FIT_TARGET
-fitc, --fit-ctx N	--fit 可设置的最小上下文大小，默认：4096<br>环境变量：LLAMA_ARG_FIT_CTX
--check-tensors	检查模型张量数据是否有无效值（默认：false）
--override-kv KEY=TYPE,...	高级选项：按键覆盖模型元数据。<br>可指定多个覆盖，用逗号分隔。<br>类型：int, float, bool, str。<br>示例：--override-kv tokenizer.ggml.add_bos_token=bool,tokenizer.ggml.add_eos_token=bool
--op-offload, --no-op-offload	是否将主机张量操作卸载到设备（默认：true）
--lora FNAME	LoRA 适配器路径（逗号分隔加载多个）
--lora-scaled FNAME,...	带有用户定义缩放的 LoRA 适配器（格式：FNAME,SCALE,...）<br>注意：使用逗号分隔
--control-vector FNAME	添加控制向量（多个用逗号分隔）
--control-vector-scaled FNAME,SCALE,...	添加带有用户定义缩放的控制向量（格式：FNAME,SCALE,...）
--control-vector-layer-range START END	应用控制向量的层范围，包含起始和结束
-m, --model FNAME	要加载的模型路径<br>环境变量：LLAMA_ARG_MODEL
-mu, --model-url MODEL_URL	模型下载 URL（默认：未使用）<br>环境变量：LLAMA_ARG_MODEL_URL
-dr, --docker-repo [<repo>/]<model>[:<quant>]	Docker Hub 模型仓库，repo 可选，默认为 ai/，quant 可选，默认为空。<br>示例：gemma3（默认：未使用）<br>环境变量：LLAMA_ARG_DOCKER_REPO
-hf, -hfr, --hf-repo <repo>[/<quant>]	Hugging Face 模型仓库；quant 可选（不区分大小写），默认为 Q4_K_M，若不存在则回退到仓库中的第一个文件。<br>如果有 mmproj 也会自动下载，可通过 --no-mmproj 禁用。<br>示例：ggml-org/GLM-4.7-Flash-GGUF（默认：未使用）<br>环境变量：LLAMA_ARG_HF_REPO
-hff, --hf-file FILE	Hugging Face 模型文件名。如果指定，将覆盖 --hf-repo 中的 quant（默认：未使用）<br>环境变量：LLAMA_ARG_HF_FILE
-hfv, -hfrv, --hf-repo-v <repo>[/<quant>]	声码器模型的 Hugging Face 仓库（默认：未使用）<br>环境变量：LLAMA_ARG_HF_REPO_V
-hffv, --hf-file-v FILE	声码器模型的 Hugging Face 文件名（默认：未使用）<br>环境变量：LLAMA_ARG_HF_FILE_V
-hft, --hf-token TOKEN	Hugging Face 访问令牌（默认：从环境变量 HF_TOKEN 读取）<br>环境变量：HF_TOKEN
--log-disable	禁用日志
--log-file FNAME	日志写入文件<br>环境变量：LLAMA_ARG_LOG_FILE
--log-colors [on\|off\|auto]	设置彩色日志（'on', 'off' 或 'auto'，默认：'auto'）<br>'auto' 在输出到终端时启用颜色<br>环境变量：LLAMA_ARG_LOG_COLORS
-v, --verbose, --log-verbose	将详细级别设置为无穷大（即记录所有消息，用于调试）
--offline	离线模式：强制使用缓存，阻止网络访问<br>环境变量：LLAMA_ARG_OFFLINE
-lv, --verbosity, --log-verbosity N	设置详细阈值，更高详细度的消息将被忽略。<br>值：<br>0: 常规输出<br>1: 错误<br>2: 警告<br>3: 信息<br>4: 跟踪（更多信息）<br>5: 调试<br>默认：1<br>环境变量：LLAMA_ARG_LOG_VERBOSITY
--log-prefix, --no-log-prefix	在日志消息中启用前缀<br>环境变量：LLAMA_ARG_LOG_PREFIX
--log-timestamps, --no-log-timestamps	在日志消息中启用时间戳<br>环境变量：LLAMA_ARG_LOG_TIMESTAMPS
--spec-draft-type-k, -ctkd, --cache-type-k-draft TYPE	草稿模型 KV 缓存中 K 的数据类型<br>允许值同上（默认：f16）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_CACHE_TYPE_K
--spec-draft-type-v, -ctvd, --cache-type-v-draft TYPE	草稿模型 KV 缓存中 V 的数据类型<br>允许值同上（默认：f16）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_CACHE_TYPE_V

---

二、采样参数（sampling params）

参数	说明
--samplers SAMPLERS	按顺序使用的采样器，用 ';' 分隔（默认：penalties;dry;top_n_sigma;top_k;typ_p;top_p;min_p;xtc;temperature）
-s, --seed SEED	随机数生成器种子（默认：-1，-1 表示使用随机种子）
--sampler-seq, --sampling-seq SEQUENCE	简化的采样器序列（默认：edskypmxt）
--ignore-eos	忽略结束流 token 并继续生成（隐含 --logit-bias EOS-inf）
--temp, --temperature N	温度（默认：0.80）
--top-k N	Top-k 采样（默认：40，0 = 禁用）<br>环境变量：LLAMA_ARG_TOP_K
--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 = 禁用，-1 = ctx_size）
--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	最后 n 个 token 的 DRY 惩罚（默认：-1，0 = 禁用，-1 = 上下文大小）
--dry-sequence-breaker STRING	添加 DRY 采样的序列中断符，会清除默认中断符（\n, :, ", *）；使用 "none" 表示不使用任何中断符
--adaptive-target N	自适应-p：选择接近此概率的 token（有效范围 0.0 到 1.0；负数 = 禁用）（默认：-1.00）<br>更多信息参见文档
--adaptive-decay N	自适应-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 和局部典型采样器将被忽略。<br>（默认：0，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 增加 token ' Hello' 的似然，或 --logit-bias 15043-1 降低
--grammar GRAMMAR	类似 BNF 的语法约束生成（参见 grammars/ 目录示例）
--grammar-file FNAME	从文件读取语法
-j, --json-schema SCHEMA	JSON Schema 约束生成（https://json-schema.org/），例如 {} 表示任意 JSON 对象。<br>对于外部 $refs 的 schema，请改用 --grammar + example/json_schema_to_grammar.py
-jf, --json-schema-file FILE	包含 JSON Schema 的文件，约束生成（https://json-schema.org/），例如 {} 表示任意 JSON 对象。<br>对于外部 $refs，请改用 --grammar + example/json_schema_to_grammar.py
-bs, --backend-sampling	启用后端采样（实验性）（默认：禁用）<br>环境变量：LLAMA_ARG_BACKEND_SAMPLING

---

三、推测解码参数（speculative params）

参数	说明
--spec-draft-hf, -hfd, -hfrd, --hf-repo-draft <repo>[/<quant>]	同 --hf-repo，但用于草稿模型（默认：未使用）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_HF_REPO
--spec-draft-threads, -td, --threads-draft N	生成时使用的线程数（默认：同 --threads）
--spec-draft-threads-batch, -tbd, --threads-batch-draft N	批处理和提示处理时使用的线程数（默认：同 --threads-draft）
--spec-draft-cpu-mask, -Cd, --cpu-mask-draft M	草稿模型的 CPU 亲和性掩码，与 --cpu-range-draft 互补（默认：同 --cpu-mask）
--spec-draft-cpu-range, -Crd, --cpu-range-draft lo-hi	草稿模型的 CPU 亲和性范围，与 --cpu-mask-draft 互补（默认：同 --cpu-mask）
--spec-draft-cpu-strict, --cpu-strict-draft <0\|1>	是否为草稿模型使用严格的 CPU 绑定（默认：同 --cpu-strict）
--spec-draft-prio, --prio-draft N	草稿进程/线程优先级：0-normal, 1-medium, 2-high, 3-realtime（默认：0）
--spec-draft-poll, --poll-draft <0\|1>	是否轮询等待草稿模型工作（默认：同 --poll）
--spec-draft-cpu-mask-batch, -Cbd, --cpu-mask-batch-draft M	草稿模型批处理时的 CPU 亲和性掩码（默认：同 --cpu-mask）
--spec-draft-cpu-strict-batch, --cpu-strict-batch-draft <0\|1>	草稿模型批处理时是否严格 CPU 绑定（默认：--cpu-strict-draft）
--spec-draft-prio-batch, --prio-batch-draft N	草稿模型批处理优先级（默认：0）
--spec-draft-poll-batch, --poll-batch-draft <0\|1>	批处理时是否轮询等待草稿模型工作（默认：--poll-draft）
--spec-draft-override-tensor, -otd, --override-tensor-draft <KEY=TYPE,...>	覆盖草稿模型的张量缓冲区类型（默认：同 --override-tensor）
--spec-draft-cpu-moe, -cmoed, --cpu-moe-draft	将草稿模型的所有 MoE 权重保留在 CPU 中<br>环境变量：LLAMA_ARG_SPEC_DRAFT_CPU_MOE
--spec-draft-n-cpu-moe, --spec-draft-ncmoe, -ncmoed, --n-cpu-moe-draft N	将草稿模型前 N 层的 MoE 权重保留在 CPU 中<br>环境变量：LLAMA_ARG_SPEC_DRAFT_N_CPU_MOE
--spec-draft-n-max N	推测解码中草稿 token 的最大数量（默认：3）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_N_MAX
--spec-draft-n-min N	推测解码中草稿 token 的最小数量（默认：0）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_N_MIN
--spec-draft-p-split, --draft-p-split P	推测解码分割概率（默认：0.10）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_P_SPLIT
--spec-draft-p-min, --draft-p-min P	最小推测解码概率（贪婪）（默认：0.00）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_P_MIN
--spec-draft-backend-sampling, --no-spec-draft-backend-sampling	将草稿采样卸载到后端（默认：启用）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_BACKEND_SAMPLING
--spec-draft-device, -devd, --device-draft <dev1,dev2,..>	用于卸载草稿模型的设备列表（none = 不卸载），使用 --list-devices 查看可用设备
--spec-draft-ngl, -ngld, --gpu-layers-draft, --n-gpu-layers-draft N	草稿模型存储在 VRAM 中的最大层数，精确数字、'auto' 或 'all'（默认：auto）<br>环境变量：LLAMA_ARG_N_GPU_LAYERS_DRAFT
--spec-draft-model, -md, --model-draft FNAME	推测解码的草稿模型路径（默认：未使用）<br>环境变量：LLAMA_ARG_SPEC_DRAFT_MODEL
--spec-type none,draft-simple,draft-eagle3,draft-mtp,draft-dflash,ngram-simple,ngram-map-k,ngram-map-k4v,ngram-mod,ngram-cache	推测解码类型（逗号分隔列表），默认：none<br>环境变量：LLAMA_ARG_SPEC_TYPE
--spec-ngram-mod-n-min N	基于 ngram 的推测解码使用的最小 ngram token 数（默认：48）
--spec-ngram-mod-n-max N	基于 ngram 的推测解码使用的最大 ngram token 数（默认：64）
--spec-ngram-mod-n-match N	ngram-mod 查找长度（默认：24）
--spec-ngram-simple-size-n N	ngram-simple 推测解码的 ngram 大小 N（查找 ngram 长度）（默认：12）
--spec-ngram-simple-size-m N	ngram-simple 推测解码的 ngram 大小 M（草稿 mgram 长度）（默认：48）
--spec-ngram-simple-min-hits N	ngram-simple 推测解码的最小命中数（默认：1）
--spec-ngram-map-k-size-n N	ngram-map-k 推测解码的 ngram 大小 N（默认：12）
--spec-ngram-map-k-size-m N	ngram-map-k 推测解码的 ngram 大小 M（默认：48）
--spec-ngram-map-k-min-hits N	ngram-map-k 最小命中数（默认：1）
--spec-ngram-map-k4v-size-n N	ngram-map-k4v 推测解码的 ngram 大小 N（默认：12）
--spec-ngram-map-k4v-size-m N	ngram-map-k4v 推测解码的 ngram 大小 M（默认：48）
--spec-ngram-map-k4v-min-hits N	ngram-map-k4v 最小命中数（默认：1）
--draft, --draft-n, --draft-max N	此参数已移除，请使用 --spec-draft-n-max 或 --spec-ngram-mod-n-max<br>环境变量：LLAMA_ARG_DRAFT_MAX
--draft-min, --draft-n-min N	此参数已移除，请使用 --spec-draft-n-min 或 --spec-ngram-mod-n-min<br>环境变量：LLAMA_ARG_DRAFT_MIN

---

四、示例特定参数（example-specific params）

参数	说明
--verbose-prompt	生成前打印详细提示（默认：false）
--display-prompt, --no-display-prompt	生成时是否打印提示（默认：true）
-co, --color [on\|off\|auto]	颜色输出，区分提示、用户输入和生成内容（'on', 'off' 或 'auto'，默认：'auto'）<br>'auto' 在输出到终端时启用颜色
-ctxcp, --ctx-checkpoints, --swa-checkpoints N	每个槽位创建的上下文检查点最大数量（默认：32）<br>更多信息参见文档<br>环境变量：LLAMA_ARG_CTX_CHECKPOINTS
-cram, --cache-ram N	设置最大缓存大小（MiB）（默认：8192，-1 = 无限制，0 = 禁用）<br>更多信息参见文档<br>环境变量：LLAMA_ARG_CACHE_RAM
--context-shift, --no-context-shift	是否在无限文本生成中使用上下文移位（默认：禁用）<br>环境变量：LLAMA_ARG_CONTEXT_SHIFT
-sys, --system-prompt PROMPT	系统提示（如果适用，取决于聊天模板）
--show-timings, --no-show-timings	每次响应后是否显示计时信息（默认：true）<br>环境变量：LLAMA_ARG_SHOW_TIMINGS
-sysf, --system-prompt-file FNAME	包含系统提示的文件（默认：无）
-r, --reverse-prompt PROMPT	在 PROMPT 处停止生成，在交互模式下返回控制权
-sp, --special	启用特殊 token 输出（默认：false）
-cnv, --conversation, -no-cnv, --no-conversation	是否以对话模式运行：<br>- 不打印特殊 token 和后缀/前缀<br>- 同时启用交互模式<br>（默认：如果聊天模板可用则自动启用）
-st, --single-turn	仅运行单轮对话，完成后退出；如果第一轮用 --prompt 预定义则不会交互（默认：false）
-mli, --multiline-input	允许输入多行文本，不必每行用 \ 结束
--warmup, --no-warmup	是否用空运行进行预热（默认：启用）
-mm, --mmproj FILE	多模态投影仪文件路径，参见 tools/mtmd/README.md<br>注意：如果使用了 -hf，此参数可省略<br>环境变量：LLAMA_ARG_MMPROJ
-mmu, --mmproj-url URL	多模态投影仪文件 URL，参见 tools/mtmd/README.md<br>环境变量：LLAMA_ARG_MMPROJ_URL
--mmproj-auto, --no-mmproj, --no-mmproj-auto	是否使用多模态投影仪文件（如果可用），使用 -hf 时有用（默认：启用）<br>环境变量：LLAMA_ARG_MMPROJ_AUTO
--mmproj-offload, --no-mmproj-offload	是否启用多模态投影仪的 GPU 卸载（默认：启用）<br>环境变量：LLAMA_ARG_MMPROJ_OFFLOAD
--image, --audio, --video FILE	图像、音频或视频文件路径（用于多模态模型），多个文件用逗号分隔
--image-min-tokens N	每个图像可占用的最小 token 数，仅用于动态分辨率视觉模型（默认：从模型读取）<br>环境变量：LLAMA_ARG_IMAGE_MIN_TOKENS
--image-max-tokens N	每个图像可占用的最大 token 数，仅用于动态分辨率视觉模型（默认：从模型读取）<br>环境变量：LLAMA_ARG_IMAGE_MAX_TOKENS
--chat-template-kwargs STRING	为 JSON 模板解析器设置额外参数，必须为有效的 JSON 对象字符串，例如 '{"key1":"value1","key2":"value2"}'<br>环境变量：LLAMA_ARG_CHAT_TEMPLATE_KWARGS
--jinja, --no-jinja	是否使用 Jinja 模板引擎进行聊天（默认：启用）<br>环境变量：LLAMA_ARG_JINJA
--reasoning-format FORMAT	控制是否允许思维标签以及是否从响应中提取，以及返回格式；可选值：<br>- none: 思维保留在 message.content 中不解析<br>- deepseek: 将思维放入 message.reasoning_content<br>- deepseek-legacy: 保留 <think> 标签在 content 中，同时填充 reasoning_content<br>（默认：auto）<br>环境变量：LLAMA_ARG_THINK
-rea, --reasoning [on\|off\|auto]	在聊天中使用推理/思考（'on', 'off' 或 'auto'，默认：'auto'（从模板检测））<br>环境变量：LLAMA_ARG_REASONING
--reasoning-budget N	思考的 token 预算：-1 为无限制，0 为立即结束，N>0 为 token 预算（默认：-1）<br>环境变量：LLAMA_ARG_THINK_BUDGET
--reasoning-budget-message MESSAGE	当推理预算耗尽时，在结束思维标签前注入的消息（默认：无）<br>环境变量：LLAMA_ARG_THINK_BUDGET_MESSAGE
--reasoning-preserve, --no-reasoning-preserve	在完整历史中保留推理痕迹，而不仅仅是最后一条助手消息（默认：模板默认）<br>兼容某些具有 supports_preserve_reasoning 能力的模板<br>示例：https://docs.z.ai/guides/capabilities/thinking-mode#preserved-thinking<br>环境变量：LLAMA_ARG_REASONING_PRESERVE
--chat-template JINJA_TEMPLATE	设置自定义 Jinja 聊天模板（默认：从模型元数据读取）<br>如果指定了后缀/前缀，模板将被禁用。<br>仅接受常用模板（除非在此之前设置了 --jinja）：<br>内置模板列表：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<br>环境变量：LLAMA_ARG_CHAT_TEMPLATE
--chat-template-file JINJA_TEMPLATE_FILE	从文件读取自定义 Jinja 聊天模板（默认：从模型元数据）<br>如果指定了后缀/前缀，模板将被禁用。<br>仅接受常用模板（除非在此之前设置了 --jinja）。<br>内置模板列表同上。<br>环境变量：LLAMA_ARG_CHAT_TEMPLATE_FILE
--skip-chat-parsing, --no-skip-chat-parsing	强制使用纯内容解析器，即使指定了 Jinja 模板；模型将在 content 部分输出所有内容，包括推理和/或工具调用（默认：禁用）<br>环境变量：LLAMA_ARG_SKIP_CHAT_PARSING
--simple-io	使用基本 I/O，以获得更好的子进程和受限控制台兼容性
--log-prompts-dir PATH	将提示记录到目录（仅用于调试，默认：禁用）
--gpt-oss-20b-default	使用 gpt-oss-20b（注意：可从互联网下载权重）
--gpt-oss-120b-default	使用 gpt-oss-120b（注意：可从互联网下载权重）
--vision-gemma-4b-default	使用 Gemma 3 4B QAT（注意：可从互联网下载权重）
--vision-gemma-12b-default	使用 Gemma 3 12B QAT（注意：可从互联网下载权重）
--spec-default	启用默认的推测解码配置

---

说明：本手册基于 llama-cli -h 输出翻译整理，具体行为可能随版本变化，请以实际运行时的帮助信息为准。

llama-server 特有参数（仅列出与 llama-cli 不同或新增的部分）

通用参数（如 -t, -c, --samplers, --spec-* 等）请参考 llama-cli 手册，此处不重复。

服务器专属参数（example‑specific）

参数	说明
-lcs, --lookup-cache-static FNAME	静态查找缓存路径（生成时不更新）
-lcd, --lookup-cache-dynamic FNAME	动态查找缓存路径（生成时更新）
-cms, --checkpoint-min-step N	检查点最小间隔（token），默认 8192，0=无限制。环境变量：LLAMA_ARG_CHECKPOINT_MIN_SPACING_NT
-kvu, --kv-unified, -no-kvu, --no-kv-unified	是否使用统一 KV 缓冲区（默认：若槽位数自动则启用）。环境变量：LLAMA_ARG_KV_UNIFIED
--cache-idle-slots, --no-cache-idle-slots	是否在统一 KV 下将空闲槽保存到缓存并在新任务时清除（需 --cache-ram，默认启用）。环境变量：LLAMA_ARG_CACHE_IDLE_SLOTS
--spm-infill	使用 Suffix/Prefix/Middle 填充模式（而非 Prefix/Suffix/Middle），默认禁用
--pooling {none,mean,cls,last,rank}	嵌入池化类型，默认模型值。环境变量：LLAMA_ARG_POOLING
-np, --parallel N	服务器槽位数（注意：llama-cli 中此参数表示并行序列数，含义不同），默认 -1（自动）。环境变量：LLAMA_ARG_N_PARALLEL
-cb, --cont-batching, -nocb, --no-cont-batching	启用连续批处理（动态批处理），默认启用。环境变量：LLAMA_ARG_CONT_BATCHING
--mtmd-batch-max-tokens N	编码图像时每批最大图像 token 数，默认 1024。环境变量：LLAMA_ARG_MTMD_BATCH_MAX_TOKENS
-a, --alias STRING	模型名称别名（逗号分隔，供 API 使用）。环境变量：LLAMA_ARG_ALIAS
--tags STRING	模型标签（逗号分隔，仅信息展示）。环境变量：LLAMA_ARG_TAGS
--embd-normalize N	嵌入归一化：-1=无，0=最大绝对值 int16，1=曼哈顿，2=欧几里得，>2=p-范数（默认 2）
--host HOST	监听 IP 或 UNIX 套接字（.sock 结尾），默认 127.0.0.1。环境变量：LLAMA_ARG_HOST
--port PORT	监听端口，默认 8080。环境变量：LLAMA_ARG_PORT
--reuse-port	允许复用端口，默认禁用。环境变量：LLAMA_ARG_REUSE_PORT
--path PATH	静态文件服务路径，默认空。环境变量：LLAMA_ARG_STATIC_PATH
--api-prefix PREFIX	API 路径前缀（不带尾部斜杠），默认空。环境变量：LLAMA_ARG_API_PREFIX
--ui-config, --webui-config JSON	默认 UI 设置的 JSON。环境变量：LLAMA_ARG_UI_CONFIG
--ui-config-file, --webui-config-file PATH	包含 UI 设置的 JSON 文件。环境变量：LLAMA_ARG_UI_CONFIG_FILE
--ui-mcp-proxy, --webui-mcp-proxy, --no-...	实验性：启用 MCP CORS 代理（非信任环境禁用），默认禁用。环境变量：LLAMA_ARG_UI_MCP_PROXY
--tools TOOL1,TOOL2,...	实验性：启用内置工具（all 为全部），可用：read_file, file_glob_search, grep_search, exec_shell_command, write_file, edit_file, apply_diff, get_datetime。非信任环境禁用。环境变量：LLAMA_ARG_TOOLS
-ag, --agent, -no-ag, --no-agent	启用 CORS 代理和所有内置工具（非信任环境禁用），默认禁用。环境变量：LLAMA_ARG_AGENT
--ui, --webui, --no-ui, --no-webui	是否启用 Web UI，默认启用。环境变量：LLAMA_ARG_UI
--embedding, --embeddings	仅支持嵌入用例（专用嵌入模型），默认禁用。环境变量：LLAMA_ARG_EMBEDDINGS
--rerank, --reranking	启用重排序端点，默认禁用。环境变量：LLAMA_ARG_RERANKING
--api-key KEY	API 认证密钥（多个逗号分隔）。环境变量：LLAMA_API_KEY
--api-key-file FNAME	包含 API 密钥的文件（每行一个，#注释）。环境变量：LLAMA_ARG_API_KEY_FILE
--ssl-key-file FNAME	PEM SSL 私钥文件。环境变量：LLAMA_ARG_SSL_KEY_FILE
--ssl-cert-file FNAME	PEM SSL 证书文件。环境变量：LLAMA_ARG_SSL_CERT_FILE
-to, --timeout N	读写超时（秒），默认 3600。环境变量：LLAMA_ARG_TIMEOUT
--sse-ping-interval N	SSE 心跳间隔（秒），-1 禁用，默认 30。环境变量：LLAMA_ARG_SSE_PING_INTERVAL
--threads-http N	HTTP 请求处理线程数，默认 -1。环境变量：LLAMA_ARG_THREADS_HTTP
--cache-prompt, --no-cache-prompt	启用提示缓存，默认启用。环境变量：LLAMA_ARG_CACHE_PROMPT
--cache-reuse N	通过 KV 移位重用缓存的最小分块大小（需启用提示缓存），默认 0。环境变量：LLAMA_ARG_CACHE_REUSE
--metrics	启用 Prometheus 指标端点，默认禁用。环境变量：LLAMA_ARG_ENDPOINT_METRICS
--props	允许通过 POST /props 更改全局属性，默认禁用。环境变量：LLAMA_ARG_ENDPOINT_PROPS
--slots, --no-slots	暴露槽位监控端点，默认启用。环境变量：LLAMA_ARG_ENDPOINT_SLOTS
--slot-save-path PATH	保存槽位 KV 缓存的路径，默认禁用
--media-path PATH	本地媒体文件目录，可通过 file:// 访问，默认禁用
--models-dir PATH	路由器服务器模型目录，默认禁用。环境变量：LLAMA_ARG_MODELS_DIR
--models-preset PATH	路由器服务器模型预设 INI 文件，默认禁用。环境变量：LLAMA_ARG_MODELS_PRESET
--models-max N	路由器同时加载最大模型数，默认 4，0=无限制。环境变量：LLAMA_ARG_MODELS_MAX
--models-autoload, --no-models-autoload	路由器是否自动加载模型，默认启用。环境变量：LLAMA_ARG_MODELS_AUTOLOAD
--prefill-assistant, --no-prefill-assistant	若最后一条消息是 assistant，是否预填充响应（默认启用预填充）。环境变量：LLAMA_ARG_PREFILL_ASSISTANT
-sps, --slot-prompt-similarity SIMILARITY	请求提示与槽位提示匹配阈值（0.10，0.0=禁用）
--lora-init-without-apply	加载 LoRA 但不立即应用（后续通过 API 应用），默认禁用
--sleep-idle-seconds SECONDS	空闲多少秒后休眠，-1 禁用，默认 -1
-mv, --model-vocoder FNAME	声码器模型路径（音频生成），默认未使用
--tts-use-guide-tokens	使用引导 token 改善 TTS 单词召回率
--embd-gemma-default	使用默认 EmbeddingGemma 模型（可从网络下载）
--fim-qwen-1.5b-default	使用默认 Qwen 2.5 Coder 1.5B（可从网络下载）
--fim-qwen-3b-default	使用默认 Qwen 2.5 Coder 3B（可从网络下载）
--fim-qwen-7b-default	使用默认 Qwen 2.5 Coder 7B（可从网络下载）
--fim-qwen-7b-spec	使用 Qwen 2.5 Coder 7B + 0.5B 草稿模型（推测解码，可从网络下载）
--fim-qwen-14b-spec	使用 Qwen 2.5 Coder 14B + 0.5B 草稿模型（推测解码，可从网络下载）
--fim-qwen-30b-default	使用默认 Qwen 3 Coder 30B A3B Instruct（可从网络下载）
--gpt-oss-20b-default	使用 gpt-oss-20b（可从网络下载）
--gpt-oss-120b-default	使用 gpt-oss-120b（可从网络下载）
--vision-gemma-4b-default	使用 Gemma 3 4B QAT（可从网络下载）
--vision-gemma-12b-default	使用 Gemma 3 12B QAT（可从网络下载）
--spec-default	启用默认推测解码配置

说明：所有带 (env: ...) 的参数均支持对应环境变量，具体取值以实际程序输出为准。