本文引用的文件
本文件聚焦 AI 数据清洗中的“清洗模板向量索引”,说明其如何把两套模板库的结构元数据向量化并写入 pgvector,再参与模板匹配候选召回。重点覆盖以下问题:
AiCleanTemplateVectorIndex 与 AiCleanVectorProperties 的职责边界;AiTemplateMatcher、HeaderScorer 的协同方式;该能力是“增强型召回”:向量不可用时,主流程仍按指纹、打分和模型三腿继续运行,不会阻断上传或清洗。
章节来源
向量索引位于 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
图表来源
章节来源
它是向量索引的统一入口,承担以下职责:
isAvailable(),并提供不可用原因。TemplateMetaChangedEvent,对既有模板与 AI 模板执行异步增删改。recall(queryText, topK) 返回模板 ID 与分数,用于提升候选排序。searchTables(queryText, topK) 返回物理表名与字段清单,供 Agent 生成 SQL。status() 暴露向量表名、维度、文档数等运维信息。它定义 zsjz.ai-clean.vector 命名空间下的配置项:
| 配置项 | 默认值 | 含义 |
|---|---:|---|
| enabled | true | 向量索引总开关 |
| autoIndexOnTemplateChange | true | 模板变更时是否自动增量更新 |
| topK | 12 | 向量召回条数上限 |
| scoreThreshold | 0.30 | pgvector cosine 转 score 后的召回门槛 |
| maxDocumentsPerRebuild | 5000 | 单次全量重建最大文档数 |
| autoRebuildOnStartup | true | 启动时若索引不存在或为空则后台重建一次 |
这些配置共同决定向量链路是“开启且增强”、“仅观察”还是“完全关闭”。
章节来源
向量索引统一消费两套模板元数据:
table_info + table_fieldai_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: 只提升排序,不改判档
图表来源
章节来源
向量索引并不直接保存业务对象,而是构造三类内部表示:
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;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"
图表来源
章节来源
构建内容时,索引会把模板类型、中英文表名、表头和字段清单拼接成自然语言风格的 content。这样,查询文本(例如主表块表头)与文档文本在 embedding 空间中具有可比性。
具体构建过程可概括为:
FieldBrief 列表;payload;content;通过 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
图表来源
章节来源
AiTemplateMatcher 是三条腿的模板匹配器:
向量索引只在第三步之前介入,调用 mergeRecall 做两件事:
AiCleanTemplateVectorIndex.recall 获取候选;max(headerScore, vectorScore);关键点:向量召回只改变候选顺序,不参与出口 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
图表来源
章节来源
HeaderScorer 是传统规则打分器,负责基于表头集合、字段名、列序、形状和必填覆盖计算确定性分数。它不关心向量索引,也不依赖 pgvector。
两者的分工很清晰:
HeaderScorer 负责“能不能稳准地判定”;当向量召回命中某个候选时,AiTemplateMatcher 会把它在排序中的位置前移,从而增加 LLM 选中它的概率。但最终是否出口 A,仍需满足:
HeaderScorer.STRONG;FILE_COVERAGE_MIN。这意味着:向量召回可以“拉高热度”,但不能“代替硬规则”。
章节来源
向量索引支持三种构建路径:
| 场景 | 触发方式 | 行为 |
|---|---|---|
| 模板新增/更新/删除 | TemplateMetaChangedEvent |
异步增量索引或删除 |
| 应用启动 | ApplicationReadyEvent |
若启用且可用、向量表不存在或为空,则后台全量重建 |
| 运维操作 | /js/a/aiClean/templateVector/rebuild |
同步全量重建,返回写入文档数 |
增量索引使用单线程守护线程池,保证同一进程内增量任务串行执行,避免同 doc_id 并发写或重复建表。全量重建使用独立互斥锁,防止两个 rebuild 同时 DROP 向量表。
stateDiagram-v2
[*] --> 未构建
未构建 --> 已构建 : "rebuildNow() 成功"
已构建 --> 已构建 : "模板变更增量更新"
已构建 --> 已构建 : "启动自举补建"
已构建 --> 已构建 : "手动重建"
未构建 --> 未构建 : "索引不可用/空查询"
图表来源
章节来源
AiCleanVectorProperties.scoreThreshold 控制,默认 0.30。整个链路遵循 fail-open:
enabled=false,不调用向量索引。recall 和 searchTables 返回空列表。因此,pgvector 不可用或模型不可用不会中断上传、清洗或模板识别主流程。
章节来源
向量索引对外部系统的依赖主要包括:
EmbeddingProvider:负责本地或在线嵌入模型的可用性、维度、表标签和实际向量化。RagVectorMapper:负责 pgvector 表的建表、删表、计数、搜索和写入。table_info、table_field、ai_clean_template、ai_clean_field。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
图表来源
章节来源
O(T+F+A),其中 T 是既有模板数,F 是既有字段数,A 是 AI 模板数。content 和 payload 与字段数量线性相关。maxDocumentsPerRebuild 截断,避免一次性打爆内存。topK 过大,召回结果过多可能反而稀释真实候选;默认 12 与 LLM 短名单一致,避免把太多噪声塞进提示词。maxDocumentsPerRebuild,必要时调大上限,并结合分页或增量重建策略。章节来源
建议在 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 |
模板库超过此数时需调大 |
章节来源
/js/a/aiClean/templateVector/rebuild。/js/a/aiClean/templateVector/status 查看:
注意:
ServerException,调用方不应期望正常返回写入结果。章节来源
available=true;章节来源
现象:search_table_schema 返回空或提示索引为空;模板匹配没有向量召回。
可能原因:
autoRebuildOnStartup=false;处理:
status 接口;zsjz.ai-clean.vector.auto-rebuild-on-startup=true;章节来源
现象:
处理:
scoreThreshold 以扩大召回范围;topK 调整短名单规模。章节来源
现象:模板已落库,但向量检索不到新模板。
可能原因:
autoIndexOnTemplateChange=false;处理:
zsjz.ai-clean.vector.auto-index-on-template-change;章节来源
现象:pgvector 连接失败、向量表不存在、嵌入模型超时。
行为:
recall 返回空列表;searchTables 返回空列表;处理:
章节来源
现象:召回有结果,但 LLM 仍选错模板。
可能原因:
处理:
HeaderScorer 的确定性门槛;章节来源
AiCleanTemplateVectorIndex 和 AiCleanVectorProperties 共同构成了 AI 清洗模板的语义召回基础设施。它把两套模板库的结构元数据向量化并存入 pgvector,服务于两条主线:
与传统规则匹配相比,向量索引不是替代方案,而是增强方案:
HeaderScorer 和模型置信度共同守住;在模板数量增长时,向量索引能显著降低 LLM 候选池噪声,提高匹配效率与准确率。运维上应重点关注: