向量存储与检索.md 29 KB

向量存储与检索

本文引用的文件

  • sql/knowledge_base.sql
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeDocIndexer.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/event/KnowledgeDocIndexEvent.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeProperties.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/tools/KnowledgeSearchTool.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/rag/RagSchemaService.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/rag/EmbeddingProvider.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/AttachmentDocIndexer.java
  • ai-server/src/main/resources/application.yaml

目录

  1. 简介
  2. 项目结构与定位
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与调优
  8. 故障排查指南
  9. 结论
  10. 附录:SQL 与 Java 示例

简介

本文聚焦知识库(module/knowledge)的知识文档向量层,说明其在 pgvector 中的表结构设计、主键与外键语义、向量维度来源、索引类型与查询语句,并解释 KnowledgeVectorMapper 提供的建表、插入、删除和相似检索接口如何被 Agent 的 KnowledgeSearchTool 以及 RAG Schema 检索链路间接使用。同时补充向量归一化、余弦距离计算、批量写入、索引刷新策略、维度不匹配处理、召回率调优、pgvector 扩展安装和性能监控建议。

项目结构与定位

知识库向量能力属于 AI Server 的“知识文档 RAG”子模块,与“附件大文档 RAG”“模板元数据向量索引”共享同一套嵌入模型路由(EmbeddingProvider),但物理表隔离、调用方不同:

层次 职责 关键文件
数据定义 知识库元数据、文档元数据、下载记录;向量表动态命名约定 sql/knowledge_base.sql
持久化映射 原生 SQL 的向量表 Mapper KnowledgeVectorMapper.java
异步索引 事件驱动分块、向量化、落库、状态机 KnowledgeDocIndexer.java
事件发布 事务后提交发布,fail-open KnowledgeDocIndexEvent.java
配置 知识库开关、分块、TopK、阈值、并发与预算 KnowledgeProperties.java
Agent 工具 search_knowledge 语义检索 KnowledgeSearchTool.java
统一 RAG 门面 表结构向量检索入口,供 Agent 工具使用 RagSchemaService.java
嵌入模型路由 本地 ONNX / 在线模型二选一、维度与表标签 EmbeddingProvider.java
通用向量化逻辑 文本分块、向量字面量构造、虚拟线程执行 AttachmentDocIndexer.java
全局配置 向量模型开关、bge-m3 参数、RAG 默认 TopK 与阈值 application.yaml
graph TB
    subgraph "知识库"
        KB_SQL["知识库 DDL<br/>knowledge_base / knowledge_doc"]
        KB_VEC["向量表 kb_vec_{kbId}{tag}_d{dims}"]
    end

    subgraph "Java 服务层"
        Event["KnowledgeDocIndexEvent"]
        Indexer["KnowledgeDocIndexer"]
        Mapper["KnowledgeVectorMapper"]
        Tool["KnowledgeSearchTool"]
        Embed["EmbeddingProvider"]
        AppCfg["application.yaml"]
    end

    KB_SQL --> Indexer
    Embed --> Indexer
    Indexer --> Mapper
    Mapper --> KB_VEC
    Tool --> Indexer
    AppCfg --> Embed

图表来源

  • sql/knowledge_base.sql:1-70
  • KnowledgeVectorMapper.java:1-64
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeSearchTool.java:1-66
  • EmbeddingProvider.java:1-200
  • application.yaml

章节来源

  • sql/knowledge_base.sql:1-70
  • application.yaml

