AI 识别标注

一、插件能为业务带来什么？

AI 识别标注插件将业务记录中的图片提交给指定工作流，由 AI 员工输出结构化的标注框、风险等级、检查结论和描述。它适合在工地巡检、质量检查、设备运维等业务表中批量处理图片，并将识别结果沉淀到图片标注插件的标注记录表。

插件主要提供以下能力：

在业务表内发起识别：可配置表头批量动作和行操作，分别处理勾选记录或单条记录。
支持多个附件字段：可同时选择原生“附件”和“附件（多种录入方式）”字段；非图片附件会自动忽略。
按工作流执行 AI 识别：仅可选择已启用、触发数据表为 imageTransmissionRecords 且包含 AI 员工节点的工作流。
自动沉淀识别结果：按钮任务完成后，结果自动写入 imageAnnotations 标注记录，可在图片标注插件中查看和继续编辑。
支持人工确认的辅助标注：图片标注编辑器内的“AI 标注”只导入临时结果，必须由用户点击“保存全部”后才会成为正式标注记录。
提供任务可追踪性：每张图片都会生成图像传输记录，保留图片地址、来源业务记录、工作流、执行状态、错误信息及 AI 原始结果。

典型闭环如下：

配置 AI 标注工作流 -> 在业务表配置“AI 识别标注”按钮 -> 选择业务记录和附件图片 -> AI 工作流识别 -> 写入标注记录 -> 人工查看、复核和编辑。

二、适用场景

插件适用于图片数量较多、需要通过 AI 快速初筛并保留人工复核能力的场景，例如：

工地安全巡检：识别安全帽、安全带、临边防护、违规作业等问题。
生产质量检查：定位产品表面缺陷、装配异常和工艺问题。
设备运维：识别设备破损、渗漏、仪表异常或需维修部位。
工程验收：识别现场照片中的待整改项，并记录风险和检查结论。
图像数据生产：批量生成初始标注，再由人工修正后用于 YOLO 数据集导出和模型训练。

三、核心使用方式

1. 在业务表配置“AI 识别标注”按钮

插件会将“AI 识别标注”注册到业务表的“配置按钮”菜单中，支持两种位置：

位置	Schema 类型	处理对象	典型用途
表头	`customize:bulkAction`	用户勾选的多条记录	批量处理巡检、质检等记录的附件图片
行操作	`customize:recordAction`	当前单条记录	对某一条业务记录立即发起识别

在按钮的“配置”中设置以下内容：

附件字段：可多选当前业务表中的图片附件字段。支持原生附件和“附件（多种录入方式）”。
关联工作流：选择已启用且符合 AI 标注条件的工作流。
提取全部图片：默认开启。开启后处理所选附件字段内的全部图片；关闭后每个字段只处理第一张图片。
提交前二次确认：默认开启。开启后用户提交任务前需要确认。

保存页面配置后，业务人员即可在表头或行操作中使用该按钮。

2. 批量提交与处理进度

用户点击按钮后，系统会依次执行：

读取选中业务记录及配置的附件字段。
过滤非图片附件，解析每张图片的 URL 和图片标识。
为每张图片创建一条图像传输记录并触发指定工作流。
轮询 AI 工作流状态和识别结果。
将完成的结果写入 imageAnnotations 标注记录。

处理过程中，页面右上角会显示一个非阻塞进度提示，展示已处理图片数和总图片数。用户可以继续浏览或操作页面；任务完成后系统会显示成功、部分完成或失败提示。

单张图片识别失败不会中断后续图片。任务最长轮询 120 秒；查询发生短暂失败时会自动重试，连续失败后才将该图片标记为失败。

3. 在图片标注编辑器中使用 AI 辅助标注

安装并启用图片标注插件后，用户可在图片标注编辑器右侧使用“AI 标注”：

在 AI 区域选择允许使用的工作流。
点击“AI 标注”，等待识别结果返回。
检查 AI 返回的标注框、图片风险等级、检查结论和描述。
如果当前图片已有标注框，根据提示决定是否替换。
按需人工修正后，点击“保存全部”。

此入口和业务表的“AI 识别标注”按钮有不同的保存语义：

入口	AI 结果处理方式
业务表“AI 识别标注”按钮	任务完成后自动写入正式标注记录
图片标注编辑器“AI 标注”	结果只保留在当前编辑器中，用户点击“保存全部”后才写入正式标注记录

四、部署前准备

必需依赖

使用本插件前，请确保以下插件已安装并启用：

@nocobase/plugin-ai，用于配置和运行 AI 员工。
@nocobase/plugin-workflow，用于配置图片识别工作流。

支持的图片格式

系统优先按照附件的 MIME 类型识别图片；缺少 MIME 类型时，会根据文件扩展名识别以下格式：

PNG
JPG / JPEG
WebP
GIF
BMP

五、管理员首次配置

建议按“AI 员工 -> AI 标注工作流 -> 节点参数 -> 业务表按钮 -> 标注记录查看”的顺序完成配置。

步骤 1：创建或确认 AI 员工

先在 AI 员工管理中配置可用的模型、系统提示词和结构化输出能力。插件提供 AI 标注相关预设，管理员可按实际检测对象调整提示词和输出字段。

AI 输出应至少包含标注框数组；每个标注框使用归一化坐标：

{
  "labelId": "类别 ID",
  "labelName": "类别名称",
  "riskLevel": "01",
  "cx": 0.5,
  "cy": 0.5,
  "w": 0.2,
  "h": 0.3
}

其中 cx、cy 是标注框中心点，w、h 是宽度和高度，取值范围为 0 到 1。

步骤 2：配置 AI 标注工作流

创建数据表事件工作流，并将触发数据表设置为 imageTransmissionRecords。工作流需满足以下条件，才会出现在按钮的“关联工作流”下拉选项中：

