一个“会聊天的模型”和一个“会干活的模型”之间差的不是算力而是一整套把它架到生产环境里的工程链路。做这个全栈 AI 修图 Agent 项目我最大的感受是真正决定体验好坏的不是单次修图效果有多惊艳而是用户用自然语言说了一句话之后系统能不能稳定地把这句话拆成可以执行的步骤、按顺序调用工具、再把结果平安送回来。这篇文章就把这个项目从需求拆解、Agent 决策链路、全栈选型到多端适配踩坑的过程完整盘一遍给正在做或打算做 AI Agent 类全栈项目的朋友做个参考。1. 从一个“会聊天的大模型”到一个“会干活的修图助手”项目是怎么长出来的1.1 项目定位与背景这个项目的起点其实很朴素修图工具已经很多了美图秀秀、Photoshop、Canva 都很成熟AI 修图能力也不算新鲜SDStable Diffusion生态里的 ControlNet、局部重绘、图生图都能干不少事。但有一个场景始终很痛——对非专业用户来说修图工具的功能太碎学习成本太高。你让一个普通用户理解“蒙版”“曲线”“通道”这些概念不现实他们想要的就是一句“帮我把背景换掉”“把脸上油光去掉”然后完事。市面上已有的 AI 修图产品很多只是把某个单一能力包了一层壳输入输出都是固化的用户没法做“组合操作”。比如“把这个产品图抠出来换到一张户外场景里再整体调成暖色调”这种涉及多个图像处理步骤、需要前后依赖的任务传统工具要么做不到、要么需要用户手动一步步操作。这个项目想解决的就是让用户用自然语言下发一句话系统通过 Agent 自主规划、调用工具、执行并返回成品图。1.2 为什么要用 Agent 而不是写死流程一开始我确实想过更省事的方案直接调大模型的图像生成接口把用户指令拼进 Prompt让模型端到端出图。这个方法在简单需求上确实能用但问题也很明显——可解释性差、可控性差、算力成本高。比如用户说“把左上方那个杂物去掉”端到端出图模型往往会重新生成整张图连背景结构都变了有时候还会在无关区域乱发挥。Agent 方案则把链路拆开了大模型只负责“理解”和“决策”真正动手的是底层一个个具体的图像处理工具。大模型生成的是 JSON 格式的工具调用指令类似“先执行 tool_remove_object参数是 bbox[...]”每个工具只负责一个明确动作结果可验证、可回滚、可追踪。这样做的好处很实际单个修图步骤的质量由传统成熟的算法或专用模型保证大模型只做调度效果稳定性和容错率都高出一大截。1.3 项目最终形态整个项目做完之后用户端的体验是这样一条链路用户上传一张原始图片输入一段自然语言指令语音或文字都可以前端接了语音识别接口后端 Agent 服务接收任务把用户指令和大模型的系统提示词一起送入大模型大模型返回结构化 JSON描述需要执行的修图动作序列Agent 编排引擎按顺序调用图像处理工具每个工具执行完更新中间状态全部步骤完成返回最终图片和操作日志前端在 web 端、小程序端、App 端都能看到结果。这个形态的核心优势在于用户永远不用关心“怎么修”只关心“想修成什么样”。而对我们开发者来说每次修图动作都是可审计的出问题了能定位到具体是哪个工具、哪一步失效而不是对着黑盒模型干瞪眼。2. 修图 Agent 的决策链路拆解意图识别、步骤编排与工具调用2.1 意图识别层把模糊语言变成结构化指令这是整个 Agent 系统里最容易被低估的一环。普通用户说“天空不够蓝”模型需要判断这是“整体调色”还是“局部区域调色”说“把这个修得高级一点”“高级”是个很虚的词得先映射到具体的视觉特征上——可能是对比度、饱和度、色调的统一性。我做意图识别的时候没有让单次大模型调用完成所有事而是分了两层第一层是粗分类用一个轻量模型或者关键词规则辅助把用户指令分到“人像美化”“背景处理”“色彩调整”“物体编辑”“清晰度增强”这几个大类第二层才是细粒度理解把用户指令连同图片的元信息尺寸、主体位置检测结果一起送入大模型让它输出结构化工具调用。这么拆是有原因的。粗分类能让 Agent 提前加载对应领域的工具集合不用把所有工具描述都塞进大模型的上下文里既省 token成本又能减少模型在大量工具描述之间的“选择困难”。比如用户指令被粗分类为“人像美化”后模型只需要从“磨皮、美白、瘦脸、祛痘、眼睛放大”这几个工具体系里选而不是面对二十多个工具的完整 JSON Schema 描述。2.2 步骤编排多步修图的前后依赖怎么管理修图动作往往不是孤立的。最常见的连锁场景抠图 → 换背景 → 光影融合 → 整体调色。每一步的输出是下一步的输入中间任何一步失败后续都不能继续。步骤编排层我实现了一个轻量的 DAG有向无环图执行器每个工具调用被封装成一个节点节点有输入输出定义和前置依赖。大模型返回的不是一串扁平的调用列表而是一个带依赖关系的计划。比如说“把这个人抠出来放到海边”计划可能是这样步骤1: tool_segment_human → 输出: 前景主体 PNG带 alpha 步骤2: tool_generate_background(beach) → 输出: 背景图 步骤3: tool_composite(前景, 背景) → 输出: 合成图 步骤4: tool_color_grade(warm_tone) → 输出: 最终图这里有个很关键的设计每步工具执行后都会生成一张中间图Agent 会把这些中间图的状态“汇报”给大模型一次让它决定是按原计划继续还是根据中间结果动态调整后续动作。比如抠图后发现主体边缘发丝残留严重大模型可能会追加一步“边缘修复”再进入合成环节。这种“执行-反馈-再决策”的循环是 Agent 和普通脚本流水线最本质的区别。2.3 工具层的注册与调用机制工具层我用的是一个类似插件的注册表机制。每个修图能力就是一个独立服务对外暴露统一的 HTTP 接口或 gRPC 接口然后在 Agent 框架里注册一份“工具描述”——包括工具名称、功能描述、输入参数 JSON Schema、输出格式。注册表里的描述会被拼进大模型的系统提示词中成为大模型编排时的“选项菜单”。工具描述写得越清楚大模型用错的概率越低。我后来把一个教训沉淀成了规范工具描述里一定要写清楚“什么时候用它”和“什么时候不要用它”。比如“tool_enhance_clarity清晰度增强”的描述如果只写“增强图像清晰度”大模型可能在处理老照片修复时忘记调用它也可能在色彩调整时错误地调用它。改成“当图像模糊、噪点多或细节不足时调用不适合作为色调风格的调整手段”之后调用准确率明显提升。图像处理工具的后端实现我混合用了 OpenCV 传统算法和几个垂直小模型抠图用了现成的分割模型类似 rembg 那套超分用了 Real-ESRGAN局部重绘和生成式填充走了 SD 生态。这里给大家一个建议不要试图每个工具都自己训练模型能用成熟方案的就用成熟方案重点把 Agent 调度和工具接入层做好性价比高得多。2.4 工具调用返回结果的验证大模型生成 JSON 调用了某个工具并不代表这个工具真的执行成功了。工具执行完会返回一个状态码和数据但更重要的是一层视觉验证——比如“移除物体”工具执行完需要检查目标区域是否发生了像素变化、是否有明显的修补痕迹。这层验证我用两套方法一套是计算目标区域的像素差异另一套是把执行后的中间图再送回一个视觉理解模型做质量打分。如果一个步骤验证不通过Agent 不会直接把这个坏结果交给用户而是触发重试机制——换个参数再执行一次或者把失败信息回传给大模型让它调整计划。这一步对用户体验的兜底价值非常大否则用户拿到一张修到一半、有明显撕裂感或脏乱的图会瞬间失去对产品的信任。3. 全栈技术选型为什么是 vue golang uniapp 这一套组合3.1 后端为什么选 golang长连接和任务调度的天然契合选 golang 做后端核心原因有三个都不是跟风而是实际场景推着走的。第一个原因是 Agent 编排过程的“长任务”特性。一次复杂的修图流程可能要跑几十秒甚至几分钟中间还有多次大模型调用和图像处理服务交互。这跟传统请求-响应模式完全不一样更接近异步任务编排模式。golang 的 goroutine 在处理这类并发任务调度时非常干净一个任务一个 goroutine跑完自动回收写起来不像 Java 那套线程池要考虑各种拒绝策略。第二个原因是部署和运维成本低。golang 编译出来是一个单二进制文件配合容器部署非常省事。这个项目要跑的服务不少——API 网关、Agent 编排引擎、图像处理 worker、对象存储——用 golang 的服务可以做到构建镜像很小、资源占用可控在一台 4C8G 的云服务器上能稳定跑完整套。第三个原因是大模型 API 的流式响应处理。Agent 在编排过程中和大模型的交互如果用流式输出golang 的 net/http 和 channel 配合 SSE 协议非常顺手。我在开发中大量用了流式能力中间步骤执行完就立刻把进度推给前端用户看着“正在抠图 → 正在合成 → 正在调色”一步步推进体感上比干等十几秒黑屏好太多。3.2 前端为什么是 vue uniapp一次业务逻辑多端复用前端选型的核心矛盾是既要覆盖 Web 用户又不能放弃小程序和 App 流量。如果三端分别维护三套代码光修图参数面板和任务进度组件就要写三遍排期和 bug 数量都hold不住。uniapp 在这里的价值是让 Vue 组件的逻辑可以跨端复用。不过这里要提醒一句实话uniapp 的“多端复用”在表单、列表这些常规场景很舒服但遇到 Canvas 图像预览、大图加载、原生组件覆盖这类和宿主环境强相关的场景还是免不了写条件编译代码。项目里 Web 端用的 Canvas 绘制裁剪框小程序端就必须走原生 canvas 组件差异挺大的。所以我的原则是业务逻辑和状态管理尽量 H5与宿主环境强相关的能力用条件编译单独处理。3.3 任务状态流转的设计从提交到结果的完整链路前端和后端之间我设计了一套任务状态机这是整个全栈交互的核心协议状态含义前端展示PENDING任务已创建排队中进度条初始化PLANNING大模型正在解析指令、编排步骤“正在理解你的需求…”EXECUTING工具按序执行中展示当前步骤名和省流预览VERIFYING结果验证中“正在检查效果…”SUCCEEDED全部完成展示最终图 操作日志FAILED失败展示失败原因 重试按钮这个状态机不仅是给前端用的也是 Agent 编排引擎的驱动核心。每个状态之间的流转都会有事件触发事件可以来自大模型回包、工具执行结果、验证服务的信号。我还在状态流转时加了超时兜底——任何状态超过预设时间没往下走服务端会主动标记为失败并返回错误信息避免用户拿着一张永远转圈的任务卡到天荒地老。用户上传图片后前端先把它传到对象存储拿到 URL再把“图片 URL 自然语言指令 任务参数”一次性提交到后端。图片字段用 URL 而不是 base64 传输是性能和体积的必然选择移动端网络环境不可控一张手机原图动辄 5-10MB用 base64 会让请求体膨胀 30% 以上加上 JSON 转义开销很大。早期我图省事直接在请求里传 base64结果用户多的时候网关层经常撑不住后来才老老实实走分片直传对象存储的方案。3.4 实时进度的通信选型轮询还是推送修图任务不是即时返回的实时进度必须做推送。我在项目里同时实验过 WebSocket、SSE 和轮询三种方案最终给不同端做了区分Web 端优先用 SSE。服务端把 Agent 编排进度流式推给前端自动递归、重连机制比 WebSocket 简单而且 SSE 本质就是 HTTP对代理和负载均衡更友好。小程序端/App 端用轮询 增量拉取。小程序对长连接的支持以及切后台时连接被回收的坑比较麻烦我干脆做成每 2 秒拉一次任务状态。任务状态轻易不变实际开销也不大轮询的稳定性和省心程度反而更好。这里要专门说一个踩过的坑用 WebSocket 推送进度的时候前端如果长时间没有发心跳很多云服务商的负载均衡层会静默断开连接而且不告诉你。用户那边看进度条直接卡死服务端却以为连接还好好的。后来我在前端加了 30 秒一次的应用层心跳附带一个 sequence 编号服务端如果发现心跳序号不连续就能感知断线并让前端重新连接这个问题才算治住。4. 开发中踩过的四个深坑上下文、超时、图片体积与成本失控4.1 多轮对话上下文膨胀Agent 是怎么“失忆”的Agent 场景里最容易出问题的地方是大模型上下文的维护。用户和 Agent 的交互不是一次性的——修完图之后用户经常追加指令“背景再模糊一点”“人物往左移”。如果每次追加都把历史对话完整发给大模型上下文会越来越长最直接的后果是大模型把前面的对话“忘掉”了或者注意力被无关信息分散开始胡编工具参数。我处理这个问题做了两件事。一是滑动窗口截断历史消息只保留最近的若干轮更早的关注核心信息会被压缩成一段摘要文本。二是把中间图片从对话上下文里剔除每轮修图产生的中间图只保留“操作描述 关键参数”不让大模型在对话里反复看图像数据也省 token。经过这一层处理Agent 在五轮、八轮、十轮连续对话后的指令理解准确率基本稳定。对了还有个便宜但好用的技巧在系统提示词里明确告诉大模型“用户的新指令永远是最近的、优先级最高的”当用户说“把整体调亮一点”时模型会优先基于当前最新图片状态理解而不是被三分钟前那句“调成冷色调”带偏。4.2 长耗时任务的超时控制从 HTTP 超时到异步任务化整个链路最初设计是同步的前端发请求 → Agent 编排 → 工具执行 → 返回结果。上线测试后发现一个致命问题一次“物体移除 超分 色调调整”的任务跑了 40 多秒网关层的超时上限是 30 秒直接把请求掐断了。用户那边看到的是“请求失败”但后端的任务其实还在跑最终结果彻底丢失。这个问题的解决方案不是单纯调大超时时间而是把整个架构从同步改成异步。前端提交任务后立刻拿到 task_id后续所有进度查询都通过这个 task_id 轮询或订阅。后端把任务状态持久化到数据库这里用的 Redis键是 task_id值是一个状态结构体Agent 编排引擎每一步执行完都更新一次状态和进度百分比。这样就算用户中途退出页面重新进来也能通过 task_id 找回任务结果。我后来还加了一个任务队列缓冲层。高并发的时候图像处理 worker 处理不过来新任务不会直接拒绝而是进入队列排队前端进度条显示“排队中”。队列我用的是 Redis 的 list 结构简单可靠比引入 MQ 组件轻得多。这里的原则很明确小项目能用 Redis 解决的问题不要一上来就是一套消息中间件。4.3 图片传输与存储Base64 带来的“隐形炸弹”图片数据的传输与存储是整个项目里最容易埋雷的地方也是最不直观的。最开始搭建时前端把图片转成 base64 放在 JSON body 里发给后端本地测试一切正常因为图片小、网络快。但一放到线上移动端 5MB 原图拍出来base64 后变成 7MB 多加上 JSON 转义请求体超过 10MB结果就是用户 Wi-Fi 下还能勉强用4G 环境下经常上传超时。后来我把整条通道梳理了一遍前端先调用后端签名接口获取对象存储的临时上传凭证分片直传图片到对象存储拿到 URL提交任务时只传 URL后端通过 URL 拉取图片后端把图片按需压缩成不同规格——原图只用于最终的“高清下载”Agent 编排和中间预览都用压缩后的缩略图宽度不超过 1600px质量 85%中间过程产生的临时图片在任务完成 24 小时后自动清理只保留最终结果和物料原图。这套链路改完之后上传吞吐量直接翻了近两倍任务失败率显著下降。印象很深的一次线上问题有个用户上传了一张全景拼接图分辨率是 12000×4000后端拉取后直接塞给抠图模型内存瞬间被打爆进程崩溃。后来加了一个前置校验服务图片超出分辨率阈值的先走等比例压缩必要时提示用户“该图尺寸过大已自动压缩至 8000px 以内再进行编辑”。4.4 Token 成本失控让“每次修图不再烧钱”Agent 方案比端到端生成花的 token 更多因为每次任务要做多次大模型调用——意图分类一次、步骤编排一次、可能还有中途验证一次。上线后的第一个月账单吓了我一跳单均 token 成本比预期高出 40%。成本控制我用了组合拳。首先是模型分级意图粗分类用便宜的小模型比如轻量分类模型或规则加小模型组合只有步骤编排这种真正需要复杂推理的环节才用大模型。其次是缓存命中很多用户的需求高度相似比如“去除路人”“磨皮”“美白”这些常见需求的编排结果往往是一套模板。我把常用的编排路径缓存成模板命中模板的任务直接走固定流水线不再调用大模型做编排成本打下来一大块。再有就是控制每步的视觉输入。大模型在验证环节需要看中间图但不需要看全分辨率原图给它一个 512px 的缩略图足以判断“这人脸是否磨皮了”。我把所有发给大模型的图片统一压缩到长边 768px视觉 token 成本降低了约 60%而且没有感觉到大模型判断准确率有明显下滑。5. 多端适配里没被人说透的细节5.1 uniapp 的 Canvas 兼容问题多端适配最大的坑老实说是 Canvas。Web 端 Canvas API 和微信小程序 Canvas 的差异大到让人抓狂特别是版本之间还不停改。我们做裁剪框预览、绘制矩形标注、展示蒙版效果时同一段逻辑在 Web 端运行正常到小程序里坐标全部偏移原来是因为小程序 Canvas 的单位是物理像素需要额外乘上像素比dpr做转换。解决的办法是封装了一层统一的 Canvas 操作接口内部用条件编译区分端对外暴露一致的 API初始化、绘制图片、绘制形状、导出临时文件。所有上层组件只依赖这层接口不直接碰原生 Canvas 语法。这样之后新增端的成本低了很多也不会一改需求就把 Canvas 的坑重新踩一遍。5.2 大图的加载与内存优化小程序端和 App 端的 WebView 对超大图片的支持非常有限一张 3000px 的图直接渲染到一个组件里内存占用高得吓人而且经常白屏。后来我做了“分级加载”策略列表和预览一律使用压缩图和缩略图长边 500px 或 900px只有用户点开“查看原图”或“下载高清图”时才加载原图链接。此外每次生成新的中间预览图时同一页面上的旧预览图会主动从内存中释放用强制置空 src 的方式避免内存泄漏。未做这层处理前连续操作 5-6 次任务后小程序会直接卡死现在连续跑 20 次任务也没有出现过内存异常。5.3 登录态与任务状态在不同端之间的同步由于任务变成了异步用户可能在 Web 端发起一个修图任务然后用同一个账号打开小程序查看结果。为了支持这个场景我把任务状态和用户的账号体系绑定而不是绑定在设备或会话上。前端通过 token 换取用户身份服务端把 task_id 挂到用户维度。这样用户在任何端都能查询自己名下的全部任务历史。小程序端还做了一个订阅消息提醒任务完成时向用户发一条结果通知用户回来后直接看到最终图不用一直停在页面里等。跨端同步打通之后又多了一个技术点前端和服务端之间的图片 URL 做临时签名。对象存储的私有读权限下前端拿到的预览图 URL 是一个带过期时间的签名链接过期时间默认 30 分钟。任务刚提交时给的是短期签名 URL任务完成后服务端重新签一个长期预览 URL7 天有效期用户要下载原图时再重新签一个带下载名的临时链接。这样既保证了图片不被恶意抓取又让用户在各个端都能顺利打开。6. 实测效果、失败案例与对这个架构的复盘6.1 一个完整的实测过程拿一张带杂物的书桌照片举例输入“把桌面上那杯咖啡去掉把桌面色调统一顺便把整张图调得明亮些”。整个执行链路如下第一步Agent 调用物体检测定位到咖啡杯的坐标框执行物体移除工具桌面被周围纹理填充第二步Agent 检测到桌面和环境的色温不一致调用色彩校正工具做色偏统一第三步Agent 执行亮度/对比度调整整体提亮但算法检测到提亮后桌面阴影处出现噪点又自动补了一步轻降噪第四步所有步骤完成验证服务给最终图打过质量分后才返回。用户拿到的是一张直接可用的图过程全透明每一步都能在操作日志里展开查看。这个体验用传统方式想都不要想用户根本没有精力去研究怎么在 PS 里一步一步做。6.2 失败案例一大模型“编造”不存在的工具参数Agent 上线后遇到过几次稍显诡异的问题工具调用时大模型生成了一个不存在的参数名或者把参数值写成明显越界的数字比如把 scale 写成 3.8而工具定义里只允许 0.5-2.0。排查后确认是大模型在长上下文推理时对 JSON Schema 的记忆出现了偏差。修这个问题的思路不是训模型而是加校验层。在工具调用入口处引入 JSON Schema 的强校验校验不通过时不会直接报错而是把错误信息回传大模型让它重新生成一份合法参数。相当于给大模型配了一个“语法检查器”不合法就退回去重写。加上这层校验后工具调用失败率下降了一半以上。6.3 对这套架构的整体复盘全栈 AI 修图 Agent 这个项目做下来我认为最值得沉淀的经验有三条。第一条是Agent 的价值不在模型而在稳定工程化。真正让用户觉得好用的是步骤拆分合理、状态反馈及时、失败能自动兜底。大模型在这里更像是一个聪明但偶尔会犯错的调度员工程机制要能接住它的不稳定性。第二条是全栈项目的核心瓶颈常常在数据链路而不在功能逻辑。图片上传、压缩、存储、传输、签名这套链路才是全项目里影响体验最重的部分。图片过大、传输超时、URL 失效这类问题比修图算法本身的 bug 更容易让用户失去耐心。第三条是多端适配要舍得做抽象层。Canvas 差异、RN 渲染机制差异、长连接能力差异凡是这种跨端会炸的地方都值得提前封装成统一接口。后期改需求、修 bug 时节省的时间绝对覆盖封装成本。6.4 这个项目后续还可以怎么长如果继续做下去我计划在这里加上几个方向。一是工作流收藏与分享把用户每次成功的 Agent 编排过程保存成“配方”其他用户可以直接套用。二是批量处理模式的优化在多张图片上执行同一套洗好步骤Agent 编排一次然后并行跑图像工具吞吐量能提升很多。三是接入更多专用视觉模型比如把美肤能力换成人像专用的精细化模型把老照片修复做成独立入口工具注册表机制让这些扩展成本很低。AI Agent 修图这个方向还有相当深的护城河可以挖。表面上看比拼的是各种修图能力实际上更拼的是把自然语言翻译成工具动作的编排质量、对大规模图像任务的状态稳定性以及多端触达用户的覆盖能力。这个项目完结只是一个节点修图 Agent 的演进方向还有很多可以玩。最后分享一个开发中的小技巧所有涉及 Agent 的线上问题一定要把大模型的完整请求回包日志留下来排查“模型为什么做这个决策”时没有日志就是盲人摸象。给我完整的日志和状态流转记录绝大多数问题半小时内就能定位。