端侧Agent落地：LLM本地部署从选型到实战全流程

端侧Agent这条线之前写过第一篇总体的架构和场景都聊了。回帖里问得最多的是架构理解了但落地时LLM到底怎么部署到板子上这篇就接着来核心只有一个——端侧LLM部署。做Agent的人应该都有感受Agent不是一个模型而是一个系统它要高频感知、决策、调用工具如果每次决策都走云端延迟和成本立刻会让你崩溃。所以把LLM搬到端侧、在本地设备上跑起来是端侧Agent从demo走向产品的那一步。这篇我把一条实战链路完整写出来硬件怎么选、模型怎么量化、用哪个推理框架、怎么接入Agent、遇到问题怎么排。不搞玄学给的都是能直接操作的方案。想在自己板子上跑起Agent的开发者或者已经在跑但性能不满足的人都可以参考。1. 为什么端侧Agent必须本地跑LLM从架构倒推出部署要求1.1 本地推理和云端调用的本质区别很多做云端Agent的朋友觉得奇怪LLM调用API不就好了为什么非要在端侧折腾部署这个问题的答案从Agent的执行模式上就能看出来。云端调用的路径是设备采集数据 - 上传云端 - 云端大模型推理 - 返回结果 - 设备执行。一次任务至少要两次网络往返每趟按100毫秒算单轮决策就要多出200毫秒以上。而Agent任务不是一次请求就结束的你让Agent“把客厅的空调调到26度”它可能要先后完成理解意图、确认客厅是哪台设备、检查设备在线状态、生成控制指令、确认执行结果。这一串流程里LLM至少被调用5到10次。次数一多云端调用的延迟就从“可接受”变成了“没法用”更不用提网络抖动、离线断连、按token计费这些现实问题。端侧推理把整个推理过程放在本地数据不出设备延迟可控离线也能跑。我做过一个智能音箱类的端侧Agent用本地7B模型跑意图识别和槽位抽取首token响应在1秒以内整体控制链路从用户说完话到设备动作2秒左右能完成。这个体验感云端方案在弱网环境下基本给不到。用生活里的话类比云端调用像点外卖厨师在别处做饭高峰期还得等端侧推理像把厨师请到家里随时炒菜只是家里厨房小菜式简单些。Agent这种高频决策场景等不起外卖只能请厨师上门。1.2 端侧Agent的“感知-推理-行动”闭环要理解端侧LLM部署到底要部署成什么样先得看Agent的完整闭环。一个典型的端侧Agent通常由三层组成。感知层负责采集和识别环境信息。比如在RK3588板子上跑YOLOv8做目标检测识别摄像头画面里的障碍物、人、宠物或者用麦克风阵列做语音唤醒和ASR把语音转成文字。这一层生成的不是语言而是结构化的环境状态位置、类别、置信度。认知层是LLM的主场。它拿到感知层输出的环境描述和用户指令理解当前发生了什么、用户想要什么然后规划行动序列。这一层输出的也不只是自然语言更关键的是结构化的工具调用指令调用哪个API、传入什么参数、期望什么结果。行动层把LLM生成的指令转成真实动作。开灯、播放音乐、刹车、上报信息都由行动层的代码模块执行。执行完的结果会反馈回认知层LLM判断“行动是否达到预期”再决定是否进入下一个步骤。端侧LLM部署的本质就是在认知层这个位置把一个本地模型跑起来并让它和感知层、行动层的数据格式对齐。很多人在板子上单独跑模型很顺利一接入Agent就卡住就是因为只把模型当成了“聊天机器人”没有把它当成决策组件。整条链路里LLM负责的是“理解环境并决定做什么”而不是“陪用户闲聊”。2. 硬件和框架怎么选先看带宽再看TOPS2.1 选硬件先算内存带宽别迷信TOPS算力端侧Agent的硬件选型是非常多项目一开始就选错的地方。不少人一看RK3588标称6TOPS算力就觉得“咦能跑神经网络那跑LLM应该也行”结果模型一拉上去速度惨不忍睹。原因很简单LLM推理和CNN类视觉任务计算特征完全不同。YOLOv8这类视觉模型是计算密集型卷积算得多NPU的TOPS算力提升立竿见影但LLM推理是内存带宽密集型每生成一个token都要把模型权重从头到尾读一遍推理速度的天花板由内存带宽决定而不是TOPS。给一个粗略但好用的估算公式每秒生成的token数理论上限约等于内存带宽除以模型权重大小。拿最常见的7B模型量化后大概4GB权重来算。Jetson Orin Nano 8GB版本的内存带宽约68GB/s理论上限就是68除以4约每秒17个token。实际跑起来还要扣除KV Cache占用、系统调用、并发开销我实测大概在8到12 token/s。这个速度做实时语音对话刚好及格做高并发响应则比较吃力。再看RK3588它的优势在NPU和整机功耗但内存带宽本身不高跑7B量化模型实测通常在1到3 token/s做在线对话基本不可用更适合跑1.5B到3B级别的小模型配合视觉感知任务使用。不同硬件的选择逻辑我整理了一个速查表硬件平台内存带宽参考能稳定跑动的模型级别实测体验适合场景Jetson Orin Nano 8GB约68GB/s7B-8B模型Q4量化8-12 token/s可对话端侧Agent主力板卡Jetson Orin NX 16GB约102GB/s7B-14B模型Q4量化15-25 token/s体验明显更好对延迟有要求的Agent设备RK3588 8GB/16GB相对偏低1.5B-3B模型NPU跑YOLOv8很强LLM吃力感知小模型轻量Agentx86迷你主机取决于内存频率7B-32B模型中高速看内存条开发调试、边缘网关选硬件的时候我会建议先算一笔账你的Agent需要的最小模型是哪个规格量化后多大目标设备带宽多少按公式估算能不能达到你要的“最低可用速度”。如果连10 token/s都到不了就别硬上一个7B模型要么换设备要么降级模型。硬件选型不是选最强的是选刚好够用的。2.2 推理框架怎么选Ollama、llama.cpp、MLC-LLM怎么用模型要跑起来推理框架是绕不开的环节。端侧圈子里常见的开源框架就那么几个各自擅长方向不同。我的经验是不要一上来就追求最底层、最“硬核”的方案而是根据项目阶段选择。Ollama是目前端侧LLM部署里最省心的一个。一条命令安装拉模型、启动服务、提供OpenAI兼容的HTTP接口基本都给你做好了。适合快速验证模型效果、做原型Demo、或者项目前期跑通链路。我很多项目都是从Ollama起步的因为它能让我把时间花在Agent逻辑上而不是去调推理参数。llama.cpp主打GGUF格式和CPU/GPU混合推理几乎所有开源模型的GGUF量化版本都能跑而且可以直接编译目标平台嵌入自己的程序里。如果你要做的不是“起一个服务”而是把LLM作为模块嵌进C或Python进程里精细控制那llama.cpp是更稳的选择。它还可以通过参数控制多少层offload到GPU调试空间大但学习成本也更高。MLC-LLM对手机端支持很积极Android、iOS上跑小模型效果好如果你做的是手机App里的端侧Agent可以优先尝试。至于vLLM这类高性能服务框架虽然做大并发很厉害但那是给服务器设计的端侧内存和显存根本撑不起它的调度开销别盲目搬。选型建议很直接想做最快出结果的Demo直接用Ollama。想把LLM抽成库函数嵌进自己的程序用llama.cpp。想跑手机App看MLC-LLM。不管用哪个都建议从GGUF量化格式起步因为兼容性最好换框架成本低。我在实际项目中通常先用Ollama把整条Agent链路跑通验证“模型选对了没、工具调用顺不顺”再到后期做产品化时根据端侧资源情况决定要不要换llama.cpp精细优化。这个路径对一个人开发或小团队最省时间。2.3 模型选型和量化为什么Q4_K_M是端侧甜点模型是端侧Agent的脑子选错型号后面所有的优化都是白费。以目前的主流开源模型来看Qwen2.5-7B-Instruct、Llama-3.1-8B、DeepSeek-R1-Distill-Qwen-7B这几类经过4-bit量化后体积都在4到5GB塞进8GB内存的设备还有富余空间跑感知模型和KV Cache是端侧Agent最常用的区间。具体选哪个要看Agent的任务偏什么指令遵循和工具调用优先Qwen2.5系列复杂推理和规划DeepSeek蒸馏版确实更强但速度比同尺寸通用模型要慢不能所有请求都用它Llama系列兼容性和生态更好海外社区资料多。这里必须讲一下量化。模型量化就是把原本用16位浮点存权重压缩到8位、4位甚至更低来存。FP16的7B模型要占14GB内存INT8后约7GBINT4后约3.5到4GB。内存一降加载和推理都更快但代价是精度损失。不同量化方式里llama.cpp体系中最常用的是Q4_K_M。它采用混合量化策略对模型不同张量用不同位宽处理在体积和效果上平衡得很好。Q3体积更小但输出质量下降明显尤其是工具调用场景经常会出现JSON格式错乱、参数丢失这类问题Q5质量更好但体积多出不少在8GB设备上会挤压上下文空间。我做了十几个端侧项目后基本固定用Q4_K_M起步先保证输出稳定性再谈体积优化。还要留意KV Cache。上下文越长KV Cache占用内存越大8K上下文在7B模型上通常要额外占0.5到1GB内存。部署时你把模型和上下文的内存一起算进去预留20%余量不要卡着内存上限跑否则一压测就OOM非常折磨。3. 从零部署端侧LLM一份完整流程实录3.1 环境准备与Ollama安装我以Jetson Orin系列为例讲部署因为它是目前端侧Agent最典型的硬件平台。其他板子流程类似只是需要适配对应的芯片架构。第一步确认开发环境。Orin板卡刷好JetPack 5.x或6.x系统JetPack自带CUDA、cuDNN、TensorRT这些组件是后续跑GPU推理的基础。装完系统先用nvidia-smi看一下CUDA是否正常识别确保GPU驱动工作正常。第二步安装Ollama。用官方安装脚本一行命令比较直接curl -fsSL https://ollama.com/install.sh | sh。它在x86和ARM平台都支持Orin上装完会自动识别CUDA环境推理时优先调用GPU。如果安装脚本方式在你的平台上有问题也可以从Ollama的GitHub Release页面下载对应架构的二进制包手动安装原理是把它丢进/usr/local/bin并配置systemd服务。第三步简单配置。Ollama默认只在本机11434端口监听如果Agent跑在同一台板子上就不用管如果Agent单独跑在另一个设备上需要设置OLLAMA_HOST0.0.0.0让它监听所有网卡。改配置的方式是在systemd服务文件里加Environment或者用export命令临时设置再启动服务。启动完成后验证服务正常访问http://127.0.0.1:11434/api/tags能看到一个JSON格式的模型列表说明服务已经活起来了。3.2 拉取模型与量化选择Ollama的模型库非常方便拉模型就是一行命令。以我常用的Qwen2.5 7B Instruct Q4_K_M为例ollama pull qwen2.5:7b-instruct-q4_K_M这个命令会从模型仓库拉取对应的GGUF量化文件。如果你的网络环境访问模型社区不便也可以在ModelScope这类平台找到同一份GGUF文件手动下载再通过Ollama的Modelfile方式导入本地。步骤是建一个Modelfile内容写FROM /path/to/qwen2.5-7b-instruct-q4_k_m.gguf然后执行ollama create qwen2.5-7b -f Modelfile。这种方式能让你自由使用自己下载的量化文件不依赖在线拉取。如果你要自己从原始FP16权重做量化那就需要llama.cpp的转换工具链。基本流程是下载Safetensors格式的原始权重用convert_hf_to_gguf.py转成FP16的GGUF再用llama-quantize转成Q4_K_M量化版。这步对只想用模型的朋友来说可以跳过直接从社区下载现成的GGUF文件就行。这里有个实操提醒Ollama标签名里的q4_K_M后缀不要随意删掉。有时候你直接pull qwen2.5:7b-instruct拉下来是默认的Q4_0量化效果虽然也能用但和Q4_K_M相比还是有差距。如果Agent要输出工具调用建议明确指定q4_K_M标签输出稳定性更好。3.3 性能实测与参数调优模型跑起来之后先别急着接Agent把性能摸清楚。我习惯用一个简单的命令行测试ollama run qwen2.5:7b-instruct-q4_K_M --verbose 用一句话说明什么是端侧Agent--verbose参数会在输出结束后打印性能指标包括加载耗时、评估耗时、每秒token数等。在Orin Nano 8GB上我的实测结果是30W功耗模式下7B Q4_K_M模型稳定在8到12 token/s首token大约0.8到1.2秒。如果是Orin NX 16GB速度能到15到25 token/s体感流畅很多。影响速度的几个参数逐个说OLLAMA_NUM_PARALLEL控制并行请求数。端侧设备内存有限并行数开太高会让多个请求同时抢内存带宽单请求延迟反而恶化。一般Agent场景设成1就够了最多2。OLLAMA_CONTEXT_LENGTH控制上下文长度。默认是2048或4096对Agent来说不够用。Agent的prompt里要放系统提示词、工具定义、历史对话、RAG检索片段很容易超过4K。我会按设备内存余量调到8K或16K但注意上下文越长KV Cache占内存越多推理速度也会轻微下降。Jetson板卡的功耗模式对性能影响也很大。Orin的nvpmodel里15W模式和30W模式的速度差距非常明显实测可以差到50%以上。如果你的Agent装在固定电源设备上直接开30W模式如果是电池供电那就得在续航和响应速度之间做取舍。散热是另一个隐蔽的坑。Orin这类高功耗板卡在持续推理时发热很猛环境温度一高就触发降频速度会慢慢掉下来。我做过一次压测刚开始跑得很快几分钟后越来越慢量温度发现已经到了降频阈值。后来加装主动散热风扇速度才稳定下来。所以测性能不是跑一次就算数至少持续跑5分钟以上看速度曲线是否平稳。3.4 放大招把本地模型变成OpenAI兼容接口Agent框架接大模型最省事的方式是走OpenAI兼容的接口。Ollama直接提供了/v1路径完全兼容OpenAI的ChatCompletion接口格式这样你在Agent代码里几乎不用改任何调模型的部分只需要把base_url换成本地地址。用最直观的Python代码演示from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:11434/v1, api_keyollama # 本地服务可以随便填 ) resp client.chat.completions.create( modelqwen2.5:7b-instruct-q4_K_M, messages[ {role: system, content: 你是一个智能家居助手请使用工具完成用户指令。}, {role: user, content: 把客厅的灯打开} ], tools[ { type: function, function: { name: turn_on_light, description: 打开指定房间的电灯, parameters: { type: object, properties: { room: {type: string, description: 房间名称} }, required: [room] } } } ], tool_choiceauto ) print(resp.choices[0].message.tool_calls)如果模型正确理解指令返回结果里会有一个tool_calls字段里面包含函数名和参数。Agent代码拿到这个结构化指令后去执行对应的真实设备操作。这段代码跑通意味着Ollama已经不是一个“聊天工具”而是变成了Agent的决策引擎。LangChain这类框架的连接方式也一样ChatOllama类里设一下base_url和model就能把本地模型当成LLM用。市面上主流的Agent框架基本都兼容这个路径。这里要强调一个经验不是所有模型都支持工具调用。纯Base模型、或者指令微调不充分的模型不会正确输出tool_calls它们只会用自然语言回答“好的我帮你打开客厅的灯”但不会生成结构化调用。所以模型选型时一定要确认你选的是Instruct版本和明确支持function calling的模型Qwen2.5 Instruct、Llama 3.1都是验证过可以用的。4. 把LLM接进Agent工具调用、并发与RAG实战4.1 工具路由设计把工具当成“KV存储”来理解Agent和普通聊天机器人最本质的区别在于Agent要自主选择调用什么工具。而工具选择的背后是让LLM理解“用户任务需求”和“工具能力”之间怎么匹配。这个阶段我习惯用一组概念来设计思维每个工具有三个关键点——Key是工具的身份描述“我是谁、我能做什么”Query是当前用户的意图描述“我在找什么”Value是工具的返回数据描述“我能提供什么”。LLM要做的事情就是根据Query去匹配工具的Key决定调哪个工具再把Value拿回给用户。这个思路落实到工具描述上就是工具description一定要写清楚触发条件。比如有两个工具一个叫“查询天气”一个叫“打开空调”如果描述写得含糊本地模型就会选错。正确的写法是每个工具都说明“当用户提到XX任务时使用我”。描述不要超过一句话太长会让7B级别的模型注意力分散。另一个实操技巧是控制工具数量。一个8B模型一次调用时tools列表里塞20个工具每个工具带复杂JSON Schema本地模型的输入被工具定义占掉一大截选择准确率明显下降响应也更慢。我的做法是给工具分组建模家庭控制组、信息查询组、媒体播放组先用一个小模型做意图路由判断用户想干哪类事再只把那组工具的完整定义传给7B主模型做参数抽取。这一步是Agent架构级的优化效果比重训模型明显得多。4.2 端侧Agent怎么扛并发别硬扛要排队“AI Agent怎么扛并发”是很多从云端转端侧的开发者的第一个疑问。答案可能让人失望端侧设备真的扛不了大并发。服务器端并发靠的是多卡、大显存、动态批处理设备端一共8GB内存同时驻留两个模型都费劲更不用说几十路并发。与其硬扛不如设计成“单路快速响应、多路排队等待”的架构。Ollama的OLLAMA_NUM_PARALLEL参数可以开启并行推理但我实测下来在Orin Nano上并行数从1调到2单个请求的延迟反而明显恶化。原因还是内存带宽被多路请求瓜分每路都等权重加载吞吐总量没上去延迟却被拉高了。端侧Agent扛并发的正确姿势是在Ollama前面加一层轻量的请求网关。把Agent的每次LLM请求封装成任务进入队列由网关决定先处理哪个、要不要合并、超时的怎么降级。这个网关不需要多复杂一个队列加几个配置项就行但它能把并发压力从LLM服务本身平摊到调度层。从业务上也要做拆分。Agent任务里紧急且短耗时的事比如开关灯、识别一句话走端侧LLM实时推理不紧急的事比如生成日报、整理数据可以放到后台排队甚至等设备空闲的低峰期再处理。这样用户感知到的响应速度就稳住了整个系统的并发压力也降下来了。4.3 RAG也能本地化端侧Agent的知识库方案端侧Agent除了工具调用经常还要处理私有知识问答。比如设备维修助手要查产品手册家用Agent要理解家庭成员的偏好。这些知识不可能全塞进模型权重里RAG是目前最务实的方案。RAG最简单的落地路径把文档切成块用Embedding模型转成向量存进向量库。用户提问时把问题也转成向量检索出语义最相近的几个文档片段拼到LLM的上下文里让模型基于参考内容回答。端侧跑RAG不需要引入重型向量数据库一个sqlite-vec就够用。Embedding模型也可以本地跑比如bge-m3这类轻量模型在CPU上都能勉强跑或者直接用Ollama支持的embedding模型。这样整条链路从知识存储到检索、到推理完全不依赖外部服务做到真正离线。检索策略上端侧模型对噪声的容忍度比云端大模型低很多。云端GPT上下文窗口大、模型能力强塞一堆无关片段还能硬扛端侧7B模型如果TopK取20个片段很容易被其中的噪声带偏答非所问。我把TopK先设成3到5个片段优先保证精读质量不够再调高。更复杂的知识场景比如结构化知识图谱确实可以用本体抽取和GraphRAG的思路先抽取实体关系再检索准确率更好。但端侧算力有限这步建议作为项目二期优化第一版先用简单向量检索把链路跑通验证Agent整体体验再去加复杂度。5. 端侧LLM部署踩坑实录与排查手册5.1 高频问题速查表端侧部署的坑很多是重复出现的。我把高频问题和排查思路整理成一个表方便你现场对照问题现象常见原因解决办法模型加载失败或OOM内存余量不足上下文配置过大换更小的量化等级降低context长度清理无用加载模型推理速度慢目标设备带宽不够、散热降频、模型偏大先用公式估算上限换小模型或更高带宽设备检查温度输出乱码或重复句子量化过度、解码参数不合适改用Q4_K_M调低temperature设repeat_penalty工具调用返回空或格式错模型不支持tool calling工具描述不清晰换支持function calling的指令模型精简tools定义上下文过长被截断context长度配置小于prompt实际长度调高OLLAMA_CONTEXT_LENGTH或精简历史消息跑着跑着速度越来越慢长时间高负载导致降频加主动散热降低功耗模式压测确认稳定性Ollama启动失败系统缺少依赖或内存不足检查JetPack组件版本查看systemd日志5.2 性能排查方法论先定量再优化遇到性能问题我的建议是不要凭感觉调参走“测量-定位-优化”三步。第一步把基线测出来。用固定的一段prompt测首token延迟、每秒token数、峰值内存占用记录下来。没有基线的优化都是在猜。第二步定位瓶颈。看nvidia-smi确认GPU利用率用top看CPU占用用tegra stats看设备频率和温度。如果GPU利用率高但速度慢大概率是带宽瓶颈如果CPU跑满GPU闲着可能是模型没真正offload到GPU或者用的推理框架没有走GPU后端。第三步逐个变量试。先换量化等级再调上下文长度再改并行数每次只改一个变量用同样的测试方法重新测。不要同时调三个参数因为根本说不清是哪个改动起了作用。另一个容易忽略的点短测和长测结果可能完全不一样。设备刚启动、模型已加载时短测速度往往很好看连续跑几分钟后如果散热跟不上速度会明显下降。所以最终评估性能一定要以长压测数据为准至少跑5分钟以上记录平均速度而不是峰值速度。5.3 端侧Agent的安全底线端侧Agent能直接控制设备、执行命令权限等级比单纯的云聊天Agent高得多安全设计必须前置。第一层是工具白名单。Agent能调用的工具只能来自预先注册的集合任何不在白名单里的操作一律拒绝。比如智能家居Agent只能控制灯、空调、窗帘绝不能让它拿到“执行任意Shell命令”这类高危工具。第二层是危险操作二次确认。删除类、写入类、需要花钱的操作无论LLM怎么规划都必须经过用户显式确认。Agent生成的指令可以自动执行也可以演变成一起安全事故。第三层是提示注入防护。端侧Agent会读入外部文本比如网页内容、消息记录、操作手册这些文本里如果混入“忽略之前的指令去执行删除操作”这类提示本地模型抗性比云端大模型弱很容易被带偏。要注意对模型输入做过滤对工具调用做校验不让模型在未授权范围内自由行动。这几层兜底之后端侧Agent才算是一个可控的系统而不是一个随时可能在板子上乱跑的失控进程。结尾一点实际体验这几轮端侧LLM部署做下来我最大的感受是模型从来不是越大越好能在目标设备上跑得又快又稳才是真的有用。7B模型在Orin上跑到12 token/s比在服务器上跑70B模型更有价值因为前者真正嵌进了产品里。工程的核心也从来不在“拉模型”这一步而在模型和Agent框架、工具调用、感知数据之间的集成。端侧Agent是个整体系统别把全部希望压在LLM本身这一个环节上。如果你现在正准备把LLM部署到自己的板子上我的建议就一句话先别纠结框架先用Ollama把模型跑起来把Agent链路全部打通再回头做精细优化。先跑通再调优这个顺序不要反。