llama.cpp 最新版介绍与参数详解

版本: 9208 (5511965b1) | 构建: Clang 19.1.5 Windows x86_64 | CUDA: 12.4
项目地址: https://github.com/ggml-org/llama.cpp
本机路径: E:\llama-bin-win-cuda-12.4-x64\

一、llama.cpp 简介

llama.cpp 是一个高性能的 C/C++ 推理引擎，专注于在本地运行 GGUF 格式的大语言模型。它支持：

CPU + GPU 混合推理 — 通过 -ngl 参数将部分层卸载到 GPU（CUDA / Vulkan / Metal / SYCL）
GGUF 量化格式 — 以 Q4_K_M、Q8_0 等量化等级平衡速度与质量
OpenAI 兼容 API — llama-server 提供 /v1/chat/completions、/v1/audio/transcriptions 等标准端点
Router Server 模式 — 多模型管理、自动加载/卸载、JIT 模型切换
Flash Attention — 大幅加速长上下文推理
推测解码 (Speculative Decoding) — 用小模型草稿加速大模型
多模态支持 — 视觉（LLaVA、Qwen2-VL）、语音（Whisper）、ASR（Qwen3-ASR）

二、二进制工具集

可执行文件	用途
`llama-server.exe`	主服务器 — OpenAI API 兼容服务，支持 Router 多模型管理
`llama-cli.exe`	命令行推理客户端
`llama-bench.exe`	性能基准测试
`llama-quantize.exe`	模型量化工具
`llama-gguf-split.exe`	GGUF 文件拆分/合并
`llama-perplexity.exe`	困惑度评估
`llama-tokenize.exe`	分词/反分词工具
`llama-qwen2vl-cli.exe`	Qwen2-VL 视觉推理 CLI
`llama-llava-cli.exe`	LLaVA 视觉推理 CLI
`llama-minicpmv-cli.exe`	MiniCPM-V 视觉推理 CLI
`llama-gemma3-cli.exe`	Gemma3 视觉推理 CLI

三、llama-server 完整参数详解

3.1 模型加载

参数	说明	默认值
`-m, --model FNAME`	模型文件路径	无
`-mu, --model-url URL`	模型下载 URL	无
`-hf, --hf-repo <user>/<model>[:quant]`	HuggingFace 仓库自动下载 (量化可选, 默认 Q4_K_M)	无
`-hff, --hf-file FILE`	覆盖 --hf-repo 中的具体文件名	无
`-hft, --hf-token TOKEN`	HuggingFace 访问令牌	`HF_TOKEN` 环境变量
`-mm, --mmproj FILE`	多模态投影器 (如 Qwen-ASR 的 mmproj)	无
`-ngl, --gpu-layers N`	卸载到 GPU 的层数, 可选 `auto` 或 `all`	`auto`
`-sm, --split-mode {none,layer,row,tensor}`	多 GPU 拆分模式	`layer`
`-ts, --tensor-split N0,N1,...`	多 GPU 权重分配比例, 如 `3,1`	无
`-mg, --main-gpu INDEX`	主 GPU 索引	`0`
`-dev, --device <dev1,dev2,...>`	指定 GPU 设备列表	无
`--list-devices`	列出可用设备并退出	—
`--fit [on/off]`	自动调整未设置参数适配设备内存	`on`
`-fitt, --fit-target MiB`	--fit 的每设备余量目标	`1024`

3.2 推理参数

参数	说明	默认值
`-c, --ctx-size N`	提示上下文大小 (0 = 从模型读取)	`0`
`-n, --n-predict N`	预测 token 数量 (-1 = 无限)	`-1`
`-b, --batch-size N`	逻辑最大批大小	`2048`
`-ub, --ubatch-size N`	物理最大批大小	`512`
`-t, --threads N`	生成时 CPU 线程数	`-1`
`-tb, --threads-batch N`	批处理时 CPU 线程数	同 `--threads`
`-fa, --flash-attn [on/off/auto]`	Flash Attention	`auto`
`--mlock`	锁定模型在 RAM 防止换出	禁用
`--no-mmap`	禁用内存映射 (加载慢但减少 pageout)	启用 mmap
`-ctk, --cache-type-k TYPE`	K 缓存数据类型	`f16`
`-ctv, --cache-type-v TYPE`	V 缓存数据类型	`f16`
`--rope-scaling {none,linear,yarn}`	RoPE 频率缩放方法	`linear`
`--rope-scale N`	RoPE 上下文缩放因子	无
`--rope-freq-base N`	RoPE 基频	从模型读取
`--yarn-ext-factor N`	YaRN 外推混合因子	`-1.0`