核心组件

  • 知识库元数据表:knowledge_base 表示一个知识库,支持内置库和用户自建库;knowledge_doc 表示上传到某个知识库的文档,维护解析状态、字符数、块数和失败原因。
  • 向量表:按知识库、嵌入模型标签、向量维度动态创建,形如 kb_vec_{kbId}{tag}_d{dims}。
  • KnowledgeVectorMapper:封装向量表的建表、存在性检查、插入、相似度检索、按文档删除、按知识库删除。
  • KnowledgeDocIndexer:事件驱动的异步索引器,负责全文加载、分块、调用嵌入模型、写 pgvector、更新文档索引状态。
  • KnowledgeSearchTool:Agent 工具,暴露 search_knowledge,按自然语言检索绑定知识库的片段。
  • EmbeddingProvider:在本地 bge-m3 与在线 embedding 模型之间选择,提供维度、表标签和文本向量化。
  • RagSchemaService:统一表结构向量检索门面,虽然不直接访问 KnowledgeVectorMapper,但与知识库向量层共享同一套向量模型与 pgvector 部署方式。

章节来源

  • KnowledgeVectorMapper.java:1-64
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeSearchTool.java:1-66
  • EmbeddingProvider.java:1-200
  • RagSchemaService.java:1-181

架构总览

知识库向量层是“文档 → 文本 → 分块 → 向量 → pgvector → 相似度检索”的闭环:

sequenceDiagram
    participant User as "用户或 Agent"
    participant Tool as "KnowledgeSearchTool"
    participant Indexer as "KnowledgeDocIndexer"
    participant Provider as "EmbeddingProvider"
    participant Mapper as "KnowledgeVectorMapper"
    participant PG as "pgvector 表 kb_vec_{kbId}{tag}_d{dims}"

    User->>Tool: 调用 search_knowledge(query, top_k)
    Tool->>Indexer: search(query, kbId)
    Indexer->>Provider: embed(query)
    Provider-->>Indexer: double[] queryVector
    Indexer->>Mapper: searchInKb(table, vector, kbId, threshold, limit)
    Mapper->>PG: 相似度检索 + kbId 过滤
    PG-->>Mapper: content/payload/score
    Mapper-->>Indexer: 结果列表
    Indexer-->>Tool: SearchHit 列表
    Tool-->>User: JSON 片段、来源、分数

图表来源

  • KnowledgeSearchTool.java:1-66
  • KnowledgeDocIndexer.java:250-359
  • KnowledgeVectorMapper.java:28-52
  • EmbeddingProvider.java:140-190

详细组件分析

向量表结构与主外键语义

固定表设计

knowledge_base 和 knowledge_doc 是固定结构,用于知识库与文档元数据:

字段 含义 约束
knowledge_base.id 知识库主键,内置库固定为 1 主键
knowledge_base.user_id 创建者,内置库为平台管理员 非空
knowledge_base.is_builtin 1=内置,0=自建 非空,默认 0
knowledge_doc.id 文档主键 主键
knowledge_doc.kb_id 所属知识库 非空,业务上关联 knowledge_base.id
knowledge_doc.user_id 上传者,列表与下载隔离依据 非空
knowledge_doc.sidecar_path Tika 提取的全文路径,向量化优先读取 可选
knowledge_doc.chunk_count 已向量化块数 整数,默认 0
knowledge_doc.index_status 索引状态:PENDING / INDEXING / READY / FAILED 字符串,默认 PENDING

动态向量表

向量表不是固定 DDL,而是由 KnowledgeVectorMapper.createVectorTable 在运行时创建,表名规则为:

组成部分 说明
kb_vec_ 前缀
{kbId} 知识库 ID,实现知识库级物理隔离
{tag} 嵌入模型标签,本地模式为 _bge_m3,在线模式为空串
_d{dims} 向量维度,来自当前 EmbeddingProvider.dimensions()

向量表结构如下:

列 类型 用途 约束
doc_id VARCHAR(128) 分块主键,值为 docId:chunkNo 主键
content TEXT 分块原文内容 无
payload JSONB 来源元数据,包含 kbId、docId、docName、chunkNo 无
embedding vector(${dims}) pgvector 稠密向量 无显式索引

主键是 doc_id,没有传统意义上的外键约束。隔离通过两层保证:

  1. 表名中包含 kbId。
  2. 检索时强制 payload->>'kbId' = #{kbId}。

因此,它不是严格的关系型外键,而是“命名空间 + payload 过滤”的业务隔离。

