清洗模板与字段映射.md 36 KB

清洗模板与字段映射

本文引用的文件

  • ai_clean.sql
  • ai_clean_field_short_names.sql
  • ai_clean_synonym_init.sql
  • AiCleanTemplate.java
  • AiCleanField.java
  • RuleBind.java
  • AiRulePlan.java
  • TemplateCandidate.java
  • AiTemplateMatcher.java
  • HeaderNormalizer.java
  • HeaderFingerprint.java
  • AiCleanStore.java

目录

  1. 引言
  2. 实体定义与关系
  3. 模板如何描述目标表结构
  4. 字段短名、规则计划与字段映射
  5. 模板加载与匹配流程
  6. 创建模板、绑定规则与字段映射示例
  7. 依赖分析
  8. 常见问题与排查建议
  9. 结论

引言

本文面向 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 : "一对多"

图表来源

  • ai_clean.sql:18-60
  • ai_clean.sql:62-98

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 标准审计字段 创建人、创建时间、更新时间

章节来源

  • AiCleanTemplate.java:18-163
  • ai_clean.sql:18-60

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 字符。

章节来源

  • AiCleanField.java:18-97
  • ai_clean_field_short_names.sql:1-16
  • ai_clean.sql:62-98

RuleBind 字段说明

RuleBind 不是持久化实体,而是“一列的绑定结果”:

字段 类型 含义
fileColIndex 整数 文件列序号,0 基;越界会被丢弃
fieldNameEn 字符串 目标字段名;模型允许回中文名或英文名,后端会规范化为规范英文名
hints 字符串列表 清洗提示,如 SCALE:10000;不认识的提示被丢弃
required 布尔值 模型自报是否必填;后端以模板字段的 required 为准覆盖
confidence 浮点值 模型自报本列置信度,用于双采样一致性比较

章节来源

  • RuleBind.java:1-48

AiRulePlan 的职责

AiRulePlan 是“由绑定结果拼出两套执行计划”的内存类:

  • 出口 A:生成既有 cleaner 需要的 TableRuleDTO 列表,使用既有 table_field 元数据。
  • 出口 B:生成 AI 侧清洗计划,输出 CompiledColumn 列表和 AiCleanField 列表,并据此构造动态表。
  • 类型来源优先级:模板字段类型优先 → 列形状推断 → 表头关键词推断 → TEXT。

章节来源

  • AiRulePlan.java:1-120
  • AiRulePlan.java:120-250
  • AiRulePlan.java:250-479

TemplateCandidate 的作用

TemplateCandidate 是候选模板的记录形式,既可以是既有 table_info 模板,也可以是 AI 侧 ai_clean_template 模板。它向模型暴露的是带序号的简洁视图,而不是直接回填真实 ID,从而降低模型幻觉风险。

关键字段:

字段 含义
no 提示词中的 1 基序号
fromAiLib 是否来自 AI 模板库
templateId 既有模板 ID
aiTemplateId AI 模板 ID
nameCn / nameEn 模板中文名和物理表名
headers 模板列头
fields 字段摘要,包含中文名、英文名、类型、是否必填、长度、方向配置
score Java 侧归一化打分,供排序和模型参考

章节来源

  • TemplateCandidate.java:1-51

模板如何描述目标表结构

一个清洗模板描述的不是某一份数据,而是“一类具有相同结构和语义的文件”。它通过三层信息表达目标表结构:

  1. 模板层:AiCleanTemplate 提供表级元数据,包括中文名、物理表名、归一化表头、指纹、分类、状态、版本、置信度等。
  2. 字段层:AiCleanField 提供列级元数据,包括物理列名、中文展示名、语义英文名、类型、是否必填、排序、原始列号等。
  3. 映射层: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 动态表"]
    

图表来源

  • AiTemplateMatcher.java:24-78
  • HeaderNormalizer.java:12-66
  • HeaderFingerprint.java:12-86
  • AiRulePlan.java:120-250

目标表结构与字段短名

