AI 数据清洗.md 24 KB

AI 数据清洗

本文引用的文件

  • ai_clean.sql
  • ai_clean_field_short_names.sql
  • ai_clean_row_stats.sql
  • ai_clean_synonym_init.sql
  • AiCleanTemplate.java
  • AiCleanField.java
  • AiCleanRule.java
  • AiCleanJob.java
  • AiCleanBatch.java
  • AiCleanSynonym.java
  • AiCleanStatusEnum.java
  • AiCleanExitEnum.java
  • AiCleanStageEnum.java
  • AiCleanService.java
  • AiSmartCleanService.java
  • AiTemplateMatcher.java
  • AiCleanTemplateVectorIndex.java
  • cleaning.vue

目录

  1. 引言
  2. 项目结构与职责边界
  3. 核心实体与数据模型
  4. 整体架构与业务流程
  5. 智能模板匹配流程
  6. 字段映射、同义词与短名规则
  7. 批量清洗任务与执行状态
  8. 结果统计、错误日志与重试策略
  9. 端到端操作示例
  10. 常见问题排查
  11. 结论

引言

AI 数据清洗是既有文件清洗链路的辅助入口:用户上传 CSV/Excel 后,系统先尝试用既有模板匹配;对未匹配或需要结构归一的表块,再由 AI 判定模板、生成清洗规则,并写入独立动态表。该能力不直接修改既有业务表,而是通过“出口 A/B”两条路径分流,保证主链路稳定、可回滚、可观测。

项目结构与职责边界

AI 清洗相关代码集中在后端 ai-server 的 module/aiclean 包中,前端在 Electron 应用的清洗页面发起上传和查看结果,数据库元数据由 SQL 脚本维护。

graph TB
    FE["前端清洗页面<br/>cleaning.vue"] --> API["智能清洗编排服务<br/>AiSmartCleanService"]
    API --> CLEAN["单任务清洗主流程<br/>AiCleanService"]
    CLEAN --> MATCH["模板匹配器<br/>AiTemplateMatcher"]
    MATCH --> INDEX["向量索引<br/>AiCleanTemplateVectorIndex"]
    CLEAN --> STORE["DuckDB 存储<br/>AiCleanStore / AiDuckDb"]
    CLEAN --> DB["PostgreSQL 元数据<br/>ai_clean_* 表"]
    STORE --> DUCK["DuckDB 动态表<br/>ai_clean_{templateId}"]

图示来源

  • AiSmartCleanService.java:1-250
  • AiCleanService.java:1-260
  • AiTemplateMatcher.java:1-220
  • AiCleanTemplateVectorIndex.java:1-200

章节来源

  • AiSmartCleanService.java:1-250
  • AiCleanService.java:1-260

核心实体与数据模型

AI 清洗使用一组独立于既有 table_info/table_field 的 PostgreSQL 表。这些表承担模板、字段、规则、任务、批次和同义词的职责,但不会把 AI 生成的模板行写进既有模板库,从而避免触发旧匹配逻辑异常。

