本地大模型跑Agent卡顿？调低num_gpu是关键

一个被忽视的本地模型调优参数

在本地部署大语言模型（LLM）时，许多开发者会遇到一个令人困惑的现象：模型在简单对话中表现良好，但一旦放进Agent框架（agent harness）中执行多步任务，性能就明显下降，甚至频繁出错或直接崩溃。

所谓Agent框架，是指一种让大语言模型具备自主行动能力的软件架构。与简单的一问一答不同，Agent框架允许模型调用外部工具（如搜索引擎、代码执行器、API接口）、进行多步推理、维护任务状态，并根据中间结果动态调整下一步行动。典型的Agent框架包括LangChain的AgentExecutor、AutoGPT、CrewAI等。在这种架构下，每一轮交互都会将之前的工具调用结果、思考链（Chain-of-Thought）和系统指令累积进上下文窗口，导致token消耗量远超普通对话场景。

最近一位Reddit用户分享了自己的经历，引发了社区的广泛共鸣。他表示："为什么没人早点告诉我，调低 num_gpu 竟然能让模型在Agent框架里跑得更好。我为了在本地跑模型折腾了好几个月，把 num_gpu 调低之后，我的 Hermes 模型终于能在我现有的硬件上正常工作了。"

reddit source: Num_gpu

这里提到的Hermes是由NousResearch团队开发的经过指令微调的开源大语言模型系列。它以出色的函数调用（Function Calling）和工具使用能力著称，特别适合Agent场景。Hermes模型通常基于Llama、Mistral等基座模型进行微调，使其能够准确解析结构化的工具调用指令并生成符合格式要求的输出。正因为Hermes专为Agent场景设计，它对上下文窗口的利用率极高，这也解释了为什么显存管理对于该模型尤为关键。

这个看似简单的发现，背后其实牵涉到本地推理引擎（尤其是 Ollama / llama.cpp 生态）中一个容易被误解的参数机制。

num_gpu到底控制什么

不是GPU数量，而是分层卸载

首先需要澄清一个常见误解：在 Ollama 和 llama.cpp 中，num_gpu 并不是指"使用几张显卡"，而是指将模型的多少层（layers）卸载到GPU上运行。这个参数在 llama.cpp 中对应的是 -ngl（number of GPU layers）。

llama.cpp是由Georgi Gerganov开发的开源C/C++推理引擎，专门针对Meta的LLaMA系列模型及其衍生模型进行了优化。它的核心创新在于支持模型量化和CPU/GPU混合推理，使得大语言模型能够在消费级硬件上运行。Ollama则是在llama.cpp基础上构建的高层封装工具，提供了类Docker的模型管理体验，用户可以通过简单命令拉取、运行和配置模型。两者共享底层的分层卸载（layer offloading）机制，即允许用户指定将模型的哪些Transformer层放在GPU上计算，其余层则回退到CPU执行。

当 num_gpu 设得很高（比如等于模型总层数），意味着尽可能多的层被放进显存里加速计算；
当设得较低时，一部分层会留在CPU和系统内存中运行。

直觉上，把更多层放到GPU应该更快才对。那么为什么调低反而让Agent任务跑得更顺？

显存耗尽引发的连锁问题

关键在于上下文长度（context window）。Agent框架与普通聊天有本质区别：它需要处理系统提示、工具定义、多轮对话历史、中间推理步骤等，上下文往往轻松突破数千甚至上万token。

上下文越长，KV Cache（键值缓存）占用的显存就越大。KV Cache是Transformer架构推理时的关键优化机制。在自回归生成过程中，模型每生成一个新token都需要对之前所有token执行注意力计算。如果不做缓存，每一步都需要重新计算所有历史token的Key和Value矩阵，计算量随序列长度呈二次增长。KV Cache的做法是将每一层注意力机制中已计算过的Key和Value向量缓存起来，后续生成时直接复用。其显存占用公式大致为：2 × 层数 × 注意力头数 × 头维度 × 序列长度 × 精度字节数。例如一个32层、32头、128维的模型在处理8192个token时，FP16精度下KV Cache约占用2GB显存。在Agent场景中，由于上下文长度动态增长且通常达到模型上下文窗口的上限，KV Cache的显存占用会非常可观。

如果 num_gpu 设得过高，模型权重已经占满了显存，再加上膨胀的KV Cache，就会导致：