当前实现中,“字段短名”并不是 AiCleanField 中的一个独立字段,而是通过以下两个字段共同表达:

  • column_name:物理列名,固定为 c0、c1、c2……这是 DDL 和查询实际使用的列名。
  • fieldNameEn:语义英文名,按 2026-10-18 需求与 column_name 完全一致,因此也是 c0、c1 等形式。
  • fieldNameCn:中文展示名,用于前端显示和用户理解。

也就是说,这里的“短名”更接近“物理列名”,而不是传统意义上的业务短代码。真正让模型识别字段语义的是:

  • 模板字段清单中的 cn 和 en。
  • RuleBind.fieldNameEn。
  • HeaderScorer 的同义词归一化能力。
  • AiRulePlan.typeOf 中的表头关键词推断。

章节来源

  • AiCleanField.java:40-97
  • ai_clean_field_short_names.sql:1-16
  • TemplateCandidate.java:25-51
  • AiRulePlan.java:250-479

字段短名、规则计划与字段映射

字段短名的作用

在 AI 清洗链路中,“短名”参与匹配的方式有两处:

  1. 模型绑定阶段:模型返回的 RuleBind.fieldNameEn 可能返回中文展示名或英文字段名。后端通过 AiTemplateMatcher.filterBinds 将其规范化为候选模板字段的规范英文名。
  2. 类型推断阶段:当没有模板字段元数据时,AiRulePlan.resolveType 会尝试从表头中文名、字段英文名、列形状推断类型。

因此,字段短名(更准确说是“语义英文名”)的关键作用是:给模型一个稳定的、可用于绑定和类型推断的标识域。

与 Synonym 的区别

Synonym(同义词库)和“字段短名”是不同层次的概念:

维度 字段短名 同义词
存在形式 AiCleanField.fieldNameEn、TemplateCandidate.FieldBrief.en、RuleBind.fieldNameEn ai_clean_synonym.std_word / alias_word
主要用途 标识模板字段、供模型绑定、供类型推断 把“账户名称”“客户名称”“姓名”等别名归一到标准词,提升评分和绑定成功率
影响范围 字段枚举域、绑定校验、类型兜底 评分归一化、filterBinds 绑定域
是否进入指纹 否 否;注释明确说明同义词不进入 HeaderFingerprint
典型例子 c0、c1、accountName “交易金额” ← “发生额”、“户名” ← “账户名称”

同义词库的设计原则是:星型词组,别名指向标准词;命中类型分 EXACT 和 SIMILAR;不做链式传递;不进指纹,防止存量模板指纹漂移。

章节来源

  • AiTemplateMatcher.java:370-466
  • ai_clean_synonym_init.sql:1-42
  • ai_clean.sql:150-200

规则计划

AiRulePlan 根据绑定结果生成两类计划:

出口 A:既有 cleaner 计划

出口 A 适用于命中既有模板且确定性足够强的场景。它会:

  • 从全局缓存读取既有 table_field。
  • 按 RuleBind.fieldNameEn 查找对应字段。
  • 生成 TableRuleDTO,携带表 ID、文件列序号、文件列名、字段中文名、字段英文名、类型、必填、长度、排序、借贷方向等。
  • 调用 AiRuleCompiler.compileFuns 将绑定提示编译成清洗函数链。

出口 B:AI 动态表计划

出口 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 : "生成"
    

图表来源

  • AiRulePlan.java:1-200
  • AiRulePlan.java:200-479
  • RuleBind.java:1-48
  • TemplateCandidate.java:1-51

章节来源

  • AiRulePlan.java:1-200
  • AiRulePlan.java:200-479

模板加载与匹配流程

模板加载流程

模板加载不是简单地把数据库行塞进对象,而是经历“模板 + 字段 + 候选构建 + 打分 + 匹配”的流水线:

  1. 从数据库读取 AI 模板与字段
    通过 AiCleanTemplateMapper、AiCleanFieldMapper 读取 ai_clean_template 和 ai_clean_field。
  2. 组装 AiTemplateWithFields
    匹配器内部使用 AiTemplateWithFields(template, fields) 一起传入,避免匹配过程中重复查库。
  3. 构建 TemplateCandidate
    每个模板转换为候选记录,包含序号、来源、真实 ID、表头、字段摘要和初始分数。
  4. 归一化打分
    使用 HeaderScorer.score 对候选池打分;得分用于排序,而非直接决定出口。
  5. 向量召回增强
    如果启用 LLM,则通过 AiCleanTemplateVectorIndex 召回相关模板,提高其排序分数,但不改变档位判定逻辑。
  6. 三腿匹配

    • 第一腿:表头指纹命中 AI 模板,零模型调用。
    • 第二腿:确定性极强的既有模板,可直接走出口 A。
    • 第三腿:模型裁决,返回 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(模板+字段+规则)
      

