llama.cpp Parameter Optimizer

Complete methodology for local LLM performance optimization. Core principle: maximize context while fully covering GPU memory — find the sweet spot where GPU...

Security Scan

This is an instruction-only guide for tuning llama.cpp / llama-server parameters that is internally consistent with its stated purpose; it asks for no credentials or installs and does not attempt to access unrelated system data.

Purpose & Capability

The name/description match the instructions: the SKILL.md details how to run and benchmark llama.cpp / llama-server and which flags to test. Required artifacts (none) are proportional. Minor notes: the guide claims universal applicability to 'ALL models on ANY hardware' (hyperbolic — results will vary by hardware/model), and some examples target Windows (llama-server.exe) while others appear cross-platform. meta.json lists version 2.3.0 while SKILL.md/frontmatter and registry metadata show 3.0.0 — a benign inconsistency to verify.

Instruction Scope

Instructions are focused on local benchmarking and parameter testing (change one parameter at a time, record VRAM/tokens/s, example launch commands). The guide instructs running local binaries and binding localhost or a port (and warns about binding/production exposure). It does not direct the agent to read unrelated files, secret env vars, or exfiltrate data. Users must still take care: follow the guide's isolation advice and avoid exposing services to untrusted networks.

Install Mechanism

No install specification and no code files beyond documentation — lowest-risk format. The document recommends obtaining binaries from the official llama.cpp GitHub, which is appropriate. There is no download or extract declared in the skill itself.

Credentials

The skill declares no required environment variables, credentials, or config paths and the instructions do not request secrets. Parameter tuning and local command examples do not require cloud keys or unrelated credentials.

Persistence & Privilege

Skill is not always-enabled (always: false) and is user-invocable. It does not request persistent system presence or modify other skills' settings. Autonomous invocation is permitted by default but this is normal and not uniquely risky here.

Assessment

This is mainly a how-to document for local performance tuning; it appears coherent but take the following precautions before using it: 1) Download llama.cpp / llama-server binaries only from the official repository the guide cites and verify checksums if available. 2) Run tests in an isolated environment (not production) as the guide warns — parameter tweaks can cause OOM or crashes. 3) Do not expose bound ports to public networks; follow the guide's localhost/reverse-proxy + HTTPS advice. 4) Verify which OS the example commands target (Windows vs Linux) and adapt as needed. 5) Note the meta.json/version mismatch and the author/homepage are not strongly identified — if you need higher assurance, confirm the author's identity or seek corroborating guides or benchmarks. 6) Start with small models and backups before applying suggested parameters to large production deployments.

llama.cpp 启动参数优化技能 / llama.cpp Parameter Optimization Guide

中文 | English
标准化的 LLM 本地部署启动参数优化评估流程，通过严格的控制变量测试，找到最佳的性能/质量平衡点。
A standardized methodology for optimizing local LLM deployment parameters, using rigorous control variable testing to find the optimal performance/quality balance.

⚠️ 安全声明 / Safety Notice

