做全栈这么些年手上项目一个接一个地完结但这次这个AI修图Agent项目确实值得单独拿出来好好复盘一下。不只是因为技术栈够全——Vue、Golang、UniApp、AI大模型全搅和在一起——更重要的是这个项目把“Agent”从一个概念真正落到了实际场景里让用户对着图片说一句人话就能完成一整套复杂的修图流程。这篇文章我会从项目定位、Agent架构设计、全栈实现细节、多端适配到上线部署把整个项目的关键环节和踩坑心得都捋一遍给同样想搞全栈AI项目的朋友一个完整参考。先说这个项目是干什么的。简单来说它是一款多端AI修图工作台用户可以通过自然语言指令完成人像美化、背景替换、清晰度增强、老照片修复、智能抠图、商品图去杂乱等操作。背后的核心引擎是一个按Agent思路构建的图像处理服务——它不是简单调一个API而是把“理解指令、拆解步骤、调用工具、分步执行、结果反馈”这套流程完整地跑起来。前端覆盖了App、小程序、H5和PC端业务层用了UniApp Vue 3后端服务用Golang编排AI能力整个项目从用户界面到AI服务端都是我们自己搭的。如果你是前端想转全栈或者正琢磨着把AI能力接进自己的产品里这篇复盘很有参考价值尤其是Agent工具调用的实现套路和全栈项目的代码组织方式我会分成几大块讲透。1. 项目定位与架构选型思路1.1 为什么选择AI Agent而不是传统修图模式传统修图软件的交互逻辑是“用户点按钮软件执行固定操作”不管是Photoshop里的滤镜菜单还是手机修图App里的美颜开关本质上都是离散功能的堆叠。用户需要先了解“磨皮”和“祛痘”是两回事需要知道“抠图”之后还要“换背景”对专业门槛有一定要求。我们的目标很明确让用户只输入一句口语化描述比如“把这个人的背景换成海边日落顺便调亮一点”AI就能接住这个需求。这就要求系统不能只做一个指令映射它得具备一定的“判断和规划”能力——先识别出指令里包含几个子任务然后决定调用哪些图像处理工具按什么顺序执行最后整合结果返回给用户。这其实就是Agent的基本形态感知输入、拆解任务、选择工具、执行动作、反馈结果。AI修图Agent和那些“一键成图”的脚本工具最本质的区别在于它有一层“任务理解和编排”的智能层而不是把用户输入死板地映射到某个固定函数。1.2 全栈技术选型Vue Golang UniApp怎么分工这个项目涉及的技术栈偏广我刚开始搭架子的时候就很明确每一层都要选最合适的工具而不是图省事一套语言打天下。前端这块业务面向的是多端用户。手机App、微信小程序、H5、PC后台管理端如果用原生开发去分别维护工作量直接翻四五倍。所以前端统一走UniApp Vue 3的组合。UniApp能一套代码编译到多个平台Vue 3的组合式API在维护复杂交互状态时比选项式API顺手得多。后端服务用Golang写核心原因是它适合做高并发的AI任务编排。修图Agent接到请求后往往要编排多个算法模型的调用期间的网络IO、任务队列、状态同步都比较密集。Golang的goroutine模型处理这类IO密集型任务非常舒服部署时又是一个单一二进制文件配合Docker做分发异常省心。AI这块服务端直接对接了多个图像模型服务包括人像分割模型、超分辨率重建模型、图像描述模型和对话理解模型。Agent的“大脑”部分用了大语言模型的Function Calling能力配合一套自定义的工具协议让模型懂得去调用我们封装的图像处理能力。1.3 项目模块划分与目录结构全栈项目最怕的就是代码堆在一起时间一长没人能维护。这个项目我在一开始就按职责把代码仓库拆成了几个相对独立的模块。ai-retouch-agent/ ├── app-frontend/ # UniApp 前端工程App/小程序/H5 ├── admin-console/ # PC 管理后台Vue3 Element Plus ├── server/ # Golang 后端服务 │ ├── api/ # HTTP API 层 │ ├── agent/ # Agent 编排核心 │ ├── tools/ # 图像工具封装层 │ ├── tasks/ # 异步任务队列 │ └── pkg/ # 公共库 ├── ai-worker/ # 图像模型调用 Worker └── deploy/ # Docker 编排与部署脚本这样的划分方式有几个明显的好处前端工程师可以独立开发UI逻辑后端同学专注Agent编排和API设计AI Worker服务因为只负责图像处理也能根据负载单独扩容。实际开发中我们经常遇到某个图像模型的队列堆积这个时候只要单独加Worker实例就解决了不需要动其他模块。2. Agent核心设计与修图工具链拆解2.1 Agent工作流从用户一句话到完整修图AI修图Agent的工作流是这个项目的灵魂。我把它拆成五个核心阶段每个阶段都有明确的职责边界。第一阶段是意图识别。用户输入“帮我把照片里的人抠出来换一个纯色背景然后把人调白一点”系统先把这句话送到大语言模型让模型输出结构化的意图数据。这里不是简单叫模型改个JSON而是通过Prompt设计和Function Calling机制让模型以固定Schema形式返回意图类型抠图背景替换美白、主体区域人像、背景描述纯色、附加操作提亮肤色。第二阶段是任务拆分。Agent拿到结构化意图后判断出这是一个三步任务第一步执行分割第二步执行背景替换第三步执行人像美白。这一步是在代码里完成的通过一个任务规划器把大目标拆成小的原子任务。拆分的依据是工具清单——Agent知道自己有哪些工具每个工具能做什么所以它会根据能力边界来规划路径。第三阶段是工具路由。每个原子任务对应一个具体的工具函数比如segmentation_tool、background_replace_tool、skin_whiten_tool。Agent拿着任务参数到工具注册表里面找到对应的处理器然后开始真实调用。这一步最关键的是参数的准确性比如背景替换工具需要接收分割结果的mask如果上一步Segmentation没能把mask传过来整个链路就会断。第四阶段是执行编排。多个工具调用之间有时序依赖前一个工具的输出是后一个工具的输入。这里我们维护了一个简单的有向无环图调度器负责按依赖关系逐个执行。比如“替换背景之前必须先做人体分割”节点之间有明确的前置约束不会出现乱序执行。第五阶段是回传整合。所有图像工具执行完Worker把处理后的图片上传到对象存储再把URL回传给Agent。Agent最后可能还会调一次语言模型生成一段给用户看的处理摘要比如“已完成人像分割背景替换为海边日落肤色提亮到了自然水平”。2.2 修图工具的封装与对接抠图、美颜、超分、修复图像工具是Agent真正“干活”的手。整个项目里我们自己封装了七个核心图像工具每个工具都有独立的接口定义和容错机制。人像分割工具负责把画面里的人像主体精准地抠出来。底层的深度学习模型输出的是带透明通道的PNG在人体边缘、发丝这些细节上做了引导滤波和边缘羽化处理避免出现生硬的切割效果。纯色背景替换和后续的美颜操作都重度依赖这个工具的输出质量。背景替换工具接收分割好的主体图和用户描述的目标背景用图像融合算法把主体贴到新背景里面。这里有一个细节直接贴上去会显得很假所以工具里还集成了色彩统一和阴影生成的处理让主体和新背景的光影关系尽量协调。很多人用到这步就停了但我们额外做了前景边缘的像素级混合效果差距非常明显。人像美颜工具把美白、磨皮、瘦脸、大眼这些操作聚合到一个接口里。底层没有用简单的滤镜叠滤镜而是通过人脸关键点检测生成像素级的形变和肤色映射。磨皮的时候会特意保留皮肤纹理细节避免出现那种“塑料脸”的失真效果。图片超分工具主要用于低分辨率图片的清晰度增强对比一些模糊的老照片特别管用。模型采用Real-ESRGAN的思路四倍放大后画面的边缘轮廓依然锐利不是那种生硬的插值放大纹理细节是真实补出来的。老照片修复工具则更进一步针对划痕、噪点、褪色做了专项优化在超分之前多跑了一个去划痕和颜色校正的预处理。图像扩展工具可以按比例扩展画布并用AI生成与画面风格一致的新内容把横图变竖图或做构图二次调整。移除物体工具做杂物清理比如去掉照片里多余的电线杆和路人通过涂鸦mask指定区域后生成替代内容。这些工具每个都跑过上百张真图的压力和效果测试不会说模型一换就整个崩掉。每个工具对外暴露的都是统一的接口格式输入一张图或图片URL加一组参数输出一张处理后的图片或图片URL中间所有算法细节都屏蔽在工具内部。这种统一封装的风格让Agent侧的工具调用代码变得非常简单——它根本不关心“超分”和“抠图”在算法上有什么不同它只需要知道哪个工具能完成哪个语义任务就够了。对后续代码维护和模型迭代来说这个设计非常关键。2.3 Agent工具协议定义与Function Calling实战工具要能被Agent正确调用两边必须有约定。这个项目里我们定义了一套自己的工具协议为了让大语言模型能理解并使用这些工具我们利用了主流大模型提供的Function Calling能力。具体来说我们把每个工具按照OpenAPI风格的Schema描述清楚包含工具名称、用途说明、参数名、参数类型、参数是否必填、参数取值范围。一个background_replace_tool的Schema长这样{ name: background_replace_tool, description: 替换图片背景保持主体不变。适合人像、商品图背景更换需要先完成主体分割或提供透明底图。, parameters: { type: object, properties: { image_url: { type: string, description: 输入图片的URL地址 }, background_prompt: { type: string, description: 目标背景的文本描述如海边日落、纯白背景、办公室 }, subject_mask_url: { type: string, description: 主体分割的mask图URL可选传入可提高边缘质量 } }, required: [image_url, background_prompt] } }调用大模型的时候我们把工具列表通过tools参数塞给它用户在对话里输入自然语言请求模型在生成回复时如果觉得需要调用工具就会返回一个tool_calls指令我们把指令转成真实的函数调用。拿到结果后我们再把图片URL和处理摘要回传给模型让模型接着理解或生成最终的自然语言回复。这里有一个很关键的经验工具描述一定要写得足够具体尤其是模糊描述会导致模型乱选工具。比如你想让人体分割和背景替换分两个工具如果你把分割工具描述成“图像分割工具用于抠图”模型可能会在“我需要把背景换掉”这个请求里直接去调分割工具而不是去调背景替换工具。我们后来把工具描述改成了“人像分割工具用于提取人像主体生成透明底图是背景替换的前置步骤”模型选错的概率马上就降下来了。工具的描述也是一种Prompt工程。工具名称的命名要直观参数描述要写清楚传入的值应该是什么范围比如“background_prompt”一定要注明是“背景的文本描述不能传图片URL”。维护工具注册表时必须像维护接口文档一样对待它每次新增工具这个Schema写不好后面Agent就会在茫茫多工具里迷路。2.4 多步任务调度与状态机设计Agent执行多步修图任务的时候要保持整个过程的稳定性和可观测性。我们的方案是每一步都处于明确的执行状态中整个流程用一个状态机来管理。状态定义方面任务从PENDING开始经过RUNNING进入SUCCEEDED或者FAILED失败允许有限次数的RETRY。当任务被拆成多个子任务时每个子任务都维护自己的状态父任务在所有子任务都成功之后才完成。任务编排层面我们实现了一个轻量的调度器核心逻辑是从任务队列里取出待执行的原子任务判断它的依赖是否全部完成。如果依赖完成就投递给执行器如果某个依赖失败直接标记当前任务失败并触发补偿策略。补偿策略用的是“重试一次降级方案”比如分割工具超时了重试还是失败就通知用户“当前繁忙请稍后再试”而不是让用户在漫长等待后看到一个神秘错误。实际开发中我们还发现Agent任务不能一直保持同步阻塞。AI修图任务一般都超过5秒HTTP长连接很难扛住。所以我们把任务设计成异步模式用户提交请求后立刻返回一个task_id前端轮询或者通过WebSocket订阅任务状态后端在任务完成后通过消息通道推送结果。这个设计在后面多端适配的时候帮了大忙小程序和App都能用同一套机制接状态推送不会出现某端连接被掐断的问题。3. 全栈实操从后端API到前端交互的完整实现3.1 后端Golang服务架构与任务队列落地后端Golang服务除了API网关和鉴权之外重头戏就是任务队列和Worker的实现。我们没有引入太重的消息中间件初期版本直接用Redis的List结构做任务队列配合Golang的goroutine池做并发消费。用户提交修图任务时API层先做基础校验比如图片URL是否可达、文件大小是否超限、用户是否有足够的调用额度校验通过就生成一个任务ID把任务详情序列化后Push到Redis队列。消费端的一组Worker协程从队列里BRPOP任务来执行这种结构简单直接单机撑个几百个并发任务没问题。最开始我没用代理通道直接在Server进程里并发调用AI能力结果经常出现某个模型服务超时把整个Server拖垮的情况。后来把Agent编排和图像调用拆出去放进独立的Worker进程Server只负责API和任务投递问题才彻底解决。API层我们用的Gin框架接口路径和组织方式已经很成熟。举个核心路由的例子r : gin.Default() api : r.Group(/api/v1) { api.POST(/agent/tasks, a.CreateTask) // 创建修图任务 api.GET(/agent/tasks/:id, a.GetTaskState) // 查询任务状态 api.GET(/agent/tasks/:id/result, a.GetTaskResult) // 获取任务结果 }创建任务的逻辑看起来很简单接收JSON请求体提取image_url和instruction然后做两件事。一是同步调用一次大模型让模型解析用户的自然语言指令生成工具调用计划这一步是同步等待的一般2-3秒返回。二是把工具调用计划包装成一个任务投递到Redis队列立即返回task_id。这里有一个值得分享的权衡为什么不把“意图解析”也放进异步任务里我们实测发现用户提交指令后如果没有一点点同步等待的感觉纯异步回来一个“处理中”交互上会有点懵。而且同步返回任务计划还能让前端在下一次请求时拿到结构化的步骤列表比如“即将执行1. 人像分割 2. 背景替换 3. 提亮美化”用户的感知会好很多。3.2 前端UniApp多端适配与交互设计前端这块是用户能看到的部分UI和交互直接决定了项目的使用感受。我们基于UniApp构建同时编译到App、微信小程序和H5。用UniApp这套方案虽然做不到每个平台都100%的原生体验但胜在开发效率高逻辑代码一套搞定。修图核心交互集中在“上传图片 → 输入指令 → 查看效果”这个闭环里。用户上传图片的时候我们支持拍照和相册选择小程序端会用uni.chooseImageApp端偏原生一点用图片选择插件H5直接走文件上传。上传的图片先压缩到2MB以内前端用canvas绘制压缩图避免原图过大导致传输太慢。指令输入框是我们做得很用心的地方。除了普通的文本输入我们给用户预制了一批提示词模板像“一键去背景、换纯色背景”“人像动漫化”“老照片修复增强清晰度”。用户选一个模板指令就自动填进去对完全不懂修图的小白来说这个交互门槛就低多了。提交任务之后前端进入一个任务卡片视图。卡片上展示当前执行到哪一步了后端通过WebSocket推送状态前端动态更新步骤的进度和状态。最后一张处理前和处理后的对比图以左右拖动滑块的形式呈现直观展示效果差异。多端对比图交互实现的时候H5直接用CSS滑块搞定小程序要用movable-area来模拟App端则是canvas绘制各端的实现细节确实有差异需要单独处理。还有一点值得提醒小程序端的WebSocket连接和App端不一样退出页面时会自动断开所以在onHide生命周期里要主动处理监听器的释放和重连逻辑否则会出现用户切后台再回来任务状态半天不刷新的情况。后面我们干脆加了一个兜底策略——页面重新展示时额外调用一次查询接口把最新状态拉回来。3.3 管理后台与用户资产体系全栈项目不只是用户端一个面管理后台是运营侧的必备模块。资产管理后台我们用Vue3 Element Plus单独搭建了一个admin工程主要看几个东西用户维度看调用次数、任务成功率、平均耗时任务维度看每种工具的使用占比比如背景替换是不是比超分用得多这直接影响后续算力分配图片结果维度可以人工审核AI生成内容万一模型生成了不合适的内容后台能一键下架删除。用户资产体系这块我们设计了简单的积分制新用户注册送20积分一次抠图消耗2积分一次老照片修复消耗5积分积分不足的时候提示充值或订阅。积分系统单独放在Golang服务里的一个模块操作扣减用Redis的原子递减防止并发扣成负数。这个小系统虽然简单但对商业闭环的验证非常重要毕竟一个项目如果能跑通用户付费就说明产品真的有价值。3.4 AI能力接口异常重试与服务降级AI能力调用是全程最容易出问题的地方大模型、图像模型任何一个超时都可能让整个任务挂掉。我们做了两层防护。第一层是超时控制。所有的AI模型调用都设置明确的超时时间大模型Function Calling的响应超时设为15秒图像模型看具体任务类型分割和超分这类耗时的设为30秒。超时之后不是直接失败而是进入重试队列指数退避重试最多3次每次间隔逐步拉长。第二层是服务降级。如果重试还是失败我们就走降级方案——用户请求的是背景替换但分割模型挂了那么系统自动改为调用较慢但更稳的备选模型服务而不是直接报错。对用户来说他只是在等待时间上多花了几秒但不至于完全用不了。这种容错设计在对接多家AI能力的时候尤其重要。我们早期很天真认为第三方AI服务一定稳定可用结果上线第一天就被教育了。外部服务的稳定性是不可控的业务系统必须为自己的可用性兜底。后来我们把每一种能力都抽象成接口底层可以有多个实现运行时按健康度动态路由整个系统的稳定性明显上来了。4. 项目管理、部署上线与常见问题排查4.1 多端工程的整体发布流程全栈项目开发完只是开始能够高效发布上线才是结束。我们的项目发布流程是这样的功能开发完成后先跑一键式自动化测试前端检查编译产物能否正常产出后端跑接口测试集。然后把Golang服务打成Docker镜像推到镜像仓库前端UniApp分别编译成各端产物小程序直接上传到微信公众平台App端打包成安装包H5产物放到CDN。部署环境上我们用的是Docker Compose编排所有服务包括Golang API服务、Worker进程、Redis和MySQL。机器配置不需要太高档4核8G的云主机就能跑起来等用户量上来之后再把Redis和API服务拆开到独立机器。部署这块一定要提前做不要等项目做完了才考虑上线问题。很多全栈项目烂尾在部署阶段就是因为代码在本地跑得好好的一到线上就各种环境问题。我们从第一次联调开始就坚持用Docker跑环境后面上线的过程一路顺畅。4.2 实操中遇到的典型问题速查整个开发过程里踩过的坑不少我挑几个典型的整理成了表格大家做类似全栈AI项目的时候能有个预期知道哪里容易出问题提前防范。问题现象根因分析解决方案Agent接到指令后调用工具混乱比如“换背景”却调了分割工具工具描述与用户意图的语义匹配不清晰重写工具Schema描述明确每个工具的适用场景、前置条件和限制把相似工具的边界划清楚多端中某端收不到任务状态推送各端WebSocket生命周期不一致页面切后台连接断开回到前台时主动刷新一次任务状态查询后端保留任务的最新状态快照大模型返回的工具调用参数格式非法Image URL被截断模型输出不稳定偶尔会在参数里混入额外字符参数解析后做严格校验解析失败就自动重试一次重试时在Prompt里附加格式要求图片处理时间过长前端频繁轮询也有延迟任务队列消费速率跟不上提交速率Worker数量不够增加Worker实例并给不同工具设置不同优先级队列轻量任务先执行原图超过10MB上传失败或处理超时图片没有在客户端压缩模型端也无法处理超大图片前端统一压缩到合理尺寸服务端再做一次校验和转码Redis队列数据堆积导致任务延迟消费者异常退出队列里积压了大量任务给任务记录添加超时和心跳机制Worker崩溃后自动重新入队小程序端调用上传接口偶发白屏小程序对部分图片格式兼容性不佳前端统一转成JPG格式再上传同时捕获异常并提示用户重新选择4.3 性能优化图片处理和模型调用的提速技巧性能是AI修图项目的生命线用户等太久会直接流失。我们在性能优化上做了几件事。第一是图片预处理前置。用户上传的图片先在客户端压缩到合适尺寸服务端只处理压缩后的图片等处理完成再拼接大图版本。这样可以明显减少模型端的输入数据量提升推理速度。我们实测同样的分割模型处理一张1200px的图和处理一张4000px的图耗时会差两三倍。第二是结果缓存。同一个用户的同一张图选择同样的处理参数短期内不需要重复跑模型。我们以图片内容的感知哈希值加指令参数做key在Redis里缓存处理结果。用户重复提交时直接秒回既省了算力成本又优化了用户体验。第三是并发调度GPU和推理服务。AI Worker服务支持并发调用模型接口但要注意模型服务本身有个最大并发数超了会排队。我们根据模型服务的能力动态控制并发不让请求无限打过去造成雪崩。4.4 项目扩展与商业化探索的方向项目完结不是终点它的架构决定了它能往哪些方向继续延伸。我这里列出几个我们在复盘时讨论过的扩展方向。第一个方向是修图能力插件化。现在七个工具是写死在注册表里的但工具协议已经支持动态注册。完全可以做一个工具插件市场开发者按照我们定义的Schema开发新的修图工具上传后就能在Agent的工具库里上线。这样产品就从一个封闭工具变成了可扩展的平台。第二个方向是围绕“批量处理”做能力。目前还是单张图片的修图任务但商品电商场景里商家一次要处理几百张商品图批量去背景、批量统一色调的需求很常见。在现有任务队列基础上加一个批量任务编排器就能实现用户上传一个图片列表给一段统一指令Agent自动遍历处理并汇总结果。第三个方向是做专属工作流。用户在后台拖拽编排工具节点生成一条“自动化修图流水线”以后上传新图自动跑这条流水线。这和Zapier、Make这类自动化平台的逻辑一致本质上就是把Agent的能力沉淀成用户可以自定义的“技能路线”。这些方向都不是推倒重来而是顺着现有架构自然长出来的。这也是我做全栈项目时一直坚持的原则——基础架构要留出扩展位要为后来的可能性提前铺好路。最后再分享一点个人做全栈AI项目的体会。全栈开发容易让人陷入“什么都碰一点什么都不精”的状态但AI项目其实非常考验全局思维能力。前端交互怎么做才能让用户理解AI处理过程后端任务编排怎么设计才能扛住不确定的算法耗时AI能力怎么封装才能优雅地解耦和多路替换——这些问题一环扣一环任何一个层面掉链子整个项目体验都会拉胯。这个AI修图Agent项目做下来我最大的收获不是多会了几个框架而是真正理解了什么叫“系统设计”——先有对Agent工作流的清晰建模把修图工具的边界定义清楚再把每一步落到恰当的技术实现上。后面我再做其他AI项目整体的节奏和稳定性都跟以前不是一个水平。全栈AI真的不只是技术堆叠更是一种从全局想问题、从细节做事情的思维方式。
