本文引用的文件
本文面向 AI 数据清洗中的“清洗模板”和“字段映射”机制,重点说明以下问题:
AiCleanTemplate、AiCleanField、RuleBind、AiRulePlan 等实体的字段含义。TemplateCandidate,再由 AiTemplateMatcher 结合表头指纹与 HeaderNormalizer 完成匹配。Synonym 的区别。该机制的核心思想是:AI 侧模板与既有业务模板互不相干。AI 生成的模板、字段、清洗函数链和任务轨迹全部落在 ai_clean_template、ai_clean_field、ai_clean_rule、ai_clean_job 等表中,避免写入既有 table_info 后触发旧匹配器异常或污染用户模板库。
| 实体 | 对应表 | 主键 | 主要职责 | 关键外键 |
|---|---|---|---|---|
AiCleanTemplate |
ai_clean_template |
id |
描述一张由 AI 维护的动态表,包括中文名、物理表名、归一化表头、指纹、分类、状态、版本、置信度等 | 无;但可记录参考的既有模板 main_ref_template_id |
AiCleanField |
ai_clean_field |
id |
描述模板中的每一列,包括物理列名、中文展示名、语义英文名、数据类型、是否必填、长度、排序、原始列号等 | ai_template_id → AiCleanTemplate.id |
RuleBind |
内存模型 | 无 | 描述一次清洗中“文件第几列”到“模板哪个字段”的绑定关系及清洗提示 | 无;通过 fileNameEn 与候选模板字段关联 |
AiRulePlan |
内存类 | 无 | 根据绑定结果生成两套执行计划:出口 A(既有 cleaner)和出口 B(AI 动态表) | 无;消费 RuleBind、TemplateCandidate、ColStat |
TemplateCandidate |
内存记录 | 无 | 向模型展示的候选模板,包含序号、来源、真实 ID、表头、字段摘要、分数 | 无;封装既有模板或 AI 模板信息 |
erDiagram
AI_CLEAN_TEMPLATE {
bigint id PK
varchar table_name_cn
varchar table_name_en
varchar headers
varchar header_md5
integer header_line_no
text func_regex
integer block_no
text struct_ops
integer needs_struct
varchar category
varchar category_l2
integer main_ref_template_id
varchar match_tier
varchar status
integer ver
numeric confidence
bigint create_by
timestamp create_time
timestamp update_time
}
AI_CLEAN_FIELD {
bigint id PK
bigint ai_template_id FK
varchar column_name
varchar field_name_cn
varchar field_name_en
varchar field_type
integer required
integer field_len
integer field_sort
text direction_conf
integer col_index
integer matched
timestamp create_time
}
AI_CLEAN_TEMPLATE ||--o{ AI_CLEAN_FIELD : "一对多"
图表来源
AiCleanTemplate 字段说明AiCleanTemplate 承担与既有 table_info 相似的角色,但完全独立存储:
| 字段 | 类型 | 含义 |
|---|---|---|
id |
雪花 ID | 模板主键,同时用于生成物理表名 ai_clean_{id} |
tableNameCn |
字符串 | 模板中文名,通常来自 sheet 名或文件名 |
tableNameEn |
字符串 | DuckDB 内物理表名,格式为 ai_clean_ + 模板 ID |
headers |
字符串 | 结构归一后的列头,逗号分隔 |
headerMd5 |
字符串 | 归一化表头指纹,唯一键;命中后可零模型复用模板 |
headerLineNo |
整数 | 表头所在行号 |
funcRegex |
文本 | 表头之上正文里外提姓名/卡号的正则,沿用既有 JSON 语义 |
blockNo |
整数 | 单 sheet 多表头时的块序号 |
structOps |
文本 | 结构指令快照,重放时免模型再判 |
needsStruct |
整数 | 1 表示必须结构归一才能看懂表头;此类模板不参与既有匹配 |
category / categoryL2 |
字符串 | 业务分类和二级分类 |
mainRefTemplateId |
整数 | 判定参考的既有模板 ID,仅溯源用 |
matchTier |
字符串 | 定档结果:STRONG、WEAK、NONE |
status |
字符串 | DRAFT、ONLINE、OFFLINE;OFFLINE 表示摘除治理树但保留数据 |
ver |
整数 | 规则版本,每次订正加一 |
confidence |
数值 | 登记时的整体置信度 |
createBy / createTime / updateTime |
标准审计字段 | 创建人、创建时间、更新时间 |
章节来源
AiCleanField 字段说明AiCleanField 对位既有 table_field,但与既有表无关,是双重真源:
| 字段 | 类型 | 含义 |
|---|---|---|
id |
雪花 ID | 字段主键 |
aiTemplateId |
长整型 | 所属 AI 模板 ID |
columnName |
字符串 | 动态表物理列名,固定为 c0、c1 等,只含小写字母、数字和下划线 |
fieldNameCn |
字符串 | 前端展示用的中文列头,沿用原文件列头 |
fieldNameEn |
字符串 | 语义英文名;按 2026-10-18 需求与 columnName 一致 |
fieldType |
字符串 | 字段类型,取值来源于 FieldTypeEnum |
required |
整数 | 是否必填 |
fieldLen |
整数 | 声明长度,AI 动态表统一无界,长度只做展示校验 |
fieldSort |
整数 | 列序,决定前端列表头顺序 |
directionConf |
文本 | 借贷方向字典 JSON,沿用既有格式 |
colIndex |
整数 | 原文件里的列序号,重放时定位用 |
matched |
整数 | 双采样一致性标记:1 作为打分证据,0 不作为证据 |
createTime |
时间戳 | 创建时间 |
需要注意:column_name 和 field_name_en 的列宽已被收窄为 varchar(5),因为固定前缀 c 加上最多四位位置编号不会超过 5 字符。
章节来源
RuleBind 字段说明RuleBind 不是持久化实体,而是“一列的绑定结果”:
| 字段 | 类型 | 含义 |
|---|---|---|
fileColIndex |
整数 | 文件列序号,0 基;越界会被丢弃 |
fieldNameEn |
字符串 | 目标字段名;模型允许回中文名或英文名,后端会规范化为规范英文名 |
hints |
字符串列表 | 清洗提示,如 SCALE:10000;不认识的提示被丢弃 |
required |
布尔值 | 模型自报是否必填;后端以模板字段的 required 为准覆盖 |
confidence |
浮点值 | 模型自报本列置信度,用于双采样一致性比较 |
章节来源
AiRulePlan 的职责AiRulePlan 是“由绑定结果拼出两套执行计划”的内存类:
TableRuleDTO 列表,使用既有 table_field 元数据。CompiledColumn 列表和 AiCleanField 列表,并据此构造动态表。TEXT。章节来源
TemplateCandidate 的作用TemplateCandidate 是候选模板的记录形式,既可以是既有 table_info 模板,也可以是 AI 侧 ai_clean_template 模板。它向模型暴露的是带序号的简洁视图,而不是直接回填真实 ID,从而降低模型幻觉风险。
关键字段:
| 字段 | 含义 |
|---|---|
no |
提示词中的 1 基序号 |
fromAiLib |
是否来自 AI 模板库 |
templateId |
既有模板 ID |
aiTemplateId |
AI 模板 ID |
nameCn / nameEn |
模板中文名和物理表名 |
headers |
模板列头 |
fields |
字段摘要,包含中文名、英文名、类型、是否必填、长度、方向配置 |
score |
Java 侧归一化打分,供排序和模型参考 |
章节来源
一个清洗模板描述的不是某一份数据,而是“一类具有相同结构和语义的文件”。它通过三层信息表达目标表结构:
AiCleanTemplate 提供表级元数据,包括中文名、物理表名、归一化表头、指纹、分类、状态、版本、置信度等。AiCleanField 提供列级元数据,包括物理列名、中文展示名、语义英文名、类型、是否必填、排序、原始列号等。映射层:RuleBind 描述具体上传文件中“第几列”对应“模板中的哪个字段”,并可附加清洗提示。
flowchart TD
Start["上传文件"] --> Probe["探测表头与列统计"]
Probe --> Normalize["HeaderNormalizer 归一化表头"]
Normalize --> Fingerprint["HeaderFingerprint 计算指纹"]
Fingerprint --> Match["AiTemplateMatcher 三腿匹配"]
Match --> Candidate["构建 TemplateCandidate"]
Candidate --> Plan["AiRulePlan 生成清洗计划"]
Plan --> ExportA["出口 A:既有 cleaner"]
Plan --> ExportB["出口 B:AI 动态表"]
图表来源
当前实现中,“字段短名”并不是 AiCleanField 中的一个独立字段,而是通过以下两个字段共同表达:
column_name:物理列名,固定为 c0、c1、c2……这是 DDL 和查询实际使用的列名。fieldNameEn:语义英文名,按 2026-10-18 需求与 column_name 完全一致,因此也是 c0、c1 等形式。fieldNameCn:中文展示名,用于前端显示和用户理解。也就是说,这里的“短名”更接近“物理列名”,而不是传统意义上的业务短代码。真正让模型识别字段语义的是:
cn 和 en。RuleBind.fieldNameEn。HeaderScorer 的同义词归一化能力。AiRulePlan.typeOf 中的表头关键词推断。章节来源
在 AI 清洗链路中,“短名”参与匹配的方式有两处:
RuleBind.fieldNameEn 可能返回中文展示名或英文字段名。后端通过 AiTemplateMatcher.filterBinds 将其规范化为候选模板字段的规范英文名。AiRulePlan.resolveType 会尝试从表头中文名、字段英文名、列形状推断类型。因此,字段短名(更准确说是“语义英文名”)的关键作用是:给模型一个稳定的、可用于绑定和类型推断的标识域。
Synonym(同义词库)和“字段短名”是不同层次的概念:
| 维度 | 字段短名 | 同义词 |
|---|---|---|
| 存在形式 | AiCleanField.fieldNameEn、TemplateCandidate.FieldBrief.en、RuleBind.fieldNameEn |
ai_clean_synonym.std_word / alias_word |
| 主要用途 | 标识模板字段、供模型绑定、供类型推断 | 把“账户名称”“客户名称”“姓名”等别名归一到标准词,提升评分和绑定成功率 |
| 影响范围 | 字段枚举域、绑定校验、类型兜底 | 评分归一化、filterBinds 绑定域 |
| 是否进入指纹 | 否 | 否;注释明确说明同义词不进入 HeaderFingerprint |
| 典型例子 | c0、c1、accountName |
“交易金额” ← “发生额”、“户名” ← “账户名称” |
同义词库的设计原则是:星型词组,别名指向标准词;命中类型分 EXACT 和 SIMILAR;不做链式传递;不进指纹,防止存量模板指纹漂移。
章节来源
AiRulePlan 根据绑定结果生成两类计划:
出口 A 适用于命中既有模板且确定性足够强的场景。它会:
table_field。RuleBind.fieldNameEn 查找对应字段。TableRuleDTO,携带表 ID、文件列序号、文件列名、字段中文名、字段英文名、类型、必填、长度、排序、借贷方向等。AiRuleCompiler.compileFuns 将绑定提示编译成清洗函数链。出口 B 适用于 AI 模板或置信度不足的既有模板。它会:
c0、c1、c2……AiCleanField 和 CompiledColumn。支持复用已有 AI 模板:forStoredTemplate 按存档 colIndex 复用,forStoredTemplateByMapping 按字段名映射复用。
classDiagram
class AiRulePlan {
+forExisting(binds, cand, headerNames) List
+forExistingColumns(binds, cand, headerNames) List
+forAi(binds, headerNames, colStats, cand) Plan
+forStoredTemplate(storedFields, binds) Plan
+forStoredTemplateByMapping(storedFields, binds) Plan
+resolveType(header, bind, stat) String
+typeOf(name) String
}
class RuleBind {
+fileColIndex Integer
+fieldNameEn String
+hints List
+required Boolean
+confidence Double
}
class TemplateCandidate {
+no int
+fromAiLib boolean
+templateId Integer
+aiTemplateId Long
+nameCn String
+nameEn String
+headers List
+fields List
+score double
}
class CompiledColumn {
+fileColIndex Integer
+columnName String
+fieldNameEn String
+type String
+required Boolean
+fieldLen Integer
+functions List
+directionConf String
}
class AiCleanField {
+columnName String
+fieldNameCn String
+fieldNameEn String
+fieldType String
+required Integer
+fieldLen Integer
+fieldSort Integer
+colIndex Integer
}
AiRulePlan --> RuleBind : "消费"
AiRulePlan --> TemplateCandidate : "消费"
AiRulePlan --> CompiledColumn : "生成"
AiRulePlan --> AiCleanField : "生成"
图表来源
章节来源
模板加载不是简单地把数据库行塞进对象,而是经历“模板 + 字段 + 候选构建 + 打分 + 匹配”的流水线:
AiCleanTemplateMapper、AiCleanFieldMapper 读取 ai_clean_template 和 ai_clean_field。AiTemplateWithFieldsAiTemplateWithFields(template, fields) 一起传入,避免匹配过程中重复查库。TemplateCandidateHeaderScorer.score 对候选池打分;得分用于排序,而非直接决定出口。AiCleanTemplateVectorIndex 召回相关模板,提高其排序分数,但不改变档位判定逻辑。三腿匹配
第三腿:模型裁决,返回 AiRuleDraft,包含选中的模板序号、字段绑定和置信度。
sequenceDiagram
participant Service as "AiCleanService"
participant Matcher as "AiTemplateMatcher"
participant Loader as "TemplateCandidateLoader"
participant Index as "AiCleanTemplateVectorIndex"
participant LLM as "LlmService"
participant Store as "AiCleanStore"
Service->>Matcher: match(SheetEvidence, aiOnline, llmEnabled)
Matcher->>Matcher: 计算表头指纹
Matcher->>Matcher: 比对 ai_clean_template.header_md5
alt 指纹命中
Matcher-->>Service: STRONG 档 + 出口 B
else 指纹未命中
Matcher->>Loader: 加载既有模板候选
Matcher->>Matcher: 合并 AI 模板候选
Matcher->>Matcher: HeaderScorer 打分
alt 确定性极强
Matcher-->>Service: STRONG 档 + 可能出口 A
else 需要模型裁决
Matcher->>Index: 向量召回
Matcher->>LLM: askLlm(短名单)
LLM-->>Matcher: AiRuleDraft
Matcher->>Matcher: filterBinds + 档位判定
Matcher-->>Service: 匹配结果
end
end
Service->>Store: register(模板+字段+规则)
图表来源
HeaderNormalizer 负责列名归一化:
HeaderFingerprint 负责按“有效列位置 + 归一化列名”拼接后计算 MD5:
顺序敏感是故意设计:列序一变,规则里存的列序号就会整体错位,不能误复用。
flowchart TD
Raw["原始表头"] --> HalfWidth["半角转换"]
HalfWidth --> RemoveBracket["去除括号字符<br/>保留括号内容"]
RemoveBracket --> RemoveJunk["去除杂字符"]
RemoveJunk --> StripSuffix["循环剥离常见后缀"]
StripSuffix --> Lower["转小写"]
Lower --> Fingerprint["按位置+归一化名拼接<br/>计算 MD5"]
图表来源
章节来源
假设有一份 CSV 文件,表头如下:
| 文件列序号 | CSV 表头 | Excel 列名 | 业务含义 |
|---|---|---|---|
| 0 | 账号 | Account | 银行账号 |
| 1 | 户名 | Name | 账户持有人 |
| 2 | 交易金额 | Amount | 发生额或余额 |
| 3 | 日期 | Date | 交易日期 |
| 4 | 备注 | Remark | 补充说明 |
在数据库中创建一条 ai_clean_template 记录:
table_name_cn:银行账户流水table_name_en:由后端生成,形如 ai_clean_{id}headers:归一化后的列头,逗号分隔header_md5:按当前归一化规则和位置计算的 MD5category:业务分类,例如 FileCategoryEnum 中的值status:新建时为 DRAFT,上线后改为 ONLINEver:初始为 1章节来源
为模板插入若干 ai_clean_field 记录:
| 字段 | 示例值 | 说明 |
|---|---|---|
ai_template_id |
模板 ID | 关联到上一步创建的模板 |
column_name |
c0、c1、c2、c3、c4 |
物理列名 |
field_name_cn |
账号、户名、交易金额、日期、备注 | 前端展示名 |
field_name_en |
c0、c1、c2、c3、c4 |
与 column_name 一致 |
field_type |
ACCT_CARD_NO、TEXT、MONEY、DATE、TEXT |
字段类型 |
required |
1 或 0 | 是否必填 |
field_sort |
1、2、3、4、5 | 前端排序 |
col_index |
0、1、2、3、4 | 原文件列序号 |
注意:field_name_en 现在与 column_name 完全一致,都是 c0、c1 这类短名;真正的语义识别更多依赖 fieldNameCn、fieldType 以及模型绑定时看到的候选字段摘要。
章节来源
绑定规则描述“文件列 → 模板字段”的关系。对于上述 CSV,模型可能返回如下绑定:
| 文件列序号 | 目标字段英文名 | 清洗提示 | 是否必填 |
|---|---|---|---|
| 0 | c0 | 空 | 否 |
| 1 | c1 | 空 | 否 |
| 2 | c2 | SCALE:10000 |
是 |
| 3 | c3 | 空 | 否 |
| 4 | c4 | 空 | 否 |
后端会通过 AiTemplateMatcher.filterBinds 做两件事:
fieldNameEn 是否在候选模板字段枚举内。fileColIndex 是否越界。章节来源
导出计划后,数据写入的目标取决于出口:
table_field.fieldNameEn 决定。ai_clean_{模板ID},列名为 c0、c1、c2……;AiRulePlan.forAi 会为每个非空表头生成一列。对于自建表场景,即使模型只绑定部分列,AiRulePlan.forAi 也会保留其余列,类型按模板元数据、列形状、表头关键词推断。
章节来源
AiCleanStore.register 会:
ai_clean_template。ai_clean_field。ai_clean_rule。删除模板时,会先删规则、再删字段、最后删模板,并发布删除事件。
章节来源
graph TB
AiCleanService["AiCleanService"]
AiTemplateMatcher["AiTemplateMatcher"]
HeaderNormalizer["HeaderNormalizer"]
HeaderFingerprint["HeaderFingerprint"]
TemplateCandidate["TemplateCandidate"]
AiRulePlan["AiRulePlan"]
RuleBind["RuleBind"]
AiCleanStore["AiCleanStore"]
AiCleanTemplate["AiCleanTemplate"]
AiCleanField["AiCleanField"]
AiCleanService --> AiTemplateMatcher
AiTemplateMatcher --> HeaderNormalizer
AiTemplateMatcher --> HeaderFingerprint
AiTemplateMatcher --> TemplateCandidate
AiTemplateMatcher --> AiRulePlan
AiRulePlan --> RuleBind
AiRulePlan --> AiCleanField
AiCleanStore --> AiCleanTemplate
AiCleanStore --> AiCleanField
图表来源
AiCleanService 是入口,协调任务、判定、清洗和落库。AiTemplateMatcher 是匹配中枢,负责三腿匹配、模型调用、候选排序和出口选择。HeaderNormalizer 和 HeaderFingerprint 是纯工具类,不参与业务状态。AiRulePlan 是执行计划转换器,连接绑定结果与清洗执行。AiCleanStore 是 AI 模板的唯一落库入口,不碰既有 table_info。这种设计保证了:
章节来源
现象
上传文件后,没有命中任何模板,进入模型裁决或直接判定为未命中。
可能原因
status 不是 ONLINE,或 needsStruct=1 的模板无法参与既有匹配。templateNo 越界,被当作未命中。STRONG 档,无法进入出口 A。排查建议
ai_clean_template.status 是否为 ONLINE。headers 和 header_md5 是否与当前归一化规则一致。needsStruct=1,这类模板要求结构归一,不能走既有匹配。templateNo 是否在短名单范围内。章节来源
现象
数据能入库,但列内容写到错误列,例如账号写到金额列。
可能原因
colIndex 时假定列序不变。filterBinds 把歧义绑定丢弃,导致该列没有被显式绑定。排查建议
RuleBind.fileColIndex 是否落在实际列数范围内。AiTemplateMatcher.filterBinds 是否因相似解析歧义丢弃了绑定。forStoredTemplate 还是 forStoredTemplateByMapping。headers,确认列序是否一致。AiRulePlan.expandedColumnCount 与非空表头数量是否匹配。章节来源
现象
多个模板字段看起来像同一个短名,模型绑定不稳定或后端丢弃绑定。
说明
当前实现中,field_name_en 与 column_name 都固定为 c0、c1 等短名,因此同一模板内不会有短名冲突;跨模板之间也不直接通过 field_name_en 匹配,而是通过候选池序号和模型返回值。
真正的冲突风险来自:
排查建议
fieldNameCn 是否过于相似。ai_clean_synonym 中是否存在大量别名指向同一个标准词。filterBinds 的相似解析是否返回 0 个或 ≥2 个命中。章节来源
现象
列类型推断错误,例如时间戳被当成数字,金额被当成文本,电话号码被当成普通字符串。
可能原因
field_type 为空或未设置,退回到类型推断。PHONE、IDCARD、DATE、DATETIME、TIME、MONEY、ACCT 等强特征。RuleBind.fieldNameEn 也没有帮助推断类型。排查建议
field_type。AiRulePlan.resolveType 的类型来源优先级是否正确生效。章节来源
现象
治理树能看到 AI 模板节点,但打开物理表时报不存在。
可能原因
排查建议
ai_clean_template.status 是否为 ONLINE。ai_clean_field 是否有对应字段记录。ai_clean_rule 是否有对应规则记录。ai_clean_{模板ID} 约定。table_info 来绕过该问题,这会污染既有匹配器。章节来源
AI 清洗模板与字段映射机制的核心价值在于:
ai_clean_template 和 ai_clean_field 替代既有 table_info 和 table_field,避免 AI 判断污染用户模板库。HeaderNormalizer 和 HeaderFingerprint 保证零模型复用的安全性。AiTemplateMatcher 的三腿匹配平衡成本与准确性:指纹直通、归一化打分、模型裁决。RuleBind 表达文件列到模板字段的语义映射,并通过 filterBinds 防造字段、防歧义。AiRulePlan 同时支撑既有 cleaner 和 AI 动态表两套执行路径。Synonym 提升表头评分和绑定成功率,但严格限制其不影响指纹和档位判定。在实际使用中,最重要的实践是:模板字段类型优先于自动推断,表头语义优先于列形状,模板状态必须为 ONLINE,模型返回的绑定必须经过后端校验。只有同时满足这些条件,清洗模板才能真正稳定地描述目标表结构、字段短名、规则计划和字段映射关系。