RAG Schema、向量检索与知识库集成.md 29 KB

RAG Schema、向量检索与知识库集成

本文引用的文件

  • RagSchemaService.java
  • WorkspaceSchemaCatalog.java
  • RagSchemaSearchTool.java
  • AiCleanTemplateVectorIndex.java
  • RagProperties.java
  • RagVectorMapper.java
  • RagIndexStatus.java
  • RagIndexStatusVO.java
  • KnowledgeDocIndexer.java
  • KnowledgeBaseService.java
  • KnowledgeDocParser.java
  • KnowledgeSearchTool.java
  • EmbeddingDebugController.java
  • EmbeddingService.java
  • OnnxEmbeddingEngine.java

目录

  1. 简介
  2. 项目结构定位
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能特征与优化建议
  8. 使用示例
  9. 常见问题排查
  10. 结论

简介

本说明聚焦于三类能力:

  • RAG Schema:把模板库中的业务表结构与字段向量化,供 Agent 在对话时按自然语言语义挑选目标表。
  • 向量检索与知识库:把用户上传的知识文档经 Tika 解析、分块、嵌入后存入 pgvector,Agent 可按知识片段召回并注入提示词。
  • 索引状态与调试:通过 RagIndexStatus 描述索引生命周期状态,并提供嵌入调试接口辅助定位本地模型问题。

这些能力共同构成一个面向 Agent 的“数据表结构 + 业务知识”双通道上下文增强机制:Agent 先理解意图,再决定调用表结构检索工具、知识库检索工具,最后由大模型生成 SQL 或业务回答。

项目结构定位

相关代码集中在 ai-server 模块中,分为三层:

  • Agent 工具层:暴露 search_table_schema、search_knowledge 等工具给 LLM 调用。
  • RAG 门面与服务层:封装向量索引重建、查询、状态与知识库索引流程。
  • 嵌入与存储层:本地 ONNX 向量推理、pgvector 向量表操作、Tika 文档解析。

    graph TB
    subgraph "Agent 工具"
        ToolA["search_table_schema<br/>RagSchemaSearchTool"]
        ToolB["search_knowledge<br/>KnowledgeSearchTool"]
    end
    
    subgraph "RAG 服务"
        Facade["RagSchemaService"]
        Indexer["AiCleanTemplateVectorIndex"]
        KIndexer["KnowledgeDocIndexer"]
        Catalog["WorkspaceSchemaCatalog"]
    end
    
    subgraph "嵌入与存储"
        Embed["EmbeddingService / OnnxEmbeddingEngine"]
        PG["pgvector 向量表"]
        Tika["Apache Tika"]
    end
    
    ToolA --> Facade
    ToolB --> KIndexer
    Facade --> Indexer
    Indexer --> Catalog
    Indexer --> Embed
    Indexer --> PG
    KIndexer --> Embed
    KIndexer --> PG
    KIndexer --> Tika
    

图表来源

  • RagSchemaSearchTool.java:27-51
  • KnowledgeSearchTool.java:31-65
  • RagSchemaService.java:45-181
  • AiCleanTemplateVectorIndex.java:1-60
  • KnowledgeDocIndexer.java:1-40
  • KnowledgeDocParser.java:1-20
  • EmbeddingService.java:1-40
  • RagVectorMapper.java:1-25

章节来源

  • RagSchemaService.java:1-30
  • AiCleanTemplateVectorIndex.java:1-60
  • KnowledgeDocIndexer.java:1-40

核心组件

