这个项目做完了从立项到收尾差不多一个半月。名字叫“全栈 AI 修图 Agent”听起来挺唬人实际上做的事情可以概括成一句话让用户用自然语言描述修图意图一个 Agent 后台自己决定调用哪些图像处理工具、按什么顺序处理、处理完怎么返回结果。今天把这套东西从设计到实现完整拆一遍包括那些文档里不会写的坑。项目代码量不算大前端大约四千行后端加 Agent 编排逻辑差不多七千行但整个链路涉及的东西很杂模型推理、工具调用、状态管理、并发任务调度、前端画布交互每一块都有不少讲究。如果你正打算做类似的 AI 工具类项目或者想搞明白所谓的“Agent”到底在产品里怎么落地这篇应该能帮你少走不少弯路。先说清楚一个容易被营销号带偏的点这个项目里的“AI 修图”不是搞了个多厉害的生图模型真正的核心是“Agent 编排”。什么意思就是用户说“把背景换掉顺便给我磨个皮”系统要把这句话拆解成“抠图 → 换背景 → 人脸检测 → 磨皮 → 合成”这么一串操作然后按顺序调用不同的图像处理模块每一步还要看结果对不对不对就重新调整参数再来一次。这种“理解意图 拆解任务 调用工具 校验结果”的循环才是 Agent 的核心。下面开始正题。1. 这项目到底做了什么从需求反推设计先别急着写代码1.1 所谓“全栈 AI 修图 Agent”到底是啥项目标题里的“全栈”两个字很多人以为是前后端都会的意思其实放在这个项目里更准确的理解是“完整工程链路”。它不是一个简单的滤镜库也不是一个调 API 的 demo而是从用户输入自然语言指令开始到最终拿到一张修好的图中间所有环节都由系统自动完成的闭环产品。具体到功能上这套系统支持的操作包括人脸美化磨皮、瘦脸、大眼、背景替换、一键调色日系、胶片、赛博朋克等滤镜、图像修复去水印、去杂物、超分辨率放大。用户操作方式有两种一种是直接输入文字指令比如“帮我把这张图调成日系色调并且把背景换成海边”另一种是上传原图后在前端画布上框选区域再输入针对该区域的指令比如“只把框里的杂物去掉”。听起来功能不多但难点在于这些功能不是独立存在的。真实用户的需求往往是组合式的一句指令里可能包含多个操作意图而这些意图之间有先后依赖关系。比如“先帮我瘦脸再调色”和“先调色再瘦脸”在人脸特征点上做处理的逻辑是完全不一样的。Agent 需要能识别这种顺序要求而不是机械地把所有工具挨个跑一遍。这个项目的定位不是给专业设计师用的而是面向普通用户所以交互上要求尽量简单最好用户只需要说一句话剩下的交给系统。这也决定了技术上必须走 Agent 路线用大模型做意图理解和任务规划而不是人工把每种可能的组合都写死。1.2 为什么用 Agent 而不是传统规则流程做图像处理工具的老牌软件比如美图秀秀、Photoshop 里的批处理走的是规则流程。用户手动点选各种功能或者预设一套固定的操作序列每次执行都是一模一样的。这种方式的好处是稳定可控坏处是灵活度差。用户说“把这张图弄得高级一点”规则流程根本处理不了这种模糊的表达因为“高级”在不同人眼里是完全不同的操作路径。Agent 的思路是把决策权交给模型。大模型当“大脑”理解用户的模糊描述结合图像内容分析结果自主规划出一条操作路径。我在项目里做了一个对比测试用同一张人像照片和同一句指令“让这张照片更有质感”规则流程只能套一个预设滤镜而 Agent 会先检测人脸区域分析光线情况然后决定是否先做曝光补偿、再增强皮肤细节、最后叠加胶片颗粒效果整个路径每次都可能不同。两者怎么选取决于产品定位。如果你做的是固定功能流程比如证件照换底那规则流程完全够用上 Agent 反而是过度设计。但如果你做的工具要面对各种稀奇古怪的用户需求而且希望系统能不断学习优化那 Agent 的价值就体现出来了。这个项目因为目标是通用性修图助手所以从一开始就走 Agent 方案。我在设计阶段列过一个对比表格贴在项目文档首页提醒自己不要跑偏维度规则流程Agent 编排指令理解只支持固定操作项支持自然语言模糊表达任务规划预设路径不可变动态路径按需组合可扩展性每加功能要改主流程新增工具函数即可稳定性高不容易出错依赖模型能力偶发误判调试方式走断点看代码要看模型输入输出日志结论很明确这个项目要的是灵活度所以 Agent 方案是唯一合理选择。1.3 技术选型背后的几个考量技术选型这块我纠结的时间最长因为每个选择都是一连串连锁反应。后端语言最开始在 Node.js 和 Python 之间犹豫。Node.js 做 Web 服务很顺手异步处理 WebSocket 连接也方便但 AI 生态还是 Python 强图像处理库、模型推理框架大多都有成熟的 Python 接口。最后选了 Python 写后端FastAPI 做 Web 框架Uvicorn 跑 ASGI配合 WebSocket 做实时任务推送。前端用 React 加 TypeScript原因很简单Canvas 操作的生态和组件库在 React 体系下最成熟团队里也最熟。模型推理这块有两条路线本地部署开源模型或者调云端 API。最开始想全部本地部署可控性强不用考虑数据外泄但算力是个现实问题。一张 1080Ti 跑人脸关键点检测没问题跑超分就卡得不行。最后做了个折中抠图和人脸相关的小模型本地部署调色和超分这类吃算力的调用云端 API。这种混合架构的好处是大部分操作响应很快少数重计算任务虽然慢一点但用户可以接受。前端画布这块踩了个小坑直接用 Canvas 2D API 写图像编辑功能代码量非常大后来引入了 Fabric.js 做画布基础层。这个库封装了对象模型、缩放旋转、序列化这些基础能力省了至少两周工作量。不过 Fabric.js 性能上限不高图片分辨率超过 4000 像素后会明显掉帧项目里加了限制超过阈值的图先降采样再上画布处理完成后再把高分辨率原图传给后端做最终输出。2. Agent 核心链路从“听懂人话”到“动手修图”2.1 三层编排结构路由器、工具层、兜底策略整个 Agent 的编排结构我分了三层每一层的职责比较清晰。第一层是意图路由器。用户输入的指令进来之后先经过这一步由大模型判断这句话到底想干嘛。输出是一个结构化的 JSON包含操作类型列表和每个操作的参数。举个例子用户说“照片太暗了帮我提亮一点顺便去去噪点”路由器输出的 JSON 大致长这样{ actions: [ {tool: brightness_adjust, params: {level: 15}}, {tool: denoise, params: {strength: 0.3}} ], priority: [brightness_adjust, denoise] }注意这里有个priority字段用来表达操作的先后顺序。正常情况下工具执行顺序由 Agent 自己决定但如果用户明确说了“先提亮再去噪”那系统必须尊重用户的顺序要求。这个字段就是给这种场景留的口子。第二层是工具调度层。拿到结构化指令后这一层负责把操作映射到具体的函数调用。每个工具都是独立注册的有一个统一的接口签名后面代码部分会详细说。这一层的核心设计思想是“面向协议不面向具体实现”也就是说调度层不关心某个工具内部是本地模型还是云端 API只要工具模块按照约定返回结果就行。第三层是兜底策略层。这是我自己加的很多 Agent 项目会忽略这一层。兜底策略处理两类情况一类是工具执行失败比如模型超时、返回空结果需要 Agent 判断是重试、换参数还是换工具另一类是结果质量不达标比如人脸磨皮效果太假Agent 需要降低参数强度重新执行。这层本质上是一个独立的校验循环跑在主要执行链路之后。没有第三层的 Agent 是很脆弱的因为真实场景里模型必然有误判工具必然有异常如果所有错误都交给外层 try-catch用户体验就是莫名其妙失败。有了兜底策略很多小问题可以在内部消化掉。2.2 工具函数的接口设计与状态管理工具注册机制是整个 Agent 的骨架每个工具必须按照统一规范实现。我定义的接口长这样class ImageTool: name: str description: str input_schema: dict output_schema: dict async def run(self, context: ToolContext) - ToolResult: pass这个设计参考了函数调用的模式。name和description除了给开发者看更重要的是喂给大模型让模型知道有哪些工具可用。input_schema和output_schema是参数和返回值的 JSON Schema 定义模型通过这个了解怎么调用。实际项目里有这样一个具体例子人脸美颜工具的注册信息face_beauty_tool ImageTool( nameface_beauty, description人脸美颜支持磨皮、瘦脸、大眼、美白、红润等效果参数类型为字符串和整数, input_schema{ type: object, properties: { smooth: {type: integer, description: 磨皮强度, 0-100}, slim_face: {type: integer, description: 瘦脸强度, 0-100}, eye_enlarge: {type: integer, description: 大眼强度, 0-100}, whiten: {type: integer, description: 美白强度, 0-100} } }, output_schema{ type: object, properties: { result_url: {type: string, description: 处理后的图片下载地址}, face_count: {type: integer, description: 检测到的人脸数量} } } )有几个细节值得注意。参数范围直接写死在描述里0-100模型就能给出合理的参数值不会乱传。另外一个经验是参数名尽量用语义化的英文模型更容易理解。一开始我用的是s、f、e这种缩写模型经常给错参数后来改成全称准确率明显提升。状态管理这块是 Agent 项目里最容易出问题的点。修图操作是有状态的前一个工具处理完的结果是下一个工具的输入。我的处理方案是维护一个全局的图像状态对象包含当前图像 URL、修改历史、元数据每次工具执行后更新这个状态同时把状态的关键信息注入到模型上下文里。但这里有个矛盾如果把完整的图像状态全量塞给模型token 消耗会爆炸。折中方案是只注入状态描述不注入图像本身。比如状态对象里存了“当前图像分辨率 3000x2000已经做过磨皮处理人脸区域坐标 [(100,200), (300,400)]”模型读到这些文本信息足以判断下一步操作。2.3 上下文压缩处理长指令和多轮修改场景Agent 项目跑起来以后遇到最多的实际问题不是模型不够聪明而是上下文太长。一个修图会话里用户可能会连续提十几条指令“背景再换一张”、“脸再瘦一点”、“整体色调偏冷一些”每执行一次Agent 都要把之前的操作历史塞给模型很快 token 就爆了。我的解决办法是三层递进的上下文压缩策略。第一层操作摘要。不把完整的工具调用日志给模型而是维护一个动态更新的摘要比如“已完成调色(日系)、抠图当前人像位于画布中央背景为透明”。这个摘要每次工具执行完后由模型自行总结控制在 100 字以内。第二层会话裁剪。超过一定轮数后把最早的历史记录从上下文中移除只保留最近几轮的关键信息。这个思路有点类似操作系统的页面置换算法因为修图场景里用户最新的意图往往是最重要的早期的操作影响会逐渐衰减。第三层图像状态外置。图像本身不走模型上下文而是存到一个可访问的状态仓库里模型需要时通过工具查询。比如模型想知道当前图像是不是已经磨过皮了它调用get_image_status工具返回“已磨皮强度 40”而不是在上下文里带着整张图。这三层策略组合下来一个长会话的上下文消耗可以减少 70% 左右。这也是 Agent 项目能真正落地的关键不然只能做 demo没法做产品。2.4 工具调用的“确认-执行-校验”模式工具调用看起来简单就是模型给出参数后端执行函数。但直接这样做会出很多问题。最典型的是参数越界模型给了磨皮强度 150但工具只接受 0-100还有逻辑冲突用户要求“去水印”但同一个位置被处理了两次第二次去水印的时候直接把第一次的结果给破坏了。我后来设计了一套“确认-执行-校验”三步模式内部叫 CEC 循环。确认阶段模型给出一组工具调用意图后先不急着执行而是由校验层做一次参数合法性检查过滤掉明显不合理的值。这一步用 JSON Schema 校验加上轻量级语义检查比如检测人脸坐标是否超出图像边界。执行阶段调用工具模块。所有工具都是异步执行的对于耗时的模型推理操作比如超分辨率会把任务丢到后台队列通过 WebSocket 推送进度给前端用户看到的是“处理中 60%”。校验阶段每个工具执行完后结果不是直接返回给模型完事而是先过一个质量检测器。拿人脸美颜来说执行完要做一次人脸关键点检测对比处理前后的关键点位置变化。如果变化幅度超出预设范围说明效果太夸张系统会自动调低参数重新执行一次。这个机制在保存最终结果前加了一层保险避免“假脸”效果直接交给用户。这套循环让最终出图成功率从最开始的 68% 提升到了 91%。损失是平均处理时间多了一两秒但换来的是稳定可用的交付物这个代价相当值得。3. 前后端实现可复现的核心代码与踩坑指南3.1 后端服务模块划分FastAPI WebSocket 实时任务推送后端目录结构是我调试了几天后最终定下来的按照职责分模块而不是按技术分层分backend/ app/ main.py # FastAPI 入口注册路由和中间件 routers/ upload.py # 文件上传 tasks.py # 任务提交、状态查询 ws.py # WebSocket 连接管理 agent/ router.py # 意图识别与结构化输出 scheduler.py # 工具调度执行器 cecloop.py # 确认-执行-校验循环 tools/ registry.py # 工具注册表 face.py # 人脸相关工具 background.py # 抠图、背景替换 color.py # 调色工具 restore.py # 修复工具 enhancer.py # 超分工具 models/ local.py # 本地模型推理封装 cloud.py # 云端 API 调用封装 state/ image_state.py # 图像状态管理 utils/ image_io.py # 图像读写与格式转换 logger.py # 结构化日志每个模块都保持单一职责方便单独调试。任务提交接口是最关键的一个前端上传图片后调用下面这个接口创建任务app.post(/tasks) async def create_task( image: UploadFile File(...), instruction: str Form(...), region: str Form() ): task_id str(uuid.uuid4()) image_path await save_upload(image) # 如果用户选了画布区域格式为 x,y,w,h region_obj parse_region(region) task { task_id: task_id, status: pending, image_path: image_path, instruction: instruction, region: region_obj, created_at: datetime.now() } tasks_db[task_id] task # 丢到后台队列执行 asyncio.create_task(agent_process_task(task_id)) return {task_id: task_id, status: pending}注意这里用asyncio.create_task把 Agent 处理逻辑丢到后台而不是同步等待。因为一个完整的 Agent 处理循环可能要跑十几秒甚至更久如果同步处理前端请求直接超时。前端通过 WebSocket 接收任务状态更新。定义的消息协议只有几种{type: task_status, data: {task_id: xxx, status: processing, progress: 30, message: 正在抠图}} {type: tool_called, data: {task_id: xxx, tool: face_beauty, params: {...}}} {type: task_result, data: {task_id: xxx, status: success, result_url: https://...}} {type: task_error, data: {task_id: xxx, status: failed, message: ...}}前端拿到tool_called消息后会在界面上显示当前的工具调用轨迹用户能看到系统每一步在做什么而不是干等。这个细节对产品体验帮助很大很多用户反馈说看到“正在调用工具”这个过程反而觉得系统挺智能。3.2 Agent 调度执行器的核心实现调度执行器是 Agent 的主循环逻辑不复杂但细节多。核心代码如下async def agent_process_task(task_id): task tasks_db[task_id] task[status] processing try: # 1. 意图识别 ws_publish(task_id, {status: processing, progress: 5, message: 正在理解指令}) plan await agent_router(task[instruction], task[image_path]) # 2. 逐项执行工具 image_state load_image_state(task[image_path]) for step in plan[actions]: tool tools_registry.get(step[tool]) if not tool: continue ws_publish(task_id, {status: processing, tool: step[tool], params: step[params]}) # 确认-执行-校验 params await cecloop.confirm(tool, step[params], image_state) result await cecloop.execute(tool, params, image_state) image_state await cecloop.verify(tool, result, image_state) update_state(task_id, image_state) # 3. 生成最终结果 output_path await save_result_image(image_state) upload_url await upload_to_storage(output_path) task[status] success task[result_url] upload_url ws_publish(task_id, {status: success, result_url: upload_url}) except Exception as e: task[status] failed task[error] str(e) ws_publish(task_id, {status: failed, message: str(e)})这里有几个点我在实际运行中踩过坑。第一agent_router返回的plan不一定是可靠的。模型偶尔会生成根本不存在的工具名或者参数类型完全错误所以调度器里加了if not tool: continue的兜底遇到未知工具直接跳过并记录日志而不是让整个任务崩溃。第二image_state的传递不能只是变量传递因为工具执行可能在不同的 worker 里。项目里用 Redis 做状态缓存每个 task 的状态有一个独立的 key工具执行后写入下一个工具执行前读取。这样即使处理进程崩溃状态也能恢复。第三WebSocket 推送不能阻塞主流程。我一开始直接在主流程里调用ws_publish遇到大量并发任务时WebSocket 发送慢会拖累整体处理速度。后来改成了异步消息队列主流程只管往队列里丢消息由单独的推送协程处理发送解耦之后并发稳定了很多。3.3 前端交互设计画布、操作历史与实时反馈前端是整个产品观感上最直接的体现也是我改版最多的地方。第一版做得像内部工具一个上传按钮加一个输入框用户上传图片、输入指令、点提交、等结果。做完给朋友试用反馈是“不知道自己上传的图到底怎么样了”。第二版方向对了增加了大画布预览、框选区域、实时状态推送用户能清楚看到自己的图在处理过程中发生的变化。前端界面分三个区域左侧工具面板展示当前可用的工具类型包括人像美化、背景替换、调色、修复、增强。用户也可以不选工具直接输入指令全交给 Agent 决定。中间是 Canvas 画布区支持框选操作。用户可以用鼠标画一个矩形区域提交指令时会带上这个区域的坐标。这样实现“只处理选中的区域”效果很实用。比如一张家族合照里只有一个人闭眼了框选那个人的脸输入“把眼睛修成睁开的状态”系统会只对这个区域做人脸修复不会动其他人。右侧是执行日志区和历史记录区。执行日志区展示 Agent 当前正在调用的工具和进度历史记录区保留每一次操作的前后对比缩略图。画布部分用了 Fabric.js核心的框选监听逻辑如下canvas.on(mouse:down, (options) { const pointer canvas.getPointer(options.e); selectionStart { x: pointer.x, y: pointer.y }; }); canvas.on(mouse:move, (options) { if (!selectionStart) return; const pointer canvas.getPointer(options.e); // 绘制选区矩形 selectionRect.set({ left: Math.min(selectionStart.x, pointer.x), top: Math.min(selectionStart.y, pointer.y), width: Math.abs(pointer.x - selectionStart.x), height: Math.abs(pointer.y - selectionStart.y) }); }); canvas.on(mouse:up, (options) { // 保存选中区域坐标供提交指令时使用 const rect selectionRect.getBoundingRect(); selectedRegion { x: rect.left, y: rect.top, w: rect.width, h: rect.height }; });有个细节上传的图片和屏幕显示的图片之间有个缩放比。如果图片实际分辨率是 3000 像素宽画布显示只有 1200 像素那用户框选的坐标要乘一个系数才是真实图片上的坐标。这个换算如果做错了框选功能基本报废。我的做法是保存一个scaleFactor每次框选结束时自动换算并且把换算后的坐标显示在界面上方便开发时核对。3.4 模型部署策略本地推理与云端 API 混用模型部署这块是项目前期最花时间的部分因为要平衡效果、速度、成本和稳定性。本地部署的模型选的都是开源模型里效果和体积比较均衡的。人脸检测用 RetinaFace轻量版推理一张图大约 300 毫秒抠图用 RMBG-1.4一张 1024x1024 的图大约 1.5 秒人脸关键点检测用 SCRFD和 RetinaFace 配合使用速度也够快。这几个模型加起来显存占用大约 2.5GB一张 3060 就能跑得动。云端 API 用在了超分辨率、老照片修复这种重计算任务上。原因是这些模型参数量很大本地跑一张 2000 像素的图要好几分钟用户绝对等不了。云端 GPU 实例虽然也慢但至少是并行处理的而且调优后的推理服务比本地裸模型快不少。混合部署的关键是路由策略。调度层不关心工具背后的模型在哪里但路由层需要根据图像尺寸、当前服务器负载、工具类型做智能判断。比如超分工具图像分辨率超过 2000 像素直接走云端低于 2000 像素先本地降采样再走云端节省成本。这一块的经验是不要过度追求全部本地化。算力成本、GPU 运维成本、模型迭代成本这些都是真实存在的。个人项目或小团队项目混合架构是投入产出比最高的方案。4. 项目完结时的关键复盘这些问题你迟早也会遇到4.1 最典型的 3 类 Agent 翻车现场一个多月跑下来Agent 翻车的情况见了不少。最典型的三种基本覆盖了绝大多数问题。第一类是意图识别错误。用户说“帮我加深一下颜色”Agent 可能理解成“增加对比度”也可能是“增加饱和度”这两个操作出来的效果差别很大。应对办法是识别到不确定的意图时让 Agent 追加追问而不是硬执行。模式上叫“澄清式交互”在路由层加一个置信度判断低于阈值就回一个问题让用户确认。第二类是工具参数错误。模型知道要调用磨皮工具但给的参数不合适比如磨皮强度 80跑出来的效果跟画像似的。这个问题靠 CEC 循环里的质量校验解决了人脸关键点变形检测不过就自动降强度重跑。但要注意重跑次数不能无限项目里限制最多重跑两次第三次还不合格就直接返回失败并提示用户手动调节参数。第三类是上下文污染。前一次操作的结果被错误地带到了后一次操作里。最典型的是用户先做了背景替换然后说“清理一下画面里的杂物”Agent 可能直接对整张图处理把新背景上的纹理当杂物清理了。解决思路是每次工具执行前重新确认当前图像状态必要时回滚到某个历史版本。这些翻车场景其实都指向同一个问题Agent 不是越复杂越好而是要有一套完整的校验和恢复机制。单纯让模型多推理几轮解决不了问题工程上的兜底设计才是稳定性的根本保障。4.2 性能瓶颈与优化方案性能这块项目里最有代表性的优化是图像处理链路的并行化改造。最开始实现的时候所有工具按计划顺序执行前一步跑完才开始下一步。遇到简单的“调色 → 磨皮”链路还好用户等待 3 到 4 秒出结果。但遇到“抠图 → 换背景 → 调色 → 超分”这种长链路实测总耗时超过 25 秒用户早就没耐心了。分析后发现链路里有些操作其实没有依赖关系。比如抠图和调色可以并行因为调色作用于原图不依赖抠图结果。我把调度器改成了有向无环图的执行模型工具之间按依赖关系分组无依赖的操作并行执行。改造后同样一条长链路的耗时从 25 秒降到了 14 秒。另外一个优化点是图像中间结果的格式。工具之间传递的中间图一开始全部保存为 PNG有透明通道文件大读写慢。后来改成了 JPEG 加统一的透明通道遮罩读写速度提升了接近一倍。对于需要保留透明信息的场景单独用 PNG 存其他环节一律用 JPEG。最后一个优化是前端预览图的降采样。后端传给前端做缩略预览的图统一压到 1280 像素宽只有用户点击“下载原图”时才输出全分辨率结果。这样 WebSocket 推送过程的数据量小了很多交互也更流畅。4.3 Agent 编排层最容易忽略的两个设计点第一个是“终止条件”。Agent 在工具调用链上需要明确什么时候算“完成”。这个项目里定义了三种完成态所有工具执行完毕达到用户指定的操作数量上限质量校验连续两次失败触发回滚后停止。没有明确终止条件的 Agent在某些极端输入下会陷入死循环不断重新规划同样的操作。我在调试时遇到过模型反复调用同一个工具、参数还不带变的情况加了终止条件后才算根治。第二个是“可观测性”。Agent 编排层的问题排查难度比普通后端大很多因为中间多了模型推理的黑盒环节。所以项目从一开始就要求全链路日志结构化每个工具调用的输入、输出、耗时、决策原因都记录成 JSON 日志。出问题时我能很快定位是哪一步决策出了问题是模型理解错了还是工具本身出了故障。这一点强烈建议任何做 Agent 项目的人一开始就搭好不然后期排查 bug 能让人崩溃。日志结构大致长这样{ timestamp: 2024-12-15T10:23:45.123Z, task_id: abc-123, event: tool_call_start, tool: face_beauty, input: {smooth: 40, slim_face: 30}, decision_source: model_plan, reason: 用户要求自然美颜选择中等强度参数 }带上决策原因是整个日志系统里最有价值的部分。因为模型为什么要这么调用产品侧只能靠日志来复盘。4.4 项目管理层面的一点体会这个项目最后能顺利完结除了技术选型团队协作方式也很重要。从一开始就坚持模块化的目录结构每个人负责的模块边界清晰然后每周做一次全链路联调。Agent 项目的问题往往是跨模块的单测跑得再绿联调该崩还是崩。提前把联调节奏固定下来后面省了很多事。另外数据闭环是这类项目最容易忽视的部分。每次任务执行完毕后把用户的原始指令、Agent 的规划结果、工具的调用参数、最终输出和用户反馈点赞还是点踩全部存下来形成一份“指令-动作-结果-反馈”的数据集。这个数据集不仅是后续调试的素材甚至可以拿来做模型微调。项目刚上线时这部分的比重不大但越到后期越值钱。5. 给你的一些落地建议如果你准备动手做一个类似的 AI 工具类 Agent 项目我的建议是从一个极小的闭环开始不要一上来就想覆盖所有修图场景。第一周只做“一句话调色”就是用户输入“调成日系”“调成黑白”“调亮一点”后端用同一个调色工具Agent 只负责决定参数。这个闭环跑通了再把新工具一个个加进来。先跑通链路再考虑覆盖更多功能。一上来就堆集成出问题了查都不知道从哪里查起。另外在选大模型做意图理解时不用一开始就追求最强的模型。项目里最开始用一个通用对话模型后来对比了多个模型之后发现指令理解这块中小参数量的模型在加了示例的情况下完全够用而且延迟低很多。真正的效果瓶颈往往在图像处理模型上而不是意图理解上。最后再说一个工具层面的心得。Agent 项目里工具的质量和工具描述的质量比 Agent 框架本身重要得多。工具函数必须稳定可靠输出结构必须清晰明确描述信息要写清楚用途、参数范围和典型调用场景。模型很依赖这些描述来决定怎么调用工具描述写得含糊模型就只能瞎猜效果自然差。我把工具的描述当成核心文档对待每个工具的描述都要经过至少两轮修改才定型。这个全栈 AI 修图 Agent 项目的完整经验差不多就这些。技术难度没有想象中那么高但踩过的坑确实不少尤其是编排层的那些细节没有实战经验很难提前感知到。好在最后出图成功率稳定在 90% 以上作为一期工程算是达到目标了。后续再想扩展方向也很明确接入更多图像处理工具、优化参数选择逻辑、用积累的数据微调一个专用规划模型。这些就等二期再说吧。