3.3 Sampling (采样) 参数

参数	说明	默认值
`--samplers LIST`	采样器链, 用 `;` 分隔	`penalties;dry;top_n_sigma;top_k;typ_p;top_p;min_p;xtc;temperature`
`-s, --seed N`	RNG 种子 (-1 = 随机)	`-1`
`--temp, --temperature N`	温度	`0.80`
`--top-k N`	Top-K 采样 (0 = 禁用)	`40`
`--top-p N`	Top-P 采样 (1.0 = 禁用)	`0.95`
`--min-p N`	Min-P 采样 (0.0 = 禁用)	`0.05`
`--repeat-penalty N`	重复惩罚 (1.0 = 禁用)	`1.00`
`--presence-penalty N`	存在惩罚	`0.00`
`--frequency-penalty N`	频率惩罚	`0.00`
`--mirostat N`	Mirostat (0=禁用, 1= v1, 2=v2)	`0`
`--mirostat-lr N`	Mirostat 学习率	`0.10`
`--mirostat-ent N`	Mirostat 目标熵	`5.00`
`--dry-multiplier N`	DRY 采样乘数	`0.00`
`--xtc-probability N`	XTC 概率	`0.00`
`--grammar GRAMMAR`	BNF 文法约束生成	无
`-j, --json-schema SCHEMA`	JSON Schema 约束	无
`--dynatemp-range N`	动态温度范围	`0.00`

3.4 服务器参数

参数	说明	默认值
`--host HOST`	监听 IP 地址	`127.0.0.1`
`--port PORT`	监听端口	`8080`
`-to, --timeout N`	读写超时 (秒)	`600`
`--threads-http N`	HTTP 处理线程数	`-1`
`-np, --parallel N`	服务器槽位数 (-1 = auto)	`-1`
`--api-key KEY`	API 密钥认证	无
`--embedding`	仅嵌入模式	禁用
`--rerank`	启用重排序端点	禁用
`-a, --alias STRING`	模型别名 (API 用)	无
`--ui, --no-ui`	启用 Web UI	启用
`--metrics`	Prometheus 指标端点	禁用
`--jinja`	Jinja 模板引擎	启用
`--reasoning-format FORMAT`	思考标签输出格式 (none/deepseek/deepseek-legacy)	`auto`
`--slot-save-path PATH`	槽 KV 缓存保存路径	禁用
`-sps, --slot-prompt-similarity N`	槽提示匹配相似度阈值	`0.10`
`--chat-template NAME`	内置聊天模板名称	从模型读取
`--cache-prompt`	启用提示缓存	启用
`--cache-reuse N`	KV 偏移重用的最小块大小	`0`

3.5 Router Server (多模型管理) ★ 核心功能

这些参数实现了类似 LM Studio 的「多模型热切换 + 自动卸载」能力：

参数	说明	默认值
`--models-dir PATH`	模型目录 — 指定 LM Studio 模型路径, 自动扫描所有 GGUF	禁用
`--models-preset PATH`	模型预设文件 — INI 格式描述每个模型的参数	禁用
`--models-max N`	最大同时加载模型数 — 设为 `1` 即实现"仅保留最近加载的 JIT 模型"	`4`
`--models-autoload`	自动加载 — 请求时自动加载未加载的模型	启用
`--cache-ram N`	KV 缓存最大 RAM (MiB) — 旧模型/槽的缓存会自动释放	`8192`
`--cache-idle-slots`	空闲槽清理 — 新任务到达时保存并清除空闲槽的 KV 缓存	启用
`--sleep-idle-seconds N`	★★★★★ 闲时自动卸载 TTL — 服务器空闲 N 秒后自动卸载模型释放显存 (-1 = 禁用)	`-1`
`--context-shift`	上下文偏移 — 无限文本生成时的上下文移位	禁用

Router Server 模型预设文件 (.ini) 格式示例

[qwen3-asr]
model = C:\Users\kekezack\.lmstudio\models\ggml-org\Qwen3-ASR-1.7B-GGUF\Qwen3-ASR-1.7B-Q8_0.gguf
mmproj = C:\Users\kekezack\.lmstudio\models\ggml-org\Qwen3-ASR-1.7B-GGUF\mmproj-Qwen3-ASR-1.7B-bf16.gguf
ngl = 99
ctx-size = 8192
alias = asr

[qwen3-8b]
model = C:\Users\kekezack\.lmstudio\models\lmstudio-community\Qwen3-8B-GGUF\Qwen3-8B-Q4_K_M.gguf
ngl = 99
ctx-size = 32768
alias = chat