组件 职责 关键输入 关键输出
RagSchemaService 表结构向量索引的统一门面:可用性判断、重建、状态、语义检索 工作空间 ID、自然语言查询、topK 索引状态 VO、命中表结构列表
WorkspaceSchemaCatalog 从模板元数据装配可查表目录 既有模板表、AI 模板表及字段 物理表名、列名、类型、注释
AiCleanTemplateVectorIndex 把两套模板元数据向量化到全局 pgvector 表,提供增量/全量重建与语义搜索 模板元数据、嵌入模型、向量 Mapper 向量行、索引状态、召回结果
KnowledgeDocIndexer 知识库文档事件驱动的异步索引器 文档 ID、全文文本、chunk 配置 向量片段、文档状态、命中片段
KnowledgeDocParser 基于 Apache Tika 的文档全文提取 原始文件流、最大字符数 纯文本
EmbeddingService / OnnxEmbeddingEngine 本地 ONNX 嵌入推理引擎 文本、模型路径、维度、线程参数 归一化向量、相似度矩阵
RagVectorMapper 原生 pgvector SQL:建表、插入、删除、余弦相似度检索 动态表名、向量字面量、阈值、limit JSON payload、score
RagIndexStatus 持久化的索引状态实体 workspaceId、模型信息、指纹、计数 idle/indexing/success/failed

章节来源

  • RagSchemaService.java:31-44
  • WorkspaceSchemaCatalog.java:15-60
  • AiCleanTemplateVectorIndex.java:61-120
  • KnowledgeDocIndexer.java:41-120
  • KnowledgeDocParser.java:21-55
  • EmbeddingService.java:41-120
  • RagVectorMapper.java:26-113
  • RagIndexStatus.java:1-59

架构总览

RAG 的整体流程可以拆成两条主线:

  1. 表结构 RAG(RAG Schema)

    • 将 table_info/table_field 与 ai_clean_template/ai_clean_field 的结构元数据转为向量,写入全局 pgvector 表。
    • Agent 通过 search_table_schema 工具按自然语言选表,返回物理表名和物理列名,便于直接写 SQL。
    • 该能力与案件 DuckDB 数据解耦,只依赖模板库元数据。
  2. 知识库 RAG

    • 用户上传文档后,系统用 Tika 提取全文,按 chunk 大小切块,调用嵌入模型生成向量并写入按知识库隔离的 pgvector 表。
    • Agent 通过 search_knowledge 工具检索绑定知识库的片段,并将来源文档名与相似度返回给 LLM。

      sequenceDiagram
      participant User as "用户"
      participant Agent as "Agent/L"
      participant ToolA as "search_table_schema"
      participant ToolB as "search_knowledge"
      participant Facade as "RagSchemaService"
      participant Index as "AiCleanTemplateVectorIndex"
      participant KIdx as "KnowledgeDocIndexer"
      participant Embed as "EmbeddingProvider"
      participant Pg as "pgvector"
      
      User->>Agent: "发送调查类问题"
      Agent->>ToolA: "根据意图调用表结构检索"
      ToolA->>Facade: "search(query, topK)"
      Facade->>Index: "searchTables(query, limit)"
      Index->>Embed: "生成查询向量"
      Embed-->>Index: "向量"
      Index->>Pg: "cosine 相似检索"
      Pg-->>Index: "命中表结构"
      Index-->>ToolA: "物理表名、列名、注释、分数"
      ToolA-->>Agent: "结构化表结构结果"
      
      Agent->>ToolB: "需要领域知识时调用知识库检索"
      ToolB->>KIdx: "search(query, kbId)"
      KIdx->>Embed: "对查询分块生成向量"
      KIdx->>Pg: "kb_vec_{kbId}{tag}_d{dims} 检索"
      Pg-->>KIdx: "知识片段+来源+分数"
      KIdx-->>ToolB: "SearchHit 列表"
      ToolB-->>Agent: "知识片段"
      Agent-->>User: "结合上下文生成答案"
      

图表来源

  • RagSchemaSearchTool.java:27-51
  • RagSchemaService.java:115-181
  • AiCleanTemplateVectorIndex.java:1-60
  • KnowledgeSearchTool.java:31-65
  • KnowledgeDocIndexer.java:41-120
  • RagVectorMapper.java:49-76

章节来源

  • RagSchemaService.java:1-30
  • KnowledgeSearchTool.java:1-25

