# 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) 格式示例

```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文件` 组织。例如:

```text
%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 使用体验, 同时又能自动控显存的方案。

#### 推荐启动命令

```bat
"%LLAMA_BIN%\llama-server.exe" --models-dir "%USERPROFILE%\.lmstudio\models" --models-preset "%CD%\models-preset.ini" --models-autoload --models-max 1 --sleep-idle-seconds 300 --cache-ram 2048 --cache-idle-slots --port 18003 --host 127.0.0.1 -ngl auto -c 32768 --flash-attn auto --jinja
```

#### 这个组合为什么像 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 模式下缓存持续堆积 |

#### 推荐理解方式

- `--models-max 1` 解决的是“**同一时刻只驻留一个模型**”。
- `--sleep-idle-seconds 300` 解决的是“**空闲 300 秒后连这个唯一模型也卸载**”。
- 两者配合后, 行为就是:
  1. 收到请求时按需加载目标模型。
  2. 如果请求切换到另一个模型, 旧模型自动卸载。
  3. 如果 300 秒没有新请求, 当前模型也自动卸载。

这就是“尽可能像 LM Studio, 但支持闲时自动卸载”的核心配置。

### 4.3 单模型直连模式

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

#### 纯单模型聊天

```bat
"%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 自动卸载

```bat
"%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`

示例:

```ini
[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 一样按需切换。

```bash
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: 最简单单模型聊天

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

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

```bat
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 + 强制单模型驻留

```bat
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 服务

```bat
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` 更偏质量。