章节来源

  • sql/knowledge_base.sql:1-70
  • KnowledgeVectorMapper.java:15-26
  • KnowledgeDocIndexer.java:300-333

向量维度来源与模型路由

向量维度来源于 EmbeddingProvider.dimensions():

  • 本地模式:zsjz.embedding.enabled=true,使用进程内 bge-m3,维度由 zsjz.embedding.dimensions 决定,默认 1024。
  • 在线模式:zsjz.embedding.enabled=false,从 agent_model 表解析 type=embedding 的活跃模型,取配置的 dimensions。
  • 若维度无效或不可用,索引或检索会降级为“无召回”,而不是静默混用不同向量空间。

本地模式下的 bge-m3 输出向量会进行 L2 归一化;在线模型返回什么向量取决于远程服务,但代码要求长度必须等于配置维度。

flowchart TD
    Start["开始"] --> CheckMode{"本地模型可用?"}
    CheckMode -->|是| LocalDims["取 zsjz.embedding.dimensions<br/>默认 1024"]
    CheckMode -->|否| OnlineSpec["解析 agent_model 中 type='embedding'"]
    OnlineSpec --> ValidSpec{"规格有效?"}
    ValidSpec -->|否| Invalid["dimensions=0,索引/检索降级"]
    ValidSpec -->|是| OnlineDims["取模型 dimensions"]
    LocalDims --> Output["返回向量维度"]
    OnlineDims --> Output
    Invalid --> Output

图表来源

  • EmbeddingProvider.java:60-120
  • application.yaml

章节来源

  • EmbeddingProvider.java:1-200
  • application.yaml

KnowledgeVectorMapper 接口

方法 行为 关键参数
createVectorTable(tableName, dims) 动态创建向量表,不存在则跳过 表名、向量维度
tableExists(tableName) 检查信息_schema 中是否存在该表 表名
insertVectorDoc(tableName, docId, content, payloadJson, embedding) 插入分块向量,冲突时忽略 doc_id、content、payload、embedding
searchInKb(tableName, embedding, kbId, threshold, limit) cosine 相似度检索,限制 kbId、阈值和 TopK 查询向量、知识库 ID、阈值、上限
deleteByDoc(tableName, docId) 删除某文档全部向量行 文档 ID
deleteByKb(tableName, kbId) 删除某知识库全部向量行 知识库 ID

插入语句使用 ON CONFLICT (doc_id) DO NOTHING,实现幂等写入;删除语句按 payload->>'docId' 或 payload->>'kbId' 过滤,确保跨维度/跨模型兼容删除。

章节来源

  • KnowledgeVectorMapper.java:1-64

索引流程与事件机制

知识库文档索引不是同步阻塞在上传请求中,而是通过 Spring 事件解耦:

sequenceDiagram
    participant Service as "上传服务"
    participant Publisher as "KnowledgeDocIndexEvent.publish"
    participant Queue as "单线程 indexExecutor"
    participant Indexer as "KnowledgeDocIndexer.indexDoc"
    participant Parser as "文档解析"
    participant Provider as "EmbeddingProvider"
    participant Mapper as "KnowledgeVectorMapper"

    Service->>Publisher: publish(docId)
    Publisher-->>Queue: afterCommit 提交事件
    Queue->>Indexer: indexDoc(docId)
    Indexer->>Parser: loadFullText()
    Parser-->>Indexer: 全文
    Indexer->>Provider: dimensions() + embed(chunk)
    Indexer->>Mapper: deleteByDoc() + insertVectorDoc()
    Indexer->>Service: 更新 chunk_count/index_status

关键点:

  • 事件发布在事务提交后执行,避免异步线程读到未提交的文档。
  • 索引队列是单线程守护线程,文档逐个处理,防止多个文档同时打满嵌入模型。
  • 单个文档内部的分块嵌入使用虚拟线程并发,并由信号量限制全局嵌入并发。
  • 每个文档有索引预算秒数,超时后剩余分块跳过,已成功的分块仍算作索引完成。
  • 失败不会抛出到队列线程,而是把状态设为 FAILED 并记录失败原因。