详细组件分析

RAG Schema:Schema Catalog 如何描述业务表结构

WorkspaceSchemaCatalog 是 Schema Catalog 的实现,它不扫描案件 DuckDB,而是从两类模板元数据组装“可查表目录”:

  • 既有模板:table_info 与 table_field。
  • AI 智能清洗动态表:ai_clean_template 与 ai_clean_field。

其输出约定非常重要:

  • tableName 使用物理表名,即 Agent 后续执行 SQL 时使用的表名。
  • columns[].name 使用物理列名;对于 AI 动态表,物理列通常是 c0..cN,而中文语义名仅用于展示和模板匹配。
  • type 来自元数据的字段类型,缺省为 TEXT。
  • comment 使用中文注释,required 表示是否必填。
  • 没有字段的表会被跳过;物理列名为空的历史脏数据也会被过滤。
  • 同名冲突时以既有模板为准。

    classDiagram
    class WorkspaceSchemaCatalog {
        +allTables() List~TableSchema~
        -appendTemplateTables(target, tables, fields) void
        -appendAiTemplateTables(target, templates, fields) void
    }
    
    class TableSchema {
        +String tableName
        +String tableComment
        +List~ColumnSchema~ columns
    }
    
    class ColumnSchema {
        +String name
        +String type
        +String comment
        +boolean required
    }
    
    WorkspaceSchemaCatalog --> TableSchema : "组装"
    TableSchema --> ColumnSchema : "包含"
    

图表来源

  • WorkspaceSchemaCatalog.java:61-140

章节来源

  • WorkspaceSchemaCatalog.java:15-60
  • WorkspaceSchemaCatalog.java:141-200

向量索引与检索:Agent 对话时的意图识别流程

RagSchemaService 是对外门面,负责:

  • 判断 RAG 能力是否可用:既要求 etl.rag.enabled,也要求底层向量索引可用。
  • 重建索引:同步重建,幂等覆盖,内部互斥避免并发 DROP 冲突。
  • 查询索引状态:不可用或文档数为 0 时返回 IDLE,不是失败。
  • 语义检索:若能力不可用抛出 409;若索引为空也抛出可操作提示;否则返回物理表结构和列信息。

    flowchart TD
    Start(["调用 search"]) --> CheckEnabled["检查 etl.rag.enabled 与向量索引可用性"]
    CheckEnabled --> Enabled{"可用?"}
    Enabled -->|否| Throw409["抛出 409:未配置嵌入模型或能力不可用"]
    Enabled -->|是| SearchIndex["调用底层 searchTables"]
    SearchIndex --> HitsEmpty{"是否有命中?"}
    HitsEmpty -->|否| CheckDocs{"索引是否为空?"}
    CheckDocs -->|是| ThrowEmpty["抛出 409:请先重建向量索引"]
    CheckDocs -->|否| ReturnEmpty["返回空列表"]
    HitsEmpty -->|是| MapResults["映射为 RagSearchResultVO"]
    MapResults --> ReturnHits["返回表名、列名、注释、分数"]
    

图表来源

  • RagSchemaService.java:75-181

章节来源

  • RagSchemaService.java:45-181

知识库下载日志、嵌入调试接口与 RAG 的关系

