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 → ~90 token/s，提升 2-3 倍；27B 案例：~23.6 tok/s，验证理论公式不可靠 | Multiple cases: MoE 262% boost, Dense 2-3x, 27B theoretical formula fails

适用场景 / 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:

⚡ 第二阶段：控制变量性能测试 / 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

🎯 优先测试：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

核心结论 / 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：多维度综合评分

步骤 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%！

最佳参数

案例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 内存覆盖原则

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

GPU 内存分析 / GPU Memory Analysis:

最佳参数

最终最佳启动命令（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

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

案例3：Qwen3.6-27B Dense + RTX 4060Ti 16GB（2026-04-28 最新测试）

⚠️ 模型说明：Qwen3.6-27B 是 Qwen3.6-35B 的更轻量版本，权重更小（~12GB vs ~13.4GB），但优化结论不完全相同！

优化成果

纯生成速度：~23.6 tok/s

核心发现（与 35B 不同之处）

1. 理论计算不可靠！实际测试才是王道

• 理论公式算出甜点 = 110K（(16GB - 12GB - 1GB缓冲) ÷ KV每token ≈ 110K）
• 实际测试 110K 直接 CUDA OOM
• 真实甜点：96K（实测稳定，18.6 tok/s）
• 结论：理论公式只能做起点参考，必须实际跑一遍才能确定

2. Batch Size 对 27B 的影响与 35B 相反

• 35B（Dense）：2048 最佳
• 27B（Dense）：512 最佳（2048 反而慢 6.6%）
• 原因：27B 权重更小，GPU 有更多余量处理小 batch 的缓存效率

3. 推理模型的思考开销是硬伤

• Qwen3.6-27B 是推理模型（reasoning mode），内置思考过程
• 简单问题（"写一句诗"）也要花 48 秒思考
• 思考阶段输出 800+ reasoning chunks，但 max_tokens 被思考占满后无法输出
• 如果不需要推理能力，换非推理版本（Qwen3.6-27B-Instruct 非推理版）体验更好

GPU 内存分析

最佳参数

最终启动命令

llama-server -m "Qwen3.6-27B-Q3_K_S.gguf" \
  --n-gpu-layers 9999 --ctx-size 96000 --port 8080 --host 127.0.0.1 \
  --threads 8 --threads-batch 8 --mlock --parallel 1 \
  --kv-unified --flash-attn on -b 512 \
  --cache-type-k q8_0 --cache-type-v q8_0

配套配置

llama-server 守护进程 (~/.config/systemd/user/llama-server.service)

[Service]
ExecStart=/home/fenglai/llama.cpp/build/bin/llama-server \
  -m /home/fenglai/models/Qwen3.6-27B-Q3_K_S.gguf \
  --n-gpu-layers 9999 --ctx-size 96000 --port 8080 --host 127.0.0.1 \
  --threads 8 --threads-batch 8 --mlock --parallel 1 \
  --kv-unified --flash-attn on -b 512 \
  --cache-type-k q8_0 --cache-type-v q8_0

OpenClaw 配置 (~/.openclaw/openclaw.json)

"contextWindow": 96000,
"maxTokens": 48000

⚠️ OpenClaw 的 contextWindow 必须与 llama-server 的 --ctx-size 保持一致，否则会导致上下文截断或 OOM。maxTokens 设为 ctx-size 的一半左右，给 prompt 留出空间。

OpenClaw 配置注意事项

• contextWindow 必须等于 --ctx-size（96000）
• maxTokens 建议设为 ctx-size / 2（48000），为 prompt 预留空间
• reserveTokensFloor（compaction 保留 token）建议设为 20000，避免频繁压缩
• 模型 reasoning: true 需开启，否则思考内容无法正确解析

进阶：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 开销，但实际测试才是唯一真理（27B 上公式算 110K，实际 96K 才是甜点）
4. 控制变量高于一切：每次只改一个参数，其他全部保持不变
5. 不要只看生成速度：Prompt 处理速度同样重要，甚至更重要
6. 量化不一定是损失：有时候反而更快，一定要实际测试
7. 默认参数通常很保守：一定要测试更大的 batch size、不同的线程数
8. 不同模型结论不同：MoE 和 Dense 最佳参数可能完全相反；同系列不同大小（27B vs 35B）的 batch size 最优值也可能相反
9. 推理模型的思考开销：Qwen3.6 等推理模型内置 thinking chain，TTFT 极长（40-50s），不适合需要低延迟的对话场景
10. OpenClaw 配置必须对齐：contextWindow 必须等于 --ctx-size，maxTokens 约等于 ctx-size / 2，否则上下文异常

快速检查清单

每次优化前过一遍：

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

安全与调试建议

参数调试安全指南

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

反常识发现总结

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

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

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. ❗ 链式测试会严重误导结论：必须严格控制变量！

示例（来自 Qwen3.6-27B Dense 实战，2026-04-28）：

1. ❗ 理论计算不可靠：公式算出 110K 甜点，实际 110K 直接 CUDA OOM，真实甜点 96K。必须实测！
2. ❗ Batch size 结论因模型而异：35B Dense 上 2048 最优，27B Dense 上 512 反而快 6.6%。不要照搬！
3. ❗ 推理模型有思考开销：Qwen3.6 内置推理链，简单问题也要 40-50 秒 TTFT，不适合日常对话
4. ❗ threads-batch 影响：--threads-batch 8 比默认 1 提升 prompt 处理速度
5. ❗ OpenClaw contextWindow 必须匹配：配置里的 contextWindow/maxTokens 要跟 --ctx-size 对齐，否则上下文异常

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