实体 主要字段 作用
AiCleanTemplate id、tableNameCn、tableNameEn、headers、headerMd5、headerLineNo、funcRegex、blockNo、structOps、needsStruct、category、matchTier、status、ver、confidence 保存 AI 新建的业务模板及结构指纹
AiCleanField aiTemplateId、columnName、fieldNameCn、fieldNameEn、fieldType、required、fieldLen、fieldSort、colIndex、matched 定义动态表的列类型、展示名、顺序与校验证据
AiCleanRule aiTemplateId、colIndex、fieldNameEn、hints、refTemplateId、ver 记录每列的扁平清洗提示,避免反序列化任意类名
AiCleanJob caseId、fileId、sheetId、blockNo、ver、status、exitCode、matchedBy、matchTier、aiTemplateId、detail、rowTotal、rowLoaded、rowRejected、rowWarned、rowUnprocessed、failReason 单个 sheet 块的幂等任务与状态线
AiCleanBatch caseId、batchId、stage、sheetTotal、aiJudgedCount、aiLoadCount、loadedRows、rejectedRows、unprocessedRows、selfBuiltCount、needReviewCount、failedCount、lastError 一次智能清洗批次的聚合进度
AiCleanSynonym stdWord、aliasWord、remark、status 表头同义词星型词组,用于评分归一与绑定域解析
erDiagram
  AI_CLEAN_TEMPLATE ||--o{ AI_CLEAN_FIELD : "拥有"
  AI_CLEAN_TEMPLATE ||--o{ AI_CLEAN_RULE : "拥有"
  AI_CLEAN_JOB }o--|| AI_CLEAN_BATCH : "属于"
  AI_CLEAN_JOB }o--|| AI_CLEAN_TEMPLATE : "创建"
  AI_CLEAN_TEMPLATE }o--|| AI_CLEAN_TEMPLATE : "参考既有模板"
  AI_CLEAN_SYNONYM {
    bigint id PK
    varchar std_word
    varchar alias_word
    smallint status
  }

图示来源

  • ai_clean.sql:1-214
  • ai_clean_row_stats.sql:1-21
  • ai_clean_synonym_init.sql:1-42

实体关系说明

  • AiCleanTemplate 与 AiCleanField 是一对多关系:一个模板对应多条列定义。
  • AiCleanTemplate 与 AiCleanRule 也是一对多关系:每个列一行规则快照。
  • AiCleanJob 通过 aiTemplateId 引用出口 B 创建的模板;若走出口 A,则通过 refTemplateId 引用既有模板。
  • AiCleanBatch 是用户点击“智能清洗”时产生的批次容器,汇总所有 job 的计数。
  • AiCleanSynonym 不参与模板主键或指纹计算,只参与评分与绑定域解析。

章节来源

  • AiCleanTemplate.java:1-163
  • AiCleanField.java:1-97
  • AiCleanRule.java:1-70
  • AiCleanJob.java:1-165
  • AiCleanBatch.java:1-99
  • AiCleanSynonym.java:1-63

整体架构与业务流程

AI 清洗有两个入口视角:

  1. 单任务视角:对未匹配模板的 sheet 提交 AiCleanJob,由 AiCleanService 完成探测、匹配、校验、入库。
  2. 批量视角:用户在前端选择多个文件后调用 AiSmartCleanService.submit,系统立即返回 batchId,后台按阶段推进,并通过 SSE 推送进度。

    sequenceDiagram
    participant User as "用户"
    participant Frontend as "清洗页面"
    participant Smart as "AiSmartCleanService"
    participant Clean as "AiCleanService"
    participant Matcher as "AiTemplateMatcher"
    participant Vector as "AiCleanTemplateVectorIndex"
    participant Duck as "DuckDB"
    participant PG as "PostgreSQL"
    
    User->>Frontend: "上传 CSV/Excel 并点智能清洗"
    Frontend->>Smart: "submit(caseId, userId, fileInfos)"
    Smart->>PG: "创建 ai_clean_batch"
    Smart->>Clean: "并发准备并判定未匹配 sheet"
    Clean->>Matcher: "match(headers, candidates)"
    Matcher->>Vector: "语义召回(仅候选排序)"
    Vector-->>Matcher: "候选列表"
    Matcher-->>Clean: "AiMatchOutcome(档位/出口/置信度)"
    alt "出口 A:既有模板"
        Clean->>PG: "记录 job 已交既有链路"
    else "出口 B:AI 自建模板"
        Clean->>PG: "保存 ai_clean_template / field / rule"
        Clean->>Duck: "建表并写入清洗后的行"
        Duck-->>Clean: "成功/拒绝/警告统计"
    end
    Clean-->>Smart: "更新 job 状态与行数"
    Smart-->>Frontend: "SSE 推送阶段与统计"
    