知识库能力由 KnowledgeBaseService、KnowledgeDocIndexer、KnowledgeDocParser 共同组成:

  • KnowledgeBaseService 负责知识库的增删改、用户隔离、内置库保护,以及级联清理文档、向量、下载日志和文档记录。
  • KnowledgeDocIndexer 订阅文档索引事件,单线程队列顺序处理文档,内部再用并发闸门限制每个文档内 chunk 的嵌入并发。
  • KnowledgeDocParser 使用 Apache Tika 自动检测并解析文档类型,提取正文;侧车 sidecar 缓存已提取文本,避免重复解析。
  • 嵌入调试接口 /embedding/debug 走 EmbeddingDebugController → EmbeddingService,用于验证本地 ONNX 模型的维度、归一化和语义区分度。

    sequenceDiagram
    participant Admin as "管理员/用户"
    participant KB as "KnowledgeBaseService"
    participant Parser as "KnowledgeDocParser"
    participant Indexer as "KnowledgeDocIndexer"
    participant Embed as "EmbeddingService"
    participant Pg as "pgvector"
    participant Debug as "EmbeddingDebugController"
    
    Admin->>KB: "上传文档"
    KB->>Parser: "提取全文"
    Parser-->>KB: "sidecar 文本"
    KB->>Indexer: "发布 KnowledgeDocIndexEvent"
    Indexer->>Indexer: "切分 chunk"
    Indexer->>Embed: "批量嵌入"
    Embed-->>Indexer: "向量"
    Indexer->>Pg: "写入 kb_vec_{kbId}{tag}_d{dims}"
    Admin->>Debug: "POST /embedding/debug"
    Debug->>Embed: "embedBatch + cosineSimilarity"
    Embed-->>Debug: "向量矩阵 + 相似度"
    

图表来源

  • KnowledgeBaseService.java:41-120
  • KnowledgeDocParser.java:21-55
  • KnowledgeDocIndexer.java:41-120
  • EmbeddingDebugController.java:24-62
  • EmbeddingService.java:80-160

章节来源

  • KnowledgeBaseService.java:1-80
  • KnowledgeDocIndexer.java:1-40
  • KnowledgeDocParser.java:1-55
  • EmbeddingDebugController.java:1-62

RagIndexStatus:索引状态的含义

RagIndexStatus 是持久化的索引状态实体,对应 rag_index_status 表,关键字段包括:

  • workspace_id:工作空间主键。
  • embedding_model_id、embedding_model_name:嵌入模型标识和名称。
  • dimensions:向量维度。
  • vector_table:实际 pgvector 表名。
  • schema_fingerprint:Schema 指纹,用于判断是否需要重建。
  • table_count:索引包含的文档/表数量。
  • status:当前状态。
  • last_error:最近一次失败原因。
  • indexed_at、update_at:时间戳。

状态常量定义如下:
| 值 | 含义 | 典型场景 | |---|---|---| | idle | 未索引 | 首次启动尚未构建,或重建前 | | indexing | 索引中 | 正在执行重建或增量索引 | | success | 成功 | 索引完成且无错误 | | failed | 失败 | 嵌入失败、pgvector 写入失败、模型维度异常等 |

注意:RagIndexStatusVO 是接口响应对象,而 RagSchemaService.getStatus 目前主要根据底层索引状态与文档数计算前端可读的 STATUS_SUCCESS 或 STATUS_IDLE;实体本身仍保留完整运维字段。

章节来源

  • RagIndexStatus.java:1-59
  • RagIndexStatusVO.java:1-24
  • RagSchemaService.java:98-144

嵌入调试接口与 RAG 的关系

/embedding/debug 是一个面向本地 ONNX 模型的调试接口,主要用于验证:

  • 模型维度是否符合预期。
  • 向量是否被正确归一化。
  • 不同文本之间的余弦相似度是否能反映语义差异。

它不参与业务路由;业务统一走 EmbeddingProvider,由 zsjz.embedding.enabled 决定使用本地模型还是在线 embedding 模型。因此,当 RAG 召回异常时,可以先用该接口确认本地模型是否正常工作。

章节来源

  • EmbeddingDebugController.java:15-62
  • EmbeddingService.java:1-40

依赖关系分析

RAG 相关组件的依赖关系如下:

