跳转到主要内容
llama.cpp 是便携性最强的本地推理运行时。它可以在 CPU、NVIDIA GPU、AMD GPU 和 Apple Silicon 上运行 —— 通常使用同一个二进制文件。这种灵活性伴随着大量的命令行参数，而默认值并不总是最适合你的硬件。本指南介绍最重要的参数以及每个参数背后的权衡。
最后验证：2026-10-14 —— llama.cpp build b11609。
本指南中的所有参数适用于 llama-server 和 llama-cli（llama.cpp build b11609，十月 14 日，2026 年）。参数名称可能在不同 build 之间发生变化 —— 运行 llama-server --help 确认你的二进制文件支持哪些参数。

​
Flash attention

使用 -fa 或 --flash-attn on 启用 flash attention。在大多数基准测试中，这是 llama.cpp 提供的最接近免费性能提升的选项 —— 你可以用相同或更少的内存获得更快的推理速度，质量损失几乎可以忽略不计。
Flash attention 改变了模型计算 token 之间注意力分数的方式。它不再将整个注意力矩阵加载到内存中，而是以适合快速 SRAM 的分块方式计算注意力。结果是：
  • 更低的 KV 缓存内存占用 —— 在长上下文长度时收益最大。
  • 更快的推理速度 —— 尤其在 GPU 上，分块计算可以很好地映射到 tensor core。
  • 相同的输出质量 —— flash attention 在数学上等价于标准注意力，不是近似计算。
始终以 -fa 开头。 除非遇到特定模型或平台的兼容性问题，否则没有理由不启用它。这是本指南中影响最大的单一参数。

​
mmap 与 mlock

llama.cpp 使用 2 种策略将模型权重加载到内存中。默认策略是 --mmap，它将模型文件直接映射到进程的虚拟地址空间。另一种策略是 --mlock，它将整个模型锁定在物理内存中。

​
mmap 的优势

--mmap 是默认选项，因为它适用于大多数交互式使用场景。操作系统按需加载模型页面，因此启动速度快，在实际访问页面之前模型文件不会重复占用内存。如果你在测试模型或运行短时会话，默认值就足够了。

​
mlock 的优势

--mlock 阻止操作系统将模型页面换出到交换空间。这在以下情况下很重要：
  • 你全天运行同一个模型并希望获得一致的延迟 —— 没有页面错误导致的冷启动惩罚。
  • 你的系统受到其他进程的内存压力，可能会换出模型权重。
  • 你使用的机器交换空间很慢（或没有交换空间），页面错误会导致推理停滞数秒。
--mlock 要求整个模型能放入可用的物理内存。如果放不下，进程将无法启动。启用前请在 Linux 上使用 free -h 或在 macOS 上使用活动监视器检查可用内存。

​
线程调优

参数 -t 设置用于推理的 CPU 线程数。正确的值取决于 CPU 实际承担的工作量。
线程越多并不总是越快。超过物理核心数后，线程会争抢缓存和内存带宽，反而会拖慢推理速度。不确定时，从物理核心数开始基准测试。
在 Apple Silicon 上，线程调优的重要性较低，因为 GPU 和 CPU 共享统一内存，Metal 后端会处理调度。默认值通常就能很好地工作。

​
GPU 卸载策略

参数 -ngl 控制你将多少模型层卸载到 GPU。GPU 上的层越多，推理速度越快，但每层都会消耗显存。

​
部分卸载

将 -ngl 设为你能放入 GPU 内存的层数。剩余的层在 CPU 上运行。
当整个模型无法放入显存时，使用部分卸载。从一个较高的值开始，逐步降低直到服务器启动且不内存溢出。

​
完全卸载

设置 -ngl 999 卸载每一层。llama.cpp 将 999 理解为”所有剩余层” —— 它并不会真的尝试卸载 999 层。
完全卸载提供最佳的推理速度，因为每次前向传播都在 GPU 上运行。模型权重和 KV 缓存都必须放入显存。

​
每层内存预算

