1. AI Forge 更新解读本地识别 AI 命名到底解决了什么1.1 先看一个真实的痛点场景做 Cocos Creator 项目最让人头疼的往往不是玩法逻辑而是资源管理。尤其是项目进入中期以后美术同学每天往项目里扔素材命名规则千奇百怪123.png、untitled_001、副本_最终版_v3、sprite_20250101……每次要找一个角色动画都得在资源管理器里翻半天。更要命的是很多团队尝试用 AI 来辅助整理资源把图片扔给大模型让模型“看图说话”自动生成文件名。想法很好但实际跑起来很快就发现问题了每张图片都要上传到云端识别大量消耗 Token。一张 2K 贴图可能被压缩失真识别结果不稳定。敏感的美术素材要经过外部服务存在信息安全风险。网络请求一个接一个等到批量处理完账单和等待时间都很感人。如果你的项目也面临类似问题那这波 Cocos AI Forge 的更新就很值得关注。新版本把“本地识别”和“AI 命名”结合起来了用本地模型先完成图像识别和资源解析再交给大模型做语义命名把最烧 Token 的步骤留在本地处理效果好的部分直接沉淀成本地结果云端只做精简的文本层面的命名。下面我会从原理、环境、配置、实战代码到排错思路把这个更新完整拆一遍。1.2 AI Forge 是什么AI Forge 是面向 Cocos Creator 生态的 AI 辅助工具集定位是“把 AI 能力以低成本、低门槛的方式集成进游戏开发工作流”。它不是一个单纯的聊天机器人而是围绕资源处理、代码生成、批量任务、本地模型接入等多个方向提供工具能力的插件体系。本次更新的重点集中在两件事本地识别在本地完成图片内容识别、资源类型判断、地图或序列帧的基础解析。这一步不依赖云端大模型不消耗 Token。AI 命名基于本地识别的结果结合预设的命名规范让大模型生成更符合项目风格的资源名称。由于送入大模型的信息已经从“整张图片”变成“结构化文本描述”Token 消耗大幅下降。简单理解就是本地识别负责“看懂”AI 命名负责“起名”。看懂这一步不走云端起名这一步只处理文本摘要。1.3 为什么“本地识别”是关键我们要理解一个基本成本逻辑Token 消耗与输入内容的长度和复杂度强相关。如果直接把一张图片丢给云端大模型模型需要把图片编码成视觉 Token一张高清贴图可能消耗几百到几千 Token且每次调用都重复消耗。如果是批量整理几百张素材成本会迅速膨胀。本地识别方案的思路完全不同第一步在本地用 OCR 或图像分类模型识别图片内容提取出关键文本、物体类别、颜色、构图信息。第二步把这些信息汇总成一小段结构化描述比如“一个拿着剑的角色站姿侧面战斗场景PNG 序列帧第 3 帧”。第三步将这段描述发给大模型做命名此时输入 Token 可能只有几十到一百比直接传图片节省一个数量级。这就是“省下大把 Token”的核心原理。它不是在 Token 计费规则上做文章而是从工作流层面把不必要的 AI 计算量砍掉了。2. 环境准备与版本说明2.1 本文演示环境整个流程在以下环境中验证过但请结合你的实际项目版本进行调整操作系统Windows 11 / macOS 14 引擎版本Cocos Creator 3.8.x2.4.x 部分功能略有差异 AI Forge 插件版本以你安装时的最新版为准 Python3.10用于本地识别服务 Node.js16.20用于插件通信与脚本调用需要说明的是AI Forge 是一个迭代较快的插件不同小版本的 UI 和配置项会有差异。本文重点讲解原理、流程和思路具体按钮位置以你自己的版本为准。2.2 安装 AI Forge 插件在 Cocos Creator 的扩展商店中搜索 AI Forge找到对应版本的扩展包安装。如果你是从社区下载的压缩包安装方式是在 Cocos Creator 中打开菜单栏 - 扩展 - 扩展管理器 - 导入扩展包安装完成后建议重启编辑器。重启后在编辑器顶部菜单栏会出现 AI Forge 的入口面板。如果是团队协作建议把扩展配置纳入项目版本管理。后续成员拉取代码后再执行一次插件安装即可。2.3 项目目录结构建议为了演示清晰我准备了一个专门用于测试的资源目录assets/ ├── raw_assets/ # 原始素材未命名状态 ├── test_character/ # 角色测试素材 │ ├── 123.png │ ├── 456.png │ └── 789.png ├── processed/ # AI Forge 处理结果输出目录 └── resources/raw_assets专门用来放“还没来得及整理”的脏素材。好处是 AI Forge 在批量处理时只扫描这个目录不会污染正常业务资源。3. 核心原理拆解本地识别、AI 命名与 Token 开销3.1 本地识别到底做了几件事本地识别不是简单调用一个 OCR API而是一个组合流程第一层文件级预判这一步完全不需要 AI。插件先读取图片的宽高、格式、透明通道等元数据判断文件类型。例如带有透明通道的 PNG大概率是 UI 图标、角色贴图或特效序列帧。分辨率为 2 的次幂的纹理可能是图集或图集里的子图。多张尺寸相同且命名连续的图片大概率是序列帧动画。第二层OCR 文字识别如果图片中包含文字比如 UI 界面截图、按钮文案、弹窗设计稿会先做 OCR 提取文字内容。这一层识别的是“图里写了什么”。在 Cocos 项目里UI 素材的命名如果能带上界面的按钮文案后期查找会非常高效。例如一个登录界面的按钮如果只是new_1.png没有任何信息量但 OCR 识别出“登录”两个字后AI 命名环节就能给出btn_login.png这样的文件名。第三层图像特征描述对没有文字的贴图需要用图像分类或目标检测模型判断画面内容是角色、场景、怪物、道具还是特效。更强的本地模型还能识别动作姿态、镜头角度等细节。三层信息汇总后会生成一段 JSON 结构这就是最终要交给大模型做命名的“素材摘要”。{ file_name: 123.png, width: 512, height: 512, has_alpha: true, ocr_text: [], scene: battle, subject: character, action: standing, orientation: side, sequence_index: 1 }这段 JSON 的大小一般不到 1KB折算成 Token 大约只有几十个。这就是本地识别最大的价值把几百 Token 的图片输入压缩成几十 Token 的文本摘要。3.2 AI 命名的工作方式AI 命名的输入不再是图片而是上一步产生的 JSON 描述。插件会把它跟预置的命名规范模板拼成 prompt再调用大模型接口生成文件名。一个典型的命名 prompt 结构如下你是一名游戏项目资源命名助手。请根据以下素材描述生成资源名称。 命名规范 1. 使用小写字母和下划线。 2. 前缀表示资源类型例如 btn、spr、bg、fx、ani。 3. 中间内容按“模块_子模块_描述”排列。 4. 不包含空格和特殊字符。 素材描述 {file_name:123.png,has_alpha:true,subject:character,action:standing,orientation:side} 请直接输出文件名不要输出解释。由于输入非常短模型回复也只有一个文件名单次调用的输入输出 Token 都很低。批量处理 100 张图片的 Token 消耗可能还不及以前直接传图处理 10 张的量。3.3 Token 是如何被省下来的我们做一组粗略对比方案输入内容预计单张 Token100 张资源总 Token纯云端识图整张图片编码800 ~ 30008 万 ~ 30 万本地识别 AI 命名1KB 结构化文本50 ~ 2000.5 万 ~ 2 万可以看到Token 消耗下降了 90% 以上。在批量处理场景下这个差距非常明显。而且因为大部分识别逻辑在本地执行即使断网资源也能完成初步整理网络恢复后再补一次 AI 命名即可。4. 完整实战用 AI Forge 自动整理一批素材4.1 准备测试素材先创建测试项目。在 Cocos Creator 中新建空项目然后在assets下创建raw_assets/test_character目录放入几张没有命名的图片素材。为了演示效果我建议你准备三类素材一张带文字的 UI 界面截图。一张角色站姿 PNG带透明通道。一组连续编号的序列帧图片。4.2 配置本地识别服务AI Forge 的本地识别通常有两种运行方式插件内置轻量模型开箱即用。连接本地部署的 OCR/分类服务适合团队共享一套识别能力。如果是团队使用推荐第二种方式。用一个本地 HTTP 服务包装识别能力插件只需要请求http://127.0.0.1:8090/api/recognize即可。下面是一个基于 FastAPI 的本地识别服务示例。它能接收图片返回文件名建议所需的结构化描述# File: local_recognize_service.py from fastapi import FastAPI, UploadFile, File from PIL import Image import io app FastAPI() # 这里是示意函数实际项目中可以替换为 ONNX、Tesseract 或其他本地模型 def fake_ocr(image: Image.Image) - list: # 假设已经请求到 OCR 引擎返回识别出的文字 return [] def fake_classify(image: Image.Image) - dict: # 假设已经请求到图像分类模型返回素材主体信息 return { subject: character, scene: battle, action: standing, orientation: side } app.post(/api/recognize) async def recognize(file: UploadFile File(...)): image_bytes await file.read() image Image.open(io.BytesIO(image_bytes)) width, height image.size has_alpha image.mode in (RGBA, LA) or transparency in image.info ocr_text fake_ocr(image) classify_info fake_classify(image) return { file_name: file.filename, width: width, height: height, has_alpha: has_alpha, ocr_text: ocr_text, **classify_info } if __name__ __main__: import uvicorn uvicorn.run(app, host127.0.0.1, port8090)这是一个非常简化的示例但已经涵盖了本地识别服务应该返回的数据结构。真实项目中OCR 可以用 PaddleOCR、Tesseract 等开源引擎图像分类可以导出一个 ONNX 模型用 onnxruntime 加载。关键点是整个识别过程不调用云端模型不消耗任何 Token。启动服务pip install fastapi uvicorn pillow uvicorn local_recognize_service:app --host 127.0.0.1 --port 8090启动后可以用 curl 验证接口是否正常curl -X POST http://127.0.0.1:8090/api/recognize \ -F fileassets/raw_assets/test_character/123.png预期返回结果类似{ file_name: 123.png, width: 512, height: 512, has_alpha: true, ocr_text: [], subject: character, scene: battle, action: standing, orientation: side }4.3 在 Cocos Creator 插件中接入 AI 命名本地识别拿到结构化描述后接下来是 AI 命名环节。AI Forge 面板中一般会有“连接 AI 服务”的配置区域需要填写 Key、模型名称和请求地址。由于不同项目的模型供应商不同我这里给出一个通用的 HTTP 调用封装。实际接入时替换请求 URL、鉴权头和请求体结构即可。// File: scripts/ai-naming.ts export interface AssetDescription { file_name: string; width: number; height: number; has_alpha: boolean; ocr_text: string[]; subject: string; scene: string; action: string; orientation: string; [key: string]: unknown; } export interface NamingResult { status: success | error; name?: string; error?: string; } const NAMING_RULES 命名规范 1. 使用小写字母和下划线。 2. 前缀表示资源类型例如 btn、spr、bg、fx、ani。 3. 中间内容按“模块_子模块_描述”排列。 4. 不包含空格和特殊字符。 5. 避免使用中文和拼音缩写。 ; /** * 基于素材描述调用 AI 接口生成资源名 */ export async function generateAssetName( desc: AssetDescription, apiUrl: string, apiKey: string, modelName: string ): PromiseNamingResult { const prompt 你是一名游戏项目资源命名助手。请根据以下素材描述生成资源名称。 ${NAMING_RULES} 素材描述 ${JSON.stringify(desc)} 请直接输出文件名不要输出解释。 ; try { const resp await fetch(apiUrl, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: modelName, messages: [ { role: system, content: 你是简洁高效的游戏资源命名助手。 }, { role: user, content: prompt } ], temperature: 0.2, max_tokens: 50 }) }); const data await resp.json(); const rawName data?.choices?.[0]?.message?.content?.trim(); if (!rawName) { return { status: error, error: AI 返回内容为空 }; } // 清理可能出现的引号、路径符号 const cleaned rawName .replace(/[]/g, ) .replace(/\.(png|jpg|jpeg|webp)$/i, ); return { status: success, name: cleaned }; } catch (e) { return { status: error, error: e instanceof Error ? e.message : 网络请求失败 }; } }这个函数做的事情非常纯粹拿到本地识别返回的 JSON拼接 prompt请求大模型接口清理返回值只保留文件名。注意max_tokens: 50这一项。因为只需要模型返回一个短文件名不需要长篇说明限制输出长度可以进一步省 Token。实际插件不会让你自己写这样的代码它会在面板里封装好但理解这个流程后你能更清楚地知道每一步 Token 花在了哪里。4.4 批量处理脚本资源整理场景下单个文件手动调用没有意义批量处理才是核心。下面是一个 Node.js 批量脚本的思路它遍历raw_assets目录对每张图片依次执行“本地识别 - AI 命名 - 重命名”。// File: scripts/batch-process.ts import { generateAssetName } from ./ai-naming; import fs from fs; import path from path; import FormData from form-data; import fetch from node-fetch; const RECOGNIZE_API http://127.0.0.1:8090/api/recognize; const AI_API https://your-ai-provider.example.com/v1/chat/completions; const AI_KEY your-api-key; const AI_MODEL your-model-name; const RAW_DIR path.resolve(__dirname, ../assets/raw_assets); /** * 调用本地识别服务 */ async function recognizeLocal(filePath: string) { const fileStream fs.createReadStream(filePath); const form new FormData(); form.append(file, fileStream, path.basename(filePath)); const resp await fetch(RECOGNIZE_API, { method: POST, body: form, headers: form.getHeaders() }); return await resp.json(); } /** * 为文件生成新名字并检查命名冲突 */ async function generateUniqueName(desc: any, usedNames: Setstring) { let rawName ; for (let i 0; i 3; i) { const result await generateAssetName(desc, AI_API, AI_KEY, AI_MODEL); if (result.status success result.name) { rawName result.name; break; } } if (!rawName) { return null; } // 检查是否与已生成的文件名冲突冲突则加序号后缀 let finalName rawName; let index 2; while (usedNames.has(finalName)) { finalName ${rawName}_${index}; index; } usedNames.add(finalName); return finalName; } async function main() { const files fs.readdirSync(RAW_DIR).filter(f { return /\.(png|jpg|jpeg|webp)$/i.test(f); }); const usedNames new Setstring(); const failedFiles: string[] []; console.log(共发现 ${files.length} 个待处理文件); for (const file of files) { const filePath path.join(RAW_DIR, file); console.log(处理中${file}); try { // 1. 本地识别 const desc await recognizeLocal(filePath); // 2. AI 命名 const newName await generateUniqueName(desc, usedNames); if (!newName) { failedFiles.push(file); console.log( ✗ 生成名字失败跳过); continue; } // 3. 重命名 const ext path.extname(file); const destPath path.join(RAW_DIR, ${newName}${ext}); fs.renameSync(filePath, destPath); console.log( ✓ ${file} - ${newName}${ext}); } catch (e) { failedFiles.push(file); console.error( ✗ 处理异常${e instanceof Error ? e.message : e}); } } console.log(\n处理完成); console.log(成功${files.length - failedFiles.length} 个); if (failedFiles.length 0) { console.log(失败${failedFiles.length} 个); console.log(失败文件, failedFiles.join(, )); } } main();这个脚本有三个设计细节需要注意第一命名冲突处理。批量重命名时可能出现两张图识别结果相同、AI 给了同样名字的情况直接用原名覆盖会造成文件丢失。这里用usedNames集合记录已用名遇到冲突自动加_2、_3后缀。第二失败重试。AI 接口偶尔会超时或返回空内容脚本内重试了 3 次仍然失败就记录到failedFiles不会中断整个流程。第三只重命名了文件没有移动目录。生产环境中你可能希望把处理完的资源移到processed目录这取决于团队规范。建议保留“先重命名、后移动”两个阶段出现问题时更容易定位。4.5 运行与验证先在本地资源目录中放置测试图片然后执行批量脚本npx ts-node scripts/batch-process.ts预期执行结果共发现 8 个待处理文件 处理中123.png ✓ 123.png - spr_character_stand_01.png 处理中456.png ✓ 456.png - ui_btn_login.png 处理中789.png ✗ 生成名字失败跳过 ... 处理完成 成功7 个 失败1 个 失败文件789.png失败的文件保留原名方便后续手动处理不会因为 AI 返回异常而破坏原始素材。验证完成后回到 Cocos Creator 编辑器在资源管理器中刷新目录就能看到重命名后的文件已同步显示。5. 常见问题与排查思路5.1 高频问题概览问题现象常见原因解决思路插件安装后不显示面板扩展版本与编辑器版本不匹配查看插件文档确认支持的 Creator 版本或切换 Creator 版本本地识别服务连不上服务未启动、端口被占用检查 8090 端口先用 curl 单独验证接口识别结果为空图片太大、模型未加载完成压缩图片或分批次处理等待模型预热AI 返回名字不符合规范prompt 规范描述不够具体在命名规范中增加“禁止缩写”“禁止数字开头”等约束Token 消耗仍然较高本地识别环节没有生效确认识别结果 JSON 是否成功传给命名环节排除直接上传图片的旧流程批量处理时遇到同名覆盖没有做冲突检查维护已使用命名集合重名前先检查文件名中文乱码系统编码或模型输出编码问题统一使用 UTF-8命名规范强制英文小写5.2 典型问题详解问题一本地识别服务启动了但插件提示“识别失败”排查顺序建议先确认服务单独调用是否正常curl -X POST http://127.0.0.1:8090/api/recognize \ -F fileassets/raw_assets/test_character/123.png如果 curl 正常但插件失败检查插件配置的识别服务地址是否写成了局域网 IP。本机测试推荐直接用127.0.0.1。检查跨域问题。有的插件运行环境不允许跨域请求本地端口需要服务端添加 CORS 响应头from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*], )问题二AI 命名返回的还是一个乱码名或者纯数字这通常是 prompt 中命名规范描述不充分导致的。在NAMING_RULES中补充“禁止纯数字开头”“必须包含类型前缀”等硬性约束。如果模型供应商支持response_format设置为 JSON 模式也可以要求模型把文件名作为 JSON 字段返回减少非目标内容输出。问题三Token 还是感觉消耗太快先做一次单文件耗时与 Token 观测记录本地识别 JSON 的大小以及 AI 命名请求的输入 Token 和输出 Token。如果输入 Token 仍然很高说明请求体中可能携带了历史对话记录检查代码是否把多轮消息都发送过去了。只保留最新一条 user 消息即可。6. 最佳实践与工程建议6.1 命名规范先行AI 命名能否输出理想结果取决于命名规范定义得有多清楚。建议在项目初期就把规范写成一个文档同时复制到 AI Forge 的 prompt 预设中。一个较完整的规范示例资源类型前缀 - spr精灵/贴图 - bg背景 - btn按钮 - fx特效 - ani动画片段 - uiUI 整体界面 - atlas图集 - aud音频 命名格式 类型前缀_模块_子模块_描述_序号 禁止事项 - 禁止使用中文 - 禁止以数字开头 - 禁止使用空格 - 禁止使用特殊字符除下划线规范越明确模型“自由发挥”的空间就越小命名稳定性越高。6.2 本地识别误判时的兜底策略本地模型不是 100% 准确的尤其遇到画面内容复杂、重叠元素多的情况识别结果可能偏差。对于这种情况建议设置一个“置信度阈值”。当识别置信度低于阈值时不进入 AI 命名流程直接标记为“需人工确认”。例如在识别服务的返回中增加confidence字段{ file_name: complex.png, confidence: 0.62, subject: unknown, need_review: true }批量脚本遇到need_review: true的文件统一移动到review目录而不是强行生成一个不靠谱的名字。这个兜底策略能让整个流程更可靠。6.3 Token 预算与批量控制即便有本地识别兜底AI 命名仍然会消耗 Token。建议做三件事控制成本批量窗口控制每批只处理 50 到 100 张避免一次性海量请求导致异常。缓存识别结果本地识别 JSON 可以保存到项目里的.cache目录。发现同名文件时直接复用识别结果不重复请求 AI。优先级排序优先处理 UI 素材和序列帧这类“命名价值高”的资源临时素材和测试素材可以先跳过。6.4 安全与合规边界素材识别过程中如果项目中包含美术外包未公开的角色设定、未发布的玩法截图管理者需要确认这些素材不会通过 AI 命名环节发送给第三方。目前的方案里本地识别部分完全在本地完成没有泄露风险但 AI 命名环节仍会把结构化描述发送到云端模型服务。如果项目保密级别较高可以考虑以下方案自建或私有化部署命名模型。在发送给云端前对描述做脱敏处理例如把subject: character替换为subject: c1得到文件名后再映射回可读名。完全禁用云端 AI 命名退回到“本地识别 规则模板命名”模式。7. 总结这一轮 AI Forge 更新解决了一个非常实际的问题资源整理工作流中的 AI 成本太高、识别链路过重。它把整个流程拆成了“本地识别 云端命名”两段核心手段是把图片压缩成结构化文本再送进大模型。实测下来批量处理大量资源的 Token 消耗能下降一个数量级同时本地识别不依赖网络对素材保密也更友好。整套链路的关键点总结下来就是本地识别负责提取图片特征与文字输出 JSON 描述。AI 命名只接收文本摘要配合精确的命名规范输出文件名。批量处理脚本需要做冲突检查、重试机制和人工兜底。命名规范越具体模型越不容易跑偏。Token 控制不是靠“少调用几次”而是从输入侧压缩每次调用的体量。如果你正被项目资源命名搞得焦头烂额或者每次批量导入素材后被一堆“未命名”文件折磨可以试试这个思路。哪怕暂时不引入完整插件把“本地识别 结构化摘要 AI 命名”这套流程拆出来自己写一套批处理脚本也能明显感受到成本差异。动手试一遍把识别 JSON 打出来看看你大概就能理解这次更新省掉的 Token 都去哪儿了。 
长河君 · 2026/9/30 5:28:18 · 阅读 1.2k Cocos AI Forge新方案：本地识别+AI命名，大幅节省Token高效整理资源
1. AI Forge 更新解读本地识别 AI 命名到底解决了什么1.1 先看一个真实的痛点场景做 Cocos Creator 项目最让人头疼的往往不是玩法逻辑而是资源管理。尤其是项目进入中期以后美术同学每天往项目里扔素材命名规则千奇百怪123.png、untitled_001、副本_最终版_v3、sprite_20250101……每次要找一个角色动画都得在资源管理器里翻半天。更要命的是很多团队尝试用 AI 来辅助整理资源把图片扔给大模型让模型“看图说话”自动生成文件名。想法很好但实际跑起来很快就发现问题了每张图片都要上传到云端识别大量消耗 Token。一张 2K 贴图可能被压缩失真识别结果不稳定。敏感的美术素材要经过外部服务存在信息安全风险。网络请求一个接一个等到批量处理完账单和等待时间都很感人。如果你的项目也面临类似问题那这波 Cocos AI Forge 的更新就很值得关注。新版本把“本地识别”和“AI 命名”结合起来了用本地模型先完成图像识别和资源解析再交给大模型做语义命名把最烧 Token 的步骤留在本地处理效果好的部分直接沉淀成本地结果云端只做精简的文本层面的命名。下面我会从原理、环境、配置、实战代码到排错思路把这个更新完整拆一遍。1.2 AI Forge 是什么AI Forge 是面向 Cocos Creator 生态的 AI 辅助工具集定位是“把 AI 能力以低成本、低门槛的方式集成进游戏开发工作流”。它不是一个单纯的聊天机器人而是围绕资源处理、代码生成、批量任务、本地模型接入等多个方向提供工具能力的插件体系。本次更新的重点集中在两件事本地识别在本地完成图片内容识别、资源类型判断、地图或序列帧的基础解析。这一步不依赖云端大模型不消耗 Token。AI 命名基于本地识别的结果结合预设的命名规范让大模型生成更符合项目风格的资源名称。由于送入大模型的信息已经从“整张图片”变成“结构化文本描述”Token 消耗大幅下降。简单理解就是本地识别负责“看懂”AI 命名负责“起名”。看懂这一步不走云端起名这一步只处理文本摘要。1.3 为什么“本地识别”是关键我们要理解一个基本成本逻辑Token 消耗与输入内容的长度和复杂度强相关。如果直接把一张图片丢给云端大模型模型需要把图片编码成视觉 Token一张高清贴图可能消耗几百到几千 Token且每次调用都重复消耗。如果是批量整理几百张素材成本会迅速膨胀。本地识别方案的思路完全不同第一步在本地用 OCR 或图像分类模型识别图片内容提取出关键文本、物体类别、颜色、构图信息。第二步把这些信息汇总成一小段结构化描述比如“一个拿着剑的角色站姿侧面战斗场景PNG 序列帧第 3 帧”。第三步将这段描述发给大模型做命名此时输入 Token 可能只有几十到一百比直接传图片节省一个数量级。这就是“省下大把 Token”的核心原理。它不是在 Token 计费规则上做文章而是从工作流层面把不必要的 AI 计算量砍掉了。2. 环境准备与版本说明2.1 本文演示环境整个流程在以下环境中验证过但请结合你的实际项目版本进行调整操作系统Windows 11 / macOS 14 引擎版本Cocos Creator 3.8.x2.4.x 部分功能略有差异 AI Forge 插件版本以你安装时的最新版为准 Python3.10用于本地识别服务 Node.js16.20用于插件通信与脚本调用需要说明的是AI Forge 是一个迭代较快的插件不同小版本的 UI 和配置项会有差异。本文重点讲解原理、流程和思路具体按钮位置以你自己的版本为准。2.2 安装 AI Forge 插件在 Cocos Creator 的扩展商店中搜索 AI Forge找到对应版本的扩展包安装。如果你是从社区下载的压缩包安装方式是在 Cocos Creator 中打开菜单栏 - 扩展 - 扩展管理器 - 导入扩展包安装完成后建议重启编辑器。重启后在编辑器顶部菜单栏会出现 AI Forge 的入口面板。如果是团队协作建议把扩展配置纳入项目版本管理。后续成员拉取代码后再执行一次插件安装即可。2.3 项目目录结构建议为了演示清晰我准备了一个专门用于测试的资源目录assets/ ├── raw_assets/ # 原始素材未命名状态 ├── test_character/ # 角色测试素材 │ ├── 123.png │ ├── 456.png │ └── 789.png ├── processed/ # AI Forge 处理结果输出目录 └── resources/raw_assets专门用来放“还没来得及整理”的脏素材。好处是 AI Forge 在批量处理时只扫描这个目录不会污染正常业务资源。3. 核心原理拆解本地识别、AI 命名与 Token 开销3.1 本地识别到底做了几件事本地识别不是简单调用一个 OCR API而是一个组合流程第一层文件级预判这一步完全不需要 AI。插件先读取图片的宽高、格式、透明通道等元数据判断文件类型。例如带有透明通道的 PNG大概率是 UI 图标、角色贴图或特效序列帧。分辨率为 2 的次幂的纹理可能是图集或图集里的子图。多张尺寸相同且命名连续的图片大概率是序列帧动画。第二层OCR 文字识别如果图片中包含文字比如 UI 界面截图、按钮文案、弹窗设计稿会先做 OCR 提取文字内容。这一层识别的是“图里写了什么”。在 Cocos 项目里UI 素材的命名如果能带上界面的按钮文案后期查找会非常高效。例如一个登录界面的按钮如果只是new_1.png没有任何信息量但 OCR 识别出“登录”两个字后AI 命名环节就能给出btn_login.png这样的文件名。第三层图像特征描述对没有文字的贴图需要用图像分类或目标检测模型判断画面内容是角色、场景、怪物、道具还是特效。更强的本地模型还能识别动作姿态、镜头角度等细节。三层信息汇总后会生成一段 JSON 结构这就是最终要交给大模型做命名的“素材摘要”。{ file_name: 123.png, width: 512, height: 512, has_alpha: true, ocr_text: [], scene: battle, subject: character, action: standing, orientation: side, sequence_index: 1 }这段 JSON 的大小一般不到 1KB折算成 Token 大约只有几十个。这就是本地识别最大的价值把几百 Token 的图片输入压缩成几十 Token 的文本摘要。3.2 AI 命名的工作方式AI 命名的输入不再是图片而是上一步产生的 JSON 描述。插件会把它跟预置的命名规范模板拼成 prompt再调用大模型接口生成文件名。一个典型的命名 prompt 结构如下你是一名游戏项目资源命名助手。请根据以下素材描述生成资源名称。 命名规范 1. 使用小写字母和下划线。 2. 前缀表示资源类型例如 btn、spr、bg、fx、ani。 3. 中间内容按“模块_子模块_描述”排列。 4. 不包含空格和特殊字符。 素材描述 {file_name:123.png,has_alpha:true,subject:character,action:standing,orientation:side} 请直接输出文件名不要输出解释。由于输入非常短模型回复也只有一个文件名单次调用的输入输出 Token 都很低。批量处理 100 张图片的 Token 消耗可能还不及以前直接传图处理 10 张的量。3.3 Token 是如何被省下来的我们做一组粗略对比方案输入内容预计单张 Token100 张资源总 Token纯云端识图整张图片编码800 ~ 30008 万 ~ 30 万本地识别 AI 命名1KB 结构化文本50 ~ 2000.5 万 ~ 2 万可以看到Token 消耗下降了 90% 以上。在批量处理场景下这个差距非常明显。而且因为大部分识别逻辑在本地执行即使断网资源也能完成初步整理网络恢复后再补一次 AI 命名即可。4. 完整实战用 AI Forge 自动整理一批素材4.1 准备测试素材先创建测试项目。在 Cocos Creator 中新建空项目然后在assets下创建raw_assets/test_character目录放入几张没有命名的图片素材。为了演示效果我建议你准备三类素材一张带文字的 UI 界面截图。一张角色站姿 PNG带透明通道。一组连续编号的序列帧图片。4.2 配置本地识别服务AI Forge 的本地识别通常有两种运行方式插件内置轻量模型开箱即用。连接本地部署的 OCR/分类服务适合团队共享一套识别能力。如果是团队使用推荐第二种方式。用一个本地 HTTP 服务包装识别能力插件只需要请求http://127.0.0.1:8090/api/recognize即可。下面是一个基于 FastAPI 的本地识别服务示例。它能接收图片返回文件名建议所需的结构化描述# File: local_recognize_service.py from fastapi import FastAPI, UploadFile, File from PIL import Image import io app FastAPI() # 这里是示意函数实际项目中可以替换为 ONNX、Tesseract 或其他本地模型 def fake_ocr(image: Image.Image) - list: # 假设已经请求到 OCR 引擎返回识别出的文字 return [] def fake_classify(image: Image.Image) - dict: # 假设已经请求到图像分类模型返回素材主体信息 return { subject: character, scene: battle, action: standing, orientation: side } app.post(/api/recognize) async def recognize(file: UploadFile File(...)): image_bytes await file.read() image Image.open(io.BytesIO(image_bytes)) width, height image.size has_alpha image.mode in (RGBA, LA) or transparency in image.info ocr_text fake_ocr(image) classify_info fake_classify(image) return { file_name: file.filename, width: width, height: height, has_alpha: has_alpha, ocr_text: ocr_text, **classify_info } if __name__ __main__: import uvicorn uvicorn.run(app, host127.0.0.1, port8090)这是一个非常简化的示例但已经涵盖了本地识别服务应该返回的数据结构。真实项目中OCR 可以用 PaddleOCR、Tesseract 等开源引擎图像分类可以导出一个 ONNX 模型用 onnxruntime 加载。关键点是整个识别过程不调用云端模型不消耗任何 Token。启动服务pip install fastapi uvicorn pillow uvicorn local_recognize_service:app --host 127.0.0.1 --port 8090启动后可以用 curl 验证接口是否正常curl -X POST http://127.0.0.1:8090/api/recognize \ -F fileassets/raw_assets/test_character/123.png预期返回结果类似{ file_name: 123.png, width: 512, height: 512, has_alpha: true, ocr_text: [], subject: character, scene: battle, action: standing, orientation: side }4.3 在 Cocos Creator 插件中接入 AI 命名本地识别拿到结构化描述后接下来是 AI 命名环节。AI Forge 面板中一般会有“连接 AI 服务”的配置区域需要填写 Key、模型名称和请求地址。由于不同项目的模型供应商不同我这里给出一个通用的 HTTP 调用封装。实际接入时替换请求 URL、鉴权头和请求体结构即可。// File: scripts/ai-naming.ts export interface AssetDescription { file_name: string; width: number; height: number; has_alpha: boolean; ocr_text: string[]; subject: string; scene: string; action: string; orientation: string; [key: string]: unknown; } export interface NamingResult { status: success | error; name?: string; error?: string; } const NAMING_RULES 命名规范 1. 使用小写字母和下划线。 2. 前缀表示资源类型例如 btn、spr、bg、fx、ani。 3. 中间内容按“模块_子模块_描述”排列。 4. 不包含空格和特殊字符。 5. 避免使用中文和拼音缩写。 ; /** * 基于素材描述调用 AI 接口生成资源名 */ export async function generateAssetName( desc: AssetDescription, apiUrl: string, apiKey: string, modelName: string ): PromiseNamingResult { const prompt 你是一名游戏项目资源命名助手。请根据以下素材描述生成资源名称。 ${NAMING_RULES} 素材描述 ${JSON.stringify(desc)} 请直接输出文件名不要输出解释。 ; try { const resp await fetch(apiUrl, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model: modelName, messages: [ { role: system, content: 你是简洁高效的游戏资源命名助手。 }, { role: user, content: prompt } ], temperature: 0.2, max_tokens: 50 }) }); const data await resp.json(); const rawName data?.choices?.[0]?.message?.content?.trim(); if (!rawName) { return { status: error, error: AI 返回内容为空 }; } // 清理可能出现的引号、路径符号 const cleaned rawName .replace(/[]/g, ) .replace(/\.(png|jpg|jpeg|webp)$/i, ); return { status: success, name: cleaned }; } catch (e) { return { status: error, error: e instanceof Error ? e.message : 网络请求失败 }; } }这个函数做的事情非常纯粹拿到本地识别返回的 JSON拼接 prompt请求大模型接口清理返回值只保留文件名。注意max_tokens: 50这一项。因为只需要模型返回一个短文件名不需要长篇说明限制输出长度可以进一步省 Token。实际插件不会让你自己写这样的代码它会在面板里封装好但理解这个流程后你能更清楚地知道每一步 Token 花在了哪里。4.4 批量处理脚本资源整理场景下单个文件手动调用没有意义批量处理才是核心。下面是一个 Node.js 批量脚本的思路它遍历raw_assets目录对每张图片依次执行“本地识别 - AI 命名 - 重命名”。// File: scripts/batch-process.ts import { generateAssetName } from ./ai-naming; import fs from fs; import path from path; import FormData from form-data; import fetch from node-fetch; const RECOGNIZE_API http://127.0.0.1:8090/api/recognize; const AI_API https://your-ai-provider.example.com/v1/chat/completions; const AI_KEY your-api-key; const AI_MODEL your-model-name; const RAW_DIR path.resolve(__dirname, ../assets/raw_assets); /** * 调用本地识别服务 */ async function recognizeLocal(filePath: string) { const fileStream fs.createReadStream(filePath); const form new FormData(); form.append(file, fileStream, path.basename(filePath)); const resp await fetch(RECOGNIZE_API, { method: POST, body: form, headers: form.getHeaders() }); return await resp.json(); } /** * 为文件生成新名字并检查命名冲突 */ async function generateUniqueName(desc: any, usedNames: Setstring) { let rawName ; for (let i 0; i 3; i) { const result await generateAssetName(desc, AI_API, AI_KEY, AI_MODEL); if (result.status success result.name) { rawName result.name; break; } } if (!rawName) { return null; } // 检查是否与已生成的文件名冲突冲突则加序号后缀 let finalName rawName; let index 2; while (usedNames.has(finalName)) { finalName ${rawName}_${index}; index; } usedNames.add(finalName); return finalName; } async function main() { const files fs.readdirSync(RAW_DIR).filter(f { return /\.(png|jpg|jpeg|webp)$/i.test(f); }); const usedNames new Setstring(); const failedFiles: string[] []; console.log(共发现 ${files.length} 个待处理文件); for (const file of files) { const filePath path.join(RAW_DIR, file); console.log(处理中${file}); try { // 1. 本地识别 const desc await recognizeLocal(filePath); // 2. AI 命名 const newName await generateUniqueName(desc, usedNames); if (!newName) { failedFiles.push(file); console.log( ✗ 生成名字失败跳过); continue; } // 3. 重命名 const ext path.extname(file); const destPath path.join(RAW_DIR, ${newName}${ext}); fs.renameSync(filePath, destPath); console.log( ✓ ${file} - ${newName}${ext}); } catch (e) { failedFiles.push(file); console.error( ✗ 处理异常${e instanceof Error ? e.message : e}); } } console.log(\n处理完成); console.log(成功${files.length - failedFiles.length} 个); if (failedFiles.length 0) { console.log(失败${failedFiles.length} 个); console.log(失败文件, failedFiles.join(, )); } } main();这个脚本有三个设计细节需要注意第一命名冲突处理。批量重命名时可能出现两张图识别结果相同、AI 给了同样名字的情况直接用原名覆盖会造成文件丢失。这里用usedNames集合记录已用名遇到冲突自动加_2、_3后缀。第二失败重试。AI 接口偶尔会超时或返回空内容脚本内重试了 3 次仍然失败就记录到failedFiles不会中断整个流程。第三只重命名了文件没有移动目录。生产环境中你可能希望把处理完的资源移到processed目录这取决于团队规范。建议保留“先重命名、后移动”两个阶段出现问题时更容易定位。4.5 运行与验证先在本地资源目录中放置测试图片然后执行批量脚本npx ts-node scripts/batch-process.ts预期执行结果共发现 8 个待处理文件 处理中123.png ✓ 123.png - spr_character_stand_01.png 处理中456.png ✓ 456.png - ui_btn_login.png 处理中789.png ✗ 生成名字失败跳过 ... 处理完成 成功7 个 失败1 个 失败文件789.png失败的文件保留原名方便后续手动处理不会因为 AI 返回异常而破坏原始素材。验证完成后回到 Cocos Creator 编辑器在资源管理器中刷新目录就能看到重命名后的文件已同步显示。5. 常见问题与排查思路5.1 高频问题概览问题现象常见原因解决思路插件安装后不显示面板扩展版本与编辑器版本不匹配查看插件文档确认支持的 Creator 版本或切换 Creator 版本本地识别服务连不上服务未启动、端口被占用检查 8090 端口先用 curl 单独验证接口识别结果为空图片太大、模型未加载完成压缩图片或分批次处理等待模型预热AI 返回名字不符合规范prompt 规范描述不够具体在命名规范中增加“禁止缩写”“禁止数字开头”等约束Token 消耗仍然较高本地识别环节没有生效确认识别结果 JSON 是否成功传给命名环节排除直接上传图片的旧流程批量处理时遇到同名覆盖没有做冲突检查维护已使用命名集合重名前先检查文件名中文乱码系统编码或模型输出编码问题统一使用 UTF-8命名规范强制英文小写5.2 典型问题详解问题一本地识别服务启动了但插件提示“识别失败”排查顺序建议先确认服务单独调用是否正常curl -X POST http://127.0.0.1:8090/api/recognize \ -F fileassets/raw_assets/test_character/123.png如果 curl 正常但插件失败检查插件配置的识别服务地址是否写成了局域网 IP。本机测试推荐直接用127.0.0.1。检查跨域问题。有的插件运行环境不允许跨域请求本地端口需要服务端添加 CORS 响应头from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*], )问题二AI 命名返回的还是一个乱码名或者纯数字这通常是 prompt 中命名规范描述不充分导致的。在NAMING_RULES中补充“禁止纯数字开头”“必须包含类型前缀”等硬性约束。如果模型供应商支持response_format设置为 JSON 模式也可以要求模型把文件名作为 JSON 字段返回减少非目标内容输出。问题三Token 还是感觉消耗太快先做一次单文件耗时与 Token 观测记录本地识别 JSON 的大小以及 AI 命名请求的输入 Token 和输出 Token。如果输入 Token 仍然很高说明请求体中可能携带了历史对话记录检查代码是否把多轮消息都发送过去了。只保留最新一条 user 消息即可。6. 最佳实践与工程建议6.1 命名规范先行AI 命名能否输出理想结果取决于命名规范定义得有多清楚。建议在项目初期就把规范写成一个文档同时复制到 AI Forge 的 prompt 预设中。一个较完整的规范示例资源类型前缀 - spr精灵/贴图 - bg背景 - btn按钮 - fx特效 - ani动画片段 - uiUI 整体界面 - atlas图集 - aud音频 命名格式 类型前缀_模块_子模块_描述_序号 禁止事项 - 禁止使用中文 - 禁止以数字开头 - 禁止使用空格 - 禁止使用特殊字符除下划线规范越明确模型“自由发挥”的空间就越小命名稳定性越高。6.2 本地识别误判时的兜底策略本地模型不是 100% 准确的尤其遇到画面内容复杂、重叠元素多的情况识别结果可能偏差。对于这种情况建议设置一个“置信度阈值”。当识别置信度低于阈值时不进入 AI 命名流程直接标记为“需人工确认”。例如在识别服务的返回中增加confidence字段{ file_name: complex.png, confidence: 0.62, subject: unknown, need_review: true }批量脚本遇到need_review: true的文件统一移动到review目录而不是强行生成一个不靠谱的名字。这个兜底策略能让整个流程更可靠。6.3 Token 预算与批量控制即便有本地识别兜底AI 命名仍然会消耗 Token。建议做三件事控制成本批量窗口控制每批只处理 50 到 100 张避免一次性海量请求导致异常。缓存识别结果本地识别 JSON 可以保存到项目里的.cache目录。发现同名文件时直接复用识别结果不重复请求 AI。优先级排序优先处理 UI 素材和序列帧这类“命名价值高”的资源临时素材和测试素材可以先跳过。6.4 安全与合规边界素材识别过程中如果项目中包含美术外包未公开的角色设定、未发布的玩法截图管理者需要确认这些素材不会通过 AI 命名环节发送给第三方。目前的方案里本地识别部分完全在本地完成没有泄露风险但 AI 命名环节仍会把结构化描述发送到云端模型服务。如果项目保密级别较高可以考虑以下方案自建或私有化部署命名模型。在发送给云端前对描述做脱敏处理例如把subject: character替换为subject: c1得到文件名后再映射回可读名。完全禁用云端 AI 命名退回到“本地识别 规则模板命名”模式。7. 总结这一轮 AI Forge 更新解决了一个非常实际的问题资源整理工作流中的 AI 成本太高、识别链路过重。它把整个流程拆成了“本地识别 云端命名”两段核心手段是把图片压缩成结构化文本再送进大模型。实测下来批量处理大量资源的 Token 消耗能下降一个数量级同时本地识别不依赖网络对素材保密也更友好。整套链路的关键点总结下来就是本地识别负责提取图片特征与文字输出 JSON 描述。AI 命名只接收文本摘要配合精确的命名规范输出文件名。批量处理脚本需要做冲突检查、重试机制和人工兜底。命名规范越具体模型越不容易跑偏。Token 控制不是靠“少调用几次”而是从输入侧压缩每次调用的体量。如果你正被项目资源命名搞得焦头烂额或者每次批量导入素材后被一堆“未命名”文件折磨可以试试这个思路。哪怕暂时不引入完整插件把“本地识别 结构化摘要 AI 命名”这套流程拆出来自己写一套批处理脚本也能明显感受到成本差异。动手试一遍把识别 JSON 打出来看看你大概就能理解这次更新省掉的 Token 都去哪儿了。