graph LR
    RagSchemaSearchTool["RagSchemaSearchTool"] --> RagSchemaService["RagSchemaService"]
    RagSchemaService --> AiCleanTemplateVectorIndex["AiCleanTemplateVectorIndex"]
    AiCleanTemplateVectorIndex --> WorkspaceSchemaCatalog["WorkspaceSchemaCatalog"]
    AiCleanTemplateVectorIndex --> RagVectorMapper["RagVectorMapper"]
    AiCleanTemplateVectorIndex --> EmbeddingProvider["EmbeddingProvider"]
    KnowledgeSearchTool["KnowledgeSearchTool"] --> KnowledgeDocIndexer["KnowledgeDocIndexer"]
    KnowledgeDocIndexer --> KnowledgeDocParser["KnowledgeDocParser"]
    KnowledgeDocIndexer --> RagVectorMapper
    KnowledgeDocIndexer --> EmbeddingProvider
    EmbeddingProvider --> EmbeddingService["EmbeddingService"]
    EmbeddingService --> OnnxEmbeddingEngine["OnnxEmbeddingEngine"]

图表来源

  • RagSchemaSearchTool.java:17-51
  • RagSchemaService.java:45-181
  • AiCleanTemplateVectorIndex.java:61-120
  • KnowledgeSearchTool.java:31-65
  • KnowledgeDocIndexer.java:41-120
  • EmbeddingService.java:41-120

章节来源

  • RagVectorMapper.java:1-113
  • OnnxEmbeddingEngine.java:1-60

性能特征与优化建议

  • 表结构向量索引

    • 向量表为全局一张 rag_tpl_d{dims},所有工作空间共享,重建幂等。
    • 增量更新由模板变更事件触发,全量重建有互斥锁,避免并发 DROP。
    • 失败采用 fail-open 策略,不影响模板识别主链路。
  • 知识库文档索引

    • 文档索引为单线程守护队列,避免多个文档同时打满嵌入模型。
    • 单个文档内 chunk 嵌入通过信号量控制并发,防止 CPU 密集型嵌入任务爆炸。
    • 支持 sidecar 缓存全文,避免重复 Tika 解析。
    • 重索引时先删除旧向量行,保证幂等。
  • 嵌入模型

    • 本地 ONNX 模型懒加载,首次调用才载入约 2.3GB 权重。
    • 支持 eager-load 预热,减少首次请求延迟。
    • 向量默认 L2 归一化,余弦相似度可直接用内积近似,但实现仍按完整公式兼容外部未归一化向量。

章节来源

  • AiCleanTemplateVectorIndex.java:1-60
  • KnowledgeDocIndexer.java:41-120
  • EmbeddingService.java:120-200
  • OnnxEmbeddingEngine.java:61-120

使用示例

开启 RAG 后发送调查类问题

  1. 确保 etl.rag.enabled=true,并配置好嵌入模型。
  2. 在 Agent 对话中发送类似“我想查看包含手机号和身份证号的数据表”的调查类问题。
  3. Agent 会调用 search_table_schema,后端 RagSchemaService.search 会根据自然语言语义检索模板库中的表结构。
  4. 返回结果包含物理表名、物理列名、列类型和中文注释,Agent 可据此生成 SQL。

章节来源

  • RagSchemaSearchTool.java:27-51
  • RagSchemaService.java:115-181

查看命中片段

  1. 如果研判方案绑定了知识库,Agent 可在需要领域知识时调用 search_knowledge。
  2. KnowledgeDocIndexer.search 会返回片段内容、来源文档名和相似度。
  3. 前端或上层逻辑可将这些片段作为上下文注入提示词,帮助大模型生成更准确的回答。

章节来源

  • KnowledgeSearchTool.java:31-65
  • KnowledgeDocIndexer.java:41-120

重新构建向量索引

  1. 调用重建接口,例如 /agent/chat/reindexWorkspace。
  2. 后端 RagSchemaService.reindexWorkspace 会调用 AiCleanTemplateVectorIndex.rebuildNow()。
  3. 重建完成后返回 RagIndexStatusVO,其中 status=SUCCESS,tableCount 为实际写入文档数,同时包含向量表名、模型名和维度。

