最近刚把一个全栈 AI 修图 Agent 的项目收尾上线整个过程踩了不少坑也沉淀了不少经验。这个项目从立项到完结大概花了两个多月覆盖了 Vue3 Golang UniApp 三端核心是把 AI 图像处理和 Agent 的任务编排结合起来做成了一个用户用自然语言就能完成修图的智能工具。如果你正在搞全栈、想接触 Agent 开发或者对 AI 图像处理落地感兴趣那这篇文章应该能给你一些真实可参考的东西——包括技术选型为什么这么做、Agent 循环怎么设计、多端适配有哪些坑还有我最后悔没有早点知道的几个优化点。项目标题虽然是又一个新项目完结但对我来说它不只是多了一个作品集项目更像是一次把大模型能力、Agent 编排、图像处理和传统全栈开发揉在一起的完整实践。1. 项目整体设计与技术选型的底层逻辑1.1 为什么做全栈 AI 修图 Agent而不是普通的修图工具先说说这个项目想解决的问题。市面上大多数修图工具不管是网页版还是客户端核心交互都是用户手动操作按钮和参数——调亮度、拉对比度、抠图、磨皮每一个动作都得用户自己去点。这个方案本身没问题但有一个天然的门槛很多人根本不知道某个效果应该用哪个功能实现。比如把背景里的路人去掉这件事在传统工具里可能涉及选区、内容识别填充、补图好几个步骤小白根本无从下手。AI 修图 Agent 的思路就不一样了。用户只需要用一句话描述目标比如把这张照片的背景换成傍晚的海滩光线自然一些Agent 自动拆解任务、选择工具、逐步执行、最后返回成品图。这背后的产品逻辑是修图工具从把人当操作员变成把人当提出需求的人。从项目层面看选Agent 修图这个组合还有一个更务实的原因AI 图像处理模型本身已经很成熟了但散落成单个 API 可调用能力时价值有限一旦用 Agent 把它们编排起来用户表达的自然语言需求就能自动映射到一段工具调用链上产品的壁垒从有没有 AI 能力变成了能不能把 AI 能力组合成完整工作流。这一点对全栈开发者尤其重要因为它意味着后端不再是简单的 CRUD而是要做任务调度、状态管理、异步处理和结果校验。1.2 Vue3 Golang UniApp 三端选型各自承担什么责任技术栈的选择是我一开始想了很久的问题。后端选 Golang 主要看重三点并发性能、部署简单、生态成熟。修图 Agent 场景里用户会频繁提交图片处理请求后端要同时处理 WebSocket 长连接推送任务状态、HTTP 上传接口、以及异步任务队列Golang 的 goroutine 模型在这种 IO 密集型场景下非常舒服写起来也不会像回调地狱那样恶心。部署上直接交叉编译成单个二进制文件扔到服务器上就跑对个人开发者来说省心不少。前端 Web 端用了 Vue3 Vite Pinia。坦白说Vue3 和 React 在这个项目里选哪个都行我选 Vue3 是因为组合式 API 在管理图像上传、任务状态轮询、画布预览这种强交互场景下写起来更顺手而且模板语法在处理多端条件渲染时更直观一些。移动端则用 UniApp 实现一套代码跑 H5、小程序和 App。这种选型有一点要提前做好心理准备UniApp 的跨端能力是同一套代码不同端有不同表现而不是写一次到处完美后面我会详细说踩坑细节。后端内部不是一个大单体而是拆成了 API 服务和 Agent 调度服务两个进程。API 服务负责鉴权、图片上传、任务查询Agent 调度服务负责接收任务、拆解执行计划、调用图像处理工具链、更新任务状态。拆开的原因很现实图像处理模型的推理时间普遍在 5 到 30 秒之间这种耗时任务如果放在请求链路里同步执行用户早就跑了。拆成独立服务后API 接口立即返回任务 ID客户端轮询或通过 WebSocket 订阅进度Agent 调度服务在后台异步处理整体体验流畅很多。1.3 Agent 架构里我用到的核心概念和组件Agent 这个词这两年很火但落到项目里到底是怎么设计的很多人其实有点模糊。我这里的 Agent 调度服务实现了一个简化的规划-执行-观察循环规划Planning接收用户自然语言指令通过大模型的 Function Calling 能力将意图解析成结构化的步骤流比如人像抠图 - 背景替换 - 色彩统一执行Execution按步骤调用对应的工具函数每个工具对应一种具体图像处理能力观察Observation每个步骤拿到结果后校验输出是否符合预期模型可以根据中间结果决定下一步是继续、调整参数还是终止这整个流程里最核心的是两件事一是大模型 Function Calling 的稳定性二是工具层的抽象设计。Function Calling 如果调用参数经常出错后面的流程全乱套工具层如果不抽象好每接一个新模型就要改一遍调度代码。关于工具抽象我写了一个统一的图像工具接口每个工具只需要实现三件事声明自己的名称和作用、定义输入的 JSON Schema、提供执行函数。这样 Agent 调度器完全不需要关心工具内部是调用云端大模型 API 还是本地 OpenCV只需要按照 Schema 传参并接收返回值。2. 核心功能拆解与关键实现细节2.1 Agent 任务编排自然语言如何变成修图步骤用户输入把图片背景换成沙滩之后系统需要经历一个意图解析阶段。我在这里用的方案是大模型 Function Calling 输出结构化 JSON而不是让它直接返回自然语言再解析。核心原因是结构化输出更可控。我给大模型定义了这样一组工具方法understand_image(image_url)分析图片内容返回画面元素、主体位置、光线方向等信息matting(subject_desc)对主体进行分割抠图返回带透明通道的 PNGreplace_background(scene_desc, style_desc)根据描述生成新背景并和前景合成adjust_color(target, params)调整饱和度、色温、对比度等参数check_quality(image_url)对结果进行质量评估输出是否达标当用户输入把这张照片的背景换成傍晚的海滩光线自然一些大模型解析后输出的工具调用链大致是这样的[ {tool: understand_image, args: {image_url: xxx}}, {tool: matting, args: {subject_desc: 人物主体}}, {tool: replace_background, args: {scene_desc: 傍晚的海滩, style_desc: 自然光线}} ]注意这只是一个简化示例实际场景中模型还可能会加上一步check_quality来做结果检查。整个调用链形成后Agent 调度器就按顺序执行。关键的参数回填在这里很重要第二个步骤matting输出的透明背景 PNG 路径要能自动变成第三个步骤的输入参数的一部分。这个步骤间数据传递我用的是一个共享上下文对象所有工具都可以读写大模型在规划时只需要声明依赖前序步骤的哪个输出字段即可。2.2 图像处理能力云端模型 API 与本地图像算法的取舍图像处理能力是这个项目最重的部分也是资金消耗最大的部分。我最终采用的是云端模型 API 为主、本地算法为辅的混合方案。云端模型 API 主要负责三类任务抠图、背景生成/替换、图像质量评估。这三个任务对模型能力要求高本地跑小模型效果差距明显直接用云端 API 最省心。以抠图为例我用的是端到端的人像分割模型返回带 alpha 通道的 PNG不需要任何后处理就能直接用。本地算法负责的是那些用 OpenCV 就能解决的任务比如格式转换、尺寸裁剪、基础色彩调整、添加文字水印。这些操作如果用大模型做成本高且速度慢但用传统图像处理算法做毫秒级就能完成。整个项目做下来我最大的感受是不要什么问题都甩给大模型传统算法在确定性任务上又快又稳。混合方案还需要考虑图片在工具链之间怎么传递。云端模型 API 输入输出通常都是 URL所以我把上传的图片先存入 OSS生成一个可访问的 URL。抠图接口返回的透明 PNG 也先上传 OSS再把 URL 传给下一步。图片多跳转几次 OSS 会有点慢但我实测下来同一地域的 OSS 内网传输延迟很低属于可接受范围。2.3 多端能力复用UniApp 的跨端策略和我的妥协移动端用 UniApp 是为了省成本这是实话。一套 Vue 代码能编译到 H5、微信小程序和 App对于个人开发者来说省了至少一半工作量。但跨端不是免费的午餐我在开发过程中做了不少妥协。第一个妥协是画布预览组件。本来想用一个功能比较强的图像编辑 Canvas 库但发现这个库在小程序端不支持。后来我换成了两端都兼容的方案Web 端用一个开源 Canvas 编辑器封装成组件小程序端直接跳转到一个内置的图片预览页面裁剪和基础调整用原生 API 实现。虽然功能弱了一些但保证了核心链路在两端都能跑通。第二个妥协是上传方式。H5 端可以直接用input typefile拿到 File 对象小程序端必须通过wx.chooseImageuni.uploadFile才能上传。我在封装层做了一个上传适配器统一暴露chooseAndUpload()方法内部根据平台走不同逻辑。第三个妥协是 WebSocket 的兼容性。UniApp 在小程序端的 WebSocket API 和 H5 端实现有细微差别比如小程序断线重连需要自己处理心跳。我在 App 端最终放弃了 WebSocket改成轮询任务状态原因是小程序的 WebSocket 在切后台后经常被系统杀掉恢复时机不可控轮询反而更省心。3. 实操过程与核心环节实现3.1 数据库设计与任务状态机这个项目的数据库表不多但任务状态机的设计我花了不少心思。核心表就三张user用户表、task任务表、task_log步骤日志表。task表的关键字段包括id、user_id、input_image_url、output_image_url、status、current_step、steps_json、created_at、updated_at。其中steps_json存的是大模型规划出来的完整步骤流current_step记录当前执行到第几步。这样设计的好处是即使 Agent 调度服务在执行途中崩溃重启后也能根据这两个字段恢复任务进度不需要从头再来。状态机的流转我定义为PENDING - RUNNING - SUCCEEDED | \ | - FAILED v CANCELED为什么加一个CANCELED状态因为用户很有可能在任务执行到一半的时候后悔。比如背景生成太慢用户点了取消这时候如果后端还在继续调用云端 API既浪费钱又没必要。我的处理方式是任务执行循环里每一步开始前都会检查一下 Redis 中的任务标记是否被置为取消如果是就直接终止并返回已取消状态。3.2 Agent 调度器的核心循环实现Agent 调度器的核心循环是整个项目的心脏。我用伪代码描述一下工作流程方便理解func (a *Agent) Run(task *Task) { steps : parseSteps(task.StepsJSON) ctx : NewContext() ctx.Set(input_image, task.InputImageURL) for i, step : range steps { // 检查任务是否被取消 if a.isCanceled(task.ID) { task.UpdateStatus(CANCELED) return } task.UpdateCurrentStep(i, step.ToolName) result, err : a.ExecuteTool(step.ToolName, ctx, step.Args) if err ! nil { task.UpdateStatus(FAILED) a.LogError(task.ID, step, err) return } // 将结果写回上下文后续步骤可以引用 ctx.Set(step.OutputKey, result) task.LogStep(task.ID, step, result) } task.UpdateStatus(SUCCEEDED) task.UpdateOutput(ctx.Get(output_image)) }这里有几个实操中很重要的细节。第一是超时控制。任何一个云端模型 API 都可能因为网络问题或服务端负载高而卡住。我给每个工具执行都加了独立的 context 超时抠图类任务给 60 秒模型生成类给 120 秒超时后整个任务直接标记失败并记录是哪个步骤超时。这样排查问题的时候能精准定位到具体工具而不是笼统地看到任务失败。第二是重试策略。对于偶发的网络错误直接判定失败有点浪费。我用了一个简单的指数退避重试第一次失败等 2 秒重试第二次失败等 4 秒最多重试 3 次。但如果报错是参数错误比如图片 URL 无法访问或者鉴权失败那重试也没有意义直接返回错误。第三个是上下文的数据量控制。因为每一步工具的输出可能是一张图片 URL、一个 JSON 对象或者一段文本如果全量塞进上下文传入大模型做下一步规划Token 消耗会非常夸张。我的方案是上下文里永远只保留最近两步的结果摘要和图片 URL不保留完整数据。这样既限制了 Token 消耗也避免上下文过长导致模型理解偏差。3.3 前端交互与任务进度展示用户端的交互流程是这样的用户在 Web 或小程序里上传一张图片在输入框里用自然语言描述想要的修图效果点击生成。前端立即创建任务拿到任务 ID然后开始轮询任务状态接口。每轮询一次拿到current_step和steps_json前端根据当前步骤名称展示对应的提示文案——比如正在抠图就提示正在分离主体正在生成背景就提示正在绘制新背景。这里有一个很影响体验的细节不要把步骤名直接展示给用户。用户看到matting这种词会一脸懵但展示正在智能识别画面主体请稍候就友好得多。我在后端任务表里额外存了一个step_display_name字段由大模型在规划时顺便生成一个面向用户的中文短句前端直接展示这个字段就行。轮询接口的设计也需要注意性能。并发高的时候用户每 2 秒请求一次任务状态如果每次请求都查数据库压力不小。我的优化方案是任务状态变更时同步写入 Redis轮询接口优先读 Redis只有当 Redis 中没有数据时才回源数据库。实际压测下来这个优化能把接口的 QPS 支撑能力提升好几倍。3.4 基于用户反馈的并发与性能优化项目上线后我陆续做了几轮并发性能优化这里挑最有价值的两个记录一下。第一个是图片预处理的并发控制。一开始我以为并发瓶颈会在 Agent 调度器上后来通过日志发现真正卡住的是 OSS 上传和内网图片拉取的 IO 操作。同一个用户如果同时提交了多张图片批量处理串行上传会非常慢。我改成了上游并发处理限制最大并发为 5。可别小看这个改动批量修图的场景下整个任务链路的耗时从原来的图片张数乘以单张耗时变成了图片张数除以 5 再乘以单张耗时体感快了很多。第二个是结果缓存的按时失效策略。用户可能对同一张图片反复测试不同风格的背景提示词。如果每次提交都重新走一遍抠图和生成流程成本不可控。我的做法是根据图片内容的 MD5 值做一层结果缓存同样一张输入图片如果只是背景描述文字变了抠图步骤的结果可以直接命中缓存省下最贵的模型调用费用。实测下来这个优化至少帮我省了 30% 的 API 成本。4. 开发与上线过程中的问题排查实录4.1 大模型输出不稳定的处理方案开发过程中骚扰我最久的问题就是大模型的 Function Calling 输出不稳定。明明给的是同一个工具定义用户类似的请求有时候模型能正确输出结构化的调用参数有时候却死活不按 Schema 来要么多了一个字段要么少了一个必填项甚至偶尔还会把工具名拼错。我试过几种方法最终有效的是组合拳把工具定义的description写得更像人话明确说明字段的取值范围和单位。比如背景描述字段原来只写场景描述后来改成用 20-50 个字描述要替换成的场景包含光线、时间、环境元素在用户原始指令前拼接一段系统提示词明确指出如果用户的修图需求不明确需要先调用 understand_image 获取图片信息再决定后续工具在解析大模型响应时做 JSON Schema 校验失败就自动重试一次并带着校验错误信息让模型修正。这一步实测能把解析成功率从 85% 提到 97% 左右4.2 图像处理链路中的典型错误与修复记录图片格式兼容问题。不同云端模型 API 对输入图片的格式和大小要求不一样。有的要求最大边不超过 1024 像素有的要求必须是 JPEG 或 PNG。我一开始没做统一预处理导致用户上传一张 5MB 的 HEIC 图片传给抠图接口时直接报错。后来我在任务创建阶段强制做了一次标准化把图片统一转换为 JPEG 格式最大边缩放到 2048 像素以内质量压缩到 85%。这个预处理能用 OpenCV 高效完成增加的开销可以忽略不计但兼容性问题基本消灭了。结果图与原图尺寸不一致。背景替换类任务容易出这个问题模型生成的背景图尺寸和原图不一致导致合成后的图片出现拉伸或裁切变形。我后来在合成阶段加了一步智能居中缩放先获取前景透明图的原始宽高再根据背景图尺寸计算缩放比例保证前景主体比例不变然后居中对齐合成。这里用到的就是最基础的计算几何原理但要提醒一点缩放前一定要先抠图先缩放后抠图的边缘质量会变差。透明通道信息丢失。有一次合成结果整体发白排查发现是中间步骤将透明 PNG 转成 JPEG 导致 alpha 通道丢失。这个问题很隐蔽因为抠图结果本身看起来没有异常但走到合成步骤时前景的透明区域全变成了白色。修复方案是在内部传递中间结果时统一使用 PNG 格式只有最终输出给用户时才转成 JPEG。这算是一个典型的格式转换安全问题以后我在设计内部接口时都会明确标注允许的图片格式。4.3 任务失败但前端无感知的体验优化上线初期用户反馈最多的问题是点了一下没反应。查日志发现其实是任务已经创建了但 Agent 调度服务在处理时因为某个工具调用失败任务直接变成了 FAILED而前端没有明显提示用户以为没反应。我在前后端各做了一步优化。后端在任务失败时不仅标记状态还会把失败原因和失败步骤的用户友好文案存入任务表比如背景生成服务暂时不可用请稍后重试前端轮询发现状态是 FAILED 时不再只是静默刷新而是弹出一个明确的错误提示框展示失败原因并提供一键重试按钮。重试的本质其实是重新创建一个任务但复用原来的输入图片和用户指令所以对用户来说体验是连续的。另外我加了任务超时的兜底逻辑。如果某个任务 RUNNING 状态超过 10 分钟还没结束后端会主动标记为 TIMEOUT避免任务永久卡在运行中占用资源。4.4 多端兼容性问题的经验沉淀UniApp 的兼容性问题在项目后期集中爆发。小程序端对 Canvas 的底层实现和 Web 端差异很大我一开始写了一个混合模式的绘制方案在 Web 端用canvas的 2D 接口小程序端判断运行环境后改用小程序专用的 Canvas API。这个方案代码重复度高但胜在可控避免了一堆环境判断的复杂逻辑。还有一个很典型的问题是小程序端的图片下载和临时文件管理。小程序不允许直接使用一张网络图片作为 canvas 绘图素材必须先调用uni.getImageInfo或uni.downloadFile将网络图片下载到本地临时文件再绘制。这个过程如果网络差非常容易失败。我最后在下载图片的地方加了一层本地缓存同一张图片第二次使用直接走缓存大幅降低了失败率。这里我给要在 UniApp 里做图像处理的同学一个建议先摸清目标端的 Canvas 能力边界再决定功能范围。我一开始想当然地以为 Web 端能跑通的 Canvas 功能小程序端都能跑结果后来花了好几天改适配得不偿失。5. 上线后的数据表现与进一步优化思路5.1 项目上线后的实际表现和我的一些验证数据项目上线运行了大约一个月后我统计了一些关键数据。累计处理任务 8000 多次任务成功率约 91%剩下的 9% 里大部分是云端模型 API 偶发超时真正因为代码逻辑错误导致的失败不到 2%。平均任务完成时间大约是 8 秒左右其中抠图大约 2 到 3 秒背景生成大约 4 到 5 秒合成和预处理各 1 秒左右。这个响应速度在用户可接受范围内毕竟不是实时滤镜而是有生成过程的场景。任务成功率是我比较在意的指标。从最初的 80% 出头的成功率提升到现在的 91%核心变化其实不是在模型层而是在工程层——重试机制、超时控制、预处理标准化这几项加上的效果非常明显。很多 AI 应用看起来是模型不行实际是工程保障没做到位这是我在这个项目里最大的收获之一。5.2 从能用到好用还可以做的优化方向项目完结不代表没有优化空间了。我复盘后觉得还有三个方向值得继续做下去。第一个是增加用户手动修正结果的能力。现在用户如果对 Agent 生成的背景不满意只能重新输入一遍指令再试一次比较低效。如果能在前端增加一个基于当前结果继续调整的功能把当前结果图作为上下文传回 Agent用户就可以说背景再暗一点或者人物往左挪一点形成一个真正的多轮交互闭环。第二个是引入并行的步骤编排。目前的 Agent 执行计划是严格的串行链路但有些情况下多个工具之间并没有依赖关系比如同时调整色彩和添加滤镜。如果能识别出可并行的步骤整体耗时还能再缩短。这需要大模型在规划时输出一个 DAG有向无环图形式的执行计划而不是简单的数组实现复杂度会有明显提升但收益也直观可见。第三个是接入流式结果输出。目前用户必须等整条任务链路跑完才能看到结果如果能在 Agent 执行完关键的抠图步骤后先把半成品图推送给用户预览用户的等待焦虑会明显缓解。这其实是一种实时过程可视化的产品思路前端 WebSocket 已经具备推送条件后端需要把中间结果图也标记为可访问状态并推送给客户端。6. 写在最后的几个心得这个项目完结后我最大的感觉是全栈 AI Agent 项目的复杂度不在于某一个技术点有多难而在于把多条技术链路串起来的时候哪里都可能掉链子。如果你准备做一个类似的项目我的建议是先把任务状态机设计得足够清晰再把工具层抽象做得足够简单最后再考虑接入更多 AI 能力。状态机决定了你的系统能多稳工具层决定了你能多快地接新模型AI 能力反而是最容易被替换的部分。我个人在实际开发中还有一个体会别舍不得用云端 API也别什么都依赖云端 API。像抠图、背景生成这种重模型任务用云端 API 是最省时间的选择但像格式转换、压缩、基础色彩调整这些确定性操作本地算法又快又省钱。把这两类任务分清楚你的项目成本和体验都能兼顾。最后再分享一个实用的小技巧。Agent 调度器里每一步执行完之后把该步骤的输入参数和输出结果都记录到日志表里。这件事一开始看起来只是普通的日志记录但等到项目上线后排查问题的时候你会发现这个日志表就是排查问题最好的线索来源。不要相信自己的记忆要让系统帮你记住每一步发生了什么。项目做完了但这个方向我还会继续折腾。AI Agent 的编排能力加上图像处理这种直观可见的反馈场景组合起来还有很多玩法可以挖掘。如果你也在做类似的全栈 AI 项目随时欢迎一起交流踩坑经验。