本文引用的文件
同义词管理是 AI 数据清洗中用于增强“表头识别”和“语义匹配”的基础设施。它的核心思想是:同一个业务含义可以用多种列头表达,例如“交易金额”“发生额”“金额”都指向同一标准含义。系统通过维护“别名 → 标准词”的星型词组,让不同来源、不同格式的文件表头更容易命中既有模板或 AI 模板。
需要特别区分的是:同义词不是模板字段的标准命名。模板字段短名(如 field_name_en)决定最终动态表的列名;同义词只是帮助系统在匹配阶段判断“这个表头是不是我们要的那一列”。
同义词功能贯穿数据库、控制器、服务层、缓存、匹配器和归一化工具类:
graph TB
SQL["初始化脚本<br/>ai_clean_synonym_init.sql"] --> DB["数据表 ai_clean_synonym"]
Controller["AiCleanSynonymController"] --> Service["AiCleanSynonymService"]
Service --> Mapper["AiCleanSynonymMapper"]
Service --> Cache["GlobalCache.initCache()"]
Cache --> Match["HeaderScorer / AiTemplateMatcher"]
Match --> Normalizer["HeaderNormalizer"]
图表来源
章节来源
表 ai_clean_synonym 保存“别名 → 标准词”的映射,关键字段如下:
| 字段 | 类型 | 含义 | 约束/说明 |
|---|---|---|---|
id |
bigint | 主键 | 自分配 ID |
std_word |
varchar(100) | 标准词 | 组内规范形式,例如“交易金额” |
alias_word |
varchar(100) | 别名 | 业务文件中可能出现的列头,例如“发生额” |
remark |
varchar(200) | 备注 | 便于记录词条来源、所属业务域 |
status |
smallint | 启用状态 | 1 表示启用,0 表示停用 |
create_by |
bigint | 创建人 | 用户标识 |
create_time |
timestamp | 创建时间 | 默认当前时间 |
update_time |
timestamp | 更新时间 | 修改时更新 |
唯一索引 (std_word, alias_word) 保证同一标准词与别名的组合不重复。
Java 实体 AiCleanSynonym 与表字段一一对应,并包含关键注释:
classDiagram
class AiCleanSynonym {
+Long id
+String stdWord
+String aliasWord
+String remark
+Integer status
+Long createBy
+LocalDateTime createTime
+LocalDateTime updateTime
}
图表来源
数据来源有两处:
ai_clean.sql 定义 ai_clean_synonym 表结构,并插入一组内置同义词。ai_clean_synonym_init.sql 面向已存在的环境,负责建表、迁移硬编码词条到数据库,并使用 on conflict do nothing 避免重复执行报错。章节来源
ai_clean_synonym_init.sql该脚本的核心目标是:
ai_clean_synonym 表。on conflict (std_word, alias_word) do nothing 保证脚本可重复执行。/aiClean/synonym 接口完成,改完后自动刷新全局缓存,无需重启。ai_clean.sql 中的作用ai_clean.sql 是 AI 清洗链路的元数据建表总入口,其中也定义了 ai_clean_synonym 表和内置词条。它强调的关键设计是:
HeaderFingerprint 指纹计算。header_md5 会随词条配置漂移,导致零模型直通链路失效。章节来源
| 维度 | 同义词 | 模板字段短名 |
|---|---|---|
| 主要作用 | 增强表头识别和语义匹配 | 作为模板侧的标准命名,决定动态表列名 |
| 使用阶段 | 匹配打分、绑定域过滤 | 模板定义、动态 DDL、前端展示 |
| 是否影响指纹 | 否 | 模板表头指纹由标准化后的原始表头决定 |
| 典型值 | “发生额”→“交易金额”、“卡号”→“账号” | c0、c1 等固定短名,或模板字段英文名 |
| 生命周期 | 运行时可增删改,刷新缓存后生效 | 通常由模板生成或人工维护模板时确定 |
| 风险边界 | 只影响“像不像”,不直接改变写入列名 | 直接影响数据落库列和业务理解 |
简单理解:
章节来源
控制器 AiCleanSynonymController 暴露以下 REST 接口:
| 方法 | 路径 | 请求体 | 返回 | 行为 |
|---|---|---|---|---|
| GET | /aiClean/synonym/list |
无 | 同义词列表 | 返回全部词条,含停用项,按标准词排序 |
| POST | /aiClean/synonym/create |
同义词对象 | 新增后的同义词 | 补全创建人,校验并插入 |
| POST | /aiClean/synonym/update |
同义词对象 | 更新后的同义词 | 根据 ID 更新标准词、别名、备注、状态 |
| POST | /aiClean/synonym/delete |
同义词对象 | 成功响应 | 传入 id 删除对应词条 |
| POST | /aiClean/synonym/toggle |
同义词对象 | 成功响应 | 启用或停用指定词条 |
服务层 AiCleanSynonymService 承担数据校验、事务处理和缓存重建:
applyWords 对标准词和别名做空字符串裁剪。assertWordsFree 确保同一归一化词不能出现在多个组中,防止别名归到两个标准词产生歧义。refreshAfterCommit 在事务提交后重建全局缓存;若无事务则立即重建。缓存重建失败不影响主流程:异常仅记录日志,旧缓存仍可用。
flowchart TD
Start(["调用增删改接口"]) --> Validate["服务层参数校验"]
Validate --> UniqueCheck["全局唯一性检查"]
UniqueCheck --> Valid{"校验通过?"}
Valid -->|否| Error["抛出业务异常"]
Valid -->|是| Persist["写入数据库"]
Persist --> Refresh["事务提交后重建全局缓存"]
Refresh --> End(["返回结果"])
图表来源
章节来源
GlobalCache 维护一个 synonymMap,键是归一化后的别名,值是归一化后的标准词。加载规则如下:
status = 1 的启用词条。HeaderNormalizer.normalize。查询失败时保留旧快照,不污染模板主缓存。
sequenceDiagram
participant Admin as "管理员"
participant Controller as "AiCleanSynonymController"
participant Service as "AiCleanSynonymService"
participant Mapper as "AiCleanSynonymMapper"
participant Cache as "GlobalCache"
participant Matcher as "HeaderScorer / AiTemplateMatcher"
Admin->>Controller: 调用增删改接口
Controller->>Service: 执行业务方法
Service->>Mapper: 写入 ai_clean_synonym
Service->>Cache: initCache()
Cache->>Mapper: 查询启用的同义词
Mapper-->>Cache: 同义词列表
Cache-->>Matcher: 提供 synonymMap
图表来源
HeaderScorer.canonicalForScore 是关键入口:
HeaderNormalizer.normalize。GlobalCache.synonymMap()。这意味着:当文件表头出现“发生额”时,打分层可将其视为“交易金额”,从而提高模板命中率。
flowchart TD
RawHeader["原始表头<br/>例如:发生额"] --> Normalize["HeaderNormalizer.normalize"]
Normalize --> Canonical["canonicalForScore"]
Canonical --> SynonymCheck{"别名命中同义词?"}
SynonymCheck -->|是| StdWord["替换为标准词<br/>例如:交易金额"]
SynonymCheck -->|否| Keep["保持归一化结果"]
StdWord --> Score["参与表头打分与覆盖率计算"]
Keep --> Score
图表来源
AiTemplateMatcher.filterBinds 在使用模型返回的绑定域时,也会基于同义词进行过滤和匹配。这样即使模型返回的字段名与模板字段名不完全一致,只要在同义词归一后能对齐,就能提高绑定成功率。
章节来源
从当前实现看,ai_clean_synonym 表没有按用户或案件分片:
case_id、user_id 等隔离字段。GlobalCache.synonymMap() 是进程级共享的静态快照。因此,当前同义词是全局共享的:同一系统中所有用户、所有案件的 AI 清洗匹配都使用同一份同义词映射。
这带来两个重要结论:
若未来需要按案件或用户隔离,需要在表结构、查询、缓存构建和权限控制上同步改造。
章节来源
场景:某银行流水使用“发生额”表示交易金额,但模板标准词是“交易金额”。
建议步骤:
/aiClean/synonym/create,传入:
stdWord: “交易金额”aliasWord: “发生额”remark: “XX 银行流水金额别名”注意:不要给“发生额”同时配置另一个标准词,否则会触发“一个词只能属于一个组”的错误。
当前控制器只提供单条 create 接口,没有专用批量导入接口。若需批量导入,可在前端或服务层循环调用 create,或自行扩展批量接口。
注意事项:
/aiClean/synonym/list 检查是否存在冲突别名。可以通过以下方式确认同义词是否生效:
/aiClean/synonym/list,确认新词条已入库且 status = 1。章节来源
可能原因:
排查建议:
/aiClean/synonym/list 确认词条存在且启用。章节来源
表现:新增时报错“词已存在于同义词组”。
原因:
处理建议:
/aiClean/synonym/list 搜索冲突词。章节来源
现象:再次执行 ai_clean_synonym_init.sql 时报主键或唯一索引冲突。
解决方案:
ai_clean_synonym_init.sql,其使用 on conflict (std_word, alias_word) do nothing,正常情况不会因重复执行报错。insert,请改用带冲突忽略的版本。章节来源
可能原因:
header_md5,同义词不应改变指纹。排查建议:
status = 1。章节来源
同义词管理的本质是在 AI 清洗匹配阶段引入一层“语义对齐”:让不同来源的文件表头能够以不同别名命中同一标准概念。它通过 ai_clean_synonym 表存储、AiCleanSynonymController 暴露接口、AiCleanSynonymService 做校验与事务控制、GlobalCache 提供进程级快照、HeaderScorer 和 AiTemplateMatcher 在匹配链路中使用。
使用时要牢记三条纪律:
header_md5 漂移。当前实现是全局共享的同义词库,适合通用业务术语;若未来需要按案件或用户隔离,需要扩展表结构、查询条件和缓存构建逻辑。