清洗模板向量索引.md 27 KB

清洗模板向量索引

本文引用的文件

  • AiCleanTemplateVectorIndex.java
  • AiCleanVectorProperties.java
  • AiTemplateMatcher.java
  • HeaderScorer.java
  • ai-template-vector-index.md

目录

  1. 引言
  2. 项目结构定位
  3. 核心组件职责
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与扩展性
  8. 配置、重建与验证示例
  9. 常见问题排查
  10. 结论

引言

本文件聚焦 AI 数据清洗中的“清洗模板向量索引”,说明其如何把两套模板库的结构元数据向量化并写入 pgvector,再参与模板匹配候选召回。重点覆盖以下问题:

  • AiCleanTemplateVectorIndex 与 AiCleanVectorProperties 的职责边界;
  • 模板如何进入向量索引,以及检索结果如何影响后续 LLM 裁决;
  • 与 AiTemplateMatcher、HeaderScorer 的协同方式;
  • 构建时机、刷新策略、元数据字段、相似度阈值与回退逻辑;
  • 配置项、重建接口、效果验证方法;
  • 向量索引与传统规则匹配的优先级关系;
  • 模板数量增长时的性能影响;
  • 常见故障与降级行为。

该能力是“增强型召回”:向量不可用时,主流程仍按指纹、打分和模型三腿继续运行,不会阻断上传或清洗。

章节来源

  • ai-template-vector-index.md:1-139

项目结构定位

向量索引位于 ai-server 模块的 aiclean/index 包下,主要代码集中在两个 Java 类中:

  • AiCleanTemplateVectorIndex:负责索引构建、增量更新、全量重建、语义召回、表结构检索、状态观测和事件监听。
  • AiCleanVectorProperties:封装 Spring 配置属性,控制开关、自动增量、topK、相似度阈值、重建上限和启动自举。

它与匹配层(aiclean/match)通过 AiTemplateMatcher.mergeRecall 协作;与传统规则打分器 HeaderScorer 并行存在,但向量召回不参与确定性档位判定。

graph TB
    subgraph "AI 清洗匹配层"
        Matcher["AiTemplateMatcher<br/>三腿匹配"]
        Scorer["HeaderScorer<br/>传统规则打分"]
    end

    subgraph "向量索引层"
        Index["AiCleanTemplateVectorIndex<br/>索引/召回/检索/事件"]
        Props["AiCleanVectorProperties<br/>配置"]
    end

    subgraph "外部存储与服务"
        PG["PostgreSQL + pgvector"]
        Embed["EmbeddingProvider<br/>本地/在线嵌入模型"]
    end

    Props --> Index
    Matcher --> Index
    Matcher --> Scorer
    Index --> PG
    Index --> Embed

图表来源

  • AiCleanTemplateVectorIndex.java:1-200
  • AiCleanVectorProperties.java:1-57
  • AiTemplateMatcher.java:1-200
  • HeaderScorer.java:1-200

章节来源

  • AiCleanTemplateVectorIndex.java:1-200
  • AiCleanVectorProperties.java:1-57

核心组件职责

AiCleanTemplateVectorIndex

它是向量索引的统一入口,承担以下职责:

  1. 可用性判断:根据配置与嵌入模型是否可用返回 isAvailable(),并提供不可用原因。
  2. 增量索引:监听 TemplateMetaChangedEvent,对既有模板与 AI 模板执行异步增删改。
  3. 全量重建:提供同步与异步重建,DROP 后重写两套模板库的全部文档,支持连续失败熔断。
  4. 向量召回:recall(queryText, topK) 返回模板 ID 与分数,用于提升候选排序。
  5. 表结构检索:searchTables(queryText, topK) 返回物理表名与字段清单,供 Agent 生成 SQL。
  6. 状态观测:status() 暴露向量表名、维度、文档数等运维信息。
  7. 失败保护:所有关键路径 fail-open,不抛异常给调用方。

AiCleanVectorProperties

