做视觉Agent之前，我先被一张食堂小票狠狠教育了一顿。事情是这样的：我想做一个能帮忙记账的助手，让语言模型看一眼小票照片，自动算出人均消费。结果模型一本正经地告诉我"我是文本模型，无法查看图片"。换成带视觉能力的多模态模型后，它倒是"看"了，但把细长的热敏小票识别成了一串乱七八糟的数字和火星文。
那一刻我意识到，把一张图片喂给模型，和让一个AI真正拥有视觉理解能力，中间还隔着一条鸿沟。这条鸿沟的名字叫Agent——它不只是"能识别图片内容"，还要能基于视觉信息做判断、调工具、连续行动。这篇内容我想完整拆解一下，怎么把一个"能看图的多模态模型"，打磨成一个"看得懂、记得住、会办事"的视觉理解Agent。适合正在做智能文档处理、界面自动化、图像问答系统的朋友参考，不管你是刚接触多模态模型，还是已经踩过几个坑，应该都能找到有用的东西。
1. 视觉Agent的本质：从"能看图"到"会办事"
1.1 视觉理解能力不等于"识别出文字"
很多人对视觉理解的理解停留在两个层面：一是OCR，把图片里的文字抓出来；二是图像分类，判断这是猫还是狗。这两件事都很重要，但它们只是视觉理解的地基。
真正的视觉理解，要求模型同时处理三件事——空间布局、语义关系和视觉推理。比如一张报销单，你需要知道"合计金额1234元"这个结论是从哪几个数字加出来的，"报销人签字"和"日期"在版面中的先后关系是什么。这已经超出了传统OCR的范畴，因为OCR只告诉你"哪里有字、字是什么"，不会告诉你"这些字之间是什么业务关系"。
带视觉能力的大语言模型（业内常叫VLM，Vision-Language Model）正好补上了这一层。它把图像切块后映射到和文本一样的语义空间里，让模型既能读文字，也能理解图表趋势、物体位置、场景氛围。这就好比给一个原本只能读文字的人配了一副眼镜，但问题也随之而来——眼镜戴上之后，他还得知道往哪儿看、看完做什么。这个"看完做什么"，就是Agent要解决的。
1.2 我理解的Agent能力闭环：感知、理解、决策、行动
做视觉Agent之前，我画过一张很朴素的能力闭环图：
- 感知（Perception）：拿到图片或视频帧，完成预处理、裁剪、压缩，保证信息不丢失。
- 理解（Understanding）：通过视觉模型输出文字描述、检测框、OCR结果、结构化数据。
- 决策（Decision）：根据理解结果，结合用户指令和历史上下文，决定下一步动作。
- 行动（Action）：调用外部工具，比如查询数据库、点击界面、写文件、发请求。
这四步看起来像教科书，但真正做起来容易漏。最常见的错误是把"理解"当成全部，也就是让模型把图片转成一段文字描述，然后直接拿这段文字去回答用户。这在简单问答里行得通，一旦任务变成"帮我统计这批发票里有多少张金额超过5000"，单次描述就不够用了。模型需要先批量识别，再对结果做聚合、筛选、排序——这已经不是一次看图能完成的，而是需要规划和多步执行。
所以我的结论是：视觉Agent的核心不是某个模型，而是一套围绕视觉输入设计的工作流。模型负责"看懂"，Agent负责"办成"。
2. 整体架构设计：把视觉理解拆成可落地的模块
2.1 我的最小可行架构
第一次做视觉Agent时，我犯了一个很典型的错误：一上来就搭了六个微服务，结果数据在模块之间传来传去，光排查序列化问题就花了两天。后来我收敛出一套最小可行架构，总共四个模块：
- 视觉输入网关：负责图片接收、格式校验、压缩、切片。
- 视觉理解引擎：加载视觉语言模型，输出标准化的JSON结果。
- 任务编排器：根据用户意图决定调用一次理解还是多次理解，维护子任务列表。
- 工具执行层：把编排器的决策变成实际动作，比如读写表格、执行Python脚本、调用搜索。
这套架构没什么高深的技术，但它逼着我定义清楚了一件事：每一层之间传输的数据结构必须是JSON，而不是文本。视觉模型输出的原始文本在理解引擎内部完成解析，转成{"type": "detection", "objects": [...]}这类结构后再传给上层。这样编排器不需要关心图片长什么样，只需要基于结构化结果做决策。
2.2 为什么要单独拆出"视觉预处理"层
很多项目没有预处理层，图片直接喂给模型。我当时也是这么干的，然后发现了三个问题。
第一，分辨率过大导致推理速度慢。一张4000x3000的照片直接传进去，显存占用翻倍，响应时间从2秒变成8秒。第二，图片方向不对导致识别率骤降。手机拍的单据经常是歪的、反的，不做校正直接输入，模型会犯很低级的错误。第三，局部细节被全局缩放丢失。小票上的金额字号很小，整图压缩后变成一团噪点，OCR识别准确率明显下降。
后来我在预处理层加了三个默认动作：EXIF方向修复、长边限制到1600像素、对疑似小字号区域做四倍放大切片。这一步用到的都是成熟的图像处理手段，但收益远超我想象——同等模型下，票据字段识别准确率能提升十个百分点左右。这个预处理层就像人进考场之前先擦擦眼镜、坐到前排，看起来不是核心能力，却直接决定考试成绩。
2.3 状态记忆：Agent不能只看这一张图
视觉Agent和单次图片问答最大的区别在于，它需要"记得"之前看过什么。比如用户说"这张发票和昨天那张是同一家公司吗"，Agent如果没有昨天那张图的结构化结果，就答不上来。
我的做法是维护一个轻量级的视觉记忆库，每次理解引擎产出的结构化结果都带时间戳、来源图片ID和内容摘要，存进本地向量索引里。新一轮对话时，任务编排器先从记忆库里检索相关条目，拼进当前上下文。这个设计帮我解决了一个很实际的问题：用户不会把所有信息一次性给全，而是像和人聊天一样，想到什么补什么。
3. 视觉模型接入与提示词设计：让模型真正"看图说话"
3.1 选型时我重点看三个指标
接入视觉模型之前，我在选型上犹豫了很久。市面上能选的有闭源API和开源权重两条路线，公开参数五花八门。结合自己的项目需求，我只盯着三个指标。
第一是OCR和版面理解的综合准确率。判断方法很简单，拿我自己手上的50张真实单据去测，不看官方榜单。第二是结构化输出能力，也就是模型能不能稳定输出JSON而不是夹带散文。第三是长上下文下的视觉表现，图片多、轮次多之后，准确率会不会崩。实测下来，不同模型在这三个维度上的反差很大。有的基准测试分数很高，但真给它一张光线很暗的实拍图，给出的描述充满编造成分；有的模型响应速度慢，但对版面结构的把握更扎实。
我不打算推荐某一家模型，更想强调方法论：拿自己的数据建一个小测试集，每次替换模型都跑一遍，用同一套指标判断好坏。这个测试集我从项目第一天就在积累，后面的模型升级都靠它把关。
3.2 提示词模板：把"看图"转成"结构化输出"
视觉模型的提示词和纯文本模型有一个显著差异——你不仅要告诉它"回答什么"，还要告诉它"倾向于从图像的哪个层面去回答"。我最终沉淀下来的提示词结构大概是这样：
- 角色设定：你是一个视觉信息抽取引擎。
- 任务指令：输入一张图片，完成指定抽取任务。
- 输出约束：只输出JSON，字段包括
items、summary、uncertainty。 - 关键细节要求：对每个识别到的字段，给出坐标框
bbox和置信度。 - 拒绝策略：无法确认时输出
unknown，严禁编造。
这几点里，"uncertainty"字段一开始我是拒绝加的，因为它让输出变得啰嗦。但后来发现，视觉模型在低光、遮挡情况下会一本正经地编造信息，强制模型输出置信度能显著减少幻觉。有时模型识别出"金额：999"，同时写着confidence: 0.61，我们就能知道这个结果需要复核，而不是直接入库。
3.3 多图输入与截图场景的特殊处理
视觉Agent不总是处理单张图。有一次我接了一个任务，用户一口气上传了二十多张合同照片，要求找出所有"违约金比例超过10%"的条款。如果简单地把所有图片拼进一个上下文，模型后半段基本处于"忘记前面图片"的状态，输出质量极不稳定。
这里我采取的办法是"先整体后局部"：先把所有图片压缩成小尺寸缩略图，让模型快速筛选出疑似包含关键条款的图片，再对筛选出的图片做高分辨率单图抽取。两步走看起来绕路，但整体效率和准确性都明显高于一次塞入多图。截图处理则刚好相反，截图通常是高清的、结构清晰的UI界面，重点不在OCR，而在于理解界面元素的层级关系和操作热点。这个场景我后面会单独展开。
4. 工具调用与记忆机制：让Agent具备连续行动能力
4.1 从"单次问答"到"多步任务"的跳转
如果你只是想让Agent"看一下这张图然后回答"，通常不需要复杂的编排逻辑。但视觉Agent的典型价值场景是多步任务——"识别所有收据，然后按日期排序，再算每周合计，最后生成表格发送到邮箱"。
实现多步任务，我依赖的是让模型能看到"工具清单"，并自己决定调用顺序。每个工具的描述写清楚输入输出。比如：
extract_fields(image_path, schema)：按规则抽取图片字段。query_memory(condition)：从历史视觉记忆里查结果。aggregate_data(records, group_key)：对结构化记录做聚合计算。write_xlsx(records, path)：把结果写成表格文件。
任务编排器不预设路径，只提供目标和约束。模型读到"把收据按日期排序"时，会自己选择先调用extract_fields遍历所有图片，再调用aggregate_data排序，最后调用write_xlsx。这种做法的好处是灵活，缺点是模型可能选错工具路径，所以我给编排器加了一个"最大步数限制"和"路径回退"机制——一旦某步执行结果和预期偏差过大，就回到上一步重新调用。
4.2 工具调用之后的视觉结果回传
工具调用看起来简单，实际操作里最容易被忽略的是"工具结果如何回填给模型"。比如Agent调用了extract_fields，拿到一个包含五张票据的JSON数组。如果直接把这个JSON塞进上下文，问题不大。但如果工具调用的是搜索接口，返回了大量网页文本，再叠加原本的图片token，上下文很容易拥堵。
我的处理方式是给工具结果做"摘要化回传"。也就是说，工具层返回的结果先经过一个压缩摘要器，保留关键字段和结论，再作为观察值（Observation）传给模型。这个摘要器我用的是规则+小模型双重策略，规则兜底保证字段完整，小模型负责生成可读摘要。做完整套之后，Agent进行多步推理时，上下文增长明显变慢，决策质量也稳住了。
4.3 记忆机制：别让Agent"看完就忘"
前面提到的视觉记忆库，在工具调用链里还有一个更细的用处：作为工具的"缓存"。同一批图片可能被不同任务反复使用，如果没有记忆，每次重新识别一遍不光花钱，还慢。
我设计了两层记忆：短期记忆和长期记忆。短期记忆存的是当前任务执行过程中的中间结果，任务结束后清空；长期记忆存的是做完之后沉淀下来的结构化结论，比如"这些发票归属项目A，总金额约12万"。长期记忆写入前我会做一步去重校验，避免同一张图片在不同时间被识别后，结论冲突导致旧数据被错误覆盖。
5. 典型场景实测：票据识别、表格结构理解、截图操作
5.1 场景一：票据/证件识别，关键字段抽取
票据识别是视觉Agent最接地气的应用。我拿自己的项目做了个小范围实测，场景是这样的：用户发来一张出租车发票照片，要求提取发票代码、发票号码、金额和日期字段，并判断是否属于可报销范围。
实测中我使用了前面说的预处理三件套，外加一个针对票据的提示词模板。第一版的字段级准确率在87%左右，主要错误来自两类：一类是发票号码里的"0"和"O"混淆，一类是日期里的"6"和"8"看反。我没有急着换模型，而是在预处理层加了"局部放大切片"和"后处理校验"。校验规则很简单——发票号码每一位都是数字和大写字母，不匹配就标记为低置信度。第二版准确率提升到了94%，剩余6%靠置信度字段送人工复核。
这个场景给我的启发是：视觉Agent不能光依赖模型能力，工程侧的后处理校验往往能解决一半以上的"眼神不好"问题。
5.2 场景二：表格与图表结构理解
表格理解比票据识别更费劲。票据字段位置相对固定，表格式图片则是千奇百怪，有合并单元格、斜线表头、跨页大表，还有手绘表格。
我测试的场景是让Agent读取一张项目进度表的截图，输出每个任务的负责人、截止日期和完成状态。第一版直接丢给视觉模型，输出结果出现了两个问题：一是模型把表格里的空单元格凭空填上了"暂无"，二是复杂表头下，模型把"已完成"和"未开始"两列的内容搞反了。
后来我在提示词里增加了一条强制要求："只描述图像中可见内容，空单元格必须输出null，禁止猜测。"同时要求模型按"行列坐标"的方式输出单元格内容，而不是按视觉从左到右的自然顺序。改成坐标输出后，拼接错位的问题大幅减少，模型能更稳定地还原表格结构。事后我复盘，坐标输出的价值在于它强迫模型在空间上对齐信息，而不是在语义上自由发挥。
5.3 场景三：截图任务操作，GUI Agent的雏形
第三个场景我试得很兴奋，让Agent看一张软件界面的截图，然后回答"用户如果想导出报表，应该点击哪里"。这其实是GUI Agent最基础的一步——从截图中理解界面元素和操作路径。
这个场景对视觉模型的要求和其他场景很不一样。它不需要精确识别图片里的每一个字，但需要理解界面布局：按钮在哪、弹窗和主界面的层级关系、哪些区域是可点击的。我用的方案是让模型输出一组带坐标的交互元素列表，每个元素包含类型（按钮、输入框、标签）、中心坐标、文字描述和操作建议。
实测下来，常见工具软件的界面识别效果不错，但遇到自绘控件和复杂嵌套弹窗时，模型容易漏识别。我的结论是，GUI Agent只靠静态截图理解还不够，需要结合界面结构树信息（比如无障碍树、DOM结构）做交叉验证。截图语义理解负责"看"，结构树负责"确认"，两条腿走路才稳。
6. 评测方式与优化方法：如何确认Agent真的看懂了
6.1 不只是看最终准确率
视觉Agent做得越多，我越觉得评测是个大问题。很多人只看最终答案对不对，比如"金额识别对了几条"。但视觉Agent是分阶段的系统，最终准确率无法告诉你问题出在感知层还是决策层。
我的做法是给每个阶段单独留日志。感知层记录预处理后的图片尺寸、切片位置；理解层记录模型的原始输出JSON；决策层记录Agent每一步选择的工具和参数。出问题时，我能顺着日志回溯到具体环节。有一次系统把某项业务指标算错了，从最终结果看是聚合计算错误，但顺着日志一查，发现是早期某张图片被预处理层错误地裁掉了一截，才导致后续数据全乱。
这里我非常建议做一张可视化排查页，把图片缩略图、识别框和置信度直接画在图上。肉眼扫一眼，比盯着十页JSON日志直观得多。
6.2 三个关键维度：准、全、稳
我在项目里逐步确定了三个评测维度：
- 准确性（Precision）：识别出的内容和客观事实一致性有多高。重点考察是否编造了图片里不存在的信息。
- 完整性（Recall）：图片里应该被找出来的信息，是不是都找到了。重点考察有没有漏掉角落里的字段、被遮挡的文字。
- 稳定性（Stability）：同一张图、同一条指令，反复跑十次，结果是否一致。视觉模型的解码过程有随机性，稳定性差的任务没法做自动化和批量处理。
三个维度要分别打分，而不是折算成一个总分。很多时候一个Agent准确性很高但完整性不行，它会把最有把握的内容做得很好，但漏掉大量边缘信息，这种Agent实际使用起来很痛苦。
6.3 最常见的三种"假看懂"
我在评测中还总结出了三种典型的"假看懂"现象，分享出来帮你排雷。
第一种叫"望文生义"。模型一看图里有个人，再一看旁边的文字"病历"，就开始猜测"病人发烧咳嗽"，但图里其实只有一张空白病历封面。第二种叫"选择性失明"。模型对图片中央的大元素描述得头头是道，但对边缘的日期戳、角落的水印编号视而不见。第三种叫"自洽幻觉"。模型识别出的数字本身能对上合计金额，但合计金额和明细项对应关系错位了，看起来合理，实质是错的。
应对这三种现象，我的方法各不相同。望文生义靠拒绝策略和低置信度标记，选择性失明靠预处理切片和多区域独立识别，自洽幻觉靠引入外部校验规则，比如金额一致性校验、商品名和类别映射。
7. 踩坑记录：视觉Agent最容易翻车的地方
7.1 分辨率陷阱：压缩了就会瞎
视觉模型对图片分辨率极其敏感。我一开始为了省显存，把所有图都压到512像素以内，结果识别票据小字时频繁出错，金额数字经常从"25.5"变成"23.5"。后来我做了个对照实验，同一张票据分别在原始分辨率、长边1024、长边512下识别，准确率差距高达二十个百分点。
现在我的原则是：重要文档类图片不做暴力压缩，优先做裁剪切片。宁可把一张大图切成四块分四次识别，也不要把整张图压到看不清。压缩只用于快速初筛，用于精抽取的图必须保留足够的像素密度。
7.2 指令遵循和视觉幻觉之间的平衡
提示词写得太宽松，模型会乱发挥；写得太严格，模型又会变得畏手畏脚，该识别出来的都不敢说。我试过一种极端提示词"任何不确定的信息都不要输出"，结果模型把很多本来能正确识别的内容也标成了unknown，完整性暴跌。
后来我把策略改成"分层置信度"：强约束只针对关键字段，允许模型输出不确定判断，但必须附带置信度和原因。比如"金额字段识别为998.5，置信度0.92，备注字段无法确认，原因是图片右下角被手遮挡"。这种方法既不压抑模型的视觉能力，又给人留了复核空间。
7.3 上下文污染：前面的对话会带偏后面的视觉判断
多轮对话里的视觉Agent有个隐蔽的坑：用户前面说了一句话，就可能污染模型对后面图片的判断。比如用户先问"这张发票是不是被改过"，问完之后又传了一张图片问"这张呢"，模型可能会在第二张图里"找"出伪造痕迹，哪怕第二张图完全正常。
这种上下文污染很难彻底消除。我的缓解办法是在每轮视觉识别前，把对话历史压缩成"任务背景摘要"，而不是原样保留所有用户话语。视觉理解引擎只接收干净的图像和当前指令，减少被前序对话带偏的概率。尤其是在自动化和批量处理场景，每一轮识别我都尽量做到"无状态"，除非确实需要跨图比较。
收尾的一点心得
做完这个视觉Agent项目，我最大的体会是：视觉理解的瓶颈往往不在模型，而在工程。模型负责提供可能性，Agent负责兜住稳定性。一个视觉Agent要真正可用，靠的不是某一个参数或者某一段提示词，而是预处理、结构化输出、后校验、记忆管理这一整套系统配合。
如果让我给后来者一个具体的建议，我会说：从你自己的30张图片开始，先做出一个"单图理解+输出JSON"的最小闭环，再逐步加上任务编排和工具调用。不要一上来就追求完美的多轮对话，先把单次看图、看准、看清这件事做到极致。视觉Agent这条路还很宽，但每一段都要踩实了再往前。