每个卸载的层同时为权重和 KV 缓存消耗显存。粗略估算：
对于 7B 模型使用 Q4_K_M（每权重约 4.5 位，约 40 层）： 预留 1-2 GB 显存余量用于 CUDA 上下文和开销。

​
批处理大小调优

两个参数控制 llama.cpp 在预填充阶段一次处理多少 token：

​
两者的交互关系

  • -b 设定外部上限。如果提示词的 token 数超过 -b，llama.cpp 会将其拆分为多个批次。
  • -ub 设定内部分块大小。llama.cpp 以最多 -ub 个 token 的微批次处理该批次。
  • -ub 必须小于或等于 -b。

​
权衡

对于短提示词（1K token 以下）的交互式聊天，默认的 -b 512 就足够了。只有当你经常摄入长文档并希望更快的首 token 时间时才增大它。

​
KV 缓存精度

KV 缓存存储每个活跃序列中每个 token 的键和值张量。默认情况下，llama.cpp 对键和值都使用 f16（16 位浮点数）。你可以切换到量化精度以较小的质量代价降低内存占用。
你可以独立设置键和值的精度。常见模式是两者都使用 q8_0，这在大多数基准测试中将 KV 缓存占用减半，质量差异不到 1%。
q4_0 KV 缓存在依赖长上下文精确注意力的任务中会带来可衡量的质量损失 —— 大海捞针检索、多文档摘要和长对话。在决定使用 q4_0 之前，请先针对你的具体工作负载进行测试。

​
MoE 优化

混合专家模型（如 Qwen3.5-35B-A3B 或 Mixtral）在每一层存储大量专家子网络，但每个 token 只激活其中少数几个。专家权重即使不活跃也仍然驻留在内存中，这使得 MoE 模型相对于其活跃参数规模而言占用过大。 在多 GPU 系统上，当显存紧张时，你可以将专家层放在 CPU 上：
--n-cpu-moe <num> 将指定数量的专家子层保留在 CPU 上，而模型的其余部分在 GPU 上运行。这是以增加少量延迟为代价来适配更大的模型。
从 --n-cpu-moe 0（所有专家在 GPU 上）开始，仅在显存不足时才增加。每个移到 CPU 的专家都会增加延迟，因为数据在前向传播期间必须跨越 PCIe 总线。

​
示例配置

​
Apple Silicon —— M 系列 Mac 优化

这将模型锁定在统一内存中，启用 flash attention，并量化 KV 缓存以充分利用内存预算。Apple Silicon 的统一内存意味着 GPU 可以访问整个内存池，因此只要模型和 KV 缓存放得下，完全卸载（-ngl 999）就能工作。
llama.cpp 在 Apple Silicon 上运行良好，但如果你专门在 Mac 上部署，MLX 针对 Apple 的 Metal 后端进行了优化，可能对同一模型提供更快的推理。当你需要跨平台可移植性或 OpenAI 兼容服务器时，使用 llama.cpp。

​
GPU 卸载 —— NVIDIA 或 AMD 独立 GPU

完全 GPU 卸载，配合 flash attention 和量化 KV 缓存。4 个 CPU 线程处理编排和分词。如果模型放不下，降低 -ngl —— 从总层数开始，每次减少 5 直到能加载。

​
纯 CPU —— 无 GPU

没有 GPU 卸载，所以 CPU 承担所有工作。线程数匹配物理核心数。较小的批处理大小保持内存占用可控。对模型权重使用 Q4_K_M 或 Q5_K_M 量化以保持较小的占用。

​
后续步骤

llama.cpp 远程访问

通过 Tokios 将你的 llama.cpp 服务器暴露给团队成员和代理 —— 无需开放端口。

推测解码

使用草稿模型、n-gram 和 EAGLE 加速解码 —— 适用于 llama.cpp 后端。

测试你的部署

调优后测量延迟和吞吐量以确认改进效果。

KV 缓存与上下文

深入解释 KV 缓存如何在不同模型架构和运行时中工作。