它定义 zsjz.ai-clean.vector 命名空间下的配置项: | 配置项 | 默认值 | 含义 | |---|---:|---| | enabled | true | 向量索引总开关 | | autoIndexOnTemplateChange | true | 模板变更时是否自动增量更新 | | topK | 12 | 向量召回条数上限 | | scoreThreshold | 0.30 | pgvector cosine 转 score 后的召回门槛 | | maxDocumentsPerRebuild | 5000 | 单次全量重建最大文档数 | | autoRebuildOnStartup | true | 启动时若索引不存在或为空则后台重建一次 |

这些配置共同决定向量链路是“开启且增强”、“仅观察”还是“完全关闭”。

章节来源

  • AiCleanTemplateVectorIndex.java:1-200
  • AiCleanVectorProperties.java:1-57

架构总览

向量索引统一消费两套模板元数据:

  • 既有模板库:table_info + table_field
  • AI 模板库:ai_clean_template + ai_clean_field

它们被写进一张全局 pgvector 表,表名形式为 rag_tpl{tag}_d{dims},其中:

  • {dims} 来自当前嵌入模型维度;
  • {tag} 由嵌入模型表标签决定,区分本地模型与在线模型,避免不同模型共用同一张向量表。

    sequenceDiagram
    participant Source as "模板元数据源"
    participant Event as "模板变更事件"
    participant Index as "AiCleanTemplateVectorIndex"
    participant Embed as "EmbeddingProvider"
    participant PG as "pgvector 表"
    participant Matcher as "AiTemplateMatcher"
    
    Source->>Event: 模板新增/更新/删除
    Event->>Index: onTemplateMetaChanged(...)
    Index->>Index: 异步提交单线程任务
    Index->>Embed: 检查可用性与维度
    Embed-->>Index: 可用 / 不可用
    Index->>PG: 建表/插入/更新/删除 doc_id
    Note over Index,PG: 既有模板 t:{id},AI 模板 a:{id}
    
    Matcher->>Index: recall(主块表头, topK)
    Index->>Embed: 将查询文本向量化
    Index->>PG: cosine 相似度检索
    PG-->>Index: 命中列表 {templateId/aiTemplateId, score}
    Index-->>Matcher: VectorHit 列表
    Matcher->>Matcher: 只提升排序,不改判档
    

图表来源

  • AiCleanTemplateVectorIndex.java:201-526
  • AiTemplateMatcher.java:201-466
  • ai-template-vector-index.md:20-40

章节来源

  • ai-template-vector-index.md:1-139
  • AiCleanTemplateVectorIndex.java:201-526

详细组件分析

向量索引的数据模型与元数据字段

向量索引并不直接保存业务对象,而是构造三类内部表示:

  • VectorDoc:待写入 pgvector 的单篇文档,包含 doc_id、content、payloadJson。
  • FieldBrief:字段摘要,包含物理列名、语义英文名、中文名、类型、是否必填。
  • VectorHit:召回结果,包含模板来源、对应 ID 和相似度分数。

pgvector 表中的核心字段如下: | 字段 | 含义 | 说明 | |---|---|---| | doc_id | 文档主键 | 既有模板为 t:{table_info.id},AI 模板为 a:{ai_clean_template.id} | | content | 嵌入原文 | 模板类型、中英文表名、表头、字段清单 | | payload | JSONB 元数据 | 模板来源、ID、表名、主表 ID、表头、字段、分类 | | embedding | 向量列 | 维度等于当前嵌入模型维度 |

payload 中两类模板的字段略有差异:

  • 既有模板使用 templateId、mainId;
  • AI 模板使用 aiTemplateId、mainId 为 null;
  • 两者都包含 headers[] 和 fields[],字段包含 name、en、cn、type、required。

    classDiagram
    class VectorDoc {
        +string docId
        +string content
        +string payloadJson
    }
    
    class FieldBrief {
        +string name
        +string en
        +string cn
        +string type
        +boolean required
    }
    
    class VectorHit {
        +string kind
        +Integer templateId
        +Long aiTemplateId
        +double score
    }
    
    class TableSchemaHit {
        +string tableName
        +List~ColumnHit~ columns
        +double score
    }
    
    class ColumnHit {
        +string name
        +string en
        +string cn
        +string type
        +boolean required
    }
    
    VectorDoc --> FieldBrief : "构建 content/payload"
    VectorHit --> VectorDoc : "解析 payload"
    TableSchemaHit --> VectorDoc : "解析 payload"
    