图表来源

  • AiTemplateMatcher.java:78-200
  • AiTemplateMatcher.java:200-466
  • AiCleanStore.java:54-120

表头归一化与指纹

HeaderNormalizer 负责列名归一化:

  • 半角转换。
  • 去掉括号字符但保留括号内容,例如“金额(元)”与“金额(万元)”仍区分。
  • 去掉常见杂字符,如空格、下划线、连字符、标点等。
  • 循环剥离常见后缀,如“明细表”“统计表”“台账”等。
  • 最终转为小写。

HeaderFingerprint 负责按“有效列位置 + 归一化列名”拼接后计算 MD5:

  • 尾部空列不参与指纹。
  • 中间空列保留占位,确保列序变化仍能改变指纹。
  • 顺序敏感是故意设计:列序一变,规则里存的列序号就会整体错位,不能误复用。

    flowchart TD
    Raw["原始表头"] --> HalfWidth["半角转换"]
    HalfWidth --> RemoveBracket["去除括号字符<br/>保留括号内容"]
    RemoveBracket --> RemoveJunk["去除杂字符"]
    RemoveJunk --> StripSuffix["循环剥离常见后缀"]
    StripSuffix --> Lower["转小写"]
    Lower --> Fingerprint["按位置+归一化名拼接<br/>计算 MD5"]
    

图表来源

  • HeaderNormalizer.java:12-66
  • HeaderFingerprint.java:12-86

章节来源

  • AiTemplateMatcher.java:24-200
  • HeaderNormalizer.java:12-66
  • HeaderFingerprint.java:12-86

创建模板、绑定规则与字段映射示例

示例背景

假设有一份 CSV 文件,表头如下:

文件列序号 CSV 表头 Excel 列名 业务含义
0 账号 Account 银行账号
1 户名 Name 账户持有人
2 交易金额 Amount 发生额或余额
3 日期 Date 交易日期
4 备注 Remark 补充说明

步骤一:创建 AI 模板

在数据库中创建一条 ai_clean_template 记录:

  • table_name_cn:银行账户流水
  • table_name_en:由后端生成,形如 ai_clean_{id}
  • headers:归一化后的列头,逗号分隔
  • header_md5:按当前归一化规则和位置计算的 MD5
  • category:业务分类,例如 FileCategoryEnum 中的值
  • status:新建时为 DRAFT,上线后改为 ONLINE
  • ver:初始为 1

章节来源

  • ai_clean.sql:18-60
  • AiCleanTemplate.java:24-163

步骤二:定义字段

为模板插入若干 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 以及模型绑定时看到的候选字段摘要。

章节来源

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

步骤三:绑定规则

绑定规则描述“文件列 → 模板字段”的关系。对于上述 CSV,模型可能返回如下绑定:

文件列序号 目标字段英文名 清洗提示 是否必填
0 c0 空 否
1 c1 空 否
2 c2 SCALE:10000 是
3 c3 空 否
4 c4 空 否

后端会通过 AiTemplateMatcher.filterBinds 做两件事:

  1. 检查 fieldNameEn 是否在候选模板字段枚举内。
  2. 如果是中文展示名,改写为规范英文名;如果是合法短名,保留。
  3. 校验 fileColIndex 是否越界。
  4. 对精确未命中的绑定尝试相似解析;歧义时丢弃该列。

章节来源

  • RuleBind.java:1-48
  • AiTemplateMatcher.java:370-466

步骤四:字段映射到目标列

导出计划后,数据写入的目标取决于出口:

  • 出口 A:写入既有业务表,列映射由既有 table_field.fieldNameEn 决定。
  • 出口 B:写入 AI 动态表 ai_clean_{模板ID},列名为 c0、c1、c2……;AiRulePlan.forAi 会为每个非空表头生成一列。