[gemma3-12b]
model = C:\Users\kekezack\.lmstudio\models\lmstudio-community\gemma-3-12b-it-GGUF\gemma-3-12b-it-Q4_K_M.gguf
mmproj = C:\Users\kekezack\.lmstudio\models\lmstudio-community\gemma-3-12b-it-GGUF\mmproj-model-f16.gguf
ngl = 99
ctx-size = 8192
alias = vision

3.6 推测解码 (Speculative Decoding)

参数	说明	默认值
`--spec-type TYPE`	推测解码类型 (none / draft-simple / draft-eagle3 / ngram-cache 等)	`none`
`-md, --model-draft FNAME`	草稿模型路径	无
`--spec-draft-n-max N`	最大草稿 token 数	`16`
`--spec-draft-n-min N`	最小草稿 token 数	`0`
`--spec-draft-p-split P`	推测解码分裂概率	`0.10`
`--spec-draft-p-min P`	最小推测概率 (贪心)	`0.75`

3.7 多模态 / 特殊模型

参数	说明
`--image-min-tokens N`	图像最小 token 数 (动态分辨率视觉模型)
`--image-max-tokens N`	图像最大 token 数
`-mv, --model-vocoder FNAME`	TTS 声码器模型路径
`--tools LIST`	内置 AI 代理工具 (read_file, grep_search 等)

四、类 LM Studio 的启动方式

这一节只讲最实用的用法: 直接复用 LM Studio 下载的模型目录, 保留它的“按请求自动切换模型”体验, 同时补上 LM Studio 默认不强调的两项能力:

TTL 闲时自动卸载: 通过 --sleep-idle-seconds 300 设置 300 秒无请求后自动卸载模型, 释放显存。
强制单模型驻留: 通过 --models-max 1 只保留最近加载的 JIT 模型, 新模型加载时自动卸载前一个。

如果你的目标是“尽可能像 LM Studio, 但更省显存”, 那么 Router Server + TTL + --models-max 1 就是首选方案。

4.1 LM Studio 模型目录

LM Studio 下载的模型通常位于 %USERPROFILE%\.lmstudio\models\ 下, 按 发布者/模型目录/GGUF文件 组织。例如:

%USERPROFILE%\.lmstudio\models\
  ggml-org\Qwen3-ASR-1.7B-GGUF\Qwen3-ASR-1.7B-Q8_0.gguf
  ggml-org\Qwen3-ASR-1.7B-GGUF\mmproj-Qwen3-ASR-1.7B-bf16.gguf
  lmstudio-community\Qwen3-8B-GGUF\Qwen3-8B-Q4_K_M.gguf

这意味着你可以直接让 llama-server 扫描这个目录, 不需要手工复制模型。

4.2 最推荐: Router Server + TTL + 单模型驻留

这是最接近 LM Studio 使用体验, 同时又能自动控显存的方案。

这个组合为什么像 LM Studio

参数	作用	对 LM Studio 体验的意义
`--models-dir "%USERPROFILE%\.lmstudio\models"`	扫描 LM Studio 模型目录	直接复用 LM Studio 已下载模型
`--models-preset "%CD%\models-preset.ini"`	为不同模型声明 `ctx-size`、`ngl`、`mmproj`、别名	类似 LM Studio 给不同模型保存配置
`--models-autoload`	请求某个未加载模型时自动加载	保留“点哪个模型就切哪个模型”的体验
`--models-max 1`	最多只允许 1 个模型同时驻留	仅保留最近加载的 JIT 模型, 新模型会顶掉前一个
`--sleep-idle-seconds 300`	300 秒无请求后自动卸载模型	闲时彻底释放显存
`--cache-idle-slots`	空闲时清理槽位 KV	降低上下文缓存占用
`--cache-ram 2048`	限制 KV 缓存总 RAM	防止 Router 模式下缓存持续堆积

4.3 单模型直连模式

如果你只跑一个固定模型, 可以不用 Router, 直接指定 -m 和 --mmproj。

纯单模型聊天

"%LLAMA_BIN%\llama-server.exe" -m "%USERPROFILE%\.lmstudio\models\lmstudio-community\Qwen3-8B-GGUF\Qwen3-8B-Q4_K_M.gguf" --port 18003 -ngl auto -c 32768 -np 4

单模型 ASR + TTL 自动卸载

