前天凌晨一点我把最后一个Bug修完把全栈AI修图Agent的版本号从0.9.8改成了1.0.0。这个项目从立项到完结前后花了三个月期间推翻了两版架构砍掉了三个听起来很酷但实际没人用的功能。今天这篇不写流水账直接把整个项目的设计思路、技术选型、踩坑经过和实操细节一次讲完。这个全栈AI修图Agent简单说就是一个Web应用用户上传一张图片用自然语言描述想要的效果比如“把背景换成白色产品往左移一点”“帮我把这个人脸磨皮再加个胶片滤镜”Agent会自动理解需求、拆解任务、调用底层AI修图模型最后输出处理完的图片。听起来不算复杂但真做起来难点全在“拆解”和“调度”这两个环节上。如果你正打算做一个完整的AI应用或者在小团队里负责AI能力落地又或者对Agent开发感兴趣但不知道怎么入手这篇文章应该能给你一些可以直接抄作业的参考。1. 项目整体设计与思路拆解1.1 为什么是Agent而不是又一个滤镜App先说需求来源。市面上修图工具其实已经很多了从专业级的Photoshop到手机上的各种一键美化但它们的交互逻辑全是“人找功能”用户得自己知道要做什么然后去菜单里找对应的按钮。可现实中大量普通用户的问题不是“怎么磨皮”而是“我想要那种看起来很高级的照片但我说不清楚具体要改哪里”。这恰恰是自然语言的优势场景。用户不用理解什么磨皮、锐化、色温、对比度只需要说“我想要一张干净的证件照”或者“把这杯咖啡从桌上P掉”剩下的交给系统。Agent就是承担这个“翻译调度”的角色把一句模糊的人类语言变成一组明确的图像处理操作。所以这个项目的定位从一开始就很清楚不是做一个“AI滤镜集合”而是做一个“能听懂人话的修图助手”。用户和系统之间只有一个对话框加一张图系统背后串起多个AI能力但用户完全不感知。这种交互形态如果用传统表单来做每个功能都得设计一套参数面板用户学习成本极高用Agent来做反而把交互收敛到一个输入框里产品逻辑清爽很多。1.2 全栈技术栈选型背后的考量项目代号叫PixelAgent技术栈基本围绕Node.js生态展开。很多做AI应用的人默认选Python因为AI模型接口大多在Python这边但实际做全栈产品时Node.js的工程效率优势非常明显前后端同构、部署轻量、WebSocket和流式处理天然友好。我最终的选择是模块选型理由前端框架Next.js 14 TypeScriptApp Router方便做服务端渲染同时可以当纯前端壳用SEO也不吃亏全局状态Zustand比Redux轻太多Agent运行时的任务状态经常要跨组件同步Zustand写起来最顺手后端框架NestJS模块化程度高依赖注入让Agent、任务队列、图片处理这些模块边界很清晰异步队列BullMQ Redis修图任务耗时动辄几秒到几十秒绝不能同步请求队列是刚需业务存储PostgreSQL Prisma业务数据量不大但关系结构复杂需要存任务、图片、操作记录、用户反馈文件存储S3兼容对象存储原图、中间产物、结果图都走对象存储本地磁盘只放临时缓存图像理解多模态大模型负责看懂图片和指令这块做到了模型无关OpenAI、Claude、国产模型都能切图像处理ComfyUI工作流 HTTP API去背景、超分、人脸修复这些能力都封装成独立工作流用HTTP调用稳定且可控后端选NestJS而不是Express或Fastify核心原因是Agent系统涉及的“零件”太多LLM调用、工具注册、队列调度、图片处理、任务恢复如果没有依赖注入和模块化约束项目写到后面一定会乱成一锅粥。NestJS的模块体系能让每个域自治测试也好写。1.3 核心功能范围界定第一阶段上线时功能范围是刻意收敛的。只做了五类场景电商商品图处理去背景、换背景色、批量处理、产品居中调整人像照片优化自动磨皮、面部修复、老照片清晰化局部修改指定区域去水印、消除杂物、替换画面元素风格化处理胶片滤镜、黑白调色、统一风格色调基础操作裁剪、缩放、旋转、压缩格式转换为什么只做这五类因为Agent系统的复杂度会随着工具数量线性增长。工具越多大模型在意图理解时的选择空间越大误选、错选的概率也越大。先把核心场景的准确率做到90%以上再逐步扩展工具这是Agent产品落地时非常重要的一条经验。2. 核心细节解析与实操要点2.1 Agent的任务拆解机制整个系统最核心的部分是把用户的自然语言转成一组结构化任务。这一步如果做不好后面所有图像处理都是白搭。我的做法是用大模型的函数调用Function Calling能力而不是让它自由发挥输出JSON。两者的差别非常大函数调用让模型从预定义的工具集合里选格式由模型厂商保证基本不会出现JSON格式错乱自由输出JSON虽然灵活但要处理各种格式异常即便加了prompt约束也经常翻车。为了让模型拆解任务时足够稳定System Prompt里写清楚了三件事角色定义、工具清单、输出约束。核心内容大概是这样的你是专业修图任务拆解引擎。用户会提供一张图片和一段自然语言修图需求。 你需要将需求拆解为一系列可执行任务。 当前可用的工具 - remove_background去除图片背景 - replace_background替换背景颜色或图片 - face_restoration人脸修复/美颜 - super_resolution超分辨率放大 - color_grading调色/滤镜应用 - inpainting局部消除或替换 - crop_resize裁剪与尺寸调整 - watermark_remove去水印 输出要求 1. 只输出JSON数组不要额外解释。 2. 每项包含tool字段、parameters字段、dependsOn数组。 3. 任务之间如果存在先后依赖必须在dependsOn中声明。 4. 如果需求超出工具范围输出reason字段说明原因不要编造工具。有一个细节很容易被忽略任务依赖。用户说“把背景去了然后换成浅灰色”这其实是两个任务而且第二步依赖第一步的结果。如果不声明依赖关系执行引擎就不知道要先做哪个或者盲目并行导致结果错误。所以在设计任务结构时dependsOn字段是必须的。2.2 工具函数的设计与参数约束每个工具本质上就是一个带JSON Schema的函数描述。大模型看到这些描述之后才能决定“该调哪个函数”“参数填什么”。这块设计的核心原则是描述要足够具体参数要尽量收敛。我当时注册了8个工具每个工具的描述都写了“在什么情况下使用”“不建议在什么情况下使用”。举个例子remove_background的描述大概是这样的const tools [ { type: function, function: { name: remove_background, description: 去除图片背景返回透明背景PNG。适合商品图、人像图不适合复杂插画和漫画。, parameters: { type: object, properties: { imageId: { type: string, description: 待处理图片的ID }, refine: { type: boolean, description: 是否精修边缘毛发默认false } }, required: [imageId] } } } ]工具数量控制在8个是我踩过几次坑之后的结论。最开始我注册了15个工具意图识别准确率明显下降模型会经常把相似功能的工具搞混比如“去水印”和“局部消除”在用户语境里很难区分。后来合并同类项把相似功能收敛到一个工具里用参数区分场景准确率一下就上来了。另一个容易被忽视的点是参数校验。大模型给出来的参数值有时会超出枚举范围比如replace_background的颜色参数模型可能会传一个不存在的颜色名。所以工具执行层必须做参数白名单校验不合法就返回错误让模型知道修正而不是直接崩掉。2.3 前端交互与实时任务进度前端体验上最大的坑是“用户不知道Agent在干嘛”。修图任务执行时间短则两三秒长则一分钟如果界面只是在转圈用户会非常焦虑。所以必须把任务级进度透出给用户。我的做法是前端调起任务后通过SSEServer-Sent Events订阅任务状态流。后端每完成一个子任务就往流里推一条消息当前任务移除背景 等待模型处理... 背景移除完成正在替换背景色...SSE比WebSocket轻量很多服务端实现简单前端用EventSource就能接不需要维护双向连接。对于这种单向状态推送的场景SSE足够用。图片预览交互上我做了对比滑轨拖动滑块可以看到处理前后的差异。这个功能看着简单但很能提升产品质感用户处理完一张图后的第一反应就是“我要看看改了多少”。对比图是在后端合成的前端的实现成本几乎为零。2.4 图像处理工程化的几个硬性要求图像处理链路里有一些工程细节不做就会在线上踩雷。第一是统一图片输入标准。不管用户传的什么格式到了后端先转成RGB的PNG或JPEG最长边限制在2048像素以内超过就等比压缩。原因很简单底层模型服务尤其是ComfyUI对输入尺寸有要求超大图会直接把显存打爆或者处理时间长得不可接受。第二是原图备份。所有操作都基于副本进行原图永不覆盖。用户后悔了要撤销直接把原图重新推入任务队列就行。这个机制能省下大量口水。第三是中间产物清理。去背景、超分这类流程会产生大量临时文件如果不定期清理对象存储的费用会非常难看。我用一个定时任务删除24小时前的中间文件只保留原图、最终结果图和对比图。3. 实操过程与核心环节实现3.1 项目目录结构与职责划分项目是Monorepo结构前后端放在同一个仓库里用pnpm workspace管理。目录大致如下pixel-agent/ ├── apps/ │ ├── web/ # Next.js前端 │ └── api/ # NestJS后端 ├── packages/ │ ├── shared/ # 前后端共享的TypeScript类型定义 │ ├── tools/ # 工具函数定义与参数Schema │ └── workflow/ # ComfyUI工作流配置与调用封装 ├── docker/ │ ├── compose.dev.yml │ └── compose.prod.yml └── scripts/ ├── cleanup.mjs # 临时文件清理脚本 └── seed.mjs # 初始化工具配置这种结构的好处是类型定义可以共享前端调用API时请求和响应的类型不会漂移。tools包单独抽出来是因为工具列表既会被NestJS用来注册也会被前端用来展示“当前Agent能做什么”的提示。3.2 Agent调度核心流程Agent的调度流程走了四步解析指令、拆分任务、执行任务、汇总结果。核心代码简化后大致是这个样子async function handleUserRequest(userId, imageId, instruction) { // 1. 调用多模态模型理解图片指令得到结构化任务列表 const tasks await llm.understand({ imageId, instruction, tools: registeredTools }); // 2. 校验任务合法性过滤掉不存在的工具 const validTasks tasks.filter(t toolRegistry.has(t.tool)); // 3. 根据依赖关系拓扑排序有环直接报错 const sortedTasks topologicalSort(validTasks); // 4. 创建任务记录推入执行队列 const job await createAgentJob(userId, imageId, sortedTasks); await queue.add(agent-job, { jobId: job.id }); return job.id; }执行引擎就是一个消费队列的Worker。每个任务执行前先检查依赖是否全部完成执行后把结果写入任务上下文供后续任务读取。所有中间结果都暂存在Redis里避免重复读写对象存储。这里要特别强调一下超时和失败处理。每个任务都必须设置超时时间我一般按工具类型区分去背景15秒超分30秒人脸修复20秒。超时后任务标记为失败由Worker决定是重试还是中止整个Agent流程。如果是模型服务偶发抖动重试两次基本能过如果连续失败就停止整个Job并通知用户不要让用户干等。3.3 对接AI修图模型的接入方式图像处理能力我没有从零训练模型而是基于ComfyUI搭了一套工作流再把工作流封装成HTTP接口。ComfyUI的好处是节点化编排去背景、超分、人脸修复这类能力都有现成节点而且可以精细控制模型参数。封装方式是在ComfyUI前面加了一层薄薄的适配器把内部的节点参数映射成简单的业务参数。比如超分接口async function superResolution(imagePath, scale 2) { const workflow loadWorkflow(upscale); workflow.setInput({ imagePath, scale, model: realesrgan-x4plus }); return await workflowClient.submit(workflow); }业务层完全不知道ComfyUI内部怎么组织节点只关注输入输出。这层抽象在后续换模型供应商时非常有用比如把超分引擎从Real-ESRGAN换成其他模型只需要改workflow配置业务代码一行不动。3.4 从开发到上线的部署细节部署层面我用了Docker Compose编排整套服务GPU机器上单独跑ComfyUI容器应用服务和模型服务物理隔离。这样ComfyUI崩了不至于拖着主服务一起死而且模型更新时可以独立重启。关键的部署配置有这么几条反向代理层的上传大小限制要调大至少50MB同时在后端再做一层20MB的压缩后校验Redis和PostgreSQL必须做持久化否则容器一重启任务队列和任务记录全没了ComfyUI容器要设置GPU resource reservation否则 Docker 默认不会把GPU挂进去API Key等敏感信息只走环境变量绝不进代码仓库上线后踩过最痛的一个坑是默认配置下BullMQ的Worker如果长时间不消费消息会被判定为stalled任务自动重试结果重试堆积把模型服务打挂了。所以要合理配置lockDuration和maxStalledCount别让重试机制变成雪崩的导火索。4. 常见问题与排查技巧实录4.1 自然语言指令解析不准怎么办这是Agent类产品最常遇到的问题。用户说“把这个弄好看一点”模型根本不知道“好看”具体指什么。我的处理策略是加了一层“意图置信度”判断如果模型认为指令过于模糊就主动向用户追问一个关键问题而不是硬拆任务。比如用户只是说“让图片更好看”Agent会回复“我注意到图片是一张人像照片你希望我做人脸美颜优化还是调整整体色调或者两个都要”这种追问机制把很多无效任务拦截在了执行之前效果提升非常明显。还有一个技巧是把常见指令模式写进System Prompt做few-shot。用户说话虽然千奇百怪但高频请求其实就那么几十种。把这几十种典型指令和对应的任务序列作为示例写进去模型的选择准确率会高很多。4.2 Agent任务一直卡在队列里不动前面提过BullMQ的stalled机制这是任务卡住的常见原因。除此之外Spring Cloud出现过Worker进程OOM后任务永远处于running状态的情况。排查时最有用的工具是BullMQ自带的队列监控面板可以看到每个任务的当前状态和卡在哪个环节。如果任务卡住了第一件事看Redis里有几个Worker在消费第二件事看模型服务的日志有没有报错。大多数时候是ComfyUI那边一次只处理一个任务排队排了很长时间。我给Worker加了并发控制默认并发数为2效果最稳定超过4个并发时GPU直接耗尽延迟雪崩。4.3 修图质量不稳定图像质量不稳定这个问题跟模型关系大但更多是参数设置的问题。去背景时遇到细碎头发总是抠不干净换了好几个模型都不理想最后发现是输入分辨率太低模型没有足够的信息分辨发丝。把输入图最大边从1024提到2048后效果明显改善。另外很多模型服务对输入图片有隐性假设。比如人脸修复模型如果输入图里人脸只占一小块区域修复效果就不行。解决方法是先做人脸检测把人脸区域裁出来单独处理再贴回原图。这个“分而治之”的思路在图像处理链路里非常常用。4.4 高并发调用下模型服务被打爆测试阶段压测到20个并发任务时ComfyUI直接返回503。后来给模型服务加了一层信号量限流超过并发上限的请求先在本地排队而不是直接打到ComfyUI。配合BullMQ的任务优先级我可以保证VIP用户的紧急任务插队优先处理。还要注意模型服务的无状态化。ComfyUI的API默认是HTTP长连接一个任务做完前不会返回。我给适配器层加了超时断开和重连机制防止模型端卡住导致客户端连接堆积。症状大概率原因排查方法任务队列积压Worker并发数过高或模型服务过载查看BullMQ监控限制并发数JSON解析失败模型自由输出格式不稳定切换成Function Calling增加重试图片处理结果发灰色彩空间转换错误检查是否统一用sRGB避免CMYK输入超时失败过多输入图片尺寸太大预处理压缩限制最长边原图被覆盖没有做好副本隔离所有操作基于副本原图只读4.5 前端渲染性能与图片加载优化前端也有坑。处理结果图动辄10MB以上直接放进 标签会让页面卡死。我做了三层优化第一层是后端生成预览用缩略图最长边1080第二层是前端用懒加载和IntersectionObserver只在图片进入视口时才加载第三层是CDN缓存重复查看同一张结果图时直接走缓存。还有一个体验细节是图片对比滑轨的实现。单纯比较处理前后整图对用户不够直观我实现了局部对比拖动滑块时只有滑块左侧显示处理前、右侧显示处理后这样用户能精确看到某个区域的变化。这个功能上线后被好几个用户特意夸过。5. 项目复盘哪些该做哪些该砍5.1 砍掉三个功能是正确决定项目过程中砍掉了三个功能。第一个是“AI生成贴纸”就是让用户上传图片后生成配套贴纸素材。听起来有意思但仔细一想跟修图主线关系不大而且生成内容质量不可控容易让用户觉得产品很玩具。第二个是“语音修图指令”技术上能做但识别准确率、噪音处理、打断重说的交互都要单独设计对初期产品来说太复杂。第三个是“老照片智能上色”因为上色效果主观性太强用户预期管理很难做省下来的时间都投入到核心场景了。砍功能也是能力。AI产品最容易犯的毛病就是什么都想塞结果什么都做不精。把去背景、人脸优化、局部消除这三个高频场景打磨到极致比堆十个六十分功能有用得多。5.2 如果重做一遍我会改什么最大的改变会是工具注册机制。当前版本用代码注册工具加一个工具要写代码、走部署流程很重。如果重来我会设计成配置化的工具注册用JSON描述工具名称、参数、触发场景、调用的模型工作流让运营同学自己就能配置和调整不用每次改代码。第二是把Agent执行轨迹可视化。整个过程其实是一棵任务树理解了几条指令、拆成了几个任务、哪个先做哪个后做、每个任务花了多少钱多少时间。这套数据如果展示给用户会让Agent行为更透明用户信任度会提升很多。当时有点赶时间这个功能没做挺可惜的。第三是把模型调用层做更深度的抽象。现在LLM部分虽然做到了模型无关但图像处理模型还是紧耦合ComfyUI。如果重来我会把所有图像处理模型统一抽象成一个接口输入图片加参数输出结果图具体用ComfyUI、外部API还是自建推理服务全部由配置决定。这样换引擎只是改配置不用动代码。5.3 全栈AI项目最大的坑是什么说一个我体会最深的事。很多人以为全栈AI项目的难点在大模型毕竟模型能力是最性感的那个部分。但实际做下来整个系统最容易出问题的恰恰是那些不起眼的工程细节任务队列的可靠性、错误重试的幂等性、超时控制、并发限流、文件清理。模型用开源的和用商业的效果差距并没有想象中那么大但一个任务因为超时崩掉用户对产品的信任损失是模型效果再好也弥补不回来的。所以我在这个项目上养成了一个习惯每次加新功能第一件事不是写功能代码而是想清楚“如果这一步挂了会发生什么”。Agent系统里任何一个环节都可能挂而用户的诉求永远是“我传了图说了需求就想看到一个结果”。能不能扛住偶发失败并让用户体面地知道发生了什么才是全栈Agent产品从Demo走向可用之间最远的距离。这个项目完结后我又把工具集扩展到了视频封面处理的方向还是复用同一套Agent调度框架只是换了底层工具实现。事实证明Agent这套“理解-拆解-调度-执行”的骨架本身是通用能力换一个垂直场景就能长出新的产品。这也是我从这个项目里收获最大的部分。