RAG：标准检索、配置驱动图与智能体 RAG

当前代码同时存在三条 RAG 使用路径：RagNode 在 Agentic Loop 中作为工具执行；RagExecutor 执行配置驱动的标准 RAG 图；AgenticRagService 执行带查询分析、评估和自修正的 Agentic RAG 图。三者共享 Dataset、Embedding Store 和模型能力，但不能把一个路径的状态字段或配置默认值直接套到另一个路径。

1. 数据进入向量库

EmbeddingStoreIngestor 的基本流程是：

text

Document
 -> DocumentTransformer（可选）
 -> DocumentSplitter
 -> TextSegmentTransformer（可选）
 -> EmbeddingModel.embedAll（每批最多 10 个 segment）
 -> KbChunkEntity
 -> EmbeddingStore.addAll

写入的 KbChunkEntity 至少携带文本、documentId、datasetId、fileName、businessKey、metadata、activated 和 delFlag。Long 元数据用字符串序列化，避免 JavaScript 精度丢失。文档转换器可清理敏感内容、规范空白；分段策略和 embedding 模型改变后，旧向量不能假设仍然兼容。

向量存储当前有 Elasticsearch/Milvus 适配，Agent 检索路径使用 KbMilvusEmbeddingStore。Embedding 维度由模型决定，集合/索引、模型、分段和过滤 metadata 必须作为同一版本管理。

2. 基础向量检索

EmbeddingStoreContentRetriever 先对 query 做 embedding，再构建 EmbeddingSearchRequest：

参数	作用
`maxResults`	最大返回片段数，默认 3，注册的内部基础检索器配置为 20
`minScore`	最低相似度，默认 0；Dataset/RAG 配置可提高阈值
`filter`	metadata 过滤器
query embedding	由当前 EmbeddingModel 生成

搜索结果从 Milvus 转为 LangChain4j Content，并把 KbChunkEntity.metadata 写回 TextSegment.metadata，供来源、文档和权限信息继续传播。Embedding 认证失败会抛出明确错误；一般检索异常不能伪装成“无结果”。

3. 标准 RAG 图

RagConfig 通过 RagGraphBuilder 动态决定节点：

启用 enableCorrection 必须同时启用质量评估；修正节点会根据 maxRetryCount 决定回到 query transform 还是 retrieval。RagExecutor.executeRetrieval 可以构造仅检索图，不应把生成节点误当成向量查询的一部分。

主要配置

配置	默认/可选值	影响
`maxResults`、`minScore`	3、0.6	初始检索规模和阈值
`enableQueryTransform`	false	重写、扩展、分解、多查询
`queryTransformStrategy`	`REWRITE`	查询改写策略
`enabledRetrievers`	`VECTOR`	VECTOR/BM25/HYBRID 能力选择
`retrievalExecutionMode`	`SIMPLE`	SIMPLE/PARALLEL/SEQUENTIAL/HYBRID
`enableRerank`、`rerankTopN`	false	重排模型和最终候选数
`enableQualityAssessment`、`qualityThreshold`	false、0.7	检索/回答质量门槛
`enableCorrection`、`maxRetryCount`	false、2	质量不足时自纠正
`aggregationStrategy`	`MERGE`	MERGE/RANK/DEDUPLICATE
`metadataFilters`	空	文档类型、时间、业务键等过滤
`enableFallback`、`timeoutMillis`	true、30000	降级和超时

配置从数据库 DTO 转为 RagConfig 或 Map 时要经过 RagConfigConverter，不要直接把前端 0/1 整数和字符串值当作 Java boolean 使用。

4. 智能体 RAG 图

AgenticRagGraphBuilder 的完整图为：

AgenticRagState 保存原始 query、分析结果、检索计划、候选内容、质量分数、迭代次数、修正 query 和最终答案。NeedsRetrievalEdge 可以让简单问题跳过检索；EvaluationRouteEdge 决定继续、自修正、综合或无答案。简化图会跳过评估和查询优化，适用于成本敏感场景。

5. 智能体循环中的 RAG 节点

RagNode 不是直接读取前端 query，而按以下优先级构造：

currentTask.parameters.query。
意图识别产生的 ragKeywords 空格拼接。
TaskExecutionState.userInput。

Dataset 过滤顺序为：targetDatasetIds 精确匹配；目标名称为空或“全部”使用全部 Dataset；名称先精确后模糊包含。没有 Dataset 会返回“未配置知识库”，输入不完整会通过 UserInputValidator 请求补充。

执行方式有两种：

条件	方式
任务参数或 Agent 子 Agent 中找到名称同时包含 Agentic/RAG 的 Agent	`AiAgentExecutionService.executeAgent` 委托子 Agent
找不到专属子 Agent	`AgenticRagService.searchAndGenerate` 直接执行多轮 RAG

结果优先使用回答；没有回答时格式化原始检索片段，并把置信度、迭代次数和目标 Dataset 写入 structured block。结果最终放入 taskExecutionResult，由后续 refining/task end 使用。

6. 检索器注册和外部调用

启动时 RetrieverRegistryConfig 注册：

EmbeddingStoreContentRetriever：RAG 图内部基础向量检索器。
AdvancedRagContentRetriever：外部使用，封装 RagExecutor，支持查询转换、质量评估、聚合等。

高级检索器不应再嵌套到内部 RetrievalNode，否则会重复执行 RAG 图和生成阶段。新增 retriever 时要声明名称、支持的参数、是否线程安全、是否可并行、超时和监听器。

7. RAG 质量与安全

metadata filter 必须带 Dataset、租户和文档激活状态，不能只按用户输入传递任意字段。
检索片段是外部/用户数据，Prompt Injection 节点和生成提示必须把它们当作不可信材料。
引用需要保留 document/chunk/source 元数据，禁止只返回裸文本导致无法追溯。
质量评估分数、无答案和空结果要区分；空结果不是“用户问题不存在”。
切换 embedding 模型、维度、分段器、reranker 或阈值时，应重建索引并比较命中率、引用准确率、延迟和成本。

RAG：标准检索、配置驱动图与智能体 RAG ​

1. 数据进入向量库 ​

2. 基础向量检索 ​

3. 标准 RAG 图 ​

主要配置 ​

4. 智能体 RAG 图 ​

5. 智能体循环中的 RAG 节点 ​

6. 检索器注册和外部调用 ​

7. RAG 质量与安全 ​