图示来源

  • AiSmartCleanService.java:1-250
  • AiCleanService.java:1-260
  • AiTemplateMatcher.java:1-220
  • AiCleanTemplateVectorIndex.java:1-200

章节来源

  • AiSmartCleanService.java:1-250
  • AiCleanService.java:1-260

智能模板匹配流程

AiTemplateMatcher 实现三条腿的瀑布式匹配:

步骤 行为 是否调用大模型 影响范围
第一条腿 表头指纹比对 header_md5 否 零模型复用 AI 模板
第二条腿 归一化打分,确定性极强时可直通既有模板 否 可能直接走出口 A
第三条腿 向量召回补候选 + 模型裁决 是 决定 STRONG/WEAK/NONE 与出口

向量索引只做“候选排序增强”,不参与档位判定,因此即使 pgvector 不可用,匹配主链路仍可降级工作。

flowchart TD
    Start(["开始"]) --> Fingerprint["计算表头指纹<br/>比对 ai_clean_template.header_md5"]
    Fingerprint --> FpHit{"指纹命中?"}
    FpHit -->|是| StrongB["STRONG → 出口 B"]
    FpHit -->|否| Score["归一化打分"]
    Score --> StrongA{"确定性足够且命中既有模板?"}
    StrongA -->|是| ExitA["出口 A:既有业务表"]
    StrongA -->|否| Recall["向量召回候选"]
    Recall --> LLM["模型从 top-K 候选中选模板"]
    LLM --> Conf{"置信度 >= 阈值?"}
    Conf -->|是| TierStrong["STRONG"]
    Conf -->|否| TierWeak["WEAK"]
    TierStrong --> Decide["根据确定性分选出口 A 或 B"]
    TierWeak --> Decide
    Decide --> End(["结束"])

图示来源

  • AiTemplateMatcher.java:1-220

章节来源

  • AiTemplateMatcher.java:1-220

字段映射、同义词与短名规则

字段短名映射

从 2026-10-18 起,AI 模板字段的物理列名固定为 c0、c1 等,field_name_en 与 column_name 完全一致。历史数据会由迁移脚本统一回填,并把两列宽度收窄到 varchar(5)。这样模型绑定时的语义域更稳定,DDL 也更安全。

章节来源

  • AiCleanField.java:1-97
  • ai_clean_field_short_names.sql:1-16

同义词机制

AiCleanSynonym 维护 alias_word → std_word 的星型词组,例如“发生额”“交易额”“金额”都归一到标准词“交易金额”。它进入评分层和绑定域解析,但不进入 HeaderFingerprint,防止存量模板指纹随词条配置漂移。

章节来源

  • AiCleanSynonym.java:1-63
  • ai_clean_synonym_init.sql:1-42

规则快照

AiCleanRule.hints 只存枚举提示数组,例如“TRIM”“UNIT_SCALE:WAN”这类扁平值,而不是带多态类名的对象 JSON。加载时在内存构造清洗函数,避免开放任意类实例化的反序列化攻击面。

章节来源

  • AiCleanRule.java:1-70

批量清洗任务与执行状态

批次阶段

智能清洗批次由 AiCleanStageEnum 描述,顺序为:

阶段 含义 终态
JUDGING AI 判定各 sheet 否
CLEANING_EXISTING 把可复用既有模板的 sheet 交给既有清洗链路 否
LOADING_AI 把 AI 自建模板的数据写入动态表 否
DONE 全部处理完 是
PARTIAL 有文件级异常,部分未处理完 是
FAILED 整个批次失败 是

章节来源

  • AiCleanStageEnum.java:1-52
  • AiCleanBatch.java:1-99

单任务状态

AiCleanStatusEnum 描述单个 job 的状态机:

状态 含义 终态
PENDING 待处理 否
PROBING 结构探测中 否
STRUCTURING 结构归一中 否
MATCHING 模板匹配中 否
VERIFYING 校验中 否
DISPATCHED_A 已交既有链路 是
LOADING 入库中 否
SUCCESS 清洗完成 是
NEED_REVIEW 待人工确认 是
FAIL 失败 是
SKIP 已跳过 是
SUPERSEDED 已被人工取代 是