对于自建表场景,即使模型只绑定部分列,AiRulePlan.forAi 也会保留其余列,类型按模板元数据、列形状、表头关键词推断。

章节来源

  • AiRulePlan.java:120-250

步骤五:保存模板与规则

AiCleanStore.register 会:

  1. 插入 ai_clean_template。
  2. 批量插入 ai_clean_field。
  3. 批量插入 ai_clean_rule。
  4. 发布模板变更事件,通知向量索引增量重建。
  5. 返回模板 ID。

删除模板时,会先删规则、再删字段、最后删模板,并发布删除事件。

章节来源

  • AiCleanStore.java:54-120

依赖分析

组件依赖图

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.java:1-250
  • AiTemplateMatcher.java:24-200
  • AiRulePlan.java:1-200
  • AiCleanStore.java:54-120

耦合与边界

  • AiCleanService 是入口,协调任务、判定、清洗和落库。
  • AiTemplateMatcher 是匹配中枢,负责三腿匹配、模型调用、候选排序和出口选择。
  • HeaderNormalizer 和 HeaderFingerprint 是纯工具类,不参与业务状态。
  • AiRulePlan 是执行计划转换器,连接绑定结果与清洗执行。
  • AiCleanStore 是 AI 模板的唯一落库入口,不碰既有 table_info。

这种设计保证了:

  • 模板匹配失败时,不会静默污染既有业务表。
  • 向量召回异常时,不会中断主匹配链路。
  • 模型幻觉返回非法序号时,会被当作未命中处理。
  • AI 模板与既有模板共享候选池,但出口选择仍有安全闸门。

章节来源

  • AiTemplateMatcher.java:24-78
  • AiCleanStore.java:24-54

常见问题与排查建议

1. 模板未命中

现象
上传文件后,没有命中任何模板,进入模型裁决或直接判定为未命中。

可能原因

  • 表头差异导致指纹不命中:括号、空格、后缀、全角半角、列序变化都会改变指纹。
  • 模板 status 不是 ONLINE,或 needsStruct=1 的模板无法参与既有匹配。
  • 向量召回不可用,降级后候选池中没有足够相似的模板。
  • 模型返回的 templateNo 越界,被当作未命中。
  • 置信度过低,未能达到 STRONG 档,无法进入出口 A。

排查建议

  1. 检查 ai_clean_template.status 是否为 ONLINE。
  2. 核对 headers 和 header_md5 是否与当前归一化规则一致。
  3. 确认模板是否属于 needsStruct=1,这类模板要求结构归一,不能走既有匹配。
  4. 查看匹配日志中是否走了向量召回,以及召回是否失败。
  5. 检查模型返回的 templateNo 是否在短名单范围内。
  6. 若命中既有模板但置信度低于阈值,只能走出口 B,不能直接写入用户既有业务表。

章节来源

  • AiTemplateMatcher.java:78-200
  • AiTemplateMatcher.java:200-466
  • AiCleanTemplate.java:70-120

2. 字段映射错位

现象
数据能入库,但列内容写到错误列,例如账号写到金额列。

可能原因

  • 表头顺序发生变化,但复用存档 colIndex 时假定列序不变。
  • 模型绑定返回的文件列序号越界或被丢弃。
  • filterBinds 把歧义绑定丢弃,导致该列没有被显式绑定。
  • 自建表场景中,模型只绑定部分列,其余列按原表头顺序保留。

排查建议

  1. 检查 RuleBind.fileColIndex 是否落在实际列数范围内。
  2. 检查 AiTemplateMatcher.filterBinds 是否因相似解析歧义丢弃了绑定。
  3. 复用已有 AI 模板时,优先确认是使用 forStoredTemplate 还是 forStoredTemplateByMapping。
  4. 对比原文件表头与模板 headers,确认列序是否一致。
  5. 对自建表,检查 AiRulePlan.expandedColumnCount 与非空表头数量是否匹配。

章节来源

  • AiTemplateMatcher.java:370-466
  • AiRulePlan.java:200-330

3. 短名冲突