"%LLAMA_BIN%\llama-server.exe" -m "%USERPROFILE%\.lmstudio\models\ggml-org\Qwen3-ASR-1.7B-GGUF\Qwen3-ASR-1.7B-Q8_0.gguf" --mmproj "%USERPROFILE%\.lmstudio\models\ggml-org\Qwen3-ASR-1.7B-GGUF\mmproj-Qwen3-ASR-1.7B-bf16.gguf" --port 18003 -ngl 99 -c 8192 -np 4 --models-max 1 --sleep-idle-seconds 300

这个模式适合专门给本项目的语音转写接口使用。虽然这里只有一个模型, 但保留 --sleep-idle-seconds 300 依然有意义: 空闲时会自动释放显存。

4.4 `models-preset.ini` 的作用

--models-preset 让 Router 知道每个模型要用什么附加参数, 尤其适合以下几类模型:

ASR / 多模态模型: 需要 mmproj
大上下文聊天模型: 需要单独的 ctx-size
不同体量模型: 需要不同 ngl
对外暴露 API: 希望提供固定 alias

示例:

[qwen3-asr]
model = %USERPROFILE%\.lmstudio\models\ggml-org\Qwen3-ASR-1.7B-GGUF\Qwen3-ASR-1.7B-Q8_0.gguf
mmproj = %USERPROFILE%\.lmstudio\models\ggml-org\Qwen3-ASR-1.7B-GGUF\mmproj-Qwen3-ASR-1.7B-bf16.gguf
ngl = 99
ctx-size = 8192
alias = asr

[qwen3-8b]
model = %USERPROFILE%\.lmstudio\models\lmstudio-community\Qwen3-8B-GGUF\Qwen3-8B-Q4_K_M.gguf
ngl = 99
ctx-size = 32768
alias = chat

4.5 模型切换 API

启动 Router Server 后, 客户端只要在请求里指定 model, llama-server 就会像 LM Studio 一样按需切换。

curl http://localhost:18003/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "C:\\Users\\kekezack\\.lmstudio\\models\\lmstudio-community\\Qwen3-8B-GGUF\\Qwen3-8B-Q4_K_M.gguf",
    "messages": [{"role": "user", "content": "你好"}]
  }'

curl http://localhost:18003/v1/audio/transcriptions \
  -F "model=Qwen3-ASR-1.7B-Q8_0.gguf" \
  -F "file=@audio.wav"

如果启用了 alias, 也可以优先用别名, 这样客户端不必写完整文件路径。

五、常用启动模板

模板 1: 最简单单模型聊天

llama-server.exe -m "model.gguf" --port 8080 -ngl auto -c 8192

模板 2: 类 LM Studio 的多模型 Router

llama-server.exe --models-dir "%USERPROFILE%\.lmstudio\models" --models-preset "models-preset.ini" --models-autoload --port 8080 -ngl auto -c 32768 --flash-attn auto

适合追求“像 LM Studio 一样自动切模型”, 但不强制限制只驻留一个模型的场景。

模板 3: 类 LM Studio + TTL + 强制单模型驻留

llama-server.exe --models-dir "%USERPROFILE%\.lmstudio\models" --models-preset "models-preset.ini" --models-autoload --models-max 1 --sleep-idle-seconds 300 --cache-ram 2048 --cache-idle-slots --port 8080 -ngl auto -c 32768 --flash-attn auto

这是本文最推荐的模板:

行为上接近 LM Studio
300 秒空闲自动卸载
新模型加载时自动卸载前一个模型

模板 4: 本项目 Qwen3-ASR 服务

llama-server.exe -m "%USERPROFILE%\.lmstudio\models\ggml-org\Qwen3-ASR-1.7B-GGUF\Qwen3-ASR-1.7B-Q8_0.gguf" --mmproj "%USERPROFILE%\.lmstudio\models\ggml-org\Qwen3-ASR-1.7B-GGUF\mmproj-Qwen3-ASR-1.7B-bf16.gguf" --port 18003 -ngl 99 -c 8192 -np 4 --models-max 1 --sleep-idle-seconds 300

适合只给语音转写服务使用, 启动简单, 空闲后也会释放显存。

六、性能与资源建议

场景	推荐参数
显存充足 (24GiB+)	`-ngl all -fa on -c 32768 --no-mmap`
显存紧张 (8GiB)	`--models-max 1 --sleep-idle-seconds 300 --cache-ram 1024 -ngl auto -fa auto`
追求速度	`-t 8 -tb 8`
长上下文	`-fa on --cache-reuse 256`
多请求并发	`-np 4` 或更高, 按 CPU/GPU 能力调整

建议组合