• 本技能仅用于 本地部署 参数优化，所有测试应在隔离环境中进行。
• llama-server 和 llama.cpp 二进制文件应仅从官方 GitHub 仓库 (https://github.com/ggerganov/llama.cpp) 获取，避免使用第三方来源。
• 网络绑定安全：本地开发/测试时建议绑定 127.0.0.1（localhost），生产环境必须通过反向代理 + HTTPS 暴露服务。
• 参数调优可能触发 OOM 崩溃，不确定最优参数时，建议使用云端模型（如 OpenAI/Gemini）进行推理验证，本地只用于性能调优。
• 不要在生产环境中使用本技能提供的示例命令直接暴露服务，需根据实际安全需求调整。

🎯 核心卖点 / Key Features

• ✅ GPU 内存覆盖原则 / GPU Memory Coverage Principle：在完全使用专用 GPU 内存的前提下，找到最大上下文值 | Find max context while fully covering GPU memory
• ✅ 四阶段十步法控制变量测试 / 4-phase 10-step process：完整的性能/质量评估 | Comprehensive performance and quality evaluation
• ✅ 大量反常识踩坑经验 / Battle-tested counterintuitive findings：避免踩同样的坑 | Avoid common pitfalls
• ✅ 通用方法论 / Universal methodology：提供系统化测试框架，具体参数需结合实际硬件验证 | Provides a systematic testing framework; specific parameters must be validated against actual hardware.
• ✅ 实战验证 / Real-world proven：35B+4060Ti 实战案例：从 ~30 token/s → ~90 token/s，提升 2-3 倍 | 35B + 4060Ti real case: ~30 → ~90 token/s, 2-3x improvement

适用场景 / When to Use

中文 | English
新模型首次部署，需要找到最佳启动参数
First-time deployment of a new model, finding optimal launch parameters
新硬件环境下的性能调优
Performance tuning on new hardware
llama.cpp / llama-server 启动参数优化
llama.cpp / llama-server launch parameter optimization
验证量化损失、长上下文能力等核心特性
Verify quantization loss, long context capabilities, and other core features

---

完整评估流程 / Complete Methodology

4 phases, 10 steps

---

📊 第一阶段：基准建立 / Phase 1: Establish Baseline

步骤 1：建立初始基准 / Step 1: Run at default parameters

中文 | English
在默认参数下运行，记录基础性能数据：
Run with default parameters and record baseline performance:

✅ 记录项 / Metrics to record：
- 生成速度 / Generation speed (tokens/s)
- Prompt 处理速度 / Prompt processing speed (tokens/s)
- 显存占用峰值 / Peak VRAM usage (GB)
- 首字延迟 / Time to first token (ms)

步骤 2：枚举所有待测试参数 / Step 2: List all parameters to test

中文 | English
列出所有可能影响性能的参数：
List all parameters that may affect performance:

参数 / Parameter	典型测试值 / Typical values
--threads	4 / 8 / 12 / 16 / CPU 核心数
-b / --batch-size	512 / 1024 / 2048 / 4096
--ctx-size	重要！优先测试！先找甜点阈值，再测其他参数
--flash-attn	on / off
--cache-type-k/v	不量化 / q8_0 / q4_0
--parallel	1 / 2 / 4
--ubatch-size	256 / 512 / 1024

---

⚡ 第二阶段：控制变量性能测试 / Phase 2: Control Variable Testing

步骤 3：逐个参数控制变量测试 / Step 3: Test one parameter at a time

中文 | English
核心原则：每次只改一个参数，其他所有参数保持基准不变！
Core principle: Change only ONE parameter each time, keep ALL others at baseline!

❌ 错误做法 / Wrong way：链式修改，改完线程改上下文，再改 FA，结果混在一起无法归因
Chain modification - change threads, then context, then FA - results can't be attributed
✅ 正确做法 / Correct way：每次测试都回到基准配置，只改一个参数
Return to baseline config for each test, change only one parameter

步骤 4：建立性能对比矩阵 / Step 4: Build comparison matrix

⚠️ 重要反常识发现 / Critical Counterintuitive Findings

• ❌ --parallel 2 不一定好 / Not always good：在 4060Ti + 35B 组合上，单请求速度反而下降 40%，调度开销超过了并发收益
  On 4060Ti + 35B Dense, parallel=2 slows single request by 40% - scheduling overhead exceeds concurrency benefit
• ✅ --flash-attn on 对长 Prompt 影响巨大 / Huge impact on long prompts：开启前 300-500 token/s，开启后 1858 token/s，快了 3-5 倍
  300-500 → 1858 token/s, 3-5x faster, but only ±5% effect on regular generation
• ❌ KV 缓存激进量化不一定好 / Aggressive KV quantization not always good：q4_K 在某些版本的 llama.cpp 上会导致模型加载速度极慢，优先用 q8_0
  q4_K can cause extremely slow loading on some llama.cpp versions - prefer q8_0

中文 | English
每个参数测试完成后，记录完整的对比表：
After each parameter test, record complete comparison table:

示例：线程数对比 / Example: Thread count comparison

线程数 / Threads	生成速度 / Gen Speed	Prompt 速度 / Prompt Speed	变化 / Change	推荐 / Recommend
8	84.8	80.0	基准 / Baseline	🏆 最佳 / Best
12	83.1	70.2	-2.0%
16	83.5	75.0	-1.5%

---

🎯 优先测试：GPU 内存甜点阈值 / Priority: GPU Memory Sweet Spot

MUST DO first - highest ROI optimization!

中文 | English
这是所有优化里性价比最高的一项，通常能白嫖 50-100% 的速度提升，零质量损失！
This is the highest ROI optimization you can do - typically 50-100% speed boost with ZERO quality loss!

背景 / Background

中文 | English
几乎所有模型+显卡的组合，都存在一个断崖式的性能阈值：
Almost every model + GPU combination has a cliff-like performance threshold:

• ✅ 阈值以下：GPU 跑满，速度达到理论最大值
  Below threshold: GPU fully utilized, maximum theoretical speed
• ❌ 阈值以上：速度直接腰斩（40-60%），但显存只多占了 30-50MB
  Above threshold: Speed drops by 40-60% (half speed), but VRAM only increases 30-50MB

这不是线性下降，是跳崖式下降！原因通常是：
This is NOT a linear degradation, but a cliff! Common causes:

1. GDDR 显存 Bank 对齐边界，跨 Bank 访问延迟翻 3-5 倍
   GDDR memory bank alignment - cross-bank access latency increases 3-5x
2. FlashAttention 的 Tile 块大小阈值，超过之后触发缓存换页
   FlashAttention tile size threshold - exceeding triggers cache swapping
3. 大页内存分配失败，TLB 命中率骤降
   Large page memory allocation failure - TLB hit rate plummets

标准测试方法 / Standard Testing Method

中文 | English

1. 从厂商标称的最大上下文开始 / Start from manufacturer's advertised maximum（比如 128K）
2. 每次降 4K / Reduce by 4K each time（必须是 2 的幂次相关步长 / Must be power-of-2 aligned）
3. 每次都跑一次完整测速（生成 600 token 左右） / Run full speed test each time (~600 tokens)
4. 找到 速度突然跳涨的那个点 / Find the point where speed suddenly jumps，就是你的黄金甜点阈值 / That's your sweet spot!

典型测试结果示例 / Typical Test Results

Qwen3.6-35B + RTX 4060Ti 16GB

上下文大小 / Context	生成速度 / Speed	显存占用 / VRAM	状态 / Status
122880 (120K, 默认)	~30 token/s	~15.2 GB	❌ 内存紧张
118000 (118K)	~29-36 token/s	~15.1 GB	❌ 内存紧张
110000 (110K)	~90 token/s	~15.0 GB	✅ 满速
96K	~86 token/s	~14.5 GB	✅ 满速
64K	~88 token/s	~14.0 GB	✅ 满速

核心结论 / Key Takeaways

中文 | English

• 通常甜点阈值 = 厂商标称最大值的 90-95%
  Typically sweet spot = 90-95% of advertised maximum
• 上下文只少 5-10%（完全感知不到），速度提升 50-100%
  Only 5-10% less context (completely unnoticeable) for 50-100% speed boost
• 这一步必须第一个做！ 所有后续参数测试都应该在甜点阈值下进行
  DO THIS FIRST! All subsequent parameter testing should be done at the sweet spot

---

✅ 第三阶段：质量验证

步骤 5：量化损失验证

对比开/关量化的输出质量，使用相同的 Prompt + 温度=0.1 最小化随机性：

测试方法：
1. 关 KV 量化（FP16），输出结果 A
2. 开 KV q8_0 量化，相同 Prompt，输出结果 B
3. 人工对比 A 和 B，判断是否有可感知的质量损失

步骤 6：上下文回忆能力测试

使用「密钥召回法」验证长上下文能力：

测试方法：
1. 构造长 Prompt：前面是大量无关填充文本
2. 在 Prompt 的 10% / 50% / 90% 位置分别藏一个随机密钥
3. 问模型：「文档中的秘密密钥是什么？」
4. 记录不同距离的召回成功率

典型测试距离：

• 短距离：~1000 token
• 中距离：~20000 token
• 长距离：~50000 token（根据最大上下文调整）

步骤 7：基本能力冒烟测试

验证模型的基础能力没有因为参数调整而下降：

测试用例：
1. 简单数学题：小明有5个苹果，给了小红2个，又买了3个，现在有几个？
2. 简单逻辑题：正方形边长4cm，面积是多少？
3. 简单代码题：用Python写一个函数求列表偶数的和

---

🎯 第四阶段：综合评估与产出

步骤 8：多维度综合评分

维度	权重	评分标准（10分制）
性能	50%	生成速度(30%) + Prompt速度(20%)
质量	40%	量化损失(15%) + 上下文回忆(15%) + 基本能力(10%)
稳定性	10%	启动成功率、运行稳定性、API兼容性

步骤 9：反常识发现总结

必须记录所有反直觉的结论！ 这些是最有价值的经验：

示例（来自 Qwen3.5-MoE 实战）：

1. ❗ 默认 batch size 是 512，改成 2048 直接快 67.7%！
2. ❗ KV q8_0 量化不是损失，反而让 Prompt 处理快了 128%！
3. ❗ Flash Attention 对 MoE 模型：生成慢 1.3%，但 Prompt 快 128%，整体收益巨大！
4. ❗ 线程不是越多越好：8 线程比 12/16 都快！
5. ❗ 链式测试会严重误导结论：必须严格控制变量！

步骤 10：产出最终最佳配置

最终输出：

1. ✅ 最佳性能配置（最快速度）
2. ✅ 最佳上下文配置（最大窗口）
3. ✅ 综合推荐配置（平衡最佳）
4. ✅ 一键启动的完整命令

---

实战案例合集

---

案例1：Qwen3.5-MoE 35B + RTX 4060Ti 16GB（MoE 模型，仅供参考）

优化成果

初始速度：23.4 tokens/s → 最终速度：84.8 tokens/s，提升 262%！

最佳参数

参数	最佳值	收益
--threads	8	+2.4%
-b / --batch-size	2048	+67.7% 最大提升！
--ctx-size	65536（最快）或 262144（最大）	64K 比 256K 快 3.7 倍
--flash-attn	on	Prompt +128%，生成 -1.3%
--cache-type-k/v	q8_0	Prompt +128%，省 512MB，零质量损失
--parallel	2	Prompt 最快，支持 2 并发
--ubatch-size	默认 512	改了反而慢 17-60%

---

案例2：Qwen3.6-35B Dense + RTX 4060Ti 16GB（Dense 模型，2026-04-26 最新测试，仅供参考）

优化成果

初始速度：~30 tokens/s → 最终速度：~90 tokens/s，提升 2-3 倍！

📋 验证方法：

# 标准 curl 测速命令（固定 temperature=0.7, max_tokens=100）
curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"请写一段500字左右的技术博客文章，讨论本地部署大语言模型的性能优化方法"}],"max_tokens":100,"temperature":0.7}'

