1. 项目定位与整体设计思路1.1 这个 Agent 解决什么问题先交代一下背景。这个项目前后做了大概三个半月核心交付物是一个“能听懂人话、自己拆任务、自己调用工具完成修图”的全栈 AI 修图 Agent覆盖了 Web 端、H5 和微信小程序三个入口。用户不需要学 Photoshop也不用理解“蒙版、通道、曲线”这些概念直接把图传上来再用自然语言说一句“帮我把背景换成一个晴天海滩人物调亮一点再把脸上瑕疵修掉”Agent 会自动拆解指令依次完成抠图、背景生成、肤色调整、瑕疵修复最后输出一张成品图。这个项目本质上解决的是“专业能力平民化”的问题。传统修图工具的学习成本高而通用 AI 对话工具只能“聊”不能真正操作图像通用图像生成工具又只能“从零生成”不能对用户自己的照片做精细编辑。修图 Agent 的定位就是补上这两者之间的空档既理解用户的模糊意图又能调用具体工具对真实图像产生可预期的修改。适合看这篇内容的人主要是两类。一类是正在做 AI 应用落地、想了解 Agent 怎么和具体业务结合的开发者另一类是本身在做全栈项目、想知道 Vue Golang UniApp 这套技术栈怎么在一个项目里顺畅配合的同学。这个项目的思路和踩坑记录对这两类人都可以直接参考。1.2 为什么选“全栈 AI Agent”这个组合先说为什么要做“全栈”而不是只做某个端。修图场景天然是多端的用户在电脑上上传高清原图做精细处理在手机上随时查看进度和结果在小程序里分享成品。如果只做 Web 端移动场景就废了如果只做小程序复杂图像处理的后台能力又撑不起来。所以从第一天起这个项目就定成了“一套核心服务 多端接入”的架构服务端统一出接口前端各自适配。再解释为什么一定要用 Agent 而不是写死流程。修图需求的变化性太大了。同样是“修掉瑕疵”有的人指痘痘有的人指皱纹有的人指照片上的杂物同样是“换背景”有的人要纯色有的人要实景有的人要保留原图的光影。如果靠硬编码规则每加一种需求就要改一轮代码永远做不完。Agent 的价值在于意图理解交给大模型任务拆分和工具选择由 Agent 动态决策真正执行图像操作的是后端注册好的原子能力。这样一来新增一种修图需求很多时候只需要新增一个工具函数和对应的描述主流程不用动。技术选型上核心是两条线。AI 能力层用了大模型的视觉理解接口来处理“看图说话”用开源图像模型服务承载“生成和编辑”业务服务层用了 Golang 写的高并发 API 网关和任务调度前端分别是 Vue 3Web、UniApp小程序和 App。为什么要用 Golang 而不是 Node 或 Python因为我们预判到图像处理任务会伴随大量的文件上传下载、任务状态推送、异步回调这些场景下 Golang 的并发模型和内存表现是最省心的而且部署时编译成单个二进制文件服务器上不用装一堆依赖。1.3 技术栈选型的核心逻辑这里直接放一张我们最终确定的技术栈清单后面逐个说选型理由。层次选型理由前端 WebVue 3 TypeScript Vite Pinia组合式 API 适合复杂交互TS 减少接口联调返工移动端UniApp Vue 3一套代码同时编译到微信小程序、H5、App覆盖多端后端Golang Gin WebSocket高并发接口服务长连接推送任务进度任务队列Redis RabbitMQ异步处理大图任务削峰填谷AI 服务层大模型视觉接口 开源图像模型意图理解走云端大模型图像编辑走私有化部署的开源模型存储阿里云 OSS / 兼容 S3原图和结果图分离支持断点续传和 CDN 加速这里有一个取舍想单独说一下。移动端一开始也纠结过要不要用纯原生或者 Flutter。最终选 UniApp 的原因很现实团队的 Vue 基础好而且小程序端是刚需UniApp 对微信小程序的适配比 Flutter 成熟得多。代价是某些原生组件比如复杂图片裁剪需要桥接原生插件我在后面“常见问题”部分会专门讲这个坑。后端没有选用 Python即使 AI 生态里 Python 更丰富。原因是我们所有图像推理服务都跑在独立的 GPU 节点上通过 HTTP 接口对外提供服务Golang 服务根本不需要直接操作 PyTorch 或 TensorFlow它只负责调度和转发。这样一来主服务的稳定性、并发能力都更可控模型升级也不影响主链路。2. Agent 核心架构拆解2.1 任务编排从用户指令到修图动作Agent 最核心的部分不是调用大模型而是“怎么把一个模糊指令变成一组可执行的工具调用序列”。我把它设计成了四层流水线。第一层是指令解析。用户上传图片后输入自然语言指令后端把图片和文本一起发给视觉语言模型得到结构化的 JSON包含任务类型、目标区域、风格参数等。比如“把背景换成黄昏海滩人物保持不动”模型返回的结构大致是{ task_type: background_replace, subject: person, background: beach at sunset, preserve: [person_position, lighting_direction], priority: high }第二层是任务规划。拿到结构化意图之后Agent 根据内部注册的工具清单把任务拆成有序步骤。这个拆分不是硬编码的而是让大模型基于工具描述动态生成。比如上面这个“换背景”任务模型会拆成主体检测 - 抠图 - 生成新背景 - 光影融合 - 输出。这个步骤序列会转成一个有向任务图记录每个节点的输入输出依赖。第三层是执行调度。每个步骤对应一个具体的工具函数调度器按依赖顺序执行。这里要特别处理失败重试和分支回退如果抠图步骤失败整个任务不应该直接挂掉而是回到规划层重新生成方案比如改用另一种分割模型再试一次。为此我在任务数据结构里加了一个retry_count和alternatives字段记录重试次数和可替换方案。第四层是结果校验。每个工具执行完返回的结果图会做一次质量检查包括分辨率、是否包含异常色块、人物边缘是否被破坏等。这个校验用传统图像算法OpenCV就够了不需要再让大模型看一遍成本和延迟都能降下来。这个编排过程是整个项目里我最满意也最花时间的部分。写死一步流程很容易但真的要达到“大多数情况下都能自己搞定”的 Agent 效果难点全在细节比如任务拆错了怎么回退、部分步骤成功部分失败怎么处理、用户中途改了需求怎么增量更新。后面实测阶段八十多轮真实用户测试大概有七成指令能被 Agent 正确拆解并完整执行还有两成半要靠重试或简化方案兜底剩下零点几成需要人工接管。这个结果在现阶段已经算能用了。2.2 工具注册与技能扩展机制Agent 能干什么完全取决于后端注册了哪些工具。我把每个工具封装成一个标准函数描述核心字段包括名称、功能描述、输入参数、输出类型、依赖的模型服务地址、预估耗时、超时时间、重试策略。一个典型的工具描述长这样{ name: remove_background, description: Remove the background from the input image and return a transparent-background PNG., parameters: { type: object, properties: { image_url: { type: string, description: Input image URL or base64 data. }, focus: { type: array, items: { type: string }, description: Objects to keep in foreground, e.g. [person, cat]. } }, required: [image_url] }, estimated_time: 5, timeout: 30, retry: { max_attempts: 2, backoff_seconds: 3 } }所有工具描述汇总成一个工具清单交给大模型做函数调用选择。这里有个关键经验工具描述里可以补充一些负面提示比如“如果图片中没有人物请调用 error_reporter 返回一个用户友好提示不要尝试强行抠图”。这能显著减少大模型乱选工具的概率。工具层目前内置了这些能力人像抠图、通用物体分割、背景重绘、人脸瑕疵修复、老照片上色、超分辨率放大、色彩调整亮度对比度饱和度色温、清晰度增强、裁剪与构图调整、文字水印去除。每个能力背后都对应一个具体的开源模型或图像处理服务通过 HTTP 调 GPU 节点执行。新增一个工具的流程也很简单先在 GPU 节点上做好推理服务的 Docker 镜像暴露一个统一的 POST 接口再在工具注册表里加一段 JSON 描述最后写一个上传到测试环境的自动化用例。整个过程半小时内能完成这也是 Agent 架构相比传统硬编码最大的优势——业务扩展从“改代码”变成了“配接口”。2.3 图像处理执行层的取舍执行层是最容易踩坑的地方因为 AI 图像模型输出的结果“不保证稳定”。同一个模型同一个参数两次出来的图可能有肉眼可见的差异。所以在这层我做了一个重要取舍能够用传统算法解决的需求绝不用 AI 模型非用 AI 不可的再加一道传统算法的兜底校验。以“人像磨皮”为例最朴素的效果其实用 OpenCV 的双边滤波就能做速度极快效果稳定但如果用户说“要保留皮肤纹理不能把脸变成塑料”那就需要上 AI 修复模型。再比如“边缘羽化”和“色彩匹配”这两个环节用传统图像算法做反而比 AI 生成更可控。AI 生成的优势在于“创造不存在的内容”比如换背景时生成一个逼真的新场景缺点在于不可控、耗时、偶尔出现视觉幻觉。所以执行层的设计原则就是创意部分交给 AI精度部分交给算法两者结合才能达到可商用的效果。这里还有一个关于图像尺寸的实操细节。上游大模型接口能接收的最大图片尺寸是有限的高分辨率原图直接传过去会被压缩导致细节丢失。我们的做法是把原图拆分处理先缩略图走意图理解得到整体修改方案再按区域裁剪高分辨率细节块逐块执行需要精细操作的工具比如人脸修复最后再拼回完整分辨率。这个“缩略图理解 分块精修 拼接回写”的流程是这次项目里对成图质量提升最明显的一个优化。3. 多端交互与工程实现3.1 Web 端Vue 3关键设计Web 端是整个项目里功能最全的端承担了“专业工作台”的角色。技术栈是 Vue 3 TypeScript Vite PiniaUI 组件库用的 Element Plus图片编辑区域是自己封装的一个画布组件。Web 端最重要的一个功能点是任务进度的实时可视化。用户上传一张 20MB 的 RAW 格式照片后端要依次完成抠图、背景生成、色彩调整等多个步骤单步可能耗时 5 到 15 秒。如果页面只是转圈用户十有八九会在等待时退出。我做了两步处理第一步后端每个任务步骤启动和完成时都推送一条 WebSocket 消息前端用一个时间线组件展示“正在抠图 / 正在生成新背景 / 正在色彩融合”第二步前端缓存每一步的中间结果图让用户可以点击时间线回看任意一步的输出相当于整个修图过程变得透明、可干预。Vue 3 的实现上有一个用得特别顺手的组合是shallowRef配合大图预览。20MB 的图如果直接塞进响应式对象Vue 的代理机制会拖慢页面。我们让大图保持非响应式只在需要更新最终结果时才重新赋值一次这样预览区域的操作流畅度提升非常明显。另外一个细节是前端做了“撤销任意步骤”的功能。因为任务图本身就是有向无环的每一步的输入输出都记录在案所以前端只需要记住每个节点的结果图 URL用户点“回到某一步”时其实就是从那个节点的输出继续往后跑。这个功能的实现成本很低但用户反馈里提到最多的就是它。3.2 移动端UniApp跨端经验移动端基于 UniApp Vue 3 实现一次编写编译输出到微信小程序和 H5。实际开发下来踩的最多的坑在小程序和 H5 的行为差异上。第一个坑是图片处理组件的兼容性。小程序端不能直接使用 HTML5 的 canvas 做像素级操作必须走小程序的Canvas 2DAPI而且不同基础库版本之间还有差异。我们最终的方案是所有需要精确像素操作的交互比如手动圈选修复区域统一放在独立的 WebView 页面里用标准的 Web 技术实现再通过 postMessage 和小程序宿主通信拿到处理结果后回传给后端。这个方案绕开了小程序原生 canvas 的种种限制维护起来也省心。第二个坑是上传大图的性能。微信小程序上传时默认有 10MB 的大小限制而且上传大文件容易触发微信的隐私授权弹窗体验很差。我们做了两层处理前端先压缩出一个不超过 2MB 的预览图用于快速预览原图通过分片上传接口传到对象存储后端拿到对象存储的 URL 后再做高质量处理。这样一来用户能一秒看到初步效果后台再慢慢处理高清版本处理完推送通知。第三个经验是关于“多端状态同步”的。用户可能在手机上发起一个任务然后切到电脑上继续操作。我们在 Pinia 和 Vuex 之上封装了一层全局状态管理器统一从后端拉取任务详情前端只做展示和交互不做真正的状态持久化。所有任务状态以后端为准前端只是后端的投影。这套设计省掉了大量跨端同步的逻辑推荐所有多端项目都这么搞。3.3 Golang 后端服务设计要点Golang 后端是这个项目的中枢承担接口服务、任务调度、文件存储、WebSocket 推送、AI 服务代理五类职责。先说任务调度。修图任务是典型的异步长任务HTTP 接口拿到上传的图片后创建任务记录并返回task_id任务进入 RabbitMQ 队列后台 worker 消费后按顺序执行 Agent 编排出的工具链。任务状态用一个标准化状态机管理pending - queued - planning - executing - reviewing - done异常状态包括failed、cancelled、needs_human_review。状态机迁移通过 Redis 记录防止 worker 崩溃后任务丢失。文件存储方面原图和结果图都存在对象存储数据库里只存 URL 和元数据。这里有一个值得注意的细节临时文件的过期清理策略。AI 处理过程中会产生大量中间图如果全部长期保存存储成本会快速上升。我们配置了一个生命周期规则原图和最终结果图永久保存中间产物 7 天后自动删除。这样既保证了用户可以随时回溯处理过程又不会把存储空间吃爆。WebSocket 推送是用户感知最明显的功能。后端每个 worker 在执行到任务节点时都会往 Redis 的频道里发一条事件消息hub组件统一接收后再推送给对应连接的客户端。这里的连接管理用了一个简单的 map sync.RWMutex性能完全够用不需要引入额外的消息中间件。一个后端的性能优化经验图像处理的 CPU 密集操作和 IO 密集操作要分开线程池。Golang 的 goroutine 虽然很轻但图像解码、编码这类操作如果全部并行执行内存会被瞬间打满。我们为“解码/编码”设置了独立的信号量限制同时进行的图像编解码操作不超过 CPU 核数的两倍而网络 IO 等待可以开更多的 goroutine。这个调整之后服务端的 P99 延迟下降了大约四成。4. 项目推进中的问题与排查实录4.1 并发高峰期的任务队列堆积第一次压测时我发现一个非常尴尬的问题单张图片处理耗时大约 10 秒但当 20 个用户同时上传图片时任务队列开始堆积后面的任务要等 3 分钟以上才能开始处理用户端体验极差。排查下来瓶颈不在 CPU 也不在模型推理而在对象存储的上传下载环节。我们的 worker 在消费任务时需要先下载原图处理完再上传结果图单张原图 10MB这个 IO 时间占了很大比重。优化方案是把上传下载的客户端连接池调大并且对大文件启用分片并行传输同时在业务层面增加“处理中”和“排队中”的差异化提示至少让用户明确知道任务在排队而不是看起来像卡死了。另一个改善很大的改动是任务优先级分级。用户主动点击“加急处理”的请求会进入高优先级队列普通请求走默认队列。高优先级队列的 worker 数量只有默认队列的一半但延迟降低了十倍左右。这种设计在生产环境中很实用不用把所有请求都当作同一级别对待。4.2 图像质量与幻觉控制的实战经验AI 图像模型最常见的翻车场景就是“幻觉”换背景时人物的手指被生成成了扭曲的形状修复老照片时眼睛被画成非对称结构超分算法把噪点放大成了纹理。这些问题的根源都是一样的——模型在理解“不存在”或被压缩丢失的细节时会凭概率“脑补”出看起来合理但实际错误的内容。针对这些问题我总结了一套实用的质量兜底策略。第一限制生成区域利用分割 mask 约束模型只在目标区域内生成背景替换时原图人物区域直接保留不参与生成第二引入参考图约束处理人像时先用原图生成一张固定姿态的线稿作为 ControlNet 参考大幅减少结构变形第三输出端叠加传统算法校验比如人脸关键点数量检查、边缘连续性检查、色彩直方图一致性检查不符合预期就重试一次重试仍失败就让 Agent 换一条处理路径。还有一个容易被忽略的点图像模型对输入图片的分辨率很敏感。直接上传 20MB 的高清图模型往往会因为过度压缩丢掉细节。我的做法是把原图在保持比例的前提下缩到模型最擅长处理的尺寸范围处理完再通过超分环节恢复到原分辨率。这个“先降后升”的流程看似多了一步实际效果比直接处理大图好太多。4.3 大模型调用成本与响应延迟的平衡Agent 类产品和普通接口的显著区别在于它每一步都会调用大模型做决策而大模型和图像模型的推理成本都是真金白银和时间。我在项目后期做了一轮比较极致的成本优化效果还挺明显的。首先是消息压缩。Agent 在和用户多轮对话时如果每次都把历史消息全部发给大模型token 消耗会快速增长。我实现了一个摘要机制当对话超过五轮时把前几轮的关键信息压缩成摘要替换掉原始消息只保留最近一轮的完整上下文。这样准确率几乎不受影响但 token 成本下降了约 40%。其次是任务合并。很多用户的指令里包含多个相关联的小操作比如“修掉痘痘顺便把脸调亮一点”。如果拆成两个独立任务意味着两次大模型调用和两次图像处理。我们在规划层做了一个指令聚合优化把可以在同一次处理中完成的操作合并成一个步骤比如瑕疵修复和亮度调整放在同一张图的同一个处理管线里执行。这个优化让单次任务的大模型调用次数从平均 4 次降到了 2.5 次左右。再次是缓存。同一个用户对同一张图反复修改时前面步骤的处理结果是可以复用的。我们在 Redis 里对图片内容做了哈希索引图片内容没变的前提下相同步骤直接取缓存结果不再重新推理。这个命中率在用户反复调整某项参数时能到 40% 以上相当于变相提升了并发能力。4.4 多端联调中的协作与规范问题项目到了中期Web、小程序、后端三个开发线并行推进联调阶段暴露出很多本来可以避免的问题。最主要的是接口约定不一致同一个字段Web 端叫bg_color小程序端叫backgroundColor后端文档写的是background三个人三个叫法导致联调时反复改代码。后来我立了一个规矩所有接口定义先写 OpenAPI 文档再写代码。前端不用自己起 mock 服务直接根据文档生成 TypeScript 类型定义后端按文档实现接口并且加了一层自动化契约测试。每次后端有接口变更CI 自动跑一遍所有消费端的数据结构校验不通过就不允许合并代码。这个流程立起来之后联调效率提升了至少一半。还有一个协作层面的建议非常适合三端同步开发的项目关键 API 必须做“版本前缀”比如/api/v1/即使内部还在快速迭代也不要为了省事直接覆盖旧接口。我们曾经因为一个图片上传接口的字段改了没加版本把已经上线的 H5 页面搞挂了一次后来就再也不敢不加版本号了。5. 复盘与后续扩展方向5.1 从项目中沉淀的三条核心经验这个项目做完最值钱的不是代码本身而是踩坑之后沉淀下来的几条判断。第一条Agent 类产品的核心竞争力不在模型而在围绕模型搭起来的“可控性工程”。模型本身都是公开能力谁都可以接入但能不能让它在各种边角场景下稳定输出、出错之后能不能自动兜底这才是真正拉开差距的地方。之前觉得“只要接上大模型就能智能”做完这个项目才彻底明白智能是模型给的可用性是工程给的。第二条技术选型要把“团队最熟的东西”放在第一位而不是“最热门的东西”。我们用 Vue 而不是 React用 Golang 而不是 Python用 UniApp 而不是 Flutter核心原因只有一个团队熟。熟就意味着踩坑成本低、交付速度快。等项目跑通了再去探索新的替代方案也不迟。第三条AI 应用的验收标准必须包含“失败路径”。传统软件开发时正常流程走通基本就能交付了但 AI 应用因为大模型的不确定性失败路径和成功路径一样重要。抠图失败了要不要重新规划模型生成了畸形人脸怎么办用户上传的不是图片而是 PDF 怎么办这些异常情况在设计和测试阶段就要明确否则一上线就会被真实用户教做人。5.2 技术层面的后续优化空间这个 Agent 目前的架构还只是“单 Agent 工具调用”的模式后续有明显的优化空间。最直接的是引入多 Agent 协作。目前一个 Agent 要同时承担意图理解、任务规划、工具调度、质量审查四类职责上下文一长就偶尔“精神分裂”。拆成规划 Agent、执行 Agent、审查 Agent 三个角色之后各自的 prompt 可以更聚焦整体稳定性应该会有提升。这也是现在 Agent 圈比较主流的方向。第二个方向是引入“用户反馈强化”机制。目前任务完成之后就结束了用户是否满意我们没有主动收集。如果加一个轻量的结果反馈入口点赞、点踩、修改后重新生成收集足够多样本之后就能用来做结果排序或者 prompt 的自动优化。这一步对整个系统的进化速度帮助会非常大。第三个方向是把指令理解从“文本 单图”扩展到“文本 多图 区域框选”。比如用户在图上画一个圆圈说“只改这个区域”这要求前端把标注信息传给 AgentAgent 再把区域信息作为附加参数传给工具。技术难度不大但对交互体验的提升很直接。5.3 产品层面的扩展思考这个项目做完之后我的感受是“AI 修图 Agent”这类产品的想象空间不在“替代 Photoshop”而在“变成用户默认的图片处理入口”。当用户习惯用自然语言和 Agent 交流之后Agent 的价值就不再只是修图而是慢慢变成一个理解用户图片内容、能主动提出修改建议的数字助手。比如结合 OCR 能力自动识别图片里的文字帮忙翻译或去除水印结合人脸识别能力在照片分享前自动模糊路人面容保护隐私结合电商场景自动生成商品白底图、场景图、营销文案。这些能力的底层都是同一个 Agent 架构只是往工具注册表里加新工具而已。在做产品规划时我给团队的判断是现阶段不用追求大而全先把“人像美化 背景处理 清晰度修复”这三板斧打磨到极致跑通用户口碑再逐步扩展。技术底座已经足够灵活后面的扩展拼的是对各场景用户需求的理解深度。