DB-GPT Agent 知识资源Knowledge Resource深度解析RetrieverResource 与知识空间检索实战【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本文以 DB-GPT 官方文档 Knowledge Resource 为骨架结合仓库源码dbgpt-core 与 dbgpt-serve展开。核心主题是DB-GPT Agent 如何通过RetrieverResource与KnowledgeSpaceRetrieverResource两类资源让智能体在对话过程中实时检索外部知识库、把检索结果注入 Prompt从而完成带外部知识增强的 Agent 应用。读完本文你将掌握知识资源的类继承关系、核心参数space_name、top_k、重排机制、底层检索链路QA 检索 → Embedding 检索 → 重排以及知识空间资源在 DB-GPT Web 服务中的注册与调用方式可直接在 Agent 应用与数据智能应用中落地知识库问答 / RAG Agent能力。一、为什么 Agent 需要 Knowledge Resource单独的 Agent 通常只具备模型自身的静态知识当用户提问超出模型训练范围如企业内部文档、私有数据库说明、最新技术资料时回答质量会明显下降。解决思路是让 Agent 在推理过程中动态访问外部知识库把命中的知识片段注入到 Prompt 中作为上下文。DB-GPT 用资源Resource抽象了这一能力。根据 文档原文Agent 的知识增强正是通过RetrieverResource这一资源实现的——它是一个可以从外部知识库检索知识的资源。从源码看所有 Agent 资源都继承自抽象基类Resourcebase.py并通过ResourceType枚举区分类型。知识资源对应的类型值为Knowledge knowledgebase.py。这意味着知识资源与数据库DB、互联网Internet、工具Tool、技能Skill等资源一样可以被 Agent 统一编排、注入和调用。二、两类 RetrieverResource 的定位与区别按文档定义目前存在两种RetrieverResource类型说明运行环境RetrieverResource通用的知识检索资源可对接任意实现了BaseRetriever接口的检索器从外部知识库检索知识任意能构造检索器实例的环境KnowledgeSpaceRetrieverResourceRetrieverResource的具体实现子类专门从 DB-GPT 的**知识空间Knowledge Space**检索知识仅限 DB-GPT 环境即运行在 DB-GPT Web Server 中两者的关系在源码中非常清晰RetrieverResource定义于 packages/dbgpt-core/src/dbgpt/agent/resource/knowledge.py位于核心包dbgpt-core属于与运行时无关的通用抽象KnowledgeSpaceRetrieverResource定义于 packages/dbgpt-serve/src/dbgpt_serve/agent/resource/knowledge.py位于服务层包dbgpt-serve直接继承RetrieverResource并组合了KnowledgeSpaceRetriever。之所以强调仅在 DB-GPT 环境中生效是因为KnowledgeSpaceRetrieverResource依赖 DB-GPT 内部的多个组件KnowledgeSpaceDao知识空间数据访问层、StorageManager存储管理器、Embedding 工厂、RAG 服务等这些组件只有在 DB-GPT Web Server 启动时才会被注册进SystemApp。三、RetrieverResource 源码剖析通用知识检索资源3.1 类结构与构造参数RetrieverResource的核心定义如下knowledge.pyclass RetrieverResource(Resource[ResourceParameters]): def __init__(self, name: str, retriever: BaseRetriever): self._name name self._retriever retriever app_config CFG.SYSTEM_APP.config.configs.get(app_config) self.need_rerank bool(app_config.models.rerankers) if self.need_rerank: rerank_embeddings RerankEmbeddingFactory.get_instance( CFG.SYSTEM_APP ).create() self.reranker RerankEmbeddingsRanker( rerank_embeddings, topkapp_config.rag.rerank_top_k ) else: self.reranker None关键点构造参数只有两个name资源名称用于 Prompt 中的资源标识与retriever一个BaseRetriever实例。因此它天然与具体知识来源解耦——任何实现了BaseRetriever的检索器向量检索、BM25、文档树检索等都可以被包装成知识资源。重排Rerank开关自动判定构造时读取应用配置app_config.models.rerankers只要配置了重排模型就会创建RerankEmbeddingsRanker其topk取自app_config.rag.rerank_top_k。也就是说是否重排是全局配置行为而非资源创建时手动指定的。资源类型与参数类方法同样清晰classmethod def type(cls) - ResourceType: return ResourceType.Knowledge # 即 knowledge classmethod def resource_parameters_class(cls, **kwargs) - Type[ResourceParameters]: return RetrieverResourceParameters3.2 核心检索流程retrieve 与重排retrieve是知识资源的核心入口knowledge.pyasync def retrieve( self, query: str, filters: Optional[MetadataFilters] None, score: float 0.0, ) - List[Chunk]: return await self.retriever.aretrieve_with_scores(query, score, filters)它直接委托给底层retriever的aretrieve_with_scores支持三个参数query检索查询文本filtersMetadataFilters元数据过滤器可用于按文档来源、标签等元数据限定检索范围score相似度分数阈值低于该分数的候选块会被过滤。此外RetrieverResource还提供了async_execute方法knowledge.pyAgent 在执行资源时最终会走到这里同样调用retrieve完成检索。3.3 检索结果如何注入 Promptget_prompt 与 get_resources这是知识资源最核心的价值所在——把检索到的 Chunk 序列化为 Agent 可读的 Prompt 片段。get_promptknowledge.py该方法带10 秒 TTL 缓存cached(cachetools.TTLCache(maxsize100, ttl10))避免短时间内的重复提问反复检索question是必填参数缺失会抛出ValueError(Question is required for knowledge resource.)调用retrieve(question)拿到候选块若need_rerank为真且候选块多于 1 条则用RerankEmbeddingsRanker对候选重新排序将命中的块拼接为--i--: chunk.content形式的编号内容组装成两种语言的模板英文\nResources-{name}:\n {content}中文\n资源-{name}:\n {content}返回值是一个元组(prompt, references)其中references即命中文档的引用信息。get_resourcesknowledge.py则返回更结构化的三元组(chunks, prompt_template, references)其中prompt_template不再拼接具体内容英文Resources-{name}:\n {content}中文资源-{name}:\n {content}由调用方自行填充适合需要把 Chunk 列表单独交付给下游处理如前端展示、引用标注的场景。3.4 引用信息references 的生成_get_referencesknowledge.py负责把命中的Chunk聚合为按文档分组的引用字典优先从chunk.metadata[prop_field][source]取文档名取不到则回退到chunk.metadata[metadata]每个文档名下挂载命中的块列表每条块记录包含id块 ID、content块内容、meta_info文档名、recall_score召回分数、retriever由哪个检索器召回最终返回结构为{self.type().value: [...]}即{knowledge: [文档1的引用, 文档2的引用, ...]}。这一结构使上层 UI 或 API 能直接拿到哪份文档、哪些片段、多少分的完整证据链是 RAG 应用展示引用来源的基础。四、KnowledgeSpaceRetrieverResource对接 DB-GPT 知识空间KnowledgeSpaceRetrieverResource是文档强调的第二种资源用于从 DB-GPT 的知识空间Knowledge Space即用户在知识库模块中创建的文档集合检索知识。其完整实现位于 packages/dbgpt-serve/src/dbgpt_serve/agent/resource/knowledge.py。4.1 构造参数与内部行为class KnowledgeSpaceRetrieverResource(RetrieverResource): def __init__( self, name: str, space_name: str, top_k: int 10, system_app: SystemApp None, ): retriever KnowledgeSpaceRetriever( space_idspace_name, top_ktop_k, system_appsystem_app, ) super().__init__(name, retrieverretriever) knowledge_spaces get_knowledge_spaces_info(namespace_name) if knowledge_spaces is not None and len(knowledge_spaces) 0: self._retriever_name knowledge_spaces[0].name self._retriever_desc knowledge_spaces[0].desc else: self._retriever_name None self._retriever_desc None参数说明参数类型默认值作用namestr必填资源名称出现在 Prompt 的资源标识中如knowledge_space_xxxspace_namestr必填目标知识空间名称会透传给KnowledgeSpaceRetriever的space_idtop_kint10检索返回的候选块数量上限会作为KnowledgeSpaceRetriever的top_ksystem_appSystemAppNoneDB-GPT 系统应用容器用于获取检索器所需的 Embedding、存储等组件构造时它会做两件事用space_name、top_k、system_app构造KnowledgeSpaceRetriever再调用父类RetrieverResource.__init__父类据此读取全局配置决定是否启用重排通过get_knowledge_spaces_info(namespace_name)查询知识空间元信息把_retriever_name与_retriever_desc暴露为属性knowledge.py供上层展示当前知识空间是什么、描述是什么。4.2 参数类space_name 与 top_kKnowledgeSpaceLoadResourceParametersknowledge.py继承自RetrieverResourceParameters仅新增两个字段dataclasses.dataclass class KnowledgeSpaceLoadResourceParameters(RetrieverResourceParameters): space_name: str dataclasses.field( defaultNone, metadata{help: _(Knowledge space name)} ) top_k: int dataclasses.field( default10, metadata{help: _(Knowledge retriver top k)} )需要特别说明的是版本兼容逻辑knowledge.py_resource_version()返回v1to_configurations在v1版本下把space_name参数的valid_values即全部可选知识空间列表直接作为配置返回——这是为了兼容旧版前端表单旧版把知识空间当作一个枚举下拉框from_dict额外支持value字段到space_name的映射兼容旧版数据结构。此外resource_parameters_class是动态生成的knowledge.py它调用KnowledgeService.get_knowledge_space拉取当前系统中全部知识空间生成形如{label: 空间名, key: 空间名, description: 空间描述}的可选项列表并嵌入到动态参数类的space_name.valid_values中。这意味着在 Web UI 上配置 Agent 时知识空间字段会自动渲染为包含现有全部知识空间的下拉列表。4.3 底层检索器 KnowledgeSpaceRetriever 的检索模式KnowledgeSpaceRetriever定义于 packages/dbgpt-serve/src/dbgpt_serve/rag/retriever/knowledge_space.py构造参数比资源层更丰富space_id、top_k默认 4、query_rewrite查询改写、rerank、llm_model、embedding_model、retrieve_mode检索模式、system_app。其初始化逻辑要点space_id必填会先在KnowledgeSpaceDao中按id查找再按name查找都查不到则抛出Knowledge space {space_id} not found通过StorageManager拿到该知识空间对应的向量存储连接器根据空间的vector_type通过_extract_space_retrieve_modeknowledge_space.py从知识空间的context.embedding.retrieve_mode中解析默认检索模式未显式指定时回退到语义检索RetrieverStrategy.SEMANTIC.value。检索模式由_aretrieve_with_score分发knowledge_space.py共四种检索模式说明SEMANTIC语义走RetrieverChain即 QA 检索 Embedding 向量检索的组合KEYWORD全文关键词调用存储连接器的afull_text_search若底层存储不支持全文检索如部分向量库会记录警告并返回空结果Tree文档树用KeywordExtractor提取关键词再通过DocTreeRetriever在文档树中检索命中节点后递归遍历叶子节点转换为 ChunkHYBRID混合语义 全文 文档树三种检索并行执行asyncio.gather结果合并后按chunk.content去重4.4 RetrieverChainQA 检索与 Embedding 检索的接力KnowledgeSpaceRetriever在构造时组建了一条RetrieverChainknowledge_space.pyself._retriever_chain RetrieverChain( retrievers[ QARetriever(space_idspace_id, top_kself._top_k, ...), EmbeddingRetriever(index_storeself._storage_connector, ...), ], executorself._executor, )RetrieverChain的实现见 retriever_chain.py它按顺序逐个调用链中的检索器返回第一个非空结果同步_retrieve与异步_aretrieve逻辑一致。具体到知识空间场景先尝试QARetriever——DB-GPT 知识空间支持QA 问答对类型的文档每条 QA 记录可直接作为精确答案命中即返回若 QA 检索无结果再走EmbeddingRetriever做向量语义检索。这一设计保证精确 QA 优先、语义召回兜底兼顾准确率与召回率。五、在 DB-GPT 环境中的注册与调用实战5.1 资源注册KnowledgeSpaceRetrieverResource 的挂载KnowledgeSpaceRetrieverResource并非自动生效而是由 DB-GPT Web Server 启动时显式注册到资源管理器。注册入口在 packages/dbgpt-app/src/dbgpt_app/component_configs.py 的_initialize_resource_manager中from dbgpt_serve.agent.resource.knowledge import KnowledgeSpaceRetrieverResource ... rm get_resource_manager(system_app) rm.register_resource(DatasourceResource) rm.register_resource(KnowledgeSpaceRetrieverResource) rm.register_resource(PluginToolPack, resource_typeResourceType.Tool) ...由此可见KnowledgeSpaceRetrieverResource与数据源资源、插件工具、应用资源等一并作为 Agent 的内置资源类型注册。注册机制本身位于 packages/dbgpt-core/src/dbgpt/agent/resource/manage.pyResourceManager负责按类型:名称管理注册项并在 Agent 构建资源时通过build_resource_by_type把AgentResource其类型值为knowledge实例化为真正的资源对象。5.2 实战调用示例在 Agent 应用中挂载知识空间仓库的 Data Manus / Agentic Data API 提供了一个非常直观的调用范式packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.pyfrom dbgpt_serve.agent.resource.knowledge import KnowledgeSpaceRetrieverResource knowledge_resource KnowledgeSpaceRetrieverResource( namefknowledge_space_{knowledge_space}, space_nameknowledge_space, top_k4, system_appCFG.SYSTEM_APP, ) knowledge_resources.append(knowledge_resource)该代码块展示了标准使用方式从对话扩展信息中解析出用户指定的知识空间名支持knowledge_space、knowledge_space_name、knowledge_space_id多个字段用知识空间名构造KnowledgeSpaceRetrieverResourcetop_k取 4把资源追加到 Agent 的资源列表后续 Agent 执行时会自动调用其async_execute/retrieve完成知识检索通过retriever_name/retriever_desc把当前知识空间的描述注入对话上下文供 Agent 了解它可用的知识范围。同时该处还演示了知识空间缺失时的容错构造失败会捕获异常并写入knowledge_context的 Warning 信息避免整个对话流程中断。5.3 适用前提与限制根据文档与源码使用KnowledgeSpaceRetrieverResource必须满足以下前提必须运行在 DB-GPT 环境即 DB-GPT Web Server因为其依赖SystemApp中注册的KnowledgeSpaceDao、StorageManager、Embedding/重排模型、RAG 服务等组件目标知识空间必须已经存在且可被KnowledgeService查询到否则构造阶段会抛出异常Knowledge space {space_id} not found检索效果依赖知识空间自身的配置包括vector_type向量存储类型与context.embedding.retrieve_mode检索模式——这两个字段决定底层走语义、关键词、文档树还是混合检索是否启用重排由全局配置models.rerankers与rag.rerank_top_k决定参考 configs/dbgpt-app-config.example.toml 中模型与 RAG 相关配置段。六、知识资源在 Agent 运行中的完整调用链综合上文可以把一次带知识空间的 Agent 问答完整链路总结为资源注册阶段Web Server 启动时_initialize_resource_manager将KnowledgeSpaceRetrieverResource注册进ResourceManager资源解析阶段Agent 应用根据对话配置中的knowledge_space字段构造KnowledgeSpaceRetrieverResource实例并查询空间名/描述参数实例化阶段ResourceManager.build_resource_by_type读取参数类space_name、top_k动态生成带valid_values的参数描述供 UI 渲染检索阶段Agent 调用async_execute→retrieve(query, filters, score)→ 底层KnowledgeSpaceRetriever按检索模式执行RetrieverChainQA 优先Embedding 兜底混合模式下三路并行重排阶段若全局配置了重排模型RerankEmbeddingsRanker对候选块重排注入阶段get_prompt/get_resources将命中的 Chunk 序列化为Resources-{name}/资源-{name}格式的上下文连同references引用证据一并返回给 Agent最终由 Agent 综合上下文给出回答。这条链路把外部知识库 → 检索 → 重排 → Prompt 注入 → Agent 回答完整打通是 DB-GPT 上构建企业知识问答、RAG Agent、文档智能分析等应用的公共底座。需要进一步动手实践时可参考仓库中的 RAG 检索示例 与 Agent 检索汇总示例并结合 configs/dbgpt-app-config.example.toml 中的模型与 RAG 配置完成环境准备。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考