⚠️ 关键原则：GPU 内存覆盖就是生命线

"GPU 内存就是生命线，够用就快，不够用就慢。"

公式：最大上下文 = (GPU VRAM - 模型权重 - 安全缓冲) ÷ KV 缓存每 token开销

以 RTX 4060Ti 16GB + Qwen3.6-35B 为例：

• 模型权重 ~13.4GB | KV缓存(ctx 110K) ~1.1GB | 计算缓冲 ~0.5GB | 总计 ~15GB
• 留出 ~1GB 缓冲，ctx-size=110000 是安全甜点

核心发现：GPU 内存覆盖原则

上下文	速度	状态
122880 (120K)	~30 token/s	❌ GPU 内存不足
118000 (118K)	~29-36 token/s	❌ GPU 内存不足
110000 (110K)	~90 token/s	✅ GPU 完全覆盖
96K / 64K / 32K	~86-88 token/s	✅ 满速

减少 8% 上下文，速度提升 2-3 倍，零质量损失！

GPU 内存分析 / GPU Memory Analysis:

项目 / Item	占用 / Usage
模型权重	~13.4 GB
KV 缓存 (ctx 120K)	~1.2 GB
计算缓冲区	~0.5 GB
总计	~15.2 GB
GPU 总 VRAM	16 GB
剩余	~0.8 GB