工作流处于启用状态且是当前版本。
触发数据表为 imageTransmissionRecords。
工作流中至少包含一个 AI 员工节点或 AI 标注员工节点。

工作流通常包括以下节点：

AI 员工节点：接收传输记录中的图片 URL，完成识别并输出结构化结果。
更新记录节点：更新当前触发的 imageTransmissionRecords 记录，写入 annotationData 等结果字段。

更新记录节点的过滤条件应限定为当前触发记录，例如：

id = 触发器变量 / 触发数据 / id

这样可避免并发任务把结果写入其他图片的传输记录。

步骤 3：配置 AI 标注节点参数

在“AI 标注节点配置”页面中可查看符合条件的工作流，并编辑其中 AI 员工节点的 AI 标注参数。可配置内容包括：

AI 员工提示词和结构化输出。
模型（建议选择视觉模型，如qwen3 Vl plus），操作者，附件（默认选择图片url），审批与通知（建议选择AI决策）
可选知识库及知识库检索参数。
是否在图片分析前自动检索知识库。

知识库相关参数为可选项。没有知识库的图片识别工作流仍可正常执行。

步骤 4：在业务表添加按钮

打开需要使用识别能力的业务表，并进入页面设计模式。
在表头操作或行操作的“配置按钮”菜单中选择“AI 识别标注”。
打开按钮配置，选择一个或多个附件字段。
选择关联工作流。
按需设置“提取全部图片”和“提交前二次确认”。
保存页面配置。

新建业务记录尚未保存时没有稳定的主键，不能提交识别任务。请先保存记录后再执行识别。

步骤 5：配置标注记录查看页

如已启用图片标注插件，可在标注记录列表中查看由按钮自动创建的 imageAnnotations 记录。建议显示以下字段：

原始图片或标注图片。
标注框、图片风险等级、检查结论和描述。
是否仅 AI 标注。
业务数据表、业务记录 ID、业务附件字段和图片标识。
创建时间、更新时间和操作人。

业务人员可从标注记录列表打开编辑器，对 AI 结果进行复核和人工修正。

六、图像传输记录与结果查询

插件维护 imageTransmissionRecords 集合，用于记录图片提交和工作流执行过程。主要字段包括：

imageUrl：待识别图片地址。
imageKey：图片标识，用于关联标注记录。
sourceCollection、sourceId、businessField：来源业务表、业务记录和附件字段。
workflowId、workflowKey、executionId：执行的工作流和执行实例。
status：pending、processing、completed 或 failed。
annotationData：AI 返回的完整结构化结果。
errorMessage：失败原因。

插件对外提供以下资源动作，供图片标注插件和自定义页面使用：

动作	说明
`imageTransmissionRecords:listEnabledWorkflows`	查询符合 AI 标注条件的启用工作流
`imageTransmissionRecords:resolveButtonImages`	根据业务记录和附件字段解析可提交的图片
`imageTransmissionRecords:submit`	提交一张图片并触发指定工作流
`imageTransmissionRecords:getAnnotation`	按传输记录 ID，或按业务来源和图片 URL 查询结果

getAnnotation 返回图片任务 ID、状态、图片 URL、总体风险等级、标注框数据、检查结论和描述。按业务来源查询时可附加 imageUrl，以定位同一业务记录下的某一张图片；不传则返回该业务记录的全部图片结果。

七、使用注意事项

业务表按钮一次会按图片串行处理。图片数量较多或模型响应较慢时，处理时间会相应增加。
只有工作流成功将结构化结果写回当前传输记录后，客户端才能取得并保存 AI 标注结果。
AI 输出中的坐标必须是 0 到 1 的归一化数值；非法坐标、未知类别或不允许的类别会被忽略。
编辑器内的 AI 标注不是自动保存入口。用户关闭编辑器或不点击“保存全部”时，临时结果不会成为正式标注记录。
业务表按钮自动保存的结果可以在后续打开标注编辑器时继续人工修改。
外部图片地址必须能被浏览器和 AI 服务访问。建议使用应用自身附件服务地址或已配置访问权限的 HTTP(S) 地址。
修改工作流、AI 员工或结构化输出后，应使用少量测试图片验证结果，再进行批量提交。

八、常见问题

1. 为什么“关联工作流”下拉没有可选项？

请依次检查：

工作流是否已启用且为当前版本。
工作流触发数据表是否为 imageTransmissionRecords。
工作流中是否有 AI 员工节点或 AI 标注员工节点。
当前用户是否具有工作流和图像传输记录的访问权限。

2. 为什么按钮提示“所选附件字段中没有可识别的图片”？

请检查按钮配置的字段是否为附件类型，并确认所选业务记录的这些字段中包含 PNG、JPG、JPEG、WebP、GIF 或 BMP 图片。普通文件、空附件和无法识别的文件类型会被跳过。

3. 为什么任务一直处于处理中或最终失败？

检查图像传输记录中的 status 和 errorMessage，再检查工作流执行记录。常见原因包括图片 URL 无法访问、AI 员工模型配置错误、结构化输出不符合要求，或工作流更新记录节点未正确限定为当前触发记录。

4. 为什么图片标注编辑器中的 AI 结果没有自动进入标注记录？

这是正常行为。编辑器中的“AI 标注”是辅助编辑能力，结果先进入当前编辑器状态；用户必须点击“保存全部”才会写入 imageAnnotations。

5. 为什么业务表按钮的结果会直接出现在标注记录表？

这是业务表“AI 识别标注”按钮的设计行为。该入口面向批量自动识别，轮询到完成结果后会自动创建或更新对应的正式标注记录，之后仍可在编辑器中人工复核和修改。