同义词管理.md 22 KB

同义词管理

本文引用的文件

  • ai_clean_synonym_init.sql
  • ai_clean.sql
  • AiCleanSynonym.java
  • AiCleanSynonymController.java
  • AiCleanSynonymService.java
  • AiCleanSynonymMapper.java
  • HeaderScorer.java
  • AiTemplateMatcher.java
  • GlobalCache.java
  • HeaderNormalizer.java

目录

  1. 简介
  2. 项目结构中的同义词相关位置
  3. 核心实体与数据表
  4. 初始化脚本的作用
  5. 同义词与模板字段短名的区别
  6. 增删改查接口与服务层逻辑
  7. 同义词在匹配链路中的使用方式
  8. 多用户与多案件隔离策略
  9. 实际使用示例
  10. 常见问题排查
  11. 总结

简介

同义词管理是 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_init.sql:1-42
  • AiCleanSynonymController.java:1-70
  • AiCleanSynonymService.java:1-178
  • AiCleanSynonymMapper.java:1-12
  • GlobalCache.java:180-320
  • HeaderScorer.java:380-520
  • HeaderNormalizer.java:1-66

章节来源

  • ai_clean_synonym_init.sql:1-42
  • ai_clean.sql:150-214
  • AiCleanSynonymController.java:1-70
  • AiCleanSynonymService.java:1-178

核心实体与数据表

数据表结构

表 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
    }

图表来源

  • AiCleanSynonym.java:1-63

数据来源与初始化方式

数据来源有两处:

  1. 数据库建表与内置词条:由 ai_clean.sql 定义 ai_clean_synonym 表结构,并插入一组内置同义词。
  2. 增量初始化脚本:ai_clean_synonym_init.sql 面向已存在的环境,负责建表、迁移硬编码词条到数据库,并使用 on conflict do nothing 避免重复执行报错。

章节来源

  • ai_clean.sql:150-214
  • ai_clean_synonym_init.sql:1-42
  • AiCleanSynonym.java:1-63

初始化脚本的作用

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 会随词条配置漂移,导致零模型直通链路失效。
  • 一个归一化词只能属于一个同义词组,不做链式传递。

章节来源

  • ai_clean_synonym_init.sql:1-42
  • ai_clean.sql:150-214

同义词与模板字段短名的区别

维度 同义词 模板字段短名
主要作用 增强表头识别和语义匹配 作为模板侧的标准命名,决定动态表列名
使用阶段 匹配打分、绑定域过滤 模板定义、动态 DDL、前端展示
是否影响指纹 否 模板表头指纹由标准化后的原始表头决定
典型值 “发生额”→“交易金额”、“卡号”→“账号” c0、c1 等固定短名,或模板字段英文名
生命周期 运行时可增删改,刷新缓存后生效 通常由模板生成或人工维护模板时确定
风险边界 只影响“像不像”,不直接改变写入列名 直接影响数据落库列和业务理解

简单理解:

  • 同义词解决“不同叫法代表同一含义”。
  • 字段短名解决“最终写到哪一列”。

章节来源

  • AiCleanSynonym.java:1-63
  • ai_clean.sql:150-214
  • HeaderScorer.java:380-520

增删改查接口与服务层逻辑

接口概览

控制器 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 承担数据校验、事务处理和缓存重建:

  1. 统一清洗:applyWords 对标准词和别名做空字符串裁剪。
  2. 全局唯一校验:assertWordsFree 确保同一归一化词不能出现在多个组中,防止别名归到两个标准词产生歧义。
  3. 禁止无意义配置:标准词与别名相同会被拒绝;任一列为空也会被拒绝。
  4. 事务提交后刷新缓存:通过 refreshAfterCommit 在事务提交后重建全局缓存;若无事务则立即重建。
  5. 缓存重建失败不影响主流程:异常仅记录日志,旧缓存仍可用。

    flowchart TD
    Start(["调用增删改接口"]) --> Validate["服务层参数校验"]
    Validate --> UniqueCheck["全局唯一性检查"]
    UniqueCheck --> Valid{"校验通过?"}
    Valid -->|否| Error["抛出业务异常"]
    Valid -->|是| Persist["写入数据库"]
    Persist --> Refresh["事务提交后重建全局缓存"]
    Refresh --> End(["返回结果"])
    