现象
多个模板字段看起来像同一个短名,模型绑定不稳定或后端丢弃绑定。

说明
当前实现中,field_name_en 与 column_name 都固定为 c0、c1 等短名,因此同一模板内不会有短名冲突;跨模板之间也不直接通过 field_name_en 匹配,而是通过候选池序号和模型返回值。

真正的冲突风险来自:

  • 多个模板字段的中文展示名非常接近,相似解析命中多个字段。
  • 同义词库中别名过多,导致归一化后难以区分。
  • 模型返回的绑定名既像字段中文名又像字段英文名,造成歧义。

排查建议

  1. 检查模板字段的 fieldNameCn 是否过于相似。
  2. 检查 ai_clean_synonym 中是否存在大量别名指向同一个标准词。
  3. 查看 filterBinds 的相似解析是否返回 0 个或 ≥2 个命中。
  4. 调整模板字段中文展示名,使其更具区分度。
  5. 不要依赖同义词解决字段名歧义,应优先通过模板字段命名和绑定约束解决。

章节来源

  • AiTemplateMatcher.java:400-466
  • ai_clean_synonym_init.sql:1-42

4. 规则计划类型不匹配

现象
列类型推断错误,例如时间戳被当成数字,金额被当成文本,电话号码被当成普通字符串。

可能原因

  • 模板字段 field_type 为空或未设置,退回到类型推断。
  • 列形状没有命中 PHONE、IDCARD、DATE、DATETIME、TIME、MONEY、ACCT 等强特征。
  • 表头关键词不包含类型提示。
  • 模型返回的 RuleBind.fieldNameEn 也没有帮助推断类型。
  • 13 位 epoch 时间戳被形状判断成长数字,而表头又没明确表达时间语义。

排查建议

  1. 在模板字段中显式设置 field_type。
  2. 在表头中使用明确关键词,如“日期时间”“交易时间”“手机号”“银行卡号”“金额”。
  3. 检查 AiRulePlan.resolveType 的类型来源优先级是否正确生效。
  4. 对时间戳列,确保表头中包含“时间”“时间戳”等语义,避免被误判为数字或卡号。
  5. 对金额列,避免只依赖整数形态;模板字段类型比列形状更可靠。

章节来源

  • AiRulePlan.java:330-479

5. 模板已登记但没有物理表

现象
治理树能看到 AI 模板节点,但打开物理表时报不存在。

可能原因

  • 模板登记成功,但建表和写数失败。
  • 历史模板升级时清理了旧元数据,新物理表尚未重建。
  • 向量索引事件发布失败,但模板登记本身不受影响。

排查建议

  1. 检查 ai_clean_template.status 是否为 ONLINE。
  2. 检查 ai_clean_field 是否有对应字段记录。
  3. 检查 ai_clean_rule 是否有对应规则记录。
  4. 确认物理表名是否符合 ai_clean_{模板ID} 约定。
  5. 不要手动修改 table_info 来绕过该问题,这会污染既有匹配器。

章节来源

  • AiCleanStore.java:54-120
  • AiCleanTemplate.java:24-40

结论

AI 清洗模板与字段映射机制的核心价值在于:

  • 用 ai_clean_template 和 ai_clean_field 替代既有 table_info 和 table_field,避免 AI 判断污染用户模板库。
  • 用 HeaderNormalizer 和 HeaderFingerprint 保证零模型复用的安全性。
  • 用 AiTemplateMatcher 的三腿匹配平衡成本与准确性:指纹直通、归一化打分、模型裁决。
  • 用 RuleBind 表达文件列到模板字段的语义映射,并通过 filterBinds 防造字段、防歧义。
  • 用 AiRulePlan 同时支撑既有 cleaner 和 AI 动态表两套执行路径。
  • 用 Synonym 提升表头评分和绑定成功率,但严格限制其不影响指纹和档位判定。

在实际使用中,最重要的实践是:模板字段类型优先于自动推断,表头语义优先于列形状,模板状态必须为 ONLINE,模型返回的绑定必须经过后端校验。只有同时满足这些条件,清洗模板才能真正稳定地描述目标表结构、字段短名、规则计划和字段映射关系。