章节来源

  • AiCleanStatusEnum.java:1-76

出口设计

AiCleanExitEnum 是整条链路的唯一分叉点:

出口 含义 目标
A 命中既有模板 既有业务表
A2 命中既有模板但需结构归一 既有业务表
A3 本该进既有表但降级 AI 动态表
B 没有合适模板 AI 动态表

章节来源

  • AiCleanExitEnum.java:1-56

结果统计、错误日志与重试策略

行级统计

AiCleanJob 和 AiCleanBatch 都有行级统计字段:

  • rowTotal:总行数。
  • rowLoaded:成功入库行数。
  • rowRejected:必填空值、类型错误、函数异常或超长导致整行拒绝的行数。
  • rowWarned:已入库但含非必填错误的行数。
  • rowUnprocessed:失败任务里尚未处理到的行数。
  • 批次维度还有 loadedRows、rejectedRows、unprocessedRows、selfBuiltCount。

这些字段让前端可以区分“洗坏了”“洗了但有警告”和“根本没跑完”。

章节来源

  • AiCleanJob.java:1-165
  • AiCleanBatch.java:1-99
  • ai_clean_row_stats.sql:1-21

错误日志

  • 任务级失败原因记录在 AiCleanJob.failReason。
  • 批次级最后错误记录在 AiCleanBatch.lastError。
  • 逐行拒绝明细保存在拒绝收集器与相关表中,应用日志默认采样前若干条,可通过配置开启全量拒绝日志。
  • 模型原始草稿记录在 AiCleanJob.draft,便于复盘 prompt 版本。

章节来源

  • AiCleanService.java:1-260
  • AiCleanJob.java:1-165

重试与幂等

  • 单任务唯一键 (caseId, fileId, sheetId, blockNo, ver) 保证同一块只被处理一次。
  • 重跑时 ver 递增,旧版本数据可按 job.id 清理。
  • 批次重复点击会复用已有 batchId,不会重复起线程或重复调既有 doClean。
  • 向量索引重建支持连续失败熔断,避免因嵌入模型或 pgvector 问题无限重试。

章节来源

  • AiCleanJob.java:1-165
  • AiSmartCleanService.java:1-250
  • AiCleanTemplateVectorIndex.java:1-200

端到端操作示例

以下示例以典型用户动作为主线,不粘贴具体代码,只给出涉及的文件和流程位置。

第一步:上传 CSV/Excel

用户在清洗页面选择本地文件或从上传树中选择文件节点。前端会检查根节点是否带有文件路径,否则智能清洗接口会返回缺少文件路径的错误。

相关位置

  • cleaning.vue
  • AiSmartCleanService.java:120-180

第二步:匹配模板

服务端创建 AiCleanBatch 并立即返回 batchId;同时启动后台虚拟线程执行判定。对每个未匹配 sheet,AiCleanService.prepareJob 或 submitUnmatched 创建 AiCleanJob,随后由 AiCleanService.judge 完成结构探测、表头指纹、打分、向量召回和模型裁决。

相关位置

  • AiSmartCleanService.java:120-220
  • AiCleanService.java:120-260
  • AiTemplateMatcher.java:120-220

第三步:执行清洗

  • 出口 A:将判定结果交给既有 DmService.doClean,AiCleanJob.status 记为 DISPATCHED_A。
  • 出口 B:保存 AiCleanTemplate、AiCleanField、AiCleanRule,并在 DuckDB 中创建 ai_clean_{templateId} 动态表,写入清洗后的数据。

相关位置

  • AiCleanExitEnum.java:1-56
  • AiCleanService.java:1-260

第四步:查看结果

前端通过 SSE 接收 cmd 103 进度快照和 cmd 104 处理日志,不再轮询状态接口。批次终态消息包含统计、状态快照和治理宣告。