图表来源

  • AiCleanSynonymController.java:1-70
  • AiCleanSynonymService.java:1-178

同义词分组、别名与标准字段的关系

  • 星型结构:一个标准词可以对应多个别名,但一个别名只能归属一个标准词。
  • 别名:来自业务文件表头,比如“发生额”“交易额”“金额”。
  • 标准词:系统内部统一的概念,比如“交易金额”“户名”“身份证号”。
  • 模板字段:模板有自己的中文名称和英文短名,但这些名称不参与同义词组的唯一性校验。

章节来源

  • AiCleanSynonymService.java:1-178
  • AiCleanSynonymController.java:1-70

同义词在匹配链路中的使用方式

全局缓存中的同义词映射

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
    

图表来源

  • AiCleanSynonymController.java:1-70
  • AiCleanSynonymService.java:140-178
  • GlobalCache.java:180-320
  • AiCleanSynonymMapper.java:1-12

表头打分中的使用

HeaderScorer.canonicalForScore 是关键入口:

  1. 先对原始表头调用 HeaderNormalizer.normalize。
  2. 再查 GlobalCache.synonymMap()。
  3. 如果别名命中,则替换为标准词;否则保持原归一化结果。
  4. 所有模板列、字段中文名、字段英文名在打分时都会走这条路径。

这意味着:当文件表头出现“发生额”时,打分层可将其视为“交易金额”,从而提高模板命中率。

flowchart TD
    RawHeader["原始表头<br/>例如:发生额"] --> Normalize["HeaderNormalizer.normalize"]
    Normalize --> Canonical["canonicalForScore"]
    Canonical --> SynonymCheck{"别名命中同义词?"}
    SynonymCheck -->|是| StdWord["替换为标准词<br/>例如:交易金额"]
    SynonymCheck -->|否| Keep["保持归一化结果"]
    StdWord --> Score["参与表头打分与覆盖率计算"]
    Keep --> Score

图表来源

  • HeaderScorer.java:380-520
  • GlobalCache.java:180-320
  • HeaderNormalizer.java:1-66

绑定域解析中的使用

AiTemplateMatcher.filterBinds 在使用模型返回的绑定域时,也会基于同义词进行过滤和匹配。这样即使模型返回的字段名与模板字段名不完全一致,只要在同义词归一后能对齐,就能提高绑定成功率。

章节来源

  • HeaderScorer.java:380-520
  • AiTemplateMatcher.java:1-200
  • GlobalCache.java:180-320

多用户与多案件隔离策略

从当前实现看,ai_clean_synonym 表没有按用户或案件分片:

  • 表中没有 case_id、user_id 等隔离字段。
  • 服务层也没有在查询或写入时加入用户/案件条件。
  • 全局缓存 GlobalCache.synonymMap() 是进程级共享的静态快照。
  • 控制器也没有从上下文取案件或用户信息来限制词条范围。

因此,当前同义词是全局共享的:同一系统中所有用户、所有案件的 AI 清洗匹配都使用同一份同义词映射。

这带来两个重要结论:

  1. 优点:业务通用术语(如“账号”“手机号”“交易金额”)只需维护一次,所有案件都能受益。
  2. 风险:某个用户误配了冲突别名,会影响其他用户;业务专属别名也可能跨案件干扰匹配。

若未来需要按案件或用户隔离,需要在表结构、查询、缓存构建和权限控制上同步改造。

章节来源

  • AiCleanSynonym.java:1-63
  • AiCleanSynonymService.java:1-178
  • GlobalCache.java:180-320

实际使用示例

添加同义词

场景:某银行流水使用“发生额”表示交易金额,但模板标准词是“交易金额”。

建议步骤:

  1. 调用 /aiClean/synonym/create,传入:
    • stdWord: “交易金额”
    • aliasWord: “发生额”
    • remark: “XX 银行流水金额别名”
  2. 后端校验标准词与别名不为空、不相同、且不与其他组冲突。
  3. 写入成功后,事务提交触发全局缓存重建。
  4. 之后上传该银行流水时,“发生额”可被识别为“交易金额”,提升匹配分数。

注意:不要给“发生额”同时配置另一个标准词,否则会触发“一个词只能属于一个组”的错误。

批量导入