最佳参数

参数	最佳值	说明
--ctx-size	110000（110K）	GPU 完全覆盖，速度最快
--threads	8	最佳
-b / --batch-size	2048	最佳
--parallel	1	❗ Dense 模型上 parallel=2 反而慢 40%
--flash-attn	on	必须开，长 Prompt 处理快 3-5 倍
--cache-type-k/v	q8_0	q4_K 有兼容性问题

最终最佳启动命令（Qwen3.6-35B Dense + 4060Ti，110K 甜点阈值）

# Linux/WSL2（推荐，绑定到 localhost）
llama-server -m "你的模型路径.gguf" --n-gpu-layers 9999 --ctx-size 110000 --port 8080 --host 127.0.0.1 --threads 8 --mlock --parallel 1 --kv-unified --flash-attn on -b 2048 --cache-type-k q8_0 --cache-type-v q8_0

# 如果需要 CPU 亲和性绑定（+5% 左右）
taskset -c 0-7 llama-server -m "你的模型路径.gguf" --n-gpu-layers 9999 --ctx-size 110000 --port 8080 --host 127.0.0.1 --threads 8 --mlock --parallel 1 --kv-unified --flash-attn on -b 2048 --cache-type-k q8_0 --cache-type-v q8_0

⚠️ 生产环境建议：如需对外提供服务，应通过 Nginx/Caddy 等反向代理 + HTTPS，不要直接暴露 llama-server。