相关位置

  • AiSmartCleanService.java:180-250
  • AiCleanBatch.java:1-99

第五步:导出结果

清洗完成后,用户可从 AI 动态表或治理树节点中查看结果。若走出口 A,数据落在既有业务表;若走出口 B,数据落在 ai_clean_{templateId} 动态表。

相关位置

  • AiCleanTemplate.java:20-60
  • ai_clean.sql:1-120

常见问题排查

字段映射不准确

现象:模型把原文件列绑到了错误语义列,或物理列名不是预期的 cN。
排查要点:

  • 检查 AiCleanField.columnName 是否为 c0、c1 等合法物理列名。
  • 检查 AiCleanField.fieldNameCn 是否保留了原始列头供用户识别。
  • 检查 AiCleanField.fieldNameEn 是否与 columnName 一致。
  • 查看 AiCleanField.matched:双采样不一致的列不作为打分证据,避免错误自我放大。
  • 查看 AiCleanRule.hints 是否包含预期清洗提示。

相关位置

  • AiCleanField.java:20-97
  • AiCleanRule.java:20-70
  • ai_clean_field_short_names.sql:1-16

同义词未生效

现象:新增别名后,表头打分仍无法命中预期标准词。
排查要点:

  • 确认 AiCleanSynonym.status 为启用。
  • 确认 std_word 与 alias_word 组合唯一,没有重复词条。
  • 注意同义词只参与评分归一和绑定域解析,不参与 header_md5 指纹;如果期望零模型复用,必须表头完全一致。
  • 检查是否存在“一个别名归到两个标准词”的歧义,服务层会阻止这种配置。

相关位置

  • AiCleanSynonym.java:1-63
  • ai_clean_synonym_init.sql:1-42

批量任务卡住

现象:前端进度停在 JUDGING、CLEANING_EXISTING 或 LOADING_AI。
排查要点:

  • 查看 AiCleanBatch.stage 是否为终态 DONE/PARTIAL/FAILED。
  • 查看 AiCleanBatch.lastError 获取批次级错误。
  • 查看对应 AiCleanJob.status,判断是卡在 PROBING、MATCHING、VERIFYING 还是 LOADING。
  • 检查源文件路径是否仍存在;缺失时会返回跳过或失败。
  • 检查向量索引是否可用,pgvector 不可用时不会阻塞主链路,但会影响语义召回质量。

相关位置

  • AiCleanStageEnum.java:1-52
  • AiCleanStatusEnum.java:1-76
  • AiSmartCleanService.java:120-250
  • AiCleanTemplateVectorIndex.java:1-200

向量索引缺失

现象:语义召回为空,模型候选变少,模板匹配更依赖打分或直接走 LLM。
排查要点:

  • 检查向量索引开关是否启用。
  • 检查嵌入模型是否可用,isAvailable() 返回 false 时会降级。
  • 检查 pgvector 是否可用;不可用时应重建或修复向量库。
  • 存量模板首次上线可能没有增量事件,需要手动触发全量重建。
  • 向量索引失败采用 fail-open 策略,不应把异常抛给上传或清洗线程。

相关位置

  • AiCleanTemplateVectorIndex.java:1-200

结论

AI 数据清洗以独立元数据表承载模板、字段、规则和任务轨迹,既能让数据进入治理树,又不侵入既有匹配链路。其核心优势在于:

  • 指纹直通大幅降低模型调用成本。
  • 向量召回只增强候选排序,不改变档位判定,避免语义误判污染既有业务表。
  • 出口 A/B 明确分流,既有表可撤销成本高,AI 表可逐 job 撤销。
  • 批次与任务双重状态机,配合行级统计和错误日志,使长任务可观测、可排错、可重试。

实际使用中应优先完善同义词与字段映射,确保模板命中准确;对长期卡住的批量任务,应从批次阶段、job 状态、源文件路径和向量索引可用性四个维度定位。