当前控制器只提供单条 create 接口,没有专用批量导入接口。若需批量导入,可在前端或服务层循环调用 create,或自行扩展批量接口。

注意事项:

  • 每条记录都要经过唯一性校验。
  • 批量操作应避免反复重建缓存;适合在服务层封装一次事务、多次写库、最后重建缓存。
  • 导入前应先调用 /aiClean/synonym/list 检查是否存在冲突别名。

查询生效范围

可以通过以下方式确认同义词是否生效:

  1. 调用 /aiClean/synonym/list,确认新词条已入库且 status = 1。
  2. 等待全局缓存重建完成。
  3. 重新上传使用该别名的文件,观察是否更接近目标模板。
  4. 若未生效,检查是否触发了缓存重建失败日志,或是否误设为停用。

章节来源

  • AiCleanSynonymController.java:1-70
  • AiCleanSynonymService.java:1-178
  • GlobalCache.java:180-320

常见问题排查

新增同义词未生效

可能原因:

  • 缓存尚未重建完成。
  • 词条被设置为停用。
  • 标准词或别名被归一化为空字符串。
  • 标准词与别名相同,被服务层拒绝。
  • 全局缓存重建失败,但主流程继续运行,旧缓存继续使用。

排查建议:

  1. 调用 /aiClean/synonym/list 确认词条存在且启用。
  2. 检查应用日志中是否有“重建全局缓存失败”的记录。
  3. 确认别名不是纯空格、括号、标点等会被清理为空的内容。
  4. 重新启动或等待下一次缓存刷新。

章节来源

  • AiCleanSynonymService.java:140-178
  • GlobalCache.java:180-320

别名冲突

表现:新增时报错“词已存在于同义词组”。

原因:

  • 同一归一化别名已经属于另一个标准词。
  • 标准词本身已作为别名出现在其他词条中。
  • 归一化后两个词相等,例如都去掉后缀、括号和空白后相同。

处理建议:

  • 使用 /aiClean/synonym/list 搜索冲突词。
  • 将冲突别名改为更具体的业务表达,例如“对方账号”而不是“账号”。
  • 不要试图把一个通用别名同时映射到多个标准词。

章节来源

  • AiCleanSynonymService.java:100-139

初始化脚本重复执行

现象:再次执行 ai_clean_synonym_init.sql 时报主键或唯一索引冲突。

解决方案:

  • 使用官方提供的 ai_clean_synonym_init.sql,其使用 on conflict (std_word, alias_word) do nothing,正常情况不会因重复执行报错。
  • 如果是旧版本脚本或手动拼接的 insert,请改用带冲突忽略的版本。
  • 若确实出现重复数据,可通过 SQL 去重后再执行初始化脚本。

章节来源

  • ai_clean_synonym_init.sql:1-42

同义词未参与匹配

可能原因:

  1. 同义词未启用。
  2. 全局缓存未刷新。
  3. 别名被归一化后无法匹配。
  4. 模板本身与该文件差异过大,仍需模型裁决。
  5. 同义词改变了模板指纹预期,但指纹直通依赖的是 header_md5,同义词不应改变指纹。

排查建议:

  • 确认 status = 1。
  • 确认缓存重建日志中无持续错误。
  • 检查别名是否与模板标准词在同一业务含义范围内。
  • 查看匹配结果是否进入模型裁决阶段:同义词提升的是相似度,不一定保证零模型直通。

章节来源

  • HeaderScorer.java:1-120
  • HeaderScorer.java:380-520
  • ai_clean.sql:150-214

总结

同义词管理的本质是在 AI 清洗匹配阶段引入一层“语义对齐”:让不同来源的文件表头能够以不同别名命中同一标准概念。它通过 ai_clean_synonym 表存储、AiCleanSynonymController 暴露接口、AiCleanSynonymService 做校验与事务控制、GlobalCache 提供进程级快照、HeaderScorer 和 AiTemplateMatcher 在匹配链路中使用。

使用时要牢记三条纪律:

  1. 同义词用于增强匹配,不改变模板字段短名。
  2. 一个归一化词只能属于一个组,不做链式传递。
  3. 同义词不参与指纹计算,避免存量模板 header_md5 漂移。

当前实现是全局共享的同义词库,适合通用业务术语;若未来需要按案件或用户隔离,需要扩展表结构、查询条件和缓存构建逻辑。