进阶：CPU 亲和性绑定（+1-5% 速度，聊胜于无）

Linux/WSL2 下可以用 taskset 把线程绑到同一物理核心簇上，减少跨核通讯开销：

taskset -c 0-7 llama-server ...

注意：核心范围要和你的 --threads 参数对应，不要跨 CCX 模块。

⚠️ 安全提示：此功能仅在 Linux/WSL2 下可用，Windows 下无等效命令。

---

核心原则

1. GPU 内存覆盖优先：在完全使用专用 GPU 内存的前提下，找到最大上下文值 — 这是提升速度最快的优化
2. GPU 内存就是生命线：够用就快，不够用就慢（GPU↔CPU 交换是最大性能杀手）
3. 甜点公式：最大上下文 = (GPU VRAM - 模型权重 - 安全缓冲) ÷ KV 缓存每 token 开销
4. 控制变量高于一切：每次只改一个参数，其他全部保持不变
5. 不要只看生成速度：Prompt 处理速度同样重要，甚至更重要
6. 量化不一定是损失：有时候反而更快，一定要实际测试
7. 默认参数通常很保守：一定要测试更大的 batch size、不同的线程数
8. 不同模型结论不同：MoE 和 Dense 模型的最佳参数可能完全相反，不要经验主义

---

快速检查清单

每次优化前过一遍：

• 已记录默认参数下的基准速度
• 已列出所有待测试的参数
• 每次测试只改一个参数
• 已验证量化损失（如果开了量化）
• 已测试长上下文回忆能力
• 已做基本能力冒烟测试
• 已记录所有反常识的发现
• 已产出最终的一键启动命令

安全与调试建议

参数调试安全指南

1. 小步测试：每次调整幅度不超过 10%，避免 OOM
2. 监控显存：使用 nvidia-smi 实时观察，确保不突破 GPU 上限
3. 崩溃自救：如果模型频繁崩溃，尝试减小 --ctx-size 或 --batch-size
4. 云端辅助调试：当本地模型因参数不当反复崩溃时，建议使用云端模型（OpenAI / Gemini / 通义千问等）进行推理验证和逻辑测试。本地环境只用于性能调优，不用于逻辑正确性验证
5. 参数记录：所有测试参数必须记录，避免重复试错
6. 避免生产配置泄露：不要在公网文档、代码仓库中暴露 llama-server 的内部参数

反常识发现总结

必须记录所有反直觉的结论！ 这些是最有价值的经验：

示例（来自 Qwen3.5-MoE 实战）：

1. ❗ 默认 batch size 是 512，改成 2048 直接快 67.7%！
2. ❗ KV q8_0 量化不是损失，反而让 Prompt 处理快了 128%！
3. ❗ Flash Attention 对 MoE 模型：生成慢 1.3%，但 Prompt 快 128%，整体收益巨大！
4. ❗ 线程不是越多越好：8 线程比 12/16 都快！
5. ❗ 链式测试会严重误导结论：必须严格控制变量！

💡 重要提醒：不同模型、不同量化版本的最佳参数差异可能很大。不要直接套用他人参数，必须实际测试。如果本地模型因参数设置不当频繁崩溃，可先用云端模型做逻辑验证，本地只用于性能调优。