图表来源

  • AiCleanTemplateVectorIndex.java:601-924

章节来源

  • AiCleanTemplateVectorIndex.java:601-924

模板如何向量化并进入检索链路

构建内容时,索引会把模板类型、中英文表名、表头和字段清单拼接成自然语言风格的 content。这样,查询文本(例如主表块表头)与文档文本在 embedding 空间中具有可比性。

具体构建过程可概括为:

  1. 读取模板及字段;
  2. 过滤无字段模板;
  3. 组装 FieldBrief 列表;
  4. 组装 payload;
  5. 拼接 content;
  6. 通过 EmbeddingProvider 获取维度并写入 pgvector。

    flowchart TD
    Start(["开始"]) --> Load["加载模板与字段"]
    Load --> FilterEmpty{"是否有字段?"}
    FilterEmpty -->|否| Skip["跳过该模板"]
    FilterEmpty -->|是| BuildFields["构建字段摘要"]
    BuildFields --> BuildPayload["构建 payload JSON"]
    BuildPayload --> BuildContent["拼接嵌入原文"]
    BuildContent --> Embed["向量化 content"]
    Embed --> Write["写入 pgvector 表"]
    Write --> End(["完成"])
    Skip --> End
    

图表来源

  • AiCleanTemplateVectorIndex.java:601-924

章节来源

  • AiCleanTemplateVectorIndex.java:601-924

与 AiTemplateMatcher 的协同

AiTemplateMatcher 是三条腿的模板匹配器:

  1. 指纹直通;
  2. 归一化打分;
  3. 模型裁决。

向量索引只在第三步之前介入,调用 mergeRecall 做两件事:

  • 从主表块表头构造查询文本;
  • 调用 AiCleanTemplateVectorIndex.recall 获取候选;
  • 对命中的候选,将其排序分数提升为 max(headerScore, vectorScore);
  • 整体重新降序排列;
  • 最终只把 top-K 候选送给 LLM。

关键点:向量召回只改变候选顺序,不参与出口 A/B 判定。即使向量分很高,也不能让一个原本不够确定的候选直接进入既有业务表。

flowchart TD
    Step1["指纹直通"] -->|命中| ExitA["出口 A:强匹配"]
    Step1 --> Step2["归一化打分"]
    Step2 -->|强匹配| ExitA
    Step2 --> Step3["向量召回"]
    Step3 --> Merge["融合分数:取 header 分与向量分较大者"]
    Merge --> Sort["重新按融合分排序"]
    Sort --> ShortList["截取 top-K 送模型"]
    ShortList --> LLM["LLM 裁决"]
    LLM --> Tier{"置信度与确定性"}
    Tier -->|STRONG+强确定性| ExitA
    Tier -->|弱或不确定| ExitB

图表来源

  • AiTemplateMatcher.java:201-466

章节来源

  • AiTemplateMatcher.java:201-466

与 HeaderScorer 的协同

HeaderScorer 是传统规则打分器,负责基于表头集合、字段名、列序、形状和必填覆盖计算确定性分数。它不关心向量索引,也不依赖 pgvector。

两者的分工很清晰:

  • HeaderScorer 负责“能不能稳准地判定”;
  • 向量索引负责“让 LLM 更容易看到正确候选”。

当向量召回命中某个候选时,AiTemplateMatcher 会把它在排序中的位置前移,从而增加 LLM 选中它的概率。但最终是否出口 A,仍需满足:

  • 档位为 STRONG;
  • 确定性分数达到 HeaderScorer.STRONG;
  • 必填字段全覆盖;
  • 数据类型形状无明显矛盾;
  • 文件侧覆盖率不低于 FILE_COVERAGE_MIN。

