1. 写这个项目的真实动机AI 修图不缺模型缺的是干完一整件事的 Agent先说句大实话这两年的 AI 修图工具单点能力已经强到离谱了。抠图、扩图、去水印、老照片修复、文生图、图生图几乎每个方向都有开源模型能跑出很惊艳的效果。但你要是真拿它们去解决一个现实中完整的修图需求马上就会发现不对劲——这些模型是散的你要用人肉流程把它们串起来先下载一个工具做抠图再换另一个网页做超分最后还要手动把结果搬进 PS 里调色。整个过程断断续续比纯手动修图省不了多少心。我这次做的全栈 AI 修图 Agent本质上是想解决这个散的问题。它不是一个单点修图功能而是一个能听需求、自己拆任务、自己调用工具、把一整条修图链路跑完的智能体。用户只需要说一句把这张照片的背景换掉顺便把分辨率提升到适合印刷Agent 就会自己判断先抠图、再生成新背景、再做超分增强、最后导出全程不需要人盯着。技术栈也定了全栈路线前端用 Vue3 UniApp 覆盖 PC 后台和 H5、小程序多端后端用 Golang 处理业务和模型调度中间加了一层 Python 写的 Agent 编排服务。这个组合不是拍脑袋选的后面我会详细说为什么 Golang 扛主服务、Vue 管桌面端、UniApp 管移动端以及 Agent 层为什么单独拆出来。这个项目适合谁参考三类人一是想入门AI 全栈但找不到完整闭环项目的开发者二是准备做 AI 应用落地、不想只停留在调 API 层面的产品经理和独立开发者三是对 Agent 架构感兴趣、想知道记忆、工具调用、任务拆解在真实项目里怎么串联的人。这篇文章我不会只讲做了什么会把踩坑过程、选型逻辑、架构取舍一并拆开讲。2. 技术选型的底层逻辑Golang、Vue3、UniApp、Python Agent 各管一摊2.1 为什么主服务必须上 Golang这次项目的后端主服务我几乎没有犹豫就选了 Golang。原因很实际AI 修图任务的典型特征是高并发请求 长时间执行 大量二进制数据传输Golang 在这三个场景下都天然占优。先说并发。Agent 修图不是用户点一下、服务端秒回结果的那种请求而是任务式的用户上传图片Agent 开始规划然后连续调用多次模型推理整个过程可能持续几十秒甚至几分钟。如果一门语言一个进程只能扛几百个协程这种长任务一多服务马上就会被打满。Golang 的 goroutine 模型成本极低几万个并发任务同时挂在服务上也吃得消这对于每个修图请求都要长时间占资源的业务形态来说是非常重要的底子。再说二进制数据。修图必然涉及图片流Golang 的 io.Reader 流式处理模式非常顺手配上io.Copy做文件转发、bytes.Buffer做内存缓冲整个文件处理链路写起来很流畅。相比之下如果用脚本语言处理大文件经常要小心内存撑爆的问题Golang 在这块的容错空间大得多。最后说部署。AI 服务往往需要和 Python 侧进程通信Golang 编译出来的单二进制丢到服务器上就能跑依赖问题少跨平台交叉编译也方便。这一点在做 Agent 服务的进程管理时尤其省心。2.2 Vue3 管桌面管理端UniApp 管移动端前端这块我最初也纠结过是统一用一个框架还是各管各的。后来定下来的方案是Vue3 写 PC 端的管理后台UniApp 做 H5 和小程序端。这个组合有自己的考量。Vue3 负责的场景是重操作。管理后台要处理批量任务、查看 Agent 的执行日志、管理底片素材库、调整模型参数这些界面信息密度高、交互复杂Vue3 的组件化生态能省不少力。尤其是有 Element Plus 这类组件库打底表格、表单、树形控件都是现成的。UniApp 负责的场景是轻操作、多端覆盖。用户在小程序里上传照片、发起修图、预览效果UI 相对简单但对多端适配要求高。UniApp 一套代码能编译到微信小程序、支付宝小程序、H5 等多个平台对这类工具型产品来说投入产出比很高。这里有个细节值得说两个前端框架之间我额外抽了一层 API Client 公共模块两边都通过一致的 RESTful 接口对接同一个后端这层公共模块直接解决了多端行为一致的问题。像用户点击修图后前端轮询任务状态这种逻辑我写了一次两边复用。2.3 Agent 编排层为什么单独拆成一个 Python 服务整个架构里最关键也是最容易被忽略的设计是把 Agent 编排层单独拆成了一个 Python 服务没有硬塞进 Golang 主服务里。道理其实不复杂Agent 的核心能力——任务拆解、工具调用、记忆管理——目前最成熟的生态在 Python 这边LangChain、LlamaIndex 这些框架对工具调用和 agent loop 的实现已经相当完善没必要自己从零写一遍状态机。Go 社区在 AI Agent 编排这块的积累还是偏薄如果强行用 Go 写 agent loop光是维护对话状态、多轮工具调用、上下文窗口管理这些逻辑工作量就会翻好几倍。所以最终架构是这样的用户请求先进 Golang 主服务做鉴权、计费、参数校验Golang 把修图任务丢进消息队列我用的 Redis Stream异步解耦Python Agent 服务消费任务调用 LLM 拆解出多步计划再去调用具体的模型服务抠图模型、超分模型、生成模型等每步执行结果通过 Redis 回传状态前端轮询展示进度最终产物写回对象存储Golang 服务生成下载链接。这样各层各司其职Golang 管并发和稳定性Python 管 Agent 的智能逻辑前端只管交互展示。以后想换更聪明的模型或者换成更强大的 Agent 框架都只需要改 Python 那一层其他部分完全不用动。3. Agent 核心能力的落地细节任务拆解、工具调用、记忆管理3.1 任务拆解从用户一句话到一串可执行计划Agent 和普通接口的本质区别是它能把一个模糊的用户意图转化成确定性的工具操作序列。我在这个项目里定义了一套中间的 JSON 协议LLM 输出这个协议代码再去逐项执行。这套协议大概是这样的结构{ plan: [ { step_id: 1, tool: background_remove, params: { input: original.jpg, method: u2net }, depends_on: [] }, { step_id: 2, tool: image_generate, params: { prompt: 现代简约风格书房暖色调, size: 1024x1024, input: null }, depends_on: [] }, { step_id: 3, tool: composite, params: { foreground: step1_result.png, background: step2_result.png, position: center }, depends_on: [1, 2] }, { step_id: 4, tool: super_resolution, params: { input: step3_result.png, scale: 4 }, depends_on: [3] } ] }为了让 LLM 输出稳定的 JSON系统提示词里给了非常严格的 schema并且做了两层兜底第一层让 LLM 直接输出 JSON第二层配置了 JSON 解析失败时的自修复 prompt让 LLM 根据报错信息把原来的输出修正一遍。实测下来在 GPT-4o 和 Claude 系列模型上第一轮输出就能直接解析的概率在 90% 以上。任务拆解还有个隐蔽的难点是depends_on依赖关系这个字段承载了步骤之间的先后顺序。比如生成新背景和抠图两个操作互不依赖可以并行但合成必须等前两步都完成才能执行。我在执行引擎里做了一个简易的拓扑排序每一轮把所有depends_on已满足的 step 挑出来并发执行这样能大幅缩短整个任务的总耗时。3.2 工具调用把模型能力包装成 Agent 的双手Agent 不能只停留在会想关键要会做。这里做的手段就是工具调用Function Calling。我梳理了当前修图场景下需要的全部原子工具每个工具都是一个独立可调用的接口基础编辑抠图、裁切、旋转、缩放质量增强超分辨率、去噪、色彩校正、低光增强生成能力文生图生成新背景/新元素、图生图风格迁移、局部重绘修复能力去水印、老照片划痕修复、面部修复合成能力前景背景合成、图层叠加、羽化融合每个工具在 Agent 层都有对应的 JSON 描述包括名称、参数、返回值格式、错误码。LLM 看到用户需求后会从这些工具列表里选取合适的组合。这里的核心经验是工具描述越精确LLM 的调用准确率越高。比如背景替换这个需求正确的工具序列是background_removeimage_generatecomposite如果工具描述里写了每个工具的输入输出格式LLM 就不容易漏步骤。3.3 记忆管理Agent 短期内记住用户在做什么这个项目我重点做了两层记忆都很轻量但效果明显。第一层是短期会话记忆。所有对话上下文存在 Redis 里key 是session:{userId}:{taskId}值是消息历史的 JSON 数组。每次 Agent 执行工具前会把之前的对话摘要塞进 prompt 里这样用户中途补充要求背景色调暖一点Agent 就能结合前面的对话理解背景指的是哪个步骤的目标而不是当成一个全新需求。第二层是用户偏好记忆。每个用户修图完成后我会把这次操作的部分特征比如是否偏好正方形构图、是否经常用暖色调写入一个简单向量库里下次新任务做计划时把用户的历史偏好作为 system prompt 的一部分。体感上有这层记忆后连续几次使用同一个功能的用户Agent 在第一次拆解时就更趋于符合他的习惯。这里我想提醒一句Agent 的记忆不是越深越好尤其是真做产品记忆涉及隐私和可解释性。我最后只保留了当前任务上下文 用户偏好画像两层不做长时跨会话推理既解决了体验问题又不用背上沉重的合规负担。4. 多端交互与图片处理链路从上传到端侧渲染4.1 上传链路分片、断点续传、压缩策略图片上传是修图产品的第一个要塞。我用 Golang 写了统一的上传网关支持三类客户端网页端、小程序端、H5 端。因为移动端网络环境不稳定我一开始就做了分片上传和断点续传每个文件按 4MB 切分分片独立上传服务端按文件标识和分片序号组合。实测中最常踩的坑是小程序端自定义上传组件和 H5 的 File API 行为不一致。UniApp 里用uni.uploadFile无法直接传分片最后得从plus或wx.uploadFile底层做封装才能实现统一的断点续传逻辑。这个部分前后花了将近两天时间建议后面要做的朋友直接在工程里留一个uploadAdapter接口各端各写一个 adapter不要试图用一套代码抹平所有差异。上传前的图片压缩也很关键。用户手机拍的照片动辄 5~10MB不压缩直接上传既慢又费服务器带宽。我在端侧先做了一次质量压缩到 85%、最长边限制在 4096 的操作然后再上传。实测这个压缩等级对人眼几乎无损但体积能缩小 60% 以上。4.2 任务进度的实时回传轮询还是 WebSocket任务进度展示我最后采用了前端轮询 后端幂等查询的模式没有上 WebSocket。原因是修图任务本身不是高频双向通信场景用户只需要知道现在进行到第几步了用轮询每 2 秒打一次状态接口在体验上已经够流畅而且大幅减少了长连接的管理成本。状态接口返回的数据结构大概长这样{ task_id: ts_20250101_abcdef, status: processing, current_step: 3, total_steps: 5, step_name: composite, progress: 60, result_url: null, error: null }前端拿到这个数据后在界面上渲染一个步骤条每一步显示对应的工具名和状态。这个把 Agent 的执行过程可视化的设计实际是用户正反馈很高的部分——大家看到正在抠图 → 正在生成背景 → 正在合成会觉得这个工具是活的而不是一个转圈死等。4.3 端侧渲染与原图对比小程序和 H5 的差异修图产品做完处理后用户往往要对比前后效果。PC 管理端我直接做了双栏对比加滑块交互这个在 Vue3 里实现非常容易。但到了小程序和 H5 端事情就没那么简单了。小程序端的 Canvas 是离屏渲染图片处理不能直接操作 DOM 里的img标签得通过uni.createCanvasContext绘制到 Canvas 上。而 H5 端可以直接用 CSS 的clip-path或两层图片叠加实现对比滑块。为了减少各端差异调试时间我在双端都采用了图片叠图片 CSS 裁切的方案底层放原图上层放处理结果通过滑块控制上层的显示宽度。这套逻辑在 H5 端非常顺畅小程序端稍微处理了下 Canvas 转图片格式的问题整体效果也能对齐。另一个端侧细节是图片加载的缓存策略我用的对象存储带有 CDN 加速但这会导致原始图片更新后用户看到的还是旧缓存。我在图片 URL 后面额外加了?versiontaskId强制刷新确保每次处理完拿到的都是最新结果这个简单的 trick 能省掉很多排查缓存问题的精力。5. 踩坑实录Agent 调用模型时最难缠的四个问题5.1 模型返回结构化内容不稳定怎么兜底Agent 要调用多个模型不同模型的输出风格差异很大有的模型会先输出一段解释文字再输出 JSON有的模型会贴心地加上 json 代码块标记直接 JSON.parse 必挂。我的方案分三层第一层输出净化用正则把被json、包裹的JSON块提取出来第二层容错解析如果直接解析失败尝试用json5这种宽松格式解析它能容忍尾逗号、单引号等问题第三层LLM 自修复前两层都失败时把报错信息拼接给同模型要求它重新输出合法 JSON这个递归兜底最终能把成功率拉到接近 100%。这层兜底逻辑看起来平平无奇但缺了它Agent 在真实环境中跑不了几次就会挂掉因为模型输出不符合预设格式不是小概率事件而是常态化现象。5.2 流式日志与二进制图片怎么共存Agent 执行过程中会产生两条信息流一条是文本日志当前在做什么、模型返回了什么另一条是二进制图片数据。最初我图省事想都塞进同一个任务流里结果前端解析时很痛苦文本和二进制混在一起没法高效分离。后来我参考了流式协议的思路把日志和图片完全分两条通道处理。文本日志走 Redis Stream 里的progress消息由前端轮询接口拉取更新状态展示图片结果走对象存储生成 URL 后通过result_url字段传给前端。这个设计带来的好处是文本和二进制各走各的通道互不阻塞当图片很大时日志照样可以实时展示给用户体验不会卡顿。5.3 跨端 Canvas 导出的图片清晰度问题有一次用户反馈在小程序里处理完的图片保存到相册后明显模糊。排查发现是 Canvas 尺寸没有和导出图片的尺寸对齐。小程序 Canvas 的默认分辨率受渲染区域限制如果画布实际大小只有 375x667导出 exif 里记录的尺寸也就是这么多自然放大就糊。解决思路是不直接渲染到可视区域而是用离屏 Canvas 在内存里创建一个目标分辨率比如 1280 或原图最长边的画布所有绘制和合成操作都在这个高分辨率画布上完成最后再导出。这个改动解决的不只是清晰度还让最终结果的尺寸可以按用户需求动态调整比如高清印刷对应 300dpi网页分享对应 72dpi。5.4 Agent 编排层的死锁问题LLM 陷入循环调用工具最让我头疼的问题Agent 在某个任务里反复调用同一个工具结果不理想就再来一次像是进入死循环。这种问题在纯代码里就是for循环写错了在 Agent 里是 LLM 的自我纠错机制跑偏了。我在执行引擎里加了三道保险每个步骤最大重试次数3超过后直接标记失败并把失败信息返回给用户全局工具调用总次数15防止 Agent 在无关线程上无限折腾倒计时熔断整个任务最长执行时间 10 分钟到点强制终止。这些约束看起来粗暴但对生产环境的稳定性至关重要。真实用户可不会等一个 Agent 循环 20 分钟给足余量再兜底才是负责任的做法。6. 部署落地的资源开销与性能数据不烧钱也能跑起来6.1 我用的实际资源清单很多读者关心全栈 Agent 项目要烧多少钱我放一下我这套方案在低配条件下的资源消耗给大家做个参考模块配置建议月成本区间按量付费Golang 主服务2核4G 云服务器约 80~150 元Python Agent 服务和主服务同机部署或 2核4G 独立约 0 或 80~150 元Redis1G 内存版性能足够约 50~100 元对象存储 CDN按实际流量初期约 30~60 元约 30~60 元大模型 APIGPT-4o/Claude 按 token任务量大时再叠加按量初期约几十到几百元这个项目的设计定位就是一线开发者能低成本跑通的级别整套用云厂商最低配起步月成本控制在一两百元以内是可行的。真正的费用大头在模型 API但可以在工具层做缓存和结果复用减少重复调用。6.2 几个关键性能数字真实跑过的数据单张 4MB 图片上传平均耗时 1.8 秒普通宽带环境抠图任务平均耗时U2Net 模型单张 2.1 秒超分任务平均耗时4 倍放大一张 512x512 的图约 6.5 秒全链路换背景 超分完整任务从上传到最后拿到结果平均 15~20 秒并发承载2核4G 服务器上同时跑 50 个任务不崩模型 API 是瓶颈。这些数据给出来不是让大家照抄指标而是想说——只要架构上把大模型串行调用转成并行、把任务拆解粒度控制好整条链路的吞吐量是完全可以优化的并不像外界想象的那样AI 应用一定又慢又贵。7. 项目完结后的复盘哪些设计复用价值最高项目收尾后我把整套代码结构重新翻了一遍梳理出三个复用价值最高的设计模块。第一个是工具层抽象。所有模型能力都封装成了标准的 function calling schema换模型、增工具都不用改 Agent 的调度逻辑。以后这个项目如果想扩展成AI 做海报、AI 做证件照只需要在工具列表里加新工具Agent 会自动学会调用它们。这个抽象层是我觉得整个项目最有含金量的部分。第二个是任务状态机。从 uploaded、queued、planning、processing、completed 到 failed每个状态都有清晰的流转和重试策略。这套状态机不仅用于修图几乎任何 AI 异步任务生成、分析、批量处理都能套用。第三个是记忆方案。当前任务上下文 用户偏好画像两层设计简单、可控、易扩展。如果未来要做更复杂的 Agent 记忆我这个结构也能平滑迁移不会推倒重来。8. 给想复刻这个项目的人几条实在建议根据我的经验如果现在让你从头做一个类似的全栈 AI Agent 修图项目有几点前置建议能少走不少弯路。第一先用最小闭环跑通一遍上传图片 → 调一个模型 → 返回结果不要一上来就搭全套架构。我最初用 FastAPI 起了个最小服务只接一个抠图模型花了半天时间调通全链路后才决定引入 Golang。先有闭环再有架构。第二Agent 编排层的核心先跑在代码流程上再让 LLM 介入。什么意思呢就是刚开始先写死一个流程固定走抠图→生成→合成→超分验证服务稳定了再引入 LLM 做动态任务拆解。动态拆解一旦出问题调试成本是静态流程的几倍。第三内存和超时一定要提前设好。Python 侧调用大模型时requests 不设 timeoutGPU 服务端一旦假死所有 Worker 都会卡住。我所有 HTTP 调用统一timeout300socket 连接层timeout30任务超时熔断必须从一开始就写进执行引擎别等出了问题再加。第四日志就是 Agent 的黑匣子一定要完整。我每步工具调用都记录入参、出参、耗时、错误信息前端能看到执行步骤出问题时也能直接定位到是哪一步模型调用挂了。很多 Agent 项目一跑就懵就是缺这套日志体系。最后一件事做这类项目你前期可能 70% 的时间在写非 AI的代码——权限系统、上传下载、任务队列、前端交互。不要觉得这些工作琐碎不值钱它们恰恰是产品能否变成真的关键。AI 模型给你的是上限工程代码决定的是下限两个都要硬。这次的项目做到完结最大的感受是AI 全栈这个词确实不是噱头。真正把一个 AI 功能落地成产品横跨编排、模型、前后端和部署的链路每环都需要有足够的工程功底。希望这篇复盘能为准备入局 AI Agent 开发的朋友提供一些实实在在的参考。