章节来源

  • RagSchemaService.java:60-97
  • RagIndexStatusVO.java:1-24

常见问题排查

pgvector 未初始化

现象

  • 向量表不存在。
  • 插入或检索时报 relation does not exist。
  • 索引状态无法读取。

可能原因

  • 向量索引尚未重建。
  • 应用启动时自举重建被关闭或未执行。
  • 模型维度变化导致新向量表名不同。

处理方式

  • 调用重建接口,让 AiCleanTemplateVectorIndex.rebuildNow() 创建 rag_tpl_d{dims}。
  • 检查 RagVectorMapper.createVectorTableIfNotExists 是否成功。
  • 确认 pgvector 扩展已在数据库中启用。

章节来源

  • RagVectorMapper.java:77-113
  • AiCleanTemplateVectorIndex.java:1-60

向量索引为空

现象

  • 调用 search_table_schema 返回 409,提示索引为空。
  • 前端显示状态为 IDLE。

可能原因

  • 从未执行重建。
  • 模板库中没有登记表或字段。
  • 嵌入模型不可用导致重建失败。

处理方式

  • 调用 /agent/chat/reindexWorkspace 重建索引。
  • 检查模板库中是否存在有效表与字段。
  • 使用 /embedding/debug 验证本地嵌入模型是否正常。

章节来源

  • RagSchemaService.java:115-144
  • EmbeddingDebugController.java:24-62

相似检索召回率低

现象

  • 自然语言查询无法命中预期表或知识片段。
  • 返回结果为空或分数很低。

可能原因

  • etl.rag.scoreThreshold 过高,过滤掉低分结果。
  • 查询过于模糊或与模板注释、列注释语义不一致。
  • 知识库 chunk 大小不合适,重要信息被切散。
  • 嵌入模型维度或模型版本发生变化,导致新旧向量不兼容。

处理方式

  • 调整 RagProperties.topK 与 scoreThreshold。
  • 改进模板表注释、字段注释,使其更接近自然语言表达。
  • 调整 KnowledgeProperties.chunkSize 与 maxChunks。
  • 模型变更后执行全量重建,避免混用不同维度的向量。

章节来源

  • RagProperties.java:1-21
  • KnowledgeDocIndexer.java:41-120

Schema 字段名不一致

现象

  • Agent 生成的 SQL 找不到列。
  • 物理列名与展示名不一致。
  • AI 动态表出现 c0..cN 这类无意义列名。

可能原因

  • 使用了中文注释或语义名,而不是物理列名。
  • AI 模板的动态表物理列名本身就是 c0..cN。
  • 历史脏数据缺少 field_name_en。

处理方式

  • 优先使用 WorkspaceSchemaCatalog 输出的物理列名。
  • 检查 table_field.field_name_en 与 ai_clean_field.column_name。
  • 修正模板元数据,使物理列名具有可读性;必要时重建向量索引。

章节来源

  • WorkspaceSchemaCatalog.java:25-60
  • WorkspaceSchemaCatalog.java:141-200

结论

本项目中的 RAG 体系围绕“模板结构语义索引”和“知识库文档语义索引”两条主线展开:

  • RagSchemaService 与 AiCleanTemplateVectorIndex 负责把业务表结构向量化,让 Agent 能根据自然语言意图选择目标表和列。
  • KnowledgeDocIndexer 与 KnowledgeDocParser 负责把文档解析、分块、嵌入并存入 pgvector,让 Agent 能检索领域知识片段。
  • RagIndexStatus 提供索引状态的持久化视图,配合前端与运维接口形成可观测闭环。
  • /embedding/debug 提供本地嵌入模型的可诊断入口,帮助区分“模型问题”和“检索配置问题”。

在实际使用中,应优先保证模板元数据准确、嵌入模型稳定、向量索引重建及时;遇到召回问题时,应从 Schema 命名、注释质量、chunk 配置、相似度阈值和模型维度四个方向逐步排查。