这意味着:向量召回可以“拉高热度”,但不能“代替硬规则”。

章节来源

  • HeaderScorer.java:1-200
  • HeaderScorer.java:201-555
  • AiTemplateMatcher.java:201-466

构建时机与刷新策略

向量索引支持三种构建路径:

场景 触发方式 行为
模板新增/更新/删除 TemplateMetaChangedEvent 异步增量索引或删除
应用启动 ApplicationReadyEvent 若启用且可用、向量表不存在或为空,则后台全量重建
运维操作 /js/a/aiClean/templateVector/rebuild 同步全量重建,返回写入文档数

增量索引使用单线程守护线程池,保证同一进程内增量任务串行执行,避免同 doc_id 并发写或重复建表。全量重建使用独立互斥锁,防止两个 rebuild 同时 DROP 向量表。

stateDiagram-v2
    [*] --> 未构建
    未构建 --> 已构建 : "rebuildNow() 成功"
    已构建 --> 已构建 : "模板变更增量更新"
    已构建 --> 已构建 : "启动自举补建"
    已构建 --> 已构建 : "手动重建"
    未构建 --> 未构建 : "索引不可用/空查询"

图表来源

  • AiCleanTemplateVectorIndex.java:201-526

章节来源

  • AiCleanTemplateVectorIndex.java:201-526
  • ai-template-vector-index.md:40-80

相似度阈值与回退逻辑

相似度阈值

  • 阈值由 AiCleanVectorProperties.scoreThreshold 控制,默认 0.30。
  • 该阈值作用于 pgvector 的 cosine 相似度结果,低于阈值的记录不会被返回。
  • 阈值过低会引入无关模板,增大提示词噪声;阈值过高可能错过“列名同义不同词”的模板,而这正是向量召回要弥补的场景。

回退逻辑

整个链路遵循 fail-open:

  1. 如果 enabled=false,不调用向量索引。
  2. 如果嵌入模型不可用,recall 和 searchTables 返回空列表。
  3. 如果向量表不存在,视为尚未构建,不报错。
  4. 如果嵌入向量生成失败,视为无召回。
  5. 如果 pgvector 查询异常,捕获后记录日志并按空结果处理。
  6. 全量重建连续失败达到阈值(默认 5 次)后中止,避免刷屏。

因此,pgvector 不可用或模型不可用不会中断上传、清洗或模板识别主流程。

章节来源

  • AiCleanVectorProperties.java:1-57
  • AiCleanTemplateVectorIndex.java:201-526
  • ai-template-vector-index.md:80-120

依赖关系分析

向量索引对外部系统的依赖主要包括:

  • EmbeddingProvider:负责本地或在线嵌入模型的可用性、维度、表标签和实际向量化。
  • RagVectorMapper:负责 pgvector 表的建表、删表、计数、搜索和写入。
  • 模板与字段 Mapper:读取 table_info、table_field、ai_clean_template、ai_clean_field。
  • Spring 事件机制:接收 TemplateMetaChangedEvent。
  • Spring 生命周期:监听 ApplicationReadyEvent。

    graph LR
    Properties["AiCleanVectorProperties"] --> Index["AiCleanTemplateVectorIndex"]
    Embed["EmbeddingProvider"] --> Index
    VectorMapper["RagVectorMapper"] --> Index
    TableInfo["TableInfoMapper"] --> Index
    TableField["TableFieldMapper"] --> Index
    TemplateMapper["AiCleanTemplateMapper"] --> Index
    FieldMapper["AiCleanFieldMapper"] --> Index
    Matcher["AiTemplateMatcher"] --> Index
    

图表来源

  • AiCleanTemplateVectorIndex.java:1-200

章节来源

  • AiCleanTemplateVectorIndex.java:1-200

性能与扩展性