想最大限度模仿 LM Studio: --models-dir + --models-preset + --models-autoload
想控制显存驻留: 再加 --models-max 1
想空闲自动释放显存: 再加 --sleep-idle-seconds 300
想避免 KV 缓存吃满内存: 再加 --cache-ram 和 --cache-idle-slots

七、常见问题

Q: 哪个方案最像 LM Studio?
A: Router Server + --models-dir + --models-preset + --models-autoload 最像 LM Studio。如果你还希望它在空闲时释放显存, 就再加 --models-max 1 --sleep-idle-seconds 300。

Q: --models-max 1 到底做了什么?
A: 它强制最多只保留 1 个已加载模型。请求切换到新模型时, 旧模型会被自动卸载, 因而实现“仅保留最近加载的 JIT 模型”。

Q: --sleep-idle-seconds 300 到底做了什么?
A: 它设置 TTL 为 300 秒。服务器在连续 300 秒没有请求时, 会把当前模型卸载掉。下一次请求到来时再自动重载。

Q: --models-max 1 和 -np 4 冲突吗?
A: 不冲突。--models-max 1 控制的是同时驻留的模型数, -np 4 控制的是单个模型可服务的并发槽位数。

Q: --sleep-idle-seconds 和 --cache-ram / --cache-idle-slots 有什么区别?
A: --sleep-idle-seconds 是卸载整个模型权重, 目标是释放显存。--cache-ram 和 --cache-idle-slots 主要管 KV 缓存, 目标是控制上下文缓存占用。两者解决的问题不同, 但通常建议一起开。

Q: 如何确认 TTL 自动卸载生效了?
A: 关注服务日志。空闲超时后通常会看到 idle / unload 相关日志; 开启更详细日志时更容易确认模型被卸载和重新加载。

Q: 支持哪些 GGUF 量化等级?
A: 从低到高通常可理解为 Q2_K < Q3_K < Q4_K < Q5_K < Q6_K < Q8_0 < F16。常用推荐是 Q4_K_M 兼顾体积与效果, Q8_0 更偏质量。

llama.cpp-参数详解.md 17 KB

고유링크 히스토리 Raw

llama.cpp 最新版介绍与参数详解

一、llama.cpp 简介

二、二进制工具集

三、llama-server 完整参数详解

3.1 模型加载

3.2 推理参数

3.3 Sampling (采样) 参数

3.4 服务器参数

3.5 Router Server (多模型管理) ★ 核心功能

Router Server 模型预设文件 (.ini) 格式示例

3.6 推测解码 (Speculative Decoding)

3.7 多模态 / 特殊模型

四、类 LM Studio 的启动方式

4.1 LM Studio 模型目录

4.2 最推荐: Router Server + TTL + 单模型驻留

推荐启动命令

这个组合为什么像 LM Studio

推荐理解方式

4.3 单模型直连模式

纯单模型聊天

单模型 ASR + TTL 自动卸载

4.4 `models-preset.ini` 的作用

4.5 模型切换 API

五、常用启动模板

模板 1: 最简单单模型聊天

模板 2: 类 LM Studio 的多模型 Router

模板 3: 类 LM Studio + TTL + 强制单模型驻留

模板 4: 本项目 Qwen3-ASR 服务

六、性能与资源建议

建议组合

七、常见问题

llama.cpp-参数详解.md 17 KB 고유링크 히스토리 Raw

llama.cpp 最新版介绍与参数详解

一、llama.cpp 简介

二、二进制工具集

三、llama-server 完整参数详解

3.1 模型加载

3.2 推理参数

3.3 Sampling (采样) 参数

3.4 服务器参数

3.5 Router Server (多模型管理) ★ 核心功能

Router Server 模型预设文件 (.ini) 格式示例

3.6 推测解码 (Speculative Decoding)

3.7 多模态 / 特殊模型

四、类 LM Studio 的启动方式

4.1 LM Studio 模型目录

4.2 最推荐: Router Server + TTL + 单模型驻留

推荐启动命令

这个组合为什么像 LM Studio

推荐理解方式

4.3 单模型直连模式

纯单模型聊天

单模型 ASR + TTL 自动卸载

4.4 models-preset.ini 的作用

4.5 模型切换 API

五、常用启动模板

模板 1: 最简单单模型聊天

模板 2: 类 LM Studio 的多模型 Router

模板 3: 类 LM Studio + TTL + 强制单模型驻留

模板 4: 本项目 Qwen3-ASR 服务

六、性能与资源建议

建议组合

七、常见问题

llama.cpp-参数详解.md 17 KB

고유링크 히스토리 Raw

4.4 `models-preset.ini` 的作用