本文引用的文件
本说明聚焦于三类能力:
RagIndexStatus 描述索引生命周期状态,并提供嵌入调试接口辅助定位本地模型问题。这些能力共同构成一个面向 Agent 的“数据表结构 + 业务知识”双通道上下文增强机制:Agent 先理解意图,再决定调用表结构检索工具、知识库检索工具,最后由大模型生成 SQL 或业务回答。
相关代码集中在 ai-server 模块中,分为三层:
search_table_schema、search_knowledge 等工具给 LLM 调用。嵌入与存储层:本地 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
图表来源
章节来源
| 组件 | 职责 | 关键输入 | 关键输出 |
|---|---|---|---|
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 |
章节来源
RAG 的整体流程可以拆成两条主线:
表结构 RAG(RAG Schema)
table_info/table_field 与 ai_clean_template/ai_clean_field 的结构元数据转为向量,写入全局 pgvector 表。search_table_schema 工具按自然语言选表,返回物理表名和物理列名,便于直接写 SQL。知识库 RAG
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: "结合上下文生成答案"
图表来源
章节来源
WorkspaceSchemaCatalog 是 Schema Catalog 的实现,它不扫描案件 DuckDB,而是从两类模板元数据组装“可查表目录”:
table_info 与 table_field。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 : "包含"
图表来源
章节来源
RagSchemaService 是对外门面,负责:
etl.rag.enabled,也要求底层向量索引可用。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["返回表名、列名、注释、分数"]
图表来源
章节来源
知识库能力由 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: "向量矩阵 + 相似度"
图表来源
章节来源
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;实体本身仍保留完整运维字段。
章节来源
/embedding/debug 是一个面向本地 ONNX 模型的调试接口,主要用于验证:
它不参与业务路由;业务统一走 EmbeddingProvider,由 zsjz.embedding.enabled 决定使用本地模型还是在线 embedding 模型。因此,当 RAG 召回异常时,可以先用该接口确认本地模型是否正常工作。
章节来源
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"]
图表来源
章节来源
表结构向量索引
rag_tpl_d{dims},所有工作空间共享,重建幂等。知识库文档索引
嵌入模型
章节来源
etl.rag.enabled=true,并配置好嵌入模型。search_table_schema,后端 RagSchemaService.search 会根据自然语言语义检索模板库中的表结构。章节来源
search_knowledge。KnowledgeDocIndexer.search 会返回片段内容、来源文档名和相似度。章节来源
/agent/chat/reindexWorkspace。RagSchemaService.reindexWorkspace 会调用 AiCleanTemplateVectorIndex.rebuildNow()。RagIndexStatusVO,其中 status=SUCCESS,tableCount 为实际写入文档数,同时包含向量表名、模型名和维度。章节来源
现象
relation does not exist。可能原因
处理方式
AiCleanTemplateVectorIndex.rebuildNow() 创建 rag_tpl_d{dims}。RagVectorMapper.createVectorTableIfNotExists 是否成功。章节来源
现象
search_table_schema 返回 409,提示索引为空。IDLE。可能原因
处理方式
/agent/chat/reindexWorkspace 重建索引。/embedding/debug 验证本地嵌入模型是否正常。章节来源
现象
可能原因
etl.rag.scoreThreshold 过高,过滤掉低分结果。处理方式
RagProperties.topK 与 scoreThreshold。KnowledgeProperties.chunkSize 与 maxChunks。章节来源
现象
c0..cN 这类无意义列名。可能原因
c0..cN。field_name_en。处理方式
WorkspaceSchemaCatalog 输出的物理列名。table_field.field_name_en 与 ai_clean_field.column_name。章节来源
本项目中的 RAG 体系围绕“模板结构语义索引”和“知识库文档语义索引”两条主线展开:
RagSchemaService 与 AiCleanTemplateVectorIndex 负责把业务表结构向量化,让 Agent 能根据自然语言意图选择目标表和列。KnowledgeDocIndexer 与 KnowledgeDocParser 负责把文档解析、分块、嵌入并存入 pgvector,让 Agent 能检索领域知识片段。RagIndexStatus 提供索引状态的持久化视图,配合前端与运维接口形成可观测闭环。/embedding/debug 提供本地嵌入模型的可诊断入口,帮助区分“模型问题”和“检索配置问题”。在实际使用中,应优先保证模板元数据准确、嵌入模型稳定、向量索引重建及时;遇到召回问题时,应从 Schema 命名、注释质量、chunk 配置、相似度阈值和模型维度四个方向逐步排查。