图表来源

  • KnowledgeDocIndexEvent.java:1-59
  • KnowledgeDocIndexer.java:60-200
  • KnowledgeDocIndexer.java:201-359

章节来源

  • KnowledgeDocIndexEvent.java:1-59
  • KnowledgeDocIndexer.java:1-359

相似检索与 Agent 使用

KnowledgeSearchTool.searchKnowledge 是 Agent 可调用的工具:

  1. 接收自然语言查询和可选 top_k。
  2. 调用 KnowledgeDocIndexer.search(query, kbId)。
  3. 先对查询文本调用 EmbeddingProvider.embed()。
  4. 根据当前模型标签和维度生成向量表名。
  5. 若表不存在,降级为空结果,不抛数据库异常。
  6. 调用 KnowledgeVectorMapper.searchInKb(),按 kbId 过滤、cosine 相似度排序、限制 TopK。
  7. 将 content、source、score 包装为工具结果返回。

    flowchart TD
    A["收到 search_knowledge(query, top_k)"] --> B["校验 kbId 与模型可用"]
    B --> C["embed(query) 得到查询向量"]
    C --> D["确定向量表名"]
    D --> E{"向量表存在?"}
    E -->|否| F["返回空结果"]
    E -->|是| G["searchInKb: cosine + kbId 过滤 + threshold + limit"]
    G --> H["解析 payload 获取 docName"]
    H --> I["返回片段列表"]
    

图表来源

  • KnowledgeSearchTool.java:1-66
  • KnowledgeDocIndexer.java:250-359

章节来源

  • KnowledgeSearchTool.java:1-66
  • KnowledgeDocIndexer.java:250-359

与 RAG Schema 检索的关系

RagSchemaService 主要面向“表结构向量索引”,不直接操作 KnowledgeVectorMapper,但它与知识库向量层共享:

  • 相同的 EmbeddingProvider,因此使用相同模型、相同维度和相同 pgvector 部署。
  • 相同的向量表命名风格:表名带模型标签和维度后缀。
  • 相同的相似度语义:cosine 距离转 score。
  • 相同的能力开关:未配置嵌入模型时,两个方向都降级或报错。

因此,知识库向量层可视为 RAG 体系中的一个“文档片段检索分支”,而 RAG Schema 是另一个“表结构检索分支”。

章节来源

  • RagSchemaService.java:1-181
  • EmbeddingProvider.java:1-200

依赖关系分析

classDiagram
    class KnowledgeVectorMapper {
        +createVectorTable(tableName, dims)
        +tableExists(tableName)
        +insertVectorDoc(tableName, docId, content, payloadJson, embedding)
        +searchInKb(tableName, embedding, kbId, threshold, limit)
        +deleteByDoc(tableName, docId)
        +deleteByKb(tableName, kbId)
    }

    class KnowledgeDocIndexer {
        +onDocIndexEvent(event)
        +indexDoc(docId)
        +search(question, kbId)
        +deleteDocVectors(kbId, docId)
        +deleteKbVectors(kbId)
        -vectorTableName(kbId, tag, dims)
    }

    class KnowledgeSearchTool {
        +searchKnowledge(query, top_k)
    }

    class EmbeddingProvider {
        +isAvailable()
        +dimensions()
        +tableTag()
        +embed(text)
    }

    class KnowledgeDocIndexEvent {
        +publish(publisher, docId)
    }

    KnowledgeDocIndexer --> KnowledgeVectorMapper : "读写向量表"
    KnowledgeDocIndexer --> EmbeddingProvider : "获取维度与向量"
    KnowledgeSearchTool --> KnowledgeDocIndexer : "语义检索"
    KnowledgeDocIndexer --> KnowledgeDocIndexEvent : "消费事件"

