这两年端侧 Agent 的热度一直没降和以往那种“云上大脑”的做法不同现在越来越多人想把整个链路压到一块本地设备上。我自己也花了很长时间折腾各种开发板和推理框架最后发现真正决定体验的往往不是哪家模型跑分多高而是部署时你有没有把硬件、量化、上下文和 Agent 调度这几件事想清楚。这篇文章就以端侧 LLM 部署为主线从硬件选型讲到 Ollama 实操再接到 Agent 接入尽量把关键环节的原理和坑都拆开说。适合正在做本地智能体的开发者也适合手里有 RK3588、Jetson Orin 等设备的硬件玩家参考。1. 端侧 LLM 部署到底在解决什么问题1.1 先弄明白“端侧 Agent”要什么端侧 Agent 和云端 Agent 最大的区别是它所有的关键模块都在本地。一个完整 Agent 通常需要大模型提供语言理解、规划、工具调用和记忆归纳能力但本地设备不是数据中心内存和算力都有限所以端侧 Agent 实际要的是一个“够用且可控”的推理底座。够用指的是模型能理解复杂一点的指令能调用工具能记住对话上下文可控则意味着模型权重、运行参数、推理缓存都在自己手里不依赖外部服务也不会因为服务波动导致整套系统瘫痪。这也就引出了端侧 LLM 部署的核心价值。首先是隐私个人数据、办公文档、摄像头画面这些敏感信息不需要离开设备Agent 可以全部在本地完成理解与处理。其次是确定性你部署的模型版本、量化参数、上下文长度完全由自己掌控不会出现云端模型偷偷换版本导致行为漂移的问题。最后是延迟端侧推理省去了网络往返一次工具调用的判断从几百毫秒压缩到几十毫秒这种低延迟对机器人控制、实时交互类 Agent 尤其重要。但这三个价值不是白来的。端侧模型因为体积受限通用知识储备和复杂推理能力通常弱于云端大模型所以你在设计端侧 Agent 时必须主动缩小任务范围把复杂任务拆成多个小步骤用外部工具补足模型能力。不要在 7B 模型上强行做一个什么都能聊的通用助手而是要让它老老实实当好“调度员”和“解析器”。1.2 三座大山内存、算力、功耗做过端侧部署的人都知道真正卡脖子的不是模型算法有多难而是硬件层面那三个硬指标内存、算力、功耗。内存决定模型上限。部署一个 7B 参数模型即使是 Q4 量化光权重就要占 4GB 左右推理时还要额外预留 KV Cache 和临时计算空间16GB 内存的设备跑 7B 模型基本就是“刚好够用”。内存不够时模型根本加载不进去或者被系统换入换出速度慢到无法接受。算力决定体验下限。这里的算力不能只看 INT8 峰值还要看内存带宽。模型推理本质上是反复读取参数权重做矩阵乘法如果内存带宽只有 30GB/s那 4.5GB 权重读一遍就要 0.15 秒理论上每秒生成上限也就 6-7 个 Token。很多板子参数表写得很唬人真跑起来却像老牛拉车问题多半就出在带宽上。功耗则决定应用场景。开发板放在桌面上一直插电无所谓但如果 Agent 要装到无人机、机械臂、AGV 小车里功耗和发热就是硬约束必须牺牲一部分性能换取续航。1.3 部署不是“把模型装上去”那么简单很多人第一次接触端侧 LLM 部署以为就是下载一个模型文件丢到板子里然后跑个推理脚本。实际做下来你会发现端侧 LLM 部署是四层工程的叠加模型压缩、格式转换、推理运行时、服务封装。模型压缩指量化、蒸馏、剪枝这些手段目的是把模型体积压到硬件能接受的范围格式转换决定模型以什么形态存储和加载比如 GGUF 格式对部署最友好推理运行时负责把模型高效地调度到底层芯片上执行服务封装则是向外提供标准 API让 Agent 框架可以稳定调用。四层缺一不可任何一层不匹配后面 Agent 接进来就会出现乱码、超时、工具调用失败这些稀奇古怪的问题。所以我把部署看作一个系统性的“适配工程”而不是单点操作。后面所有内容都围绕这四层展开。2. 硬件选型先算账再动手2.1 内存决定模型上限算力决定体验下限选硬件最常犯的错误是只看“能不能跑 GPT 级别的模型”我建议反过来先确定你的 Agent 需要什么规模的模型再倒推硬件配置。比如你要做的是本地知识库问答那 7B 模型加 RAG 方案就够如果要跑视觉语言 Agent不仅要考虑语言模型还要考虑视觉编码器占用的额外资源内存预算要往上调。有了目标模型规模后用经验公式算内存占用模型文件大小 上下文缓存 系统开销。7B 模型 Q4 量化后文件约 4.7GB如果上下文开 8192KV Cache 大约要额外 1-2GB再加上操作系统和 Agent 运行时16GB 设备实际可用内存最好不少于 8GB否则会很吃紧。算力方面则要关注推理加速单元的实际效果。Jetson 上的 GPU 和 CUDA 生态适配成熟llama.cpp、Ollama 都能直接利用RK3588 的 NPU 峰值很高但部署工具链相对碎片化很多时候你在板子上跑的还是 CPU 推理实际速度和标称 TOPS 完全是两回事。所以我建议把“实测 token/s”作为核心选型指标而不是跑分表。2.2 两张主流开发板的配置盘点我自己用得最多的是 Jetson Orin 系列和 RK3588 系列这两类板子在端侧 Agent 圈子里讨论度最高也最值得对比。Jetson Orin NX 16GB 是目前跑端侧 Agent 比较舒服的“甜点位”。它有 16GB LPDDR5 内存GPU 算力足够支撑 7B 甚至 14B 量化模型而且 CUDA 生态成熟绝大多数推理框架都是开箱即用。我做多模态 Agent 时视觉编码器加语言模型加载进去还能剩不少缓冲。缺点是价格贵而且散热做好以后体积还是偏大。RK3588 则是性价比路线的代表。常用版本板载 8GB 或 16GB 内存CPU 性能不错内置 NPU 在特定算子下能干活但模型部署时经常遇到算子兼容问题。我在 RK3588 上跑通 7B 量化模型更多是靠 CPU 推理速度比 Jetson 慢不少但它胜在便宜、接口丰富、功耗低适合做边缘网关类 Agent 或嵌入式原型验证。2.3 选型参数对比表为了让你一眼看清定位差异我整理了一张常用设备对比表按我实际体验标注价格会随行情波动仅供参考。设备内存有效算力推荐模型规模参考价格适用场景Jetson Orin NX 16GB16GB LPDDR5较强 GPU7B~14B 量化6000-8000元机器人、多模态 Agent、高质量对话Jetson Orin Nano 8GB8GB LPDDR5入门 GPU1.5B~4B 量化2000元左右入门验证、轻量 AgentRK3588 16GB16GB LPDDR4x6 TOPS NPUCPU4B~7B 低量化1300-2500元工控、边缘盒子、嵌入式原型Apple Silicon 16GB16GB 统一内存高带宽 GPU7B~14B 量化二手约5000元本地办公助手、开发调试老款 NUC 16GB16GB 双通道核显较弱7B 低量化2000-3000元服务器式常驻 Agent 服务选型时还有一个容易忽略的点内存通道数。单通道内存带宽减半对推理速度的拖累非常明显所以尽量选双通道或统一内存架构的设备。跑同一个小模型我在双通道设备上见过 2 倍的差距。3. 模型量化与格式转换3.1 量化原理用一点精度换运行可能量化这个词听起来很高级其实就是把模型里的浮点数权重从 16 位或 32 位压缩到 8 位、4 位用更少的比特表示同一个参数。你可以理解成把一本高清画册压缩成网页缩略图内存占用量直线下降画质有损失但大多数图还是能认得出来。对端侧来说量化直接决定你能不能跑得起某个模型。同样一个 7B 模型FP16 格式要占 14GB 左右绝大多数开发板直接劝退转成 Q4 量化后只需要 4-5GB16GB 内存设备就完全有机会跑起来。差别不是性能好坏而是“能不能开机”。不过量化带来的精度损失在 Agent 场景里会被放大。小模型经过量化后指令遵循能力会下降可能出现 JSON 输出格式不稳定、工具参数生成缺失、甚至完全忽略系统提示词的情况。所以我不建议一上来就使用压缩最狠的量化等级而是要留出余量。如果设备内存允许Q5、Q8 的稳定性通常会好一截。3.2 GGUF 与 llama.cpp 生态做端侧部署基本绕不开 GGUF 格式它是 llama.cpp 项目推出的模型封装格式。GGUF 把模型权重、分词器、超参数、甚至自定义的聊天模板都打包进一个文件里部署时只要加载这一个文件就能跑不需要分别处理权重和配置大大降低了集成成本。更关键的是 GGUF 支持分段保存和内存映射。分段保存方便你按资源限制加载模型的一部分内存映射则允许操作系统按需读取磁盘上的权重而不是一次性全载入内存这对小内存设备很友好。Ollama、llama.cpp、LM Studio 这些主流工具都原生支持 GGUF所以现在做端侧部署很少有人再手动转 PyTorch 权重了。自己动手转换其实也方便。先下载 HuggingFace 上的原版权重再用 llama.cpp 仓库里的convert_hf_to_gguf.py脚本转成 FP16 GGUF然后用量化工具压成目标等级。不过如果你不是要魔改模型直接用 Ollama 模型库或 HF 上现成的 GGUF 文件会更省事没必要重复造轮子。3.3 量化精度选择Q4_K_M、Q5_K_M、Q8_0量化等级不是越高越好要跟硬件内存和场景稳定性需求匹配。我用得最多的几个等级以 7B 模型为例整理如下量化等级近似模型大小质量表现适用场景Q4_K_M4.7GB均衡工具调用基本可用大多数端侧 Agent 首选Q5_K_M5.6GB更稳指令遵循更好内存有余量时优先Q8_07.2GB接近无损开发调试、效果对比IQ4_XS4.0GB压缩激进质量下降明显内存实在不够时的兜底绝大多数端侧项目我会从 Q4_K_M 起步。它的体积控制合理DPO 过的模型在 Q4 下工具调用能力通常不会断崖式下降。如果你发现模型在复杂指令或 function calling 上频繁出错再往上升一档到 Q5_K_M先不要怀疑代码很多“玄学”问题其实是量化精度引起的。3.4 Token 与 KV Cache 的基础认知部署过程中很多人对 Token 的概念含糊。Token 不是字符而是模型处理的最小文本单元可能是词、词根或几个字符的组合。模型一次生成多少个 Token直接对应它的处理粒度。这也是为什么同样一段中文不同分词器消耗的 Token 数可以相差很大。在 Agent 场景里工具定义和系统提示会占用大量 Token。比如你给模型绑定了 5 个函数每个函数带参数描述和示例光工具定义就可能吃掉几百个 Token留给真实对话的上下文余量就少了。这个“隐性成本”常被忽略等 Agent 聊到一半突然“失忆”排查半天才发现是上下文被工具描述塞满了。KV Cache 则是推理过程中缓存历史计算结果的显存区域长度随上下文窗口线性增长。你设num_ctx8192KV Cache 占用就比 2048 大四倍。在端侧设备上上下文窗口不是想开多大就多大内存换不来就卡死给你看。所以部署时先定一个较小的上下文再按实际需要逐步调大比较稳妥。4. Ollama 本地部署实操4.1 安装、拉取模型、基本参数Ollama 是目前端侧部署最省心的工具它把模型下载、格式转换、运行时加载、API 服务全部封装好了新手不用懂底层细节就能把模型跑起来。安装命令很简单Linux 下一条脚本macOS 用 HomebrewWindows 有安装包没什么好纠结的。curl -fsSL https://ollama.com/install.sh | sh装完以后拉模型就像拉 Docker 镜像一样方便。我用 Qwen2.5 系列的 7B 量化版本做主力原因是它中文支持好官方仓库直接就有 Q4_K_M 分片不用自己折腾转换。ollama pull qwen2.5:7b-q4_K_M ollama run qwen2.5:7b-q4_K_M第一次运行会自动加载模型之后再把模型常驻在内存里推理速度会快很多。这里有个小经验刚装完 Ollama 先不要急着调参数用默认配置跑一遍简单的对话把基线数据记下来后面优化才有参照。4.2 上下文与运行参数调优默认配置下 Ollama 的上下文窗口经常不够用Agent 场景里尤其明显。你可以通过环境变量设置默认上下文长度也可以在运行时通过/set parameter临时调整。我的习惯是先在启动服务时设好一个基础值然后在代码层按任务类型覆盖。OLLAMA_CONTEXT_LENGTH4096 OLLAMA_NUM_PARALLEL1 ollama serve模型温度默认是 0.8这个值对创意写作没问题但对 Agent 来说太高了。工具调用和 JSON 输出要求确定性温度太高模型很容易“发挥想象力”生成出格式乱七八糟的字段。我在 Agent 场景基本会把温度压到 0 或 0.1同时把top_p相应调低让模型尽量走更稳的生成路径。还有一个容易踩坑的点CPU/GPU 混合加载。Ollama 检测到显存或内存不足时会自动把一部分层放到 CPU 跑这会导致性能骤降。在 Jetson 这类统一内存的设备上没有这个问题但在 NUC 或一些老平台上最好手动指定层数避免全部往 CPU 上塞。4.3 开放 OpenAI 兼容接口Ollama 从较新版本开始自带 OpenAI 兼容端点/v1/chat/completions可以直接复用现有 Agent 框架不用改代码就能把模型接进去。这个设计非常聪明等于把所有依赖 OpenAI SDK 的上层应用全部平移过来。from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:11434/v1, api_keyollama, ) chat client.chat.completions.create( modelqwen2.5:7b-q4_K_M, messages[ {role: system, content: 你是一个本地智能体助手只输出 JSON 格式结果。}, {role: user, content: 帮我查一下今天有哪些定时任务需要执行。}, ], temperature0, ) print(chat.choices[0].message.content)如果你的 Ollama 版本没有/v1端点及时升级版本基本就能解决。实在跑在老版本上也可以用 FastAPI 包一层把/api/chat的响应映射成 OpenAI 的字段结构。但说实话直接用新版 Ollama 是性价比最高的路。局域网内需要给其他设备提供模型服务时设置OLLAMA_HOST0.0.0.0:11434即可这样同一网络下其他设备能通过 HTTP 调用。不过要注意尽量不要把端口直接暴露到不可信网络环境毕竟 Ollama 本身没有完整的访问认证体系。5. 端侧 Agent 的接入与编排5.1 从 LLM 到 Agent工具调用的坑单纯把模型跑起来只是第一步真正让它成为 Agent还得把工具调用链路打通。LLM 本质上是一个“下一词预测”引擎它并不知道什么叫“调用函数”。为了让模型输出结构化的指令你得用提示词和微调技巧引导它让它把工具调用以固定格式输出出来。云端大模型经过大规模 function calling 微调输出质量很高但端侧小模型没那么听话。我在实际测试里遇到最多的问题有三个一是模型返回的 JSON 格式不完整少一个花括号或逗号二是参数名跟工具定义对不上模型把location写成loc三是模型干脆自己编造了一个不存在的工具名。这些在云端可能很少见在端侧却是家常便饭。应对思路是“约束在前校验在后”。先把工具定义写得尽量简单参数越少越好同时在系统提示词里给一个完整示例告诉模型层层嵌套的 JSON 结构长什么样。然后应用层统一做 JSON Schema 校验不合法就触发重试而不是把错误结果直接传下去执行。5.2 用轻量框架把 LLM 变成 Agent如果你还在自己写 prompt 拼接逻辑我建议直接用 LangChain 或 LlamaIndex 这类框架把模型包装成 Agent。它们已经实现了工具绑定、循环执行、记忆管理等通用逻辑你可以把注意力放在业务编排上而不是重复造轮子。因为 Ollama 有 OpenAI 兼容接口接入框架只需要改 base_url 和 api_keyfrom langchain_openai import ChatOpenAI llm ChatOpenAI( modelqwen2.5:7b-q4_K_M, base_urlhttp://127.0.0.1:11434/v1, api_keyollama, temperature0, )接下来定义两个工具函数比如查询天气和查数据库然后用bind_tools把它綁定到模型上。端侧模型绑定多个工具时如果频繁出现参数错误我会临时减少工具数量把 Agent 拆分成多个子任务每个子任务只绑定 1-2 个工具。这个策略听上去很简单却比在同一个上下文里硬塞 10 个工具稳定得多。另一个建议是别迷信框架的 ReAct 循环。端侧模型有时候会在“思考-行动-观察”之间反复循环出不结果我一般会给整个 Agent 加一个最大步数限制超过就停止并返回给用户一个明确的“需要更多信息”提示。5.3 并发与吞吐端侧模型扛得住吗有不少人问端侧 Agent 能不能扛并发这个问题的答案很现实不能跟云端比但也不是完全不能并发。Ollama 支持通过OLLAMA_NUM_PARALLEL设置并行请求数默认策略是串行或非常有限的并行。把并发调大之后每个请求都要维护独立的上下文缓存合起来占用内存成倍增长板子内存不够时只会适得其反。Agent 场景的“并发”和普通 Web 服务也不太一样。一个 Agent 任务往往包含多轮工具调用每一轮都要重新进入模型推理所以单个用户的前端请求可能就会连续产生 5-10 次推理。如果同时又来了几个用户后端就很容易被打满。我的做法是在应用层再加一个任务队列把请求排队后逐个交给模型处理保证每个请求拿到完整的上下文而不是让模型被多个请求的碎片塞爆。OLLAMA_NUM_PARALLEL2 ollama serve在 Jetson Orin NX 上我测试过并发从 1 调到 2单请求延迟会小幅上升但总吞吐量能提高 40% 左右调到 4 以后反而可能因为内存不足触发模型卸载延迟剧烈抖动。所以并发不是越大越好要按实际内存和延迟数据来定。6. 常见问题排查与避坑清单6.1 内存爆掉与加载失败端侧部署最常见的失败就是模型加载不进去。现象是ollama run后长时间卡住或者日志里出现 “no space”“cannot allocate memory” 之类的错误严重时整个系统卡死。这个问题的直接原因通常是内存不足。排查顺序建议这样先看设备真实可用内存free -h在 Linux 下直接能看再看模型文件大小确认是不是目标量化等级比设备内存还大最后看 Ollama 日志确认模型是加载到了 GPU 还是 CPU以及当前有没有多个模型同时常驻。Jetson 设备上还可以用tegrastats实时查看显存和频率。解决思路也分几步换成更激进的量化等级、降低上下文窗口、同时只保持一个模型常驻。如果设备有 Swap可以把 Swap 打开作为应急兜底但注意不要完全依赖 Swap因为频繁换页会让推理速度跌到不可用。6.2 速度慢、卡顿、重复输出模型跑起来了但每秒生成一两个 Token这种体验基本没法做 Agent。排查第一步是确认模型到底跑在什么硬件上。很多设备标称有 NPU但 Ollama 实际可能没用到退到了 CPU 推理。你可以通过日志或任务管理器确认如果发现模型加载在 CPU就要考虑更换支持硬件加速的运行时或者接受现实换更小模型。另一个常见问题是输出“复读机”。Agent 模型在生成长文本时容易出现重复循环尤其当上下文很长、量化损失又大的时候。解决方法是把repeat_penalty从默认值往上调我一般从 1.1 起步最高试到 1.3。温度也需要往低调温度越高随机性越强越容易出现无意义的循环。卡顿还有一个隐藏因素是 prompt 太长特别是把大段系统提示词和工具描述全部塞进去后每次推理都要重新处理这些固定前缀。Ollama 有 prompt caching 机制重复相同的系统前缀能显著提速所以建议大家把系统提示词固定下来不要每次改动。6.3 工具调用格式错乱怎么办我之前提过端侧模型工具调用不稳定是常态但真正崩溃时排查路径还是很有规律的。第一步先检查系统提示词里是否有明确的输出格式示例而不是只在工具描述里写 JSON Schema。很多模型对抽象 Schema 的理解能力有限但看到一两行具体示例就会好很多。第二步是明确区分错误类型。如果模型输出能解析成 JSON 但字段错误那就是语义问题要写映射代码做容错如果连 JSON 都解析不了那就是生成质量问题准备一个重试循环最多重试两三次仍失败就转人工兜底。以下这个片段我经常用来做后处理import re import json def extract_json(text: str): # 去掉模型可能加的多余说明文字 text re.sub(r^[^{]*, , text) try: return json.loads(text) except json.JSONDecodeError: # 尝试截取第一个完整的 JSON 对象 start text.find({) end text.rfind(}) if start -1 or end -1: raise ValueError(no json found) return json.loads(text[start:end1])这个方法不算优雅但在端侧模型身上确实能救回不少本来要失败的调用。注意它只能兜底格式问题改不了参数值错误业务上还是需要有校验逻辑。6.4 避坑清单结合我自己的实操经验端侧 LLM 部署有几个很容易踩的坑整理出来给你避雷不要一上来就开超长上下文先把num_ctx定在一个保守值比如 2048跑通全流程后再逐步放大。不要在没搞清楚内存余量的情况下调大OLLAMA_NUM_PARALLEL并发带来的内存膨胀经常直接触发 OOM。不要只看模型排行榜选模型端侧真正重要的是量化体积和工具调用稳定性这两项才是瓶颈。不要同时常驻多个模型Ollama 默认会保留最近用过的模型这在小内存设备上非常致命用完了及时卸载。不要假设量化好的模型行为跟原版一致工具调用、格式化输出这些能力必须在量化版本上重新测。不要让 Agent 循环没有步数上限一旦模型陷入“思考-行动-观察”死循环整个任务就会卡死。7. 最后分享一些个人实操体会跑了不少板子之后我的体会是端侧 Agent 的价值不在于“参数比云上大模型还多”而在于它把推理延迟、隐私边界和数据所有权都拿回到本地。实际做项目时我会先用一台 16GB 内存的开发板把 Agent 全流程跑通模型选择永远从“现有硬件的量化体积倒推”而不是先挑一个参数最大的模型再找硬件。踩过几次坑之后我已经习惯先把num_ctx固定在 2048并发设为 1用脚本模拟 20 轮工具调用确认没有格式错乱后再谈优化。端侧部署这条路没有捷径但把基础打扎实了后面接 Agent 会顺畅很多。希望这篇文章能帮你少走几步弯路。