时间复杂度与空间复杂度

  • 全量重建读取两套模板库元数据,时间复杂度大致为 O(T+F+A),其中 T 是既有模板数,F 是既有字段数,A 是 AI 模板数。
  • 构建 content 和 payload 与字段数量线性相关。
  • 向量检索时间复杂度取决于 pgvector 底层实现,通常远小于遍历全部模板。
  • 内存方面,全量重建会先装配完整文档列表,再通过 maxDocumentsPerRebuild 截断,避免一次性打爆内存。

模板数量增长的影响

  • 传统规则打分仍需要对候选池进行排序,模板增多会使候选池变大。
  • 向量召回可以把真正相关的模板提前,减少 LLM 需要处理的短名单长度。
  • 如果 topK 过大,召回结果过多可能反而稀释真实候选;默认 12 与 LLM 短名单一致,避免把太多噪声塞进提示词。
  • 如果模板库异常膨胀,应关注 maxDocumentsPerRebuild,必要时调大上限,并结合分页或增量重建策略。

并发与一致性

  • 增量索引异步串行,避免重复建表和竞态写。
  • 全量重建有互斥锁,防止两个 rebuild 同时 DROP 表。
  • 索引最终一致:模板变更后极短时间窗口内可能检索不到,但指纹和打分腿仍可工作。

章节来源

  • AiCleanTemplateVectorIndex.java:201-526
  • AiCleanTemplateVectorIndex.java:601-924
  • AiTemplateMatcher.java:201-466

配置、重建与验证示例

配置示例

建议在 application.yaml 中配置:

zsjz:
  embedding:
    enabled: true
    model-path: bge-m3
    dimensions: 1024

  ai-clean:
    vector:
      enabled: true
      auto-index-on-template-change: true
      auto-rebuild-on-startup: true
      top-k: 12
      score-threshold: 0.30
      max-documents-per-rebuild: 5000
配置段 推荐值 调整建议
enabled true 灰度阶段可先关闭,确认主流程不受影响
autoIndexOnTemplateChange true 生产环境建议开启,降低人工维护成本
autoRebuildOnStartup true 首次部署或升级后自动补建存量模板
topK 12 模板库很大时可保持;过小可能召回不足
scoreThreshold 0.30 太低会增加噪声,太高可能漏召回同义词
maxDocumentsPerRebuild 5000 模板库超过此数时需调大

章节来源

  • AiCleanVectorProperties.java:1-57
  • ai-template-vector-index.md:80-120

重建索引示例

  1. 调用 POST /js/a/aiClean/templateVector/rebuild。
  2. 成功后,系统会重建当前嵌入模型对应的向量表。
  3. 可通过 GET /js/a/aiClean/templateVector/status 查看:
    • 是否可用;
    • 向量表名;
    • 嵌入模型名称;
    • 维度;
    • 文档数量。

注意:

  • 重建是运维动作,异常会通过日志和状态接口暴露;
  • 异步重建不会阻塞接口调用;
  • 同步重建抛出 ServerException,调用方不应期望正常返回写入结果。

章节来源

  • ai-template-vector-index.md:100-120
  • AiCleanTemplateVectorIndex.java:201-526

验证匹配效果示例

  1. 确保向量索引已构建:
    • 检查状态接口返回 available=true;
    • 检查向量表文档数等于“有字段的既有模板 + 有字段的 AI 模板”数量。
  2. 新建或更新一份 AI 模板,确认增量事件触发后文档数增加。
  3. 上传一份表头与目标模板相似的 CSV,观察:
    • 若指纹或打分命中,仍走前两腿;
    • 若进入第三腿,确认向量召回是否把目标模板排到短名单前列;
    • 若模型最终选择该模板,说明召回有效提升了候选可见性。
  4. 若 pgvector 不可用,应观察到:
    • 向量召回为空;
    • 匹配仍可能通过指纹、打分或模型完成;
    • 日志中出现降级提示。