图表来源

  • KnowledgeVectorMapper.java:1-64
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeSearchTool.java:1-66
  • KnowledgeDocIndexEvent.java:1-59
  • EmbeddingProvider.java:1-200

章节来源

  • KnowledgeVectorMapper.java:1-64
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeSearchTool.java:1-66
  • KnowledgeDocIndexEvent.java:1-59
  • EmbeddingProvider.java:1-200

性能与调优

向量归一化与余弦距离

  • 本地 bge-m3 模型输出经过 L2 归一化。
  • pgvector 使用 <=> 运算符,即余弦距离。
  • 查询 SQL 中用 1 - (embedding <=> #{embedding}::vector) 作为相似度分数,分数越高越相关。
  • 这意味着 scoreThreshold 是“最低相似度分数”,例如 0.3 表示至少 0.3 的相关度才返回。

批量写入

  • 当前 insertVectorDoc 是单条插入,没有 MyBatis batchInsert 或 COPY 批量语法。
  • 并发写入通过虚拟线程 + 全局信号量控制,适合中等规模知识库。
  • 如果知识库文档很多,建议后续增加批量插入接口,或使用 pgvector 推荐的批量写入方式,以减少网络往返和事务开销。

索引刷新策略

  • 事件驱动:文档上传或重试时发布 KnowledgeDocIndexEvent。
  • 事务后提交发布:避免异步线程读不到刚插入的文档。
  • 重索引幂等:先删除该文档旧向量行,再重新插入。
  • 文档状态机:PENDING → INDEXING → READY / FAILED。
  • 失败不中断队列:异常就地消化,记录失败原因,支持手动重试。

向量维度不匹配问题

  • 建表维度来自 EmbeddingProvider.dimensions()。
  • 本地/在线切换会导致表名带不同标签,从而物理隔离不同向量空间。
  • 搜索前检查向量表是否存在,不存在则返回空结果,避免 relation does not exist。
  • 删除向量时尝试多种标签和维度组合,提高兼容性。

召回率调优

参数 默认值 影响 调优建议
zsjz.knowledge.chunkSize 1000 分块大小 太小丢失上下文,太大 token 浪费;中文技术文档可从 500~1000 调整
zsjz.knowledge.chunkOverlap 100 分块重叠 提升边界召回,但增加冗余
zsjz.knowledge.maxChunks 2000 最大块数 超长文档只索引前部,截断会标注
zsjz.knowledge.topK 8 返回片段数 给 LLM 的候选越多,提示词压力越大
zsjz.knowledge.scoreThreshold 0.3 最低相似度 太低引入噪声,太高召回不足
zsjz.knowledge.indexConcurrency 8 嵌入并发 CPU 密集场景不宜过大
zsjz.knowledge.indexBudgetSeconds 900 单文档索引预算 过长可能卡住队列,过短导致大量跳过

pgvector 扩展安装与索引优化

  • 当前代码未自动安装 pgvector 扩展,也未创建任何 pgvector 专属索引(如 IVFFlat、HNSW)。
  • 向量列没有显式索引,查询走全表扫描,然后按余弦距离排序。
  • 当单知识库向量行数达到数万级以上,建议评估:
    • 安装 pgvector 扩展。
    • 针对 embedding 列创建 IVFFlat 或 HNSW 索引。
    • 将 CREATE TABLE IF NOT EXISTS 与索引创建拆分为运维脚本。
    • 对 payload->>'kbId' 建立函数索引或展开字段以加速隔离过滤。

性能监控建议

  • 监控 knowledge_doc.chunk_count、index_status、fail_reason。
  • 监控向量表行数:按 kbId 统计 kb_vec_* 表数量。
  • 监控嵌入模型可用性、维度、是否本地模式。
  • 监控 KnowledgeDocIndexer 日志中的预算耗尽、分块失败、索引完成信息。
  • 监控 pgvector 查询耗时,尤其是无索引时的全表余弦排序。

章节来源

  • KnowledgeProperties.java:1-65
  • KnowledgeDocIndexer.java:120-359
  • application.yaml

故障排查指南

现象 可能原因 排查步骤
知识库检索始终为空 向量表不存在、模型不可用、阈值过高 检查 EmbeddingProvider.isAvailable()、向量表是否存在、scoreThreshold
上传成功但索引失败 嵌入模型返回错误、维度无效、分块失败 查看 knowledge_doc.fail_reason 和 index_status=FAILED
切换本地/在线模型后召回异常 向量空间不一致,旧表与新表隔离 确认表名是否含模型标签,必要时重建索引
向量维度报错 在线模型配置维度与实际返回不一致 检查 agent_model 中 embedding 模型的 dimensions
索引很慢 嵌入模型 CPU 压力大、并发过高、预算过长 调整 indexConcurrency、indexBudgetSeconds
检索太慢 无 pgvector 索引,全表余弦排序 评估安装 pgvector 并创建 IVFFlat/HNSW 索引
知识库隔离失效 payload 缺失 kbId 或 SQL 拼接错误 检查 payload->>'kbId' 过滤逻辑

章节来源

  • KnowledgeDocIndexer.java:60-200
  • KnowledgeVectorMapper.java:28-64
  • EmbeddingProvider.java:140-190

结论

知识库向量层采用“动态表名 + 主键幂等 + payload 隔离 + cosine 相似度”的设计,实现了按知识库隔离的知识文档片段检索。它通过事件驱动、单文档顺序 + 分块并发、预算控制和模型路由,兼顾了稳定性与可扩展性。当前版本未使用 pgvector 专属索引,适合中小规模知识库;大规模场景需要评估 pgvector 扩展、IVFFlat/HNSW 索引、批量写入和查询计划监控。

附录:SQL 与 Java 示例

以下示例描述实际 SQL 与 Java 调用方式,不直接粘贴源代码。

向量插入

  • SQL 行为:向 kb_vec_{kbId}{tag}_d{dims} 插入一行,主键为 doc_id = '{docId}:{chunkNo}',payload 为 JSONB,embedding 为 vector。
  • 幂等语义:重复插入相同 doc_id 时忽略。
  • Java 入口:KnowledgeVectorMapper.insertVectorDoc。
  • 典型调用链:KnowledgeDocIndexer.doIndex → vectorMapper.deleteByDoc → vectorMapper.insertVectorDoc。

参考位置:

  • KnowledgeVectorMapper.java:28-37
  • KnowledgeDocIndexer.java:201-L240
  • AttachmentDocIndexer.java:293-L303

按相似度 TopK 检索

  • SQL 行为:计算 1 - (embedding <=> #{embedding}::vector) 作为 score,按 score 降序取前 limit 条,并强制 payload->>'kbId' = #{kbId} 且 score ≥ threshold。
  • Java 入口:KnowledgeVectorMapper.searchInKb。
  • Agent 入口:KnowledgeSearchTool.searchKnowledge → KnowledgeDocIndexer.search。

参考位置:

  • KnowledgeVectorMapper.java:40-52
  • KnowledgeSearchTool.java:33-66
  • KnowledgeDocIndexer.java:250-L310

按文档 ID 删除向量

  • SQL 行为:删除 payload->>'docId' = #{docId} 的全部行。
  • Java 入口:KnowledgeVectorMapper.deleteByDoc。
  • 高级清理:KnowledgeDocIndexer.deleteDocVectors 会遍历多种标签和维度组合,提高兼容删除概率。

参考位置:

  • KnowledgeVectorMapper.java:54-58
  • KnowledgeDocIndexer.java:312-L340

按知识库删除向量

  • SQL 行为:删除 payload->>'kbId' = #{kbId} 的全部行。
  • Java 入口:KnowledgeVectorMapper.deleteByKb。
  • 适用场景:级联删除知识库时清理对应向量数据。

参考位置:

  • KnowledgeVectorMapper.java:60-L64
  • KnowledgeDocIndexer.java:342-L359