显存溢出（OOM）：推理直接失败或崩溃；
频繁的显存-内存交换：系统被迫在显存和内存间反复搬运数据，性能断崖式下跌。即使是PCIe 4.0 x16接口，其带宽也仅约32GB/s，而GPU内部的显存带宽通常在500GB/s到2TB/s之间（如RTX 4090约1TB/s）。这意味着一旦发生频繁交换，有效带宽会下降一到两个数量级，表现为推理速度从每秒数十token骤降到每秒几个token甚至更低；
输出质量下降：某些引擎在显存不足时会静默截断上下文，导致模型"失忆"，Agent行为变得混乱。

把 num_gpu 调低后，给KV Cache留出了充足的显存空间，反而让整个推理流程稳定下来——这正是那位用户的Hermes模型"终于能正常工作"的根本原因。

如何找到合适的num_gpu值

平衡模型权重与KV Cache的显存分配

本地推理的核心是一场显存争夺战，参与者主要有两方：模型权重 和 KV Cache。你需要为两者都留足空间。

实用的调优思路如下：

先用 nvidia-smi 或类似工具确认自己的显存总量；
估算模型权重占用（量化后的GGUF文件大小可作参考）；
预留出Agent场景所需的长上下文缓存空间；
从较低的 num_gpu 开始，逐步往上加，直到接近显存上限但不溢出。

举个具体例子：假设你有一张12GB显存的RTX 4070，想运行一个Q4_K_M量化的13B模型（权重约7.5GB），同时需要支持8192 token的上下文。KV Cache在这个配置下可能需要约2-3GB显存，再加上引擎本身的开销约0.5-1GB，总需求约11GB。如果把所有40层都卸载到GPU，权重就占满了空间，KV Cache无处安放。将层数降到30层左右（约5.6GB权重），则能为缓存留出充裕的余量。

结合量化与上下文设置协同调优

除了调 num_gpu，还有几个协同手段：

选择更激进的量化版本（如 Q4_K_M 而非 Q8），减小权重体积，腾出更多显存。GGUF格式支持多种量化方案，每种方案在模型大小、推理速度和输出质量之间做出不同的权衡。以一个70B参数的模型为例，FP16版本约需140GB存储，Q4_K_M量化后仅需约40GB，Q8版本则约70GB。选择更激进的量化意味着权重占用更少显存，从而为KV Cache留出更多空间；
合理设置 num_ctx：不要盲目开到最大上下文，够用即可，避免KV Cache无谓膨胀。许多引擎默认会预分配整个上下文窗口对应的KV Cache空间，即使实际用不到那么多。将 num_ctx 从32768降到8192，可能就省下数GB显存；
启用KV Cache量化（部分引擎支持），进一步压缩缓存占用。llama.cpp近期引入了Q8和Q4精度的KV Cache量化选项，可以在几乎不影响输出质量的前提下将缓存占用减半甚至降至四分之一。

通过这几者的组合，即使是消费级显卡也能撑起相对复杂的Agent工作流。

对本地AI开发者的启示

这个案例最值得反思的地方在于：本地模型部署的痛点，往往不在模型本身，而在于对底层参数机制的理解不足。

很多开发者像那位Reddit用户一样，花费数月与本地模型"搏斗"，怀疑是模型能力不行、硬件不够，却忽视了几个关键的运行时参数。社区文档对 num_gpu 这类参数的说明也常常语焉不详，加剧了误解。

对于希望在本地跑Agent的开发者，建议：

理解你的推理引擎参数：num_gpu、num_ctx、量化等级都会显著影响实际表现；
区分聊天场景与Agent场景：后者对上下文和稳定性的要求高得多，参数配置需要针对性调整。简单聊天可能只需要1000-2000 token的上下文，而Agent场景中系统提示本身可能就占2000-3000 token，加上工具定义、历史记录和推理步骤，8000-16000 token是常态；
善用社区经验：许多"隐藏技巧"并不写在官方文档里，而是散落在Reddit、Discord等社区讨论中。像LocalLLaMA这样的Reddit子版块、llama.cpp的GitHub Issues、以及各种Discord服务器中积累了大量实战调优经验。

随着本地LLM生态日益成熟，掌握这些调优细节，将是充分释放消费级硬件潜力的关键一步。有时候，让模型"跑起来"的答案，就藏在一个被低估的参数里。