章节来源

  • AiTemplateMatcher.java:201-466
  • ai-template-vector-index.md:100-139

常见问题排查

向量索引缺失

现象:search_table_schema 返回空或提示索引为空;模板匹配没有向量召回。
可能原因:

  • 未调用重建接口;
  • autoRebuildOnStartup=false;
  • 启动自举条件不满足;
  • 向量表不存在或为空。

处理:

  • 调用重建接口;
  • 检查 status 接口;
  • 确认 zsjz.ai-clean.vector.auto-rebuild-on-startup=true;
  • 确认模板确实有字段。

章节来源

  • AiCleanTemplateVectorIndex.java:201-526
  • ai-template-vector-index.md:40-80

相似度阈值过高或过低

现象:

  • 阈值过高:同名不同词的模板无法召回;
  • 阈值过低:无关模板进入短名单,干扰模型判断。

处理:

  • 观察向量召回日志;
  • 适当下调 scoreThreshold 以扩大召回范围;
  • 或上调以缩小噪声;
  • 配合 topK 调整短名单规模。

章节来源

  • AiCleanVectorProperties.java:1-57

模板变更后索引未更新

现象:模板已落库,但向量检索不到新模板。
可能原因:

  • autoIndexOnTemplateChange=false;
  • 事件未发布;
  • 增量任务尚未执行;
  • 模板无字段,被当作删除处理。

处理:

  • 检查 zsjz.ai-clean.vector.auto-index-on-template-change;
  • 检查日志中是否有增量索引或删除向量记录;
  • 若无字段,补充字段后再重建;
  • 必要时调用全量重建。

章节来源

  • AiCleanTemplateVectorIndex.java:201-526
  • AiCleanTemplateVectorIndex.java:601-924

pgvector 不可用时的降级行为

现象:pgvector 连接失败、向量表不存在、嵌入模型超时。
行为:

  • recall 返回空列表;
  • searchTables 返回空列表;
  • 模板识别主流程继续使用指纹、打分和模型;
  • 日志记录降级原因;
  • 全量重建连续失败时中止并返回已写入数。

处理:

  • 检查 pgvector 插件是否安装;
  • 检查嵌入模型配置;
  • 检查向量表是否存在;
  • 恢复服务后调用重建接口补齐索引。

章节来源

  • AiCleanTemplateVectorIndex.java:201-526
  • ai-template-vector-index.md:80-120

向量召回没有提升命中率

现象:召回有结果,但 LLM 仍选错模板。
可能原因:

  • 向量召回只是候选增强,不负责判档;
  • 最终出口 A 仍需满足传统规则;
  • 模型置信度低时不会升级为 STRONG;
  • 召回命中的是池外模板或被旧排序覆盖。

处理:

  • 确认召回命中是否在候选池内;
  • 检查 HeaderScorer 的确定性门槛;
  • 检查模型置信度;
  • 优化模板描述、表头和字段语义。

章节来源

  • AiTemplateMatcher.java:201-466
  • HeaderScorer.java:1-200

结论

AiCleanTemplateVectorIndex 和 AiCleanVectorProperties 共同构成了 AI 清洗模板的语义召回基础设施。它把两套模板库的结构元数据向量化并存入 pgvector,服务于两条主线:

  1. Agent 查表与 SQL 生成;
  2. AI 模板匹配中的候选召回。

与传统规则匹配相比,向量索引不是替代方案,而是增强方案:

  • 指纹和打分仍是确定性主干;
  • 向量召回只提升候选排序;
  • 出口 A 的硬门由 HeaderScorer 和模型置信度共同守住;
  • 任何向量层失败都会降级为“无召回”,不影响主流程。

在模板数量增长时,向量索引能显著降低 LLM 候选池噪声,提高匹配效率与准确率。运维上应重点关注:

  • 启动自举是否补建存量索引;
  • 模板变更后是否自动增量;
  • 相似度阈值是否适配业务;
  • pgvector 与嵌入模型是否可用;
  • 重建是否因连续失败而熔断。