大模型应用做多了慢慢会发现一个尴尬的事实模型脑子里装的东西再多也就是个会说话的脑袋。你问它什么它能答得头头是道但你要它自己去截图看一眼报错、查一下业务数据、把结果写进表格、再发给相关的人——它就傻眼了因为它既没有眼睛也伸不出手。所以这段时间我一直琢磨一件事怎么给大模型把眼睛和手装上。眼睛负责看——截图、OCR、图像理解手负责干——查接口、执行代码、操作页面。琢磨来琢磨去最后选定 anythingLLM 来做整个底座把它打造成一个能看、能查、能调接口干活的 AI Agent。今天这篇就把我的选型思路、装配过程、踩坑记录一次性讲清楚看完你也能照着搭一套出来。这套方案适合什么人适合已经有一定大模型使用经验、想让模型真正介入业务流程的开发者也适合运维、测试、运营这些想把日常重复活儿交给 Agent 的实操型同学。不需要从头写一套 Agent 框架anythingLLM 已经把底座、对话、知识库、工具调度这些都包好了我们只需要做接线的工作。1. 底座选型为什么是 anythingLLM说实话市面上能搭 Agent 的工具不少有重型的开发框架也有各种商业平台但一圈比对下来anythingLLM 在我这里赢在三个点上。1.1 模型无关想换大脑随时换anythingLLM 是把模型接入和应用逻辑解耦的。它支持接本地模型运行时比如 Ollama 这类也支持接各种云端模型 API而且可以同时配置多套在不同工作区里用不同模型。这意味着什么意味着大脑可以随时换。今天是通用对话模型负责调度明天我想让一个专门的轻量模型处理 OCR 结果分析后天我发现某个模型推理能力不行直接改配置就切走了业务代码一点不用动。对做实际项目的人来说这种模型中立太重要了你永远不知道下一个更好的模型什么时候出来绑定死一家就亏了。1.2 工作区加知识库天然的 RAG 骨架Agent 要干活光靠模型肚子里那点知识远远不够它得能查项目文档、查历史数据、查团队规范。anythingLLM 的工作区Workspace设计在这一环非常省事每个工作区可以上传独立文档系统自动做向量化回答问题时检索增强。这比我自己拿向量数据库从零搭一套 RAG 要省太多事。我实际用下来的感受是它的文档解析和检索效果在开源方案里属于相当能打的。我给它丢了几十页的项目运维手册、接口文档、排障 SOP它基本都能在回答问题时引用对段落不会答非所问。1.3 Agent 模式自带工具调度能力很多人不知道anythingLLM 不是单纯的聊天问答工具它内置了 Agent 运行模式。在这个模式下模型不只是生成文字而是会被赋予一组工具它可以自己判断这个问题需不需要调用工具调用哪个工具拿到结果之后怎么继续。这正好是我要的手的雏形。而且它是可视化配置的不用像在开发框架里那样写一堆注册代码。对非专业程序员来说很友好对专业开发者来说也能省掉大量胶水代码。2. 整体架构大脑、眼睛、手三段式拿到一个项目先不急着动手我把整个 Agent 的能力模型拆成了三段大脑、眼睛、手。这个拆法能让后面每一步都清楚——哪里该接什么、哪里缺什么。2.1 大脑负责想不负责看和干大脑就是大模型本身在 anythingLLM 里就是那个对话模型。它要做的事情是意图理解、任务拆解和决策调度。比如我跟 Agent 说帮我看看昨天线上那台机器为什么告警。大脑收到这句话后要做三件事判断看监控截图需要用眼睛判断查告警记录需要用一只手调接口然后决定先调哪个、拿到结果怎么综合分析。它自己不直接看图片也不直接发 HTTP 请求它是指挥官。这里有个特别重要的设计理念别让大模型亲自处理它不擅长的事。视觉推理能力再强也不如专门的 OCR 引擎识别得快、准写代码能力再强也不如直接调封装好的接口稳定。所以大脑的任务是想清楚怎么做剩下的都交给外围模块。2.2 眼睛负责看把世界变成文字眼睛这一层我把它定义成一切能把视觉信息变成模型能理解的东西的模块集合。什么东西属于眼睛截图工具、OCR 识别服务、图片描述接口、表格识别引擎全是眼睛。为什么要单独做眼睛层因为大模型的理解入口是文本。模型再强本质上也还是对文字做概率预测。图片对它来说是一堆像素矩阵除非是多模态模型直接看图否则它需要眼睛先把图片翻译成文字比如把一张系统监控截图翻译成CPU 使用率 95%内存 80%磁盘 I/O 偏高。我给眼睛定的原则是能转成结构化文字的绝不让模型去看图猜。OCR 能识别的文字直接给文字需要描述场景的让图像描述模型产出结构化描述能转成表格数据的一定要按 JSON 格式输出方便下游工具处理。2.3 手负责干连接真实世界的动作手就是一切能改变外部状态、获取外部数据的工具集合。HTTP 请求、代码执行、数据库查询、文件写入、调用通知接口推送消息这些都是手。手的设计有一个度要把握不是每个操作都要做成单独的手。有些简单操作比如算个数、转个格式让模型自己写代码执行就行而有些关键操作比如查询订单状态发送审批通知这些涉及外部系统核心逻辑的一定要封装成固定参数的接口不能让模型自由发挥。我搭这套东西的时候手是最花时间的部分。原因很简单大脑和眼睛都有现成的开源方案但手必须针对你自己的业务场景去接。你公司的订单系统、监控系统、工单系统和我的完全不一样。所以这一部分最需要花心思设计。3. 给模型装上眼睛视觉能力从哪来开头我说了三种装眼睛的方案这里逐个展开说包括各自适用什么场景、有什么坑。3.1 最省事直接选用多模态模型如果预算允许、数据也不太敏感最简单的方式是直接用带视觉能力的多模态大模型。把图片作为输入的一部分直接发给模型它看一眼就能回答这是什么图里写了什么。这个方案的优势是零额外开发模型天生就会看图。但劣势也很明显一是贵图片按像素算 token一张高清截图消耗的 token 比几千字文本还多二是慢图像推理比纯文本慢不少三是它未必擅长细活比如识别一张截图里的小字表格多模态模型经常看走眼。所以我的用法是多模态模型只用于需要理解图片语义的场景比如分析一张架构图、看一张产品设计稿、判断一张截图里有没有异常告警弹窗。它负责看懂不负责抠字。3.2 最实用OCR 引擎加结构化输出真要处理文档、截图、发票、表格这类图片里的文字信息老老实实用 OCR 引擎比什么都强。本地部署一个开源 OCR 引擎类似 Tesseract 这类成熟项目把它封装成一个 HTTP 服务接收图片、返回文字干净利落。OCR 方案我在实际项目里用下来识别印刷体、屏幕文字的效果相当好尤其是在中文场景下准确率能做到 95% 以上。处理扫描件、发票、代码截图、报错弹窗都是它的拿手好戏。但 OCR 也有自己的脾气。识别表格结构经常会乱同一张表格文字能认出来但哪行哪列的关系容易错位。手写体就更别提了基本不可用。解决方法是表格类图片优先转成 Markdown 表格格式输出手写体直接放弃交给人工处理不要硬上。3.3 眼睛的核心封装统一视觉服务不管底层用多模态模型还是 OCR 引擎我强烈建议你封装一个统一的视觉服务对外只暴露一个接口传图片进去返回标准的 JSON 文本。接口内部再根据图片类型自动路由——是纯文字截图就走 OCR是场景图就走多模态描述。这个封装的收益非常大。后期想换 OCR 引擎或者换视觉模型只需要改服务内部实现Agent 这边完全不用动。我踩过一次不封装的坑一开始直接在 Agent 工具里写死了调某家的 OCR 接口后来不稳定想换一家结果所有相关工具全要改烦到崩溃。下面是视觉服务的一个简单示例用 Python 写个路由层from flask import Flask, request, jsonify import requests, base64 app Flask(__name__) # 假设内部有两个引擎ocr_engine 和 vision_engine def detect_image_type(image_bytes): # 简单判断如果图片里像素分布比较平、文字密集走 OCR # 实际项目里可以用图像统计特征比如纹理复杂度 # 这里直接给个模拟判断生产环境建议先跑一批样本调阈值 return ocr app.route(/vision/analyze, methods[POST]) def analyze(): data request.get_json() image_b64 data.get(image) # base64 编码 img_bytes base64.b64decode(image_b64) mode data.get(mode, auto) if mode auto: mode detect_image_type(img_bytes) if mode ocr: # 调用 OCR 引擎返回 {text: 识别结果, type: ocr} result {text: ocr_engine.run(img_bytes), type: ocr} else: # 调用视觉模型引擎返回 {description: ..., type: vision} result {description: vision_engine.describe(img_bytes), type: vision} return jsonify({code: 0, data: result})3.4 把视觉服务挂进 anythingLLM视觉服务写好后要在 anythingLLM 里把它变成一个 Agent 可以直接调用的工具配置一个自定义工具即可。工具名称我取的是视觉分析描述写成输入图片路径或图片 URL返回图片的文字内容或结构化描述用于查看截图、识别文档、分析图像。描述一定要写清楚工具的适用场景和输入格式。这一点很多人忽略其实极其重要。大模型是靠描述来决定要不要调用这个工具的描述写得模糊它就可能在不需要用的时候也乱调或者在真正需要的时候想不起来。工具配置好后在 Agent 的模型参数里把工具开关打开。之后你可以直接发一张截图给它它就自动调用视觉服务然后基于识别出的文字继续跟你对话。到这步第一只眼睛就装上了。4. 给模型装上手从内置工具到自定义工具视觉搞定后开始装手。手是 Agent 真正能改变世界的那部分也是工程上最容易出事的地方。4.1 anythingLLM 自带的手够不够用anythingLLM 的 Agent 模式里预置了几个常用工具比如网页内容阅读、网页搜索。这几个工具对很多场景已经够用了。比如让它去读一个技术文档页面、查一条公开信息它真能自己完成搜索-阅读-总结的闭环。但自带工具的问题是它们太通用没法对接你私域的业务系统。你的内部系统不会开放给它的通用搜索工具去查所以核心的手还是要自己做。4.2 自己造手把内部接口封装成 Agent 工具给 Agent 造手本质就是把你现有的 API 接口包装成它能理解的样子。这里最关键的不是写代码而是做接口设计裁剪。我家里的实践是优先封装两类接口查询类接口订单、状态、日志、监控数据和执行类接口发消息、写记录、触发流程。查询类优先因为只读操作风险小执行类接口一定要加上参数白名单和二次确认。拿一个实际的工具来举例。我想让 Agent 能查某电商系统的订单进度后端有一个接口本来返回 50 个字段但 Agent 只需要其中 5 个。于是我做了一层精简代理只暴露几个必要参数订单号、时间范围。返回也只保留状态、金额、更新时间、当前节点。这样模型不需要在一堆无关字段里挑减少出错概率。工具返回格式建议统一用 JSON。我甚至会在 JSON 最前面加一段纯文本摘要让模型先看到结论再决定要不要继续追问细节。这个方法能显著减少模型因为返回内容太长而迷失的情况。下面是我封装的一个查询工具的示意代码部署成独立服务后在 anythingLLM 里注册成工具 订单查询app.route(/agent/order_query, methods[POST]) def order_query(): params request.get_json() # 参数白名单只认这两个字段别的全部丢弃 order_id params.get(order_id) date_range params.get(date_range, 7d) if not order_id: return jsonify({code: 400, msg: missing order_id}) # 调内部接口拿原始数据 raw internal_api.fetch_order(order_id, date_range) # 裁剪字段加摘要 summary f订单 {order_id} 当前状态{raw[status]}金额{raw[amount]}最近更新{raw[updated_at]} return jsonify({ code: 0, data: { summary: summary, status: raw[status], amount: raw[amount], updated_at: raw[updated_at], current_node: raw[current_node] } })4.3 给手装上安全锁手能干活也能闯祸。我这里说三个必须加的安全措施。第一是权限最小化。Agent 调用的接口账号绝不使用管理员权限只给到能查到这个 Agent 分内事的最小权限。曾经有人图省事给 Agent 配了个高权限账号结果一次工具调用参数解析异常把线上一条测试数据给覆盖了教训深刻。第二是超时和重试机制。大模型的思考速度不稳定工具返回也可能慢一定要设置合理的超时不能让一个工具调用永远挂着。重试次数也要限制最多重试两次再多就直接放弃并把异常告诉模型让它换一种方案而不是反复撞同一个错误。第三是执行类操作必须二次确认。凡是会修改数据的工具我对 Agent 的要求是先输出将要执行的操作内容和影响范围等用户明确说确认之后才真正执行。这一步能挡住绝大多数误操作。5. 实操过程从零搭到全流程跑通思路理清楚了下面是我实际搭这套系统的完整流程每一步都能直接照着做。5.1 部署 anythingLLM 实例我选择用 Docker 部署一来干净二来方便备份迁移。把容器跑起来后映射好端口和存储目录就完成了基础安装。这里有个小建议把数据目录挂载到宿主机磁盘要不然容器一删所有配置和知识库全没了。安装完进入管理界面第一件事是创建管理员账号第二件事是赶紧去设置里看一下模型连接配置。5.2 接入大脑配置模型在模型配置里我把两套模型都接上了。一套是本地部署的开源模型主要跑日常问答和简单调度数据不走外网响应也快另一套是云端的能力更强的商业模型 API处理复杂推理和长文档总结。这里分享一个重要心得不同工作区可以用不同模型。我建了两个工作区一个日常积累区用的本地模型处理文档问答一个任务调度区用的强模型专门处理复杂工具调用。这样既省钱又不牺牲体验。5.3 装眼睛部署视觉服务并注册工具按前面说的我把视觉服务部署在本机另一个端口然后用一个简单的脚本测试接口能正常返回。确认没问题后进入 anythingLLM 的工具配置页新增自定义工具填上服务地址和工具描述。注册工具后我做了一次快速验证传了一张系统报错截图Agent 通过视觉服务识别出错误关键字再根据知识库里的排障文档给出了对应的处理建议。这一条链路走通就说明眼睛真正长上去了。5.4 装手注册查询类工具我先注册的是无风险的查询类工具也就是那个订单查询工具。在工具配置里填好接口地址、请求方式POST、返回格式。测试时直接让 Agent 问查一下订单 A10086 的进度它成功识别出需要调用工具返回了摘要。到此手也装上了。接下来才开始注册写操作类工具而且我故意在 Agent 的指令里加了一条规则任何修改数据的操作必须等我确认后再执行。实测下来这个约束对控制风险非常有效。5.5 端到端实测让它完成任务闭环这里记录三个我跑通的真实场景你可以感受一下完成度。第一个场景是看给它一张新上线的页面截图让它检查有没有明显排版问题。它自动调视觉服务识别文字元素结合我对页面设计要求的知识库内容列出了一个初步的问题清单。虽然不能说像资深前端那样细致但作为初筛完全够用。第二个场景是查让它统计最近一周某分类订单的数量和金额趋势。它先调订单查询工具拿到明细再用内置的代码执行工具做聚合计算最后输出了一张简洁的统计表。注意我并没有教会它怎么调聚合函数它是自己决定用代码工具来算的。第三个场景是干让它根据查询到的订单数据生成一份简短的周报并调用消息推送接口发给指定群。这一步涉及查询、生成、推送三个动作需要模型连续调度三个工具最终完整跑通了。看到消息从群里弹出来那一刻确实有一种这家伙真的能干活了的感觉。6. 踩过的坑和排查心得最后说说我在这套系统上踩的坑。这些东西文档里不会写全是用时间和事故换出来的。6.1 模型乱调工具怎么办最大的坑是模型工具调用幻觉明明不需要查任何东西它偏要调一下工具再回答或者把参数传错把订单号传成了日期。排查下来根因通常是两个一是工具描述太宽泛让模型觉得啥都能查一下二是模型能力偏弱对工具意图判断不准确。我的解法是把工具描述写得极度具体甚至直接在描述里写清触发条件和不触发条件。比如订单查询仅当用户明确提到订单号或订单进度时调用闲聊不要调用。改完之后乱调用率直线下降。另一个有效手段是把思维链提示加进系统指令里要求模型不能在调用工具前就编造结论。具体做法是给 Agent 设定先分析需要什么信息再决定是否调用工具的流程。6.2 视觉服务结果不稳定OCR 对高清晰度截图效果很好但遇到有背景色的页面截图经常把背景干扰文字也识别进来。后来我在视觉服务里加了预处理逻辑先做灰度化和二值化再送识别引擎准确率提升明显。还有一次是表格截图整体错乱后来排查发现是图片分辨率不够。这个问题的解决方案很朴素教 Agent 在调用视觉工具之前先确认图片是否清晰因为很多截图工具默认缩放导致页面文字糊成一片。让 Agent 提示用户请截取清晰的原图能解决一半问题。6.3 上下文爆炸工具返回内容太长有一次 Agent 查询了一个大范围时间段的日志工具一次性返回了几万行文本。模型上下文窗口直接被塞爆后面的对话开始胡言乱语。解决思路是限制工具返回长度。我在工具服务端做了截断策略任何返回给模型的文本最多保留前 N 个字符超出部分用一句话概括其余 N 条结果已省略可通过指定条件缩小范围。同时我会在工具返回里附带一个查询建议引导模型在数据量大时主动缩小查询范围。这样模型就不会硬着头皮处理海量返回内容了。6.4 权限和审计不能省前面提到的权限最小化是其一其二是审计日志。每次 Agent 调用工具我都会记录下时间、调用方、入参、返回状态、耗时。一开始觉得麻烦直到有一次 Agent 误触发了一个测试环境的清理任务靠着审计日志才追溯到是哪条指令导致的。所以现在的做法是所有工具服务端强制开启请求日志至少保留 30 天。这不算什么高科技但关键时刻能省很多排查时间。7. 装完眼和手之后还能怎么扩展架构搭好之后后续扩展空间其实很大。视觉服务已经被抽象成独立模块新接一个自动截图的能力就能让 Agent 定时看完监控页面再汇报手这边把消息推送、日历、邮件这些常用能力封装成工具就能组一个能自己组织会议、发周报、跟进待办的助理 Agent。我个人目前的规划是先把内部知识库继续充实让 RAG 检索的覆盖面更全减少 Agent 靠猜回答的情况然后给视觉服务增加对图表的理解能力让它能从折线图、柱状图里提取趋势信息。等这两块补齐这套 Agent 的可用性会再上一个台阶。搭这套系统给我的最大体会是不要把注意力全放在大模型本身。模型的能力已经被卷得很高真正的瓶颈在两侧——感知端能不能把真实世界的信息喂给它行动端能不能让它的决策变成实际动作。眼睛和手才是 Agent 落地过程中最能拉开差距的地方。
