本文引用的文件
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}"]
图示来源
章节来源
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
}
图示来源
AiCleanTemplate 与 AiCleanField 是一对多关系:一个模板对应多条列定义。AiCleanTemplate 与 AiCleanRule 也是一对多关系:每个列一行规则快照。AiCleanJob 通过 aiTemplateId 引用出口 B 创建的模板;若走出口 A,则通过 refTemplateId 引用既有模板。AiCleanBatch 是用户点击“智能清洗”时产生的批次容器,汇总所有 job 的计数。AiCleanSynonym 不参与模板主键或指纹计算,只参与评分与绑定域解析。章节来源
AI 清洗有两个入口视角:
AiCleanJob,由 AiCleanService 完成探测、匹配、校验、入库。批量视角:用户在前端选择多个文件后调用 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 推送阶段与统计"
图示来源
章节来源
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(["结束"])
图示来源
章节来源
从 2026-10-18 起,AI 模板字段的物理列名固定为 c0、c1 等,field_name_en 与 column_name 完全一致。历史数据会由迁移脚本统一回填,并把两列宽度收窄到 varchar(5)。这样模型绑定时的语义域更稳定,DDL 也更安全。
章节来源
AiCleanSynonym 维护 alias_word → std_word 的星型词组,例如“发生额”“交易额”“金额”都归一到标准词“交易金额”。它进入评分层和绑定域解析,但不进入 HeaderFingerprint,防止存量模板指纹随词条配置漂移。
章节来源
AiCleanRule.hints 只存枚举提示数组,例如“TRIM”“UNIT_SCALE:WAN”这类扁平值,而不是带多态类名的对象 JSON。加载时在内存构造清洗函数,避免开放任意类实例化的反序列化攻击面。
章节来源
智能清洗批次由 AiCleanStageEnum 描述,顺序为:
| 阶段 | 含义 | 终态 |
|---|---|---|
JUDGING |
AI 判定各 sheet | 否 |
CLEANING_EXISTING |
把可复用既有模板的 sheet 交给既有清洗链路 | 否 |
LOADING_AI |
把 AI 自建模板的数据写入动态表 | 否 |
DONE |
全部处理完 | 是 |
PARTIAL |
有文件级异常,部分未处理完 | 是 |
FAILED |
整个批次失败 | 是 |
章节来源
AiCleanStatusEnum 描述单个 job 的状态机:
| 状态 | 含义 | 终态 |
|---|---|---|
PENDING |
待处理 | 否 |
PROBING |
结构探测中 | 否 |
STRUCTURING |
结构归一中 | 否 |
MATCHING |
模板匹配中 | 否 |
VERIFYING |
校验中 | 否 |
DISPATCHED_A |
已交既有链路 | 是 |
LOADING |
入库中 | 否 |
SUCCESS |
清洗完成 | 是 |
NEED_REVIEW |
待人工确认 | 是 |
FAIL |
失败 | 是 |
SKIP |
已跳过 | 是 |
SUPERSEDED |
已被人工取代 | 是 |
章节来源
AiCleanExitEnum 是整条链路的唯一分叉点:
| 出口 | 含义 | 目标 |
|---|---|---|
A |
命中既有模板 | 既有业务表 |
A2 |
命中既有模板但需结构归一 | 既有业务表 |
A3 |
本该进既有表但降级 | AI 动态表 |
B |
没有合适模板 | AI 动态表 |
章节来源
AiCleanJob 和 AiCleanBatch 都有行级统计字段:
rowTotal:总行数。rowLoaded:成功入库行数。rowRejected:必填空值、类型错误、函数异常或超长导致整行拒绝的行数。rowWarned:已入库但含非必填错误的行数。rowUnprocessed:失败任务里尚未处理到的行数。loadedRows、rejectedRows、unprocessedRows、selfBuiltCount。这些字段让前端可以区分“洗坏了”“洗了但有警告”和“根本没跑完”。
章节来源
AiCleanJob.failReason。AiCleanBatch.lastError。AiCleanJob.draft,便于复盘 prompt 版本。章节来源
(caseId, fileId, sheetId, blockNo, ver) 保证同一块只被处理一次。ver 递增,旧版本数据可按 job.id 清理。batchId,不会重复起线程或重复调既有 doClean。章节来源
以下示例以典型用户动作为主线,不粘贴具体代码,只给出涉及的文件和流程位置。
用户在清洗页面选择本地文件或从上传树中选择文件节点。前端会检查根节点是否带有文件路径,否则智能清洗接口会返回缺少文件路径的错误。
相关位置
服务端创建 AiCleanBatch 并立即返回 batchId;同时启动后台虚拟线程执行判定。对每个未匹配 sheet,AiCleanService.prepareJob 或 submitUnmatched 创建 AiCleanJob,随后由 AiCleanService.judge 完成结构探测、表头指纹、打分、向量召回和模型裁决。
相关位置
DmService.doClean,AiCleanJob.status 记为 DISPATCHED_A。AiCleanTemplate、AiCleanField、AiCleanRule,并在 DuckDB 中创建 ai_clean_{templateId} 动态表,写入清洗后的数据。相关位置
前端通过 SSE 接收 cmd 103 进度快照和 cmd 104 处理日志,不再轮询状态接口。批次终态消息包含统计、状态快照和治理宣告。
相关位置
清洗完成后,用户可从 AI 动态表或治理树节点中查看结果。若走出口 A,数据落在既有业务表;若走出口 B,数据落在 ai_clean_{templateId} 动态表。
相关位置
现象:模型把原文件列绑到了错误语义列,或物理列名不是预期的 cN。
排查要点:
AiCleanField.columnName 是否为 c0、c1 等合法物理列名。AiCleanField.fieldNameCn 是否保留了原始列头供用户识别。AiCleanField.fieldNameEn 是否与 columnName 一致。AiCleanField.matched:双采样不一致的列不作为打分证据,避免错误自我放大。AiCleanRule.hints 是否包含预期清洗提示。相关位置
现象:新增别名后,表头打分仍无法命中预期标准词。
排查要点:
AiCleanSynonym.status 为启用。std_word 与 alias_word 组合唯一,没有重复词条。header_md5 指纹;如果期望零模型复用,必须表头完全一致。相关位置
现象:前端进度停在 JUDGING、CLEANING_EXISTING 或 LOADING_AI。
排查要点:
AiCleanBatch.stage 是否为终态 DONE/PARTIAL/FAILED。AiCleanBatch.lastError 获取批次级错误。AiCleanJob.status,判断是卡在 PROBING、MATCHING、VERIFYING 还是 LOADING。相关位置
现象:语义召回为空,模型候选变少,模板匹配更依赖打分或直接走 LLM。
排查要点:
isAvailable() 返回 false 时会降级。相关位置
AI 数据清洗以独立元数据表承载模板、字段、规则和任务轨迹,既能让数据进入治理树,又不侵入既有匹配链路。其核心优势在于:
实际使用中应优先完善同义词与字段映射,确保模板命中准确;对长期卡住的批量任务,应从批次阶段、job 状态、源文件路径和向量索引可用性四个维度定位。