本文系统讲解 RAG 知识库的架构设计、五大扩展实现及实战接入方法。一、为什么需要 RAG大语言模型LLM虽然能力强大但存在两个核心短板知识截止训练数据有截止日期和幻觉可能编造不存在的事实。RAGRetrieval-Augmented Generation检索增强生成通过在推理前检索外部知识库中的相关文档片段将其作为上下文注入 Prompt从而让模型的输出更准确、更可控、更具时效性。在 AgentScope Java 中RAG 能力通过 io.agentscope.core.rag.Knowledge 接口统一抽象。Agent 在推理时通过该接口检索文档片段再交给模型用于生成。agentscope-extensions-* 仓库下提供了 5 种开箱即用的实现覆盖从自建向量库到主流第三方 RAG 平台的全部场景。二、架构设计检索与管控分离2.1 核心设计原则AgentScope 的 RAG 架构遵循一个关键原则除 Simple 外所有第三方集成仅负责检索Retrieve文档导入/更新走对应平台的控制台或服务端 API。这种管控分离的设计带来三大好处好处说明职责单一 Agent 侧只关心查什么、怎么查不关心数据怎么入库状态一致 避免双侧索引状态不一致的问题无缝替换 多个 Knowledge 实现在使用侧完全可替换切换引擎零改动2.2 统一接入方式无论选择哪种 Knowledge 实现接入 Agent 的方式都是同一套代码ReActAgentagentReActAgent.builder().name(Assistant).model(model).knowledge(knowledge)// 任选一种 Knowledge 实现.ragMode(RAGMode.AGENTIC)// 或 STATIC、NONE.build();也可以将 Knowledge 包装为工具供 Agent 自主选择是否检索KnowledgeRetrievalToolstoolsnewKnowledgeRetrievalTools(knowledge);ToolkittoolkitnewToolkit();toolkit.registerObject(tools);三、五大扩展详解3.1 Simple Knowledge —— 全链路自建Maven 坐标dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-rag-simple/artifactIdversion${agentscope.version}/version/dependency适用场景 你愿意自己跑 embedding 向量库不想接入第三方 RAG 平台需要完全掌控数据链路。完整示例importio.agentscope.core.embedding.dashscope.DashScopeTextEmbedding;importio.agentscope.core.rag.knowledge.SimpleKnowledge;importio.agentscope.core.rag.store.InMemoryStore;importio.agentscope.core.rag.model.RetrieveConfig;// 1) Embedding 模型EmbeddingModelembeddingsDashScopeTextEmbedding.builder().apiKey(System.getenv(DASHSCOPE_API_KEY)).modelName(text-embedding-v3).dimensions(1024).build();// 2) 向量库这里用进程内的实现VDBStoreBasestoreInMemoryStore.builder().dimensions(1024).build();// 3) 组装 KnowledgeSimpleKnowledgeknowledgeSimpleKnowledge.builder().embeddingModel(embeddings).embeddingStore(store).build();// 4) 写入文档ListDocumentdocsnewTikaReader().read(input).block();knowledge.addDocuments(docs).block();// 5) 检索ListDocumenthitsknowledge.retrieve(什么是 AgentScope,RetrieveConfig.builder().limit(5).scoreThreshold(0.5).build()).block();3.1.1 内置文档读取器io.agentscope.core.rag.reader 包提供了一组常见格式的 Reader全部产出 ListReader输入TextReader纯文本PDFReaderPDF基于 PDFBoxWordReaderWord 文档ImageReader图片配合多模态 embedding 使用TikaReaderApache Tika 通用解析兜底ExternalApiReader调外部 API 解析OCR / 自定义流水线读取出来的 Document 已经带有元数据配合 TextChunker 与 SplitStrategy 做分块。3.1.2 内置 Embedding 提供方类服务模式DashScopeTextEmbedding阿里云百炼 DashScope文本DashScopeMultiModalEmbedding阿里云百炼 DashScope多模态文本/图像OpenAITextEmbeddingOpenAI 兼容接口文本OllamaTextEmbeddingOllama 本地文本也可以实现 EmbeddingModel 接口自行扩展。3.1.3 内置向量库适配实现部署InMemoryStore进程内开发/测试用PgVectorStorePostgreSQL pgvectorMilvusStoreMilvusQdrantStoreQdrantElasticsearchStoreElasticsearchdense_vector切换向量库只需要换一个 VDBStoreBase 实现传给 SimpleKnowledge.builder().embeddingStore(…)。3.1.4 检索参数RetrieveConfig 控制检索行为字段说明limitTopK返回的最大文档数scoreThreshold最低分数阈值0~1metadata按文档 metadata 做过滤3.2 Bailian Knowledge —— 阿里云百炼托管Maven 坐标dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-rag-bailian/artifactIdversion${agentscope.version}/version/dependency适用场景文档已经在百炼控制台上传/解析完成想要企业级特性rerank、过滤、结构化/非结构化/图片三类知识库不想自维护向量库完整示例importio.agentscope.core.rag.integration.bailian.BailianConfig;importio.agentscope.core.rag.integration.bailian.BailianKnowledge;importio.agentscope.core.rag.model.RetrieveConfig;BailianConfigconfigBailianConfig.builder().accessKeyId(System.getenv(ALIBABA_CLOUD_ACCESS_KEY_ID)).accessKeySecret(System.getenv(ALIBABA_CLOUD_ACCESS_KEY_SECRET)).workspaceId(llm-xxxxxx).indexId(kb-xxxxxx).build();BailianKnowledgeknowledgeBailianKnowledge.builder().config(config).build();ListDocumenthitsknowledge.retrieve(如何申请发票,RetrieveConfig.builder().limit(5).scoreThreshold(0.5).build()).block();Rerank / Rewrite 配置百炼支持在原始召回之上做重排和 Query 改写进一步提升相关性BailianConfigconfigBailianConfig.builder().accessKeyId(ak).accessKeySecret(sk).workspaceId(llm-xxx).indexId(kb-xxx).rerankConfig(RerankConfig.builder().enable(true).topN(5).build()).rewriteConfig(RewriteConfig.builder().enable(true).build()).build();⚠️ 启用后延迟和费用会上升按需打开。配置参数一览配置说明accessKeyId / accessKeySecret阿里云访问凭证必填workspaceId百炼业务空间 ID必填indexId知识库索引 ID必填rerankConfig rerank 开关与参数rewriteConfigquery rewrite 开关与参数 注意 BailianKnowledge.addDocuments(…) 不可用——文档管理请通过百炼控制台或百炼平台 SDK 完成。3.3 Dify Knowledge —— 复用 Dify 数据集Maven 坐标dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-rag-dify/artifactIdversion${agentscope.version}/version/dependency适用场景团队已经在 Dify 上做内容运营和文档管理想直接复用 Dify 的多种检索模式关键词 / 语义 / 混合 / 全文完整示例importio.agentscope.core.rag.integration.dify.DifyKnowledge;importio.agentscope.core.rag.integration.dify.DifyRAGConfig;importio.agentscope.core.rag.integration.dify.RetrievalMode;importio.agentscope.core.rag.model.RetrieveConfig;DifyRAGConfigconfigDifyRAGConfig.builder().apiKey(System.getenv(DIFY_RAG_API_KEY)).datasetId(your-dataset-id).retrievalMode(RetrievalMode.HYBRID_SEARCH).enableRerank(true).build();DifyKnowledgeknowledgeDifyKnowledge.builder().config(config).build();ListDocumenthitsknowledge.retrieve(如何续费会员,RetrieveConfig.builder().limit(5).scoreThreshold(0.5).build()).block();四种检索模式RetrievalMode 决定 Dify 在数据集上的检索方式枚举说明KEYWORD_SEARCH仅关键词检索SEMANTIC_SEARCH仅向量语义检索HYBRID_SEARCH关键词 向量混合推荐FULL_TEXT_SEARCH全文检索自托管 Dify如果你部署了自己的 Dify把 baseUrl 指过去DifyRAGConfigconfigDifyRAGConfig.builder().apiKey(dataset-xxx).baseUrl(https://dify.mycompany.com).datasetId(ds-xxxx).retrievalMode(RetrievalMode.HYBRID_SEARCH).build();Metadata 过滤通过 MetadataFilter 可以按 Dify 上配置的元数据字段过滤DifyRAGConfigconfigDifyRAGConfig.builder().apiKey(apiKey).datasetId(datasetId).retrievalMode(RetrievalMode.HYBRID_SEARCH).metadataFilter(MetadataFilter.builder().conditions(List.of(MetadataFilterCondition.builder().name(category).comparisonOperator().value(List.of(faq)).build())).logicalOperator(and).build()).build();关键参数字段说明apiKeyDify 数据集 API Key必填datasetId数据集 ID必填baseUrl默认 https://api.dify.ai/v1自托管时改为你的地址retrievalMode见上表enableRerank是否启用 rerankmetadataFilter元数据过滤条件3.4 HayStack Knowledge —— 自托管检索流水线Maven 坐标dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-rag-haystack/artifactIdversion${agentscope.version}/version/dependency适用场景已经在 HayStack 上落地 RAG包括索引流水线、ChromaDB、Reranker 等想要直接复用 HayStack 的端到端检索能力完整示例importio.agentscope.core.rag.integration.haystack.HayStackConfig;importio.agentscope.core.rag.integration.haystack.HayStackKnowledge;importio.agentscope.core.rag.model.RetrieveConfig;HayStackConfigconfigHayStackConfig.builder().baseUrl(http://localhost:8080)// 你的 HayStack 服务.topK(10).build();HayStackKnowledgeknowledgeHayStackKnowledge.builder().config(config).build();ListDocumenthitsknowledge.retrieve(What is AI?,RetrieveConfig.builder().limit(5).build()).block();文档管理说明addDocuments(…) 抛 UnsupportedOperationException。要新增/更新文档请准备好原始数据放入 HayStack 流水线的 source 目录触发/重新执行 HayStack 的索引流水线索引完成后本插件即可检索到新文档这种管控分离避免了双侧索引状态不一致。关键参数字段说明baseUrlHayStack 服务地址必填topK默认返回的最大条数filterPolicy过滤策略见 FilterPolicyHayStackConfig 还提供超时、自定义 header、API Key 等扩展项按 HayStack 部署侧的鉴权方案配置即可。3.5 RAGFlow Knowledge —— 复杂文档解析利器Maven 坐标dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-rag-ragflow/artifactIdversion${agentscope.version}/version/dependency适用场景知识库以扫描件、复杂排版 PDF、含图片表格为主希望使用 RAGFlow 的 chunk 切分策略与重排能力需要 OCR、知识图谱增强完整示例importio.agentscope.core.rag.integration.ragflow.RAGFlowConfig;importio.agentscope.core.rag.integration.ragflow.RAGFlowKnowledge;importio.agentscope.core.rag.model.RetrieveConfig;RAGFlowConfigconfigRAGFlowConfig.builder().apiKey(ragflow-xxxxxxxx).baseUrl(http://localhost:9380).knowledgeBaseId(kb-xxxxx).topK(10).similarityThreshold(0.5).enableRerank(true).build();RAGFlowKnowledgeknowledgeRAGFlowKnowledge.builder().config(config).build();ListDocumenthitsknowledge.retrieve(AI 是什么,RetrieveConfig.builder().limit(5).build()).block();工作机制底层调用 RAGFlow 的 POST /api/v1/datasets/{dataset_id}/retrieve-chunks 接口向量相似度搜索 可配置 topK服务端 similarityThreshold 过滤通过 RAGFlowConfig 中的 metadata 字段做过滤可选启用 RAGFlow 的 rerank⚠️ 注意 当前 RAGFlow 的 retrieve-chunks API 不支持把对话历史传过去做上下文感知检索如果你需要这种能力请自己在 query 拼接前置指令。关键参数字段说明apiKeyRAGFlow API Key必填baseUrlRAGFlow 服务地址必填knowledgeBaseId数据集/知识库 ID必填topK服务端 TopKsimilarityThreshold服务端最低相似度阈值enableRerank是否启用 rerank四、选型决策指南面对五种实现如何快速做出选择你的需求推荐方案理由自己掌控全部链路embedding 向量库Simple全链路可控支持 5 种向量库阿里云生态、企业级托管Bailian免运维支持 rerank/rewrite团队已经在用 Dify 编排Dify直接复用已有数据集4 种检索模式需要复杂 ETLPDF 表格、图片 OCR、知识图谱RAGFlow文档解析能力最强已基于 HayStack 落地 RAG 流水线HayStack无缝对接已有流水线决策流程图是否需要完全自建 ├── 是 → Simple └── 否 → 是否使用阿里云 ├── 是 → Bailian └── 否 → 是否已使用 Dify ├── 是 → Dify └── 否 → 文档是否复杂扫描件/表格/OCR ├── 是 → RAGFlow └── 否 → HayStack五、RAG Mode 详解Agent 支持三种 RAG 模式通过 .ragMode() 配置模式行为适用场景AGENTICAgent 自行决定何时检索、检索什么开放式问答Agent 自主判断STATIC每次对话前自动检索并注入上下文固定领域专属助手NONE关闭 RAG纯 LLM 对话不需要外部知识六、最佳实践总结6.1 开发阶段使用 Simple InMemoryStore 快速验证 RAG 效果用 TikaReader 兜底解析各种格式文档调整 scoreThreshold 和 limit 找到最佳召回参数6.2 生产阶段向量库切换为 PgVectorStore 或 MilvusStore考虑接入百炼获得企业级 rerank 能力复杂文档场景优先选择 RAGFlow6.3 架构建议单一数据源原则文档管理统一在一个平台完成避免双侧维护渐进式演进先用 Simple 验证效果再根据需求迁移到托管平台可观测性结合 AgentScope 的 Observability 模块监控检索延迟和召回质量七、总结AgentScope Java 的 RAG 模块通过 Knowledge 接口实现了优雅的抽象层让开发者可以✅ 用同一套代码接入 5 种不同的知识库后端✅ 在自建与托管之间自由切换✅ 通过 RAG Mode 灵活控制检索时机✅ 将检索能力封装为工具赋予 Agent 自主决策能力