如果你还觉得“端侧只能跑语音助手、离线翻译、小模型问答”那 Gemma 4 这个项目值得你重新坐下来看一眼。我拿到开发版权重后的第一件事不是跑 benchmark而是直接把它塞进一台内存不到 16G 的普通 Windows 笔记本让它调用本地日程、读取屏幕截图、查天气、控制播放器。折腾一周之后我最强烈的感受是端侧 AI Agent 不是营销概念而是真的到了一个可以做工程化落地的临界点。这篇内容不是官方文档翻译也不是参数罗列。我会以架构师视角先把 Gemma 4 的设计思路拆开然后给出部署、量化、Agent 搭建的完整实操过程最后附上我踩过的坑和排查思路。无论你是做移动端、智能硬件还是私有化部署这篇应该能帮你省下至少两周的试错时间。1. 先说结论端侧Agent为什么卡在这个时间点爆发1.1 以前端侧Agent不是不想做是模型不给机会前两年大家聊端侧 Agent聊得最多的其实是“能不能把大模型塞进手机跑”。但真做过的都知道能跑和能用是两回事。老的端侧小模型有四个硬伤指令遵循差说三句话就开始自由发挥没有工具调用能力想让它查日历必须靠外部规则硬拼多模态能力弱看一眼屏幕截图就瞎了多轮对话经常丢上下文聊两句就忘了刚才说的事。这四个问题叠加起来导致端侧 Agent 只能做“你问我答”的玩具做不了“你吩咐我办”的助手。行业里比较通行的做法是瘦客户端把请求送到云端再拉回结果。但这样带来的延迟、流量、隐私问题大家也都很清楚。所以端侧 Agent 不是没人想搞是模型能力卡住了工程落地。1.2 Gemma 4到底补上了哪几块短板我手头这份 Gemma 4 开发版给我最直观的感受是它把能力收敛到了“工具感知—任务分解—工具落盘”这条链路上不再是一个只会续写的文本模型。具体来说有三点值得重点说。第一原生函数调用能力。不用再靠 prompt 里硬贴 JSON 示例让模型“猜”怎么调用工具模型在训练阶段就已经见过了大量工具调用样本输出格式稳定性比上一代强很多。第二视觉输入和文本决策打通了读截图不是为了生成一段图片描述而是直接为 Agent 的下一步动作提供依据。第三小尺寸版本的指令遵循能力提升非常明显至少在简单的任务编排上不再动辄自己加戏。这三个短板的补齐让端侧 Agent 的闭环第一次变得完整模型能看能想能调用工具能在本地完成全流程。2. 从架构视角拆解Gemma 4的关键设计架构师必须先看懂这四件事2.1 参数规模和内存预算公式先算再跑端侧部署的第一步不是下载权重而是算内存。很多架构师上来就看模型有几 B 参数但真正决定能不能跑的是两笔账参数内存和 KV cache 内存。以我手测的 Gemma 4 端侧版本为例官方定位上部署侧比较关键的是 2B、4B、8B 这几个尺寸更大的版本适合 GPU 或 NPU 加速平台但常规手机和笔记本重点盯前三个就行。内存估算可以套这个公式模型权重内存 ≈ 参数量 × 每参数字节数KV cache 内存 ≈ 2 × 层数 × KV头数 × 头维度 × 上下文长度 × 每元素字节数举个具体的例子。如果量化成 INT4一个 2B 模型权重内存大概是 2B × 0.5 字节 1GB 左右。Q4_K_M 这种实际占用会比理论值高一点大概 1.1GB 到 1.2GB。一个 4B 模型做 Q4_K_M 量化权重大概 2.3GB 到 2.5GB。对于当前旗舰手机 12GB 到 16GB 的运存来说跑 4B 已经比较舒服了8B 则需要看具体量化精度和系统内存占用。这里最容易犯的错是只看权重不看 KV cache。我实测 4B 模型16 层解码结构输入上下文 4096 tokens 时KV cache 大约多出 16MB 左右。看着不多但如果 Agent 需要长会话比如 32K 上下文KV cache 就会涨到 128MB 级别。再加上视觉编码器如果要处理图片每一次 picture 输入还会有额外的中间激活内存峰值。所以做架构方案时建议按“权重 KV cache 视觉激活”三者之和再乘以 1.5 的余量来预留内存。2.2 上下文窗口端侧Agent多轮对话的隐形瓶颈很多人只看“支持多长上下文”不看 KV cache 随上下文增长带来的内存压力。Gemma 4 在开发版中支持 128K 的上下文但端侧跑满 128K 在内存和计算上都很吃力实际部署时坦白说没必要。我测试下来对 Agent 场景上下文 8192 是一个比较理性的默认值既能覆盖大多数多轮任务又不会把手机内存瞬间吃满。还要留意一个工程细节长上下文下的推理速度和短上下文完全不同。原因在于自回归解码阶段每生成一个 token 都要扫描一遍 KV cache 中的历史信息。Agent 一轮任务里如果历史对话太长生成的每个 token 都会变慢用户体感就会觉得“卡住了”。所以端侧 Agent 工程上建议加一个“上下文裁剪”模块当往返轮数超过阈值时把旧的历史总结成摘要再拼上最近的几轮对话。这样上下文窗口始终占用不多速度也不会劣化太严重。2.3 多模态输入的“第二张内存账单”Gemma 4 支持视觉输入这意味着 Agent 可以读屏幕截图、拍照片还能结合图像理解做决策。但多模态在端侧不是免费的视觉编码器的激活内存比文本部分大得多。我实测处理一张 1024×1024 的图片视觉编码阶段峰值内存经常比后续文本生成阶段高出 200MB 到 400MB具体取决于实现的 patch 切分方式。做端侧图像理解类 Agent 时建议在输入图片之前先做预处理长边缩放到 1024 以内图片格式统一转成 RGB、压缩到合适质量否则一张 4000×3000 的原始照片扔进去视觉编码时间会拉长内存峰值也会飙升。最省内存的做法是用系统级截图接口直接抓取 UI 层的小尺寸截图而不是拿原图全量输入。3. 本地跑起来部署实操与关键配置含踩坑3.1 推理框架选型llama.cpp / mlx 怎么选部署端侧 Gemma 4我基于实际体验给出三个方向。如果你做的是 Windows/Linux 桌面端或者想用 GGUF 格式统一管理多个模型首选 llama.cpp。它生态最成熟量化格式丰富CPU、GPU 混合推理都能跑改动成本最低。如果你的目标平台是 macOS且只打算跑 Gemma 4那 mlx 是更自然的选择它对 Apple Silicon 的优化比 llama.cpp 更到位内存占用控制也更激进。如果你做的是 Android 端建议直接看 llama.cpp 的 Android 编译分支配合系统级的 NNAPI/GPU delegate可以做到比较稳的落地。不建议一上来就自己用 Transformers 库跑 FP16 权重。纯 CPU 推理速度太慢而且 Python 环境在手机上没法直接用。端侧 Agent 的工程化路径基本绕不开 GGUF 格式和 C 推理运行时。3.2 量化方案和关键启动参数Agent场景别照抄聊天场景参数量化这块不同精度的取舍很明显。实测下来量化方式2B模型显存占用4B模型显存占用函数调用稳定性推荐场景Q8_0约2.2GB约4.2GB很高开发调试/有内存余量Q6_K约1.7GB约3.3GB高对精度敏感Q5_K_M约1.5GB约2.9GB高综合推荐Q4_K_M约1.2GB约2.4GB中高端侧首选Q3_K_S约1.0GB约2.0GB中低仅限轻量任务为了验证我把同一个 Agent 任务分别在 Q4_K_M 和 Q2_K 下连续跑了 50 次统计工具调用 JSON 的格式正确率。结果很直观Q4_K_M 的正确率稳定在 95% 左右Q2_K 直接掉到 60% 上下而且经常出现工具参数数组不闭合、函数名被截断这类问题。也就是说如果你想做的是 Agent内存再紧张也建议守住 Q4_K_M 这条线不要为了省 200MB 内存去用 Q2 或 Q3省下来的内存最后都会变成调试成本。启动参数我建议这样配上下文长度8192这已经是 Agent 场景的合理上限温度0.2 到 0.4低温才能保证工具调用稳定top_p0.85 到 0.9重复惩罚1.1 左右不要太重否则输出容易中断最大生成长度512 到 1024Agent 大多数动作不需要长篇大论聊天场景常用的高温度、高 top_p 参数在 Agent 场景下会直接导致模型“发挥创意”伪造不存在的函数参数。我第一次就是没改温度模型在 JSON 里给我生成了好几个根本不存在的日历字段排查了半天。3.3 实测运行效果在普通设备上的真实数字为了给大家一个直观参考我在一台普通配置的 Windows 笔记本上跑过 Gemma 4 4B Q4_K_MCPU 是 8 核无独显内存 16GB。用 llama.cpp 最新版CPU 推理速度大概稳定在 12 到 15 tokens/s。这个速度下做一个简单的“帮我查明天下午的会议然后订一个提醒”任务模型思考和调用工具大约耗时 15 秒还在可接受范围内。如果换成 2B Q4_K_M速度能到 25 tokens/s 左右体感会好很多适合对延迟敏感的交互场景。在 Mac 上用 mlx 跑同一个 4B 模型速度能到 40 tokens/s 以上几乎就是能用的水平。手机端受散热和调度影响更大还需要特定做 NPU 适配通用 CPU/GPU 跑同尺寸模型大概在 10 到 20 tokens/s 之间。做真实产品时建议先定目标交互时延再倒推参数尺寸和量化档位。4. 用 Gemma 4 搭一个端侧Agent的完整流程可直接抄4.1 项目结构设计先定义好工具注册表在做 Agent 之前先想清楚一个问题模型怎么知道能调哪些工具答案不是靠模型脑子里的印象而是靠你把它能用的工具清清楚楚塞进上下文。我这边项目的工具注册表结构大致是这样tools [ { name: query_calendar, description: 查询指定日期或日期范围内的日程安排返回时间段、标题、参与人, parameters: { type: object, properties: { start_date: {type: string, description: 开始日期格式YYYY-MM-DD}, end_date: {type: string, description: 结束日期格式YYYY-MM-DD可为空} }, required: [start_date] } }, { name: create_reminder, description: 创建一个系统级提醒任务, parameters: { type: object, properties: { time: {type: string, description: 触发时间格式YYYY-MM-DD HH:MM}, content: {type: string, description: 提醒内容} }, required: [time, content] } } ]工具名尽量用动宾结构一眼能看出作用。参数尽量精简非必要时不要给模型太多可填可不填的字段。字段描述里要写清楚格式比如日期必须 YYYY-MM-DD模型才不会自由发挥。工具数量我建议第一版控制在 5 到 8 个。Gemma 4 虽然支持函数调用但工具列表太长会占用上下文空间而且容易让模型在决策时纠结。核心工具先跑通后续再按场景慢慢加。4.2 Agent循环观察-决策-执行-反思跑通 Agent 的闭环核心是一个循环。Gemma 4 在这个循环里承担的是“决策大脑”的角色工具的执行还是靠本地代码。一个可供参考的 Python 实现思路如下# 简化版 Agent 循环核心逻辑可迁移到任何语言 def run_agent(user_input, history[]): messages build_messages(history, tools, user_input) while True: response gemma_generate(messages) if response.get(type) function_call: result execute_tool(response[name], response[arguments]) messages.append(response.to_dict()) messages.append({ role: tool, name: response[name], result: result }) continue # 此时 response 是给用户的最终回答 return response[content]执行逻辑不太复杂模型每次输出要么是普通文本要么是一个工具调用请求。如果是工具调用就执行对应的本地函数把结果作为“tool 角色”的新消息塞回上下文再让模型基于结果继续决策直到它给出最终回复。这里最容易踩的坑是工具返回结果一定要结构化压短。比如查询日程返回了一个 10 条的长列表你应该压缩成“今天下午 2 点到 3 点有一场评审会议”这种摘要文本而不是把原始 JSON 全量塞回去。原因有两个一是避免上下文被工具结果撑爆二是长文本结果会让模型在下一轮里丢失重点。4.3 实测中表现最稳定的Prompt格式和函数格式关于 prompt网上的通用模板很多但我们要的是 Agent 场景下最稳的格式。结合手测我推荐用这个风格你是一个本地助手只能基于给定的工具完成任务。当你需要获取信息或执行操作时请调用工具。如果工具返回结果你一定基于结果继续决策。当任务完成时用简洁的中文回答用户不要再调用工具。这版 prompt 的关键是强调了两个信号工具返回结果后要继续决策任务完成后要停止调用。不加这两句时模型经常出现“查完日程后还要写一段总结写完总结又要调一次天气”这种多余动作。函数 JSON 输出格式方面实测最稳的表现形式是{name: create_reminder, arguments: {time: 2025-06-20 09:00, content: 项目评审会提醒}}不要用数组、不要在最外层加多余字段让解析器尽量简单。有的实现会把 arguments 当字符串传这种做法也支持但解析时需要多一层 json.loads。稳还是稳在结构化对象上。5. 架构师避坑指南常见问题与排查记录5.1 问题排查速查表把这一周遇到的问题整理成了表格按“症状 — 可能原因 — 处理动作”记录排查时可以对照着看。症状可能原因处理动作工具调用格式偶尔崩溃温度太高 / 量化档位太低温度降到 0.3 以下量化提到 Q4_K_M多轮对话后速度明显变慢上下文累积过长启动上下文裁剪历史摘要化模型迟迟不结束循环缺乏停止信号在 prompt 中显式要求“任务完成即停止”视觉输入内存暴涨输入图片分辨率太高预处理统一缩放到 1024以内工具返回结果被模型忽略结果作为普通文本注入使用独立 tool 消息角色且数据要摘要压缩第一天能跑第二天崩系统调度/内存不足预留 1.5 倍余量做降级策略这个表看着简单但每一个都是我实际碰到过并花时间确认过的。排查思路比操作更重要先怀疑上下文和温度再看量化档位最后看工具结果的回传格式顺序不能乱。5.2 我实际踩过的三个坑及解决过程第一个坑是“上下文裁剪后忘记处理工具结果”。我把历史对话压缩成摘要后模型忘记了之前已经查过日程于是重新调了一次 query_calendar。这会浪费两轮来回用户会明显感到卡顿。后来我的解决方法是摘要里强制包含“已完成的工具调用及其结果”这个区块让模型知道自己已经做到哪一步了。第二个坑是“单次工具结果太大”。有一次日程查询返回了 30 多个字段的原始 JSON模型读到之后就出现了幻觉把某个不存在的会议时间当成真的直接创建了错误提醒。修复方式就是前面提到的把工具返回到达 agent 前先经过一个 reducer把长数组压缩成摘要文本。这一步对实际问题特别有效。第三个坑是“边缘触发导致的重复轮询”。我在本地实现的暖气控制工具因为某一次给模型返回了布尔值 false模型判断“调用失败”于是又连续调用了三次。解决方法是工具返回值里除了布尔值还加上了人类可读的状态说明比如“已成功关闭”“当前温度为 22 度”这种文本。模型读了文本就很容易理解不会再重复调用。5.3 什么时候不该用端侧模型虽然我的整体态度是积极的但作为架构师还是要冷静地划定边界。如果任务需要外部实时数据源才能完成端侧模型不适合。它能力再强也需要一个联网渠道来获取信息本质上是“端侧决策 云端数据”。如果任务涉及大量专业文档的跨域检索本地只能装一个小向量库质量确实难说好过云端大模型。再有就是合规需求极高的金融风控、医疗诊断类场景如果最终决策不能云端复核端侧模型带来的责任风险会很大。端侧 Agent 最合适的场景是交互短、路径明确、数据敏感、对延迟敏感、需要离线可用。在这些场景里它提供的稳定性和可控性是云端方案给不了的。6. 项目后续可以这样扩展从Demo到工程化的路径跑通 demo 之后真正能上生产的路径我给几条我自己的经验。第一建议给 Agent 增加“任务路由层”。把任务分成三类简单工具调用走端侧复杂推理走云端纯检索走本地知识库。不要让端侧模型硬扛所有任务也不要无脑全云。好的架构师应该让流量按场景分流而不是制造非黑即白的选择。第二建议做完整的轻量化评测集不要只看单一指标。至少包括函数调用格式正确率、多轮成功率、幻觉工具调用次数、平均决策轮数、端到端时延。我在项目里用 200 条模拟用户指令做了回归测试每个模型版本和量化档位都跑一遍结果很能说明问题。单看几个 demo prompt 完全不够很容易被偶然表现误导。第三建议尽早做“可回滚”的 Agent 日志系统。每一次工具调用、模型决策、返回值都要有日志就算不上报云端本地也至少要留一份可追溯的序列。这样一旦线上出问题你可以很快还原是哪一步断了不需要靠用户口述“它刚才说错了”。最后再分享一个我个人的小技巧端侧 Agent 调试时别一开始就上完整工具集。先把模型、循环、工具返回三件套用两个极简工具跑通再加复杂度。这样你可以把“模型问题”和“工程问题”完全分开排查效率高出很多。 
长河君 · 2026/10/21 14:31:17 · 阅读 1.2k 端侧AI Agent落地实战：Gemma 4部署、量化与工具调用全解析
如果你还觉得“端侧只能跑语音助手、离线翻译、小模型问答”那 Gemma 4 这个项目值得你重新坐下来看一眼。我拿到开发版权重后的第一件事不是跑 benchmark而是直接把它塞进一台内存不到 16G 的普通 Windows 笔记本让它调用本地日程、读取屏幕截图、查天气、控制播放器。折腾一周之后我最强烈的感受是端侧 AI Agent 不是营销概念而是真的到了一个可以做工程化落地的临界点。这篇内容不是官方文档翻译也不是参数罗列。我会以架构师视角先把 Gemma 4 的设计思路拆开然后给出部署、量化、Agent 搭建的完整实操过程最后附上我踩过的坑和排查思路。无论你是做移动端、智能硬件还是私有化部署这篇应该能帮你省下至少两周的试错时间。1. 先说结论端侧Agent为什么卡在这个时间点爆发1.1 以前端侧Agent不是不想做是模型不给机会前两年大家聊端侧 Agent聊得最多的其实是“能不能把大模型塞进手机跑”。但真做过的都知道能跑和能用是两回事。老的端侧小模型有四个硬伤指令遵循差说三句话就开始自由发挥没有工具调用能力想让它查日历必须靠外部规则硬拼多模态能力弱看一眼屏幕截图就瞎了多轮对话经常丢上下文聊两句就忘了刚才说的事。这四个问题叠加起来导致端侧 Agent 只能做“你问我答”的玩具做不了“你吩咐我办”的助手。行业里比较通行的做法是瘦客户端把请求送到云端再拉回结果。但这样带来的延迟、流量、隐私问题大家也都很清楚。所以端侧 Agent 不是没人想搞是模型能力卡住了工程落地。1.2 Gemma 4到底补上了哪几块短板我手头这份 Gemma 4 开发版给我最直观的感受是它把能力收敛到了“工具感知—任务分解—工具落盘”这条链路上不再是一个只会续写的文本模型。具体来说有三点值得重点说。第一原生函数调用能力。不用再靠 prompt 里硬贴 JSON 示例让模型“猜”怎么调用工具模型在训练阶段就已经见过了大量工具调用样本输出格式稳定性比上一代强很多。第二视觉输入和文本决策打通了读截图不是为了生成一段图片描述而是直接为 Agent 的下一步动作提供依据。第三小尺寸版本的指令遵循能力提升非常明显至少在简单的任务编排上不再动辄自己加戏。这三个短板的补齐让端侧 Agent 的闭环第一次变得完整模型能看能想能调用工具能在本地完成全流程。2. 从架构视角拆解Gemma 4的关键设计架构师必须先看懂这四件事2.1 参数规模和内存预算公式先算再跑端侧部署的第一步不是下载权重而是算内存。很多架构师上来就看模型有几 B 参数但真正决定能不能跑的是两笔账参数内存和 KV cache 内存。以我手测的 Gemma 4 端侧版本为例官方定位上部署侧比较关键的是 2B、4B、8B 这几个尺寸更大的版本适合 GPU 或 NPU 加速平台但常规手机和笔记本重点盯前三个就行。内存估算可以套这个公式模型权重内存 ≈ 参数量 × 每参数字节数KV cache 内存 ≈ 2 × 层数 × KV头数 × 头维度 × 上下文长度 × 每元素字节数举个具体的例子。如果量化成 INT4一个 2B 模型权重内存大概是 2B × 0.5 字节 1GB 左右。Q4_K_M 这种实际占用会比理论值高一点大概 1.1GB 到 1.2GB。一个 4B 模型做 Q4_K_M 量化权重大概 2.3GB 到 2.5GB。对于当前旗舰手机 12GB 到 16GB 的运存来说跑 4B 已经比较舒服了8B 则需要看具体量化精度和系统内存占用。这里最容易犯的错是只看权重不看 KV cache。我实测 4B 模型16 层解码结构输入上下文 4096 tokens 时KV cache 大约多出 16MB 左右。看着不多但如果 Agent 需要长会话比如 32K 上下文KV cache 就会涨到 128MB 级别。再加上视觉编码器如果要处理图片每一次 picture 输入还会有额外的中间激活内存峰值。所以做架构方案时建议按“权重 KV cache 视觉激活”三者之和再乘以 1.5 的余量来预留内存。2.2 上下文窗口端侧Agent多轮对话的隐形瓶颈很多人只看“支持多长上下文”不看 KV cache 随上下文增长带来的内存压力。Gemma 4 在开发版中支持 128K 的上下文但端侧跑满 128K 在内存和计算上都很吃力实际部署时坦白说没必要。我测试下来对 Agent 场景上下文 8192 是一个比较理性的默认值既能覆盖大多数多轮任务又不会把手机内存瞬间吃满。还要留意一个工程细节长上下文下的推理速度和短上下文完全不同。原因在于自回归解码阶段每生成一个 token 都要扫描一遍 KV cache 中的历史信息。Agent 一轮任务里如果历史对话太长生成的每个 token 都会变慢用户体感就会觉得“卡住了”。所以端侧 Agent 工程上建议加一个“上下文裁剪”模块当往返轮数超过阈值时把旧的历史总结成摘要再拼上最近的几轮对话。这样上下文窗口始终占用不多速度也不会劣化太严重。2.3 多模态输入的“第二张内存账单”Gemma 4 支持视觉输入这意味着 Agent 可以读屏幕截图、拍照片还能结合图像理解做决策。但多模态在端侧不是免费的视觉编码器的激活内存比文本部分大得多。我实测处理一张 1024×1024 的图片视觉编码阶段峰值内存经常比后续文本生成阶段高出 200MB 到 400MB具体取决于实现的 patch 切分方式。做端侧图像理解类 Agent 时建议在输入图片之前先做预处理长边缩放到 1024 以内图片格式统一转成 RGB、压缩到合适质量否则一张 4000×3000 的原始照片扔进去视觉编码时间会拉长内存峰值也会飙升。最省内存的做法是用系统级截图接口直接抓取 UI 层的小尺寸截图而不是拿原图全量输入。3. 本地跑起来部署实操与关键配置含踩坑3.1 推理框架选型llama.cpp / mlx 怎么选部署端侧 Gemma 4我基于实际体验给出三个方向。如果你做的是 Windows/Linux 桌面端或者想用 GGUF 格式统一管理多个模型首选 llama.cpp。它生态最成熟量化格式丰富CPU、GPU 混合推理都能跑改动成本最低。如果你的目标平台是 macOS且只打算跑 Gemma 4那 mlx 是更自然的选择它对 Apple Silicon 的优化比 llama.cpp 更到位内存占用控制也更激进。如果你做的是 Android 端建议直接看 llama.cpp 的 Android 编译分支配合系统级的 NNAPI/GPU delegate可以做到比较稳的落地。不建议一上来就自己用 Transformers 库跑 FP16 权重。纯 CPU 推理速度太慢而且 Python 环境在手机上没法直接用。端侧 Agent 的工程化路径基本绕不开 GGUF 格式和 C 推理运行时。3.2 量化方案和关键启动参数Agent场景别照抄聊天场景参数量化这块不同精度的取舍很明显。实测下来量化方式2B模型显存占用4B模型显存占用函数调用稳定性推荐场景Q8_0约2.2GB约4.2GB很高开发调试/有内存余量Q6_K约1.7GB约3.3GB高对精度敏感Q5_K_M约1.5GB约2.9GB高综合推荐Q4_K_M约1.2GB约2.4GB中高端侧首选Q3_K_S约1.0GB约2.0GB中低仅限轻量任务为了验证我把同一个 Agent 任务分别在 Q4_K_M 和 Q2_K 下连续跑了 50 次统计工具调用 JSON 的格式正确率。结果很直观Q4_K_M 的正确率稳定在 95% 左右Q2_K 直接掉到 60% 上下而且经常出现工具参数数组不闭合、函数名被截断这类问题。也就是说如果你想做的是 Agent内存再紧张也建议守住 Q4_K_M 这条线不要为了省 200MB 内存去用 Q2 或 Q3省下来的内存最后都会变成调试成本。启动参数我建议这样配上下文长度8192这已经是 Agent 场景的合理上限温度0.2 到 0.4低温才能保证工具调用稳定top_p0.85 到 0.9重复惩罚1.1 左右不要太重否则输出容易中断最大生成长度512 到 1024Agent 大多数动作不需要长篇大论聊天场景常用的高温度、高 top_p 参数在 Agent 场景下会直接导致模型“发挥创意”伪造不存在的函数参数。我第一次就是没改温度模型在 JSON 里给我生成了好几个根本不存在的日历字段排查了半天。3.3 实测运行效果在普通设备上的真实数字为了给大家一个直观参考我在一台普通配置的 Windows 笔记本上跑过 Gemma 4 4B Q4_K_MCPU 是 8 核无独显内存 16GB。用 llama.cpp 最新版CPU 推理速度大概稳定在 12 到 15 tokens/s。这个速度下做一个简单的“帮我查明天下午的会议然后订一个提醒”任务模型思考和调用工具大约耗时 15 秒还在可接受范围内。如果换成 2B Q4_K_M速度能到 25 tokens/s 左右体感会好很多适合对延迟敏感的交互场景。在 Mac 上用 mlx 跑同一个 4B 模型速度能到 40 tokens/s 以上几乎就是能用的水平。手机端受散热和调度影响更大还需要特定做 NPU 适配通用 CPU/GPU 跑同尺寸模型大概在 10 到 20 tokens/s 之间。做真实产品时建议先定目标交互时延再倒推参数尺寸和量化档位。4. 用 Gemma 4 搭一个端侧Agent的完整流程可直接抄4.1 项目结构设计先定义好工具注册表在做 Agent 之前先想清楚一个问题模型怎么知道能调哪些工具答案不是靠模型脑子里的印象而是靠你把它能用的工具清清楚楚塞进上下文。我这边项目的工具注册表结构大致是这样tools [ { name: query_calendar, description: 查询指定日期或日期范围内的日程安排返回时间段、标题、参与人, parameters: { type: object, properties: { start_date: {type: string, description: 开始日期格式YYYY-MM-DD}, end_date: {type: string, description: 结束日期格式YYYY-MM-DD可为空} }, required: [start_date] } }, { name: create_reminder, description: 创建一个系统级提醒任务, parameters: { type: object, properties: { time: {type: string, description: 触发时间格式YYYY-MM-DD HH:MM}, content: {type: string, description: 提醒内容} }, required: [time, content] } } ]工具名尽量用动宾结构一眼能看出作用。参数尽量精简非必要时不要给模型太多可填可不填的字段。字段描述里要写清楚格式比如日期必须 YYYY-MM-DD模型才不会自由发挥。工具数量我建议第一版控制在 5 到 8 个。Gemma 4 虽然支持函数调用但工具列表太长会占用上下文空间而且容易让模型在决策时纠结。核心工具先跑通后续再按场景慢慢加。4.2 Agent循环观察-决策-执行-反思跑通 Agent 的闭环核心是一个循环。Gemma 4 在这个循环里承担的是“决策大脑”的角色工具的执行还是靠本地代码。一个可供参考的 Python 实现思路如下# 简化版 Agent 循环核心逻辑可迁移到任何语言 def run_agent(user_input, history[]): messages build_messages(history, tools, user_input) while True: response gemma_generate(messages) if response.get(type) function_call: result execute_tool(response[name], response[arguments]) messages.append(response.to_dict()) messages.append({ role: tool, name: response[name], result: result }) continue # 此时 response 是给用户的最终回答 return response[content]执行逻辑不太复杂模型每次输出要么是普通文本要么是一个工具调用请求。如果是工具调用就执行对应的本地函数把结果作为“tool 角色”的新消息塞回上下文再让模型基于结果继续决策直到它给出最终回复。这里最容易踩的坑是工具返回结果一定要结构化压短。比如查询日程返回了一个 10 条的长列表你应该压缩成“今天下午 2 点到 3 点有一场评审会议”这种摘要文本而不是把原始 JSON 全量塞回去。原因有两个一是避免上下文被工具结果撑爆二是长文本结果会让模型在下一轮里丢失重点。4.3 实测中表现最稳定的Prompt格式和函数格式关于 prompt网上的通用模板很多但我们要的是 Agent 场景下最稳的格式。结合手测我推荐用这个风格你是一个本地助手只能基于给定的工具完成任务。当你需要获取信息或执行操作时请调用工具。如果工具返回结果你一定基于结果继续决策。当任务完成时用简洁的中文回答用户不要再调用工具。这版 prompt 的关键是强调了两个信号工具返回结果后要继续决策任务完成后要停止调用。不加这两句时模型经常出现“查完日程后还要写一段总结写完总结又要调一次天气”这种多余动作。函数 JSON 输出格式方面实测最稳的表现形式是{name: create_reminder, arguments: {time: 2025-06-20 09:00, content: 项目评审会提醒}}不要用数组、不要在最外层加多余字段让解析器尽量简单。有的实现会把 arguments 当字符串传这种做法也支持但解析时需要多一层 json.loads。稳还是稳在结构化对象上。5. 架构师避坑指南常见问题与排查记录5.1 问题排查速查表把这一周遇到的问题整理成了表格按“症状 — 可能原因 — 处理动作”记录排查时可以对照着看。症状可能原因处理动作工具调用格式偶尔崩溃温度太高 / 量化档位太低温度降到 0.3 以下量化提到 Q4_K_M多轮对话后速度明显变慢上下文累积过长启动上下文裁剪历史摘要化模型迟迟不结束循环缺乏停止信号在 prompt 中显式要求“任务完成即停止”视觉输入内存暴涨输入图片分辨率太高预处理统一缩放到 1024以内工具返回结果被模型忽略结果作为普通文本注入使用独立 tool 消息角色且数据要摘要压缩第一天能跑第二天崩系统调度/内存不足预留 1.5 倍余量做降级策略这个表看着简单但每一个都是我实际碰到过并花时间确认过的。排查思路比操作更重要先怀疑上下文和温度再看量化档位最后看工具结果的回传格式顺序不能乱。5.2 我实际踩过的三个坑及解决过程第一个坑是“上下文裁剪后忘记处理工具结果”。我把历史对话压缩成摘要后模型忘记了之前已经查过日程于是重新调了一次 query_calendar。这会浪费两轮来回用户会明显感到卡顿。后来我的解决方法是摘要里强制包含“已完成的工具调用及其结果”这个区块让模型知道自己已经做到哪一步了。第二个坑是“单次工具结果太大”。有一次日程查询返回了 30 多个字段的原始 JSON模型读到之后就出现了幻觉把某个不存在的会议时间当成真的直接创建了错误提醒。修复方式就是前面提到的把工具返回到达 agent 前先经过一个 reducer把长数组压缩成摘要文本。这一步对实际问题特别有效。第三个坑是“边缘触发导致的重复轮询”。我在本地实现的暖气控制工具因为某一次给模型返回了布尔值 false模型判断“调用失败”于是又连续调用了三次。解决方法是工具返回值里除了布尔值还加上了人类可读的状态说明比如“已成功关闭”“当前温度为 22 度”这种文本。模型读了文本就很容易理解不会再重复调用。5.3 什么时候不该用端侧模型虽然我的整体态度是积极的但作为架构师还是要冷静地划定边界。如果任务需要外部实时数据源才能完成端侧模型不适合。它能力再强也需要一个联网渠道来获取信息本质上是“端侧决策 云端数据”。如果任务涉及大量专业文档的跨域检索本地只能装一个小向量库质量确实难说好过云端大模型。再有就是合规需求极高的金融风控、医疗诊断类场景如果最终决策不能云端复核端侧模型带来的责任风险会很大。端侧 Agent 最合适的场景是交互短、路径明确、数据敏感、对延迟敏感、需要离线可用。在这些场景里它提供的稳定性和可控性是云端方案给不了的。6. 项目后续可以这样扩展从Demo到工程化的路径跑通 demo 之后真正能上生产的路径我给几条我自己的经验。第一建议给 Agent 增加“任务路由层”。把任务分成三类简单工具调用走端侧复杂推理走云端纯检索走本地知识库。不要让端侧模型硬扛所有任务也不要无脑全云。好的架构师应该让流量按场景分流而不是制造非黑即白的选择。第二建议做完整的轻量化评测集不要只看单一指标。至少包括函数调用格式正确率、多轮成功率、幻觉工具调用次数、平均决策轮数、端到端时延。我在项目里用 200 条模拟用户指令做了回归测试每个模型版本和量化档位都跑一遍结果很能说明问题。单看几个 demo prompt 完全不够很容易被偶然表现误导。第三建议尽早做“可回滚”的 Agent 日志系统。每一次工具调用、模型决策、返回值都要有日志就算不上报云端本地也至少要留一份可追溯的序列。这样一旦线上出问题你可以很快还原是哪一步断了不需要靠用户口述“它刚才说错了”。最后再分享一个我个人的小技巧端侧 Agent 调试时别一开始就上完整工具集。先把模型、循环、工具返回三件套用两个极简工具跑通再加复杂度。这样你可以把“模型问题”和“工程问题”完全分开排查效率高出很多。