openJiuwen agent-core 检索结果数据模型详解：SearchResult、RetrievalResult 与 MultiKBRetrievalResult 使用指南

人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载检索Retrieval是 AI Agent 问答、RAG检索增强生成与知识库系统的核心环节而检索返回什么结构的数据直接决定了上层应用如何消费结果。在 openJiuwen agent-core 的检索模块中openjiuwen.core.retrieval.common.retrieval_result提供了三套标准化的结果数据模型向量存储底层返回的SearchResult、检索器统一返回的RetrievalResult以及多知识库场景下携带来源信息的MultiKBRetrievalResult。本文以该模块的 API 文档为骨架结合仓库源码与示例完整讲解三个模型的设计定位、字段语义、构造方式、在检索调用链中的流转位置以及多知识库合并检索的底层原理帮助你在 Agent 应用中正确地构造、消费与溯源检索结果。模块定位检索模块的三个数据契约在 openJiuwen agent-core 的检索模块openjiuwen/core/retrieval中数据在向量存储 → 检索器 → 知识库 → 上层应用这条链路上会经历两次类型转换而retrieval_result.py正是定义这两次转换产物的核心文件数据模型产生阶段关键区别SearchResult向量存储VectorStore执行搜索后返回是原始命中记录自带id不区分文档与块RetrievalResult各类Retriever统一对外返回更贴近语义层带doc_id/chunk_id用于追溯来源MultiKBRetrievalResult多知识库合并检索函数retrieve_multi_kb_with_source返回额外携带raw_score、raw_score_scaled与kb_ids来源列表三个模型均基于 Pydantic 的BaseModel定义见 retrieval_result.py因此天然支持字段校验、默认值、序列化与反序列化可以直接作为 API 响应或存储结构使用。在模块的__init__.py中三个类都被列入_NON_LAZY_ATTRIBUTESopenjiuwen/core/retrieval/init.py意味着它们是检索模块的轻量公共契约导入时不触发重型依赖的懒加载。SearchResult向量存储层的原始命中记录SearchResult表示向量存储返回的搜索结果是检索链路中最底层的结构化结果。字段定义与语义字段类型必填说明idstr是结果 ID通常对应集合/collection 中的主键textstr是文本内容命中片段或整篇文档scorefloat是相关性得分数值越大相关性越高metadataDict[str, Any]否元数据默认{}例如{source: doc1, author: Alice}对应的 Pydantic 定义见 SearchResult其中id、text、score为必填字段metadata使用Field(default_factorydict)提供可变默认值避免多个实例共享同一字典对象。生产方VectorStore 的 search 系列接口SearchResult由向量存储层的抽象基类统一产出。VectorStore.search 的签名如下async def search( self, query_vector: List[float], top_k: int 5, filters: Optional[dict | QueryExpr] None, **kwargs, ) - List[SearchResult]:同文件还定义了返回List[SearchResult]的sparse_searchBM25 稀疏检索与hybrid_search混合检索接口。也就是说无论后端是 ChromaDB 还是 Milvus只要实现了VectorStore抽象基类其原始搜索结果统一封装为SearchResult。消费方检索器将 SearchResult 转换为 RetrievalResult以VectorRetriever.retrieve为例vector_retriever.py检索器拿到SearchResult列表后会将其转换为RetrievalResult并顺手从metadata中提取doc_id与chunk_idretrieval_result RetrievalResult( textresult.text, scoreresult.score, metadataresult.metadata, doc_idresult.metadata.get(doc_id), chunk_idresult.metadata.get(chunk_id), )这也解释了RetrievalResult的doc_id/chunk_id从何而来它们通常是建索引时写入metadata的字段ChromaDB 示例中对应document_id与chunk_id见 chroma_query_expr.py。RetrievalResult检索器统一的对外返回契约RetrievalResult是知识库检索SimpleKnowledgeBase.retrieve与所有Retriever实现统一返回的结果类型也是上层 RAG 应用直接消费的对象。字段定义与语义字段类型必填默认值说明textstr是—文本内容scorefloat是—相关性得分metadataDict[str, Any]否{}元数据如{source: doc1, author: Alice}doc_idOptional[str]否None文档 IDchunk_idOptional[str]否None文本块 ID对应定义见 RetrievalResult。基础用法样例来自原文档 from openjiuwen.core.retrieval.common.retrieval_result import RetrievalResult # 创建检索结果 result RetrievalResult( ... text这是检索到的文本, ... score0.95, ... metadata{source: doc1}, ... doc_iddoc1, ... chunk_idchunk1 ... ) print(fText: {result.text}, Score: {result.score}, Doc ID: {result.doc_id}) Text: 这是检索到的文本, Score: 0.95, Doc ID: doc1检索器的统一返回约定Retriever抽象基类base.py定义了统一的检索接口async def retrieve( self, query: str, top_k: int 5, score_threshold: Optional[float] None, mode: Literal[vector, sparse, hybrid] hybrid, **kwargs, ) - List[RetrievalResult]:仓库中四类检索器均遵循这一约定VectorRetriever向量检索向量无结果时自动回退到 BM25 稀疏检索vector_retriever.py仅支持modevector。SparseRetriever纯 BM25 稀疏检索doc_id取自metadatachunk_id直接取SearchResult.idsparse_retriever.py。HybridRetriever向量 稀疏混合检索支持alpha权重0 为纯稀疏、1 为纯向量、0.5 均衡可通过 kwargs 覆盖默认值hybrid_retriever.py。AgenticRetriever在任意底层检索器之上叠加 LLM 查询改写与多轮结果融合agentic_retriever.py融合阶段使用rrf_fusionReciprocal Rank Fusion合并多轮结果。知识库层按索引类型自动选择检索器在 SimpleKnowledgeBase 中retrieve会依据index_type自动创建对应检索器并返回List[RetrievalResult]simple_knowledge_base.pyif self.config.index_type vector: self.retriever VectorRetriever(vector_store..., embed_model...) elif self.config.index_type bm25: self.retriever SparseRetriever(vector_store...) else: # hybrid or others self.retriever HybridRetriever(vector_store..., embed_model...)同时根据RetrievalConfig.agentic决定是否包裹AgenticRetriever并将top_k、score_threshold、filters透传给底层检索器。MultiKBRetrievalResult跨知识库合并检索的带源结果当业务需要同时查询多个知识库如企业内部按部门拆分 KB时retrieve_multi_kb_with_source返回的正是MultiKBRetrievalResult它比普通结果多出合并前的原始分数与来源知识库列表两类信息。字段定义与语义字段类型必填默认值说明textstr是—文本内容scorefloat是—合并后的相关性得分跨知识库取最高分raw_scorefloat是—合并前的原始相关性得分raw_score_scaledfloat是—缩放后的原始相关性得分范围 0 到 1kb_idslist否[]包含该结果的知识库 ID 列表metadataDict[str, Any]否{}元数据对应定义见 MultiKBRetrievalResult。注意kb_ids与metadata同样使用default_factory提供独立默认容器。基础用法样例来自原文档 from openjiuwen.core.retrieval.common.retrieval_result import MultiKBRetrievalResult result MultiKBRetrievalResult( ... text相关文档文本, ... score0.92, ... raw_score0.88, ... raw_score_scaled0.90, ... kb_ids[kb_1, kb_2], ... metadata{source: doc1}, ... ) print(fText: {result.text}, Score: {result.score}, KBs: {result.kb_ids}) Text: 相关文档文本, Score: 0.92, KBs: [kb_1, kb_2]合并算法按文本去重、逐字段取最大retrieve_multi_kb_with_source的实现simple_knowledge_base.py展示了MultiKBRetrievalResult各字段的真实来源并行检索对每个知识库并发调用kb.retrieve(query, config)单个知识库失败只记录告警日志、不影响整体按文本去重合并以text为唯一键同一文本出现在多个 KB 时只保留一条记录kb_ids累加来源 ID分数取最大score、raw_score、raw_score_scaled均取跨库最大值其中raw_score/raw_score_scaled是从各库结果的metadata中读取的原始分数排序截断按score降序排序取top_k默认取自RetrievalConfig.top_k缺省 5后构造MultiKBRetrievalResult列表返回。此外仓库还提供了不带来源的简化版retrieve_multi_kbsimple_knowledge_base.py合并逻辑相同但只返回去重排序后的List[str]文本列表适用于只关心答案内容、不需要溯源信息的下游。score 与 raw_score 的实践语义raw_score是各知识库检索器返回的原始相关性得分例如向量余弦相似度转换后的值score是跨库合并后对外暴露的最终得分取最大值raw_score_scaled则是经过缩放到 0–1 区间的原始分数便于不同距离度量cosine / L2 / IP之间的横向比较。在 RAG 应用中raw_score/raw_score_scaled可用于判断该结果在某库内部是否足够可靠而kb_ids则支撑了答案溯源与回源打开原文的产品需求。从向量存储到多库合并一条完整调用链示例结合上面的分析一次多知识库检索的完整数据流转为VectorStore.search/sparse_search/hybrid_search │ 返回 List[SearchResult]底层原始命中 ▼ Retriever.retrieve │ 转换为 List[RetrievalResult]doc_id/chunk_id 从 metadata 提取 ▼ KnowledgeBase.retrieve按 index_type 自动选检索器可选 Agentic 包裹 │ 返回 List[RetrievalResult] ▼ retrieve_multi_kb_with_source │ 按 text 去重、字段取最大、kb_ids 聚合 ▼ List[MultiKBRetrievalResult]带 raw_score / raw_score_scaled / kb_ids以 ChromaDB 后端为例chroma_query_expr.py 演示了store.search(query_vector, top_k10, filters...)返回SearchResult后直接读取r.id、r.text、r.score、r.metadata的完整流程覆盖eq/ne/gt/lt/gte/lte、in_list、MatchExpr文本匹配、逻辑组合等过滤表达式milvus_query_expr.py 则展示了 Milvus 侧将距离distance转换为相似度得分后构造SearchResult的过程并额外演示了ArithmeticExpr、空值判断与 JSON 字段过滤等 Milvus 专有能力。测试验证与约束仓库为三个模型提供了专门的单元测试tests/unit_tests/core/retrieval/common/test_retrieval_result.py关键断言包括SearchResult/RetrievalResult的必填字段缺失时抛出pydantic.ValidationError如SearchResult()、RetrievalResult(text...)均会校验失败未显式传入metadata时默认值为空字典{}doc_id/chunk_id缺省为None。这说明三个模型遵循核心字段必填、扩展字段可选的严格契约构造RetrievalResult时至少需要提供text与score溯源字段doc_id/chunk_id可后续从metadata填充。小结三类结果模型的选择建议使用场景推荐模型理由直接对接向量存储、需要底层 ID 与原始分数SearchResult保留存储层主键id贴近数据库语义知识库/检索器统一返回、RAG 上游消费RetrievalResult携带doc_id/chunk_id支持溯源跨多个知识库检索且需要来源信息MultiKBRetrievalResult提供合并分数与kb_ids来源列表兼顾聚合与溯源理解三类结果模型的定位与流转关系是在 openJiuwen agent-core 上构建可靠检索应用的第一步底层用SearchResult对接异构向量存储中间层用RetrievalResult统一消费跨库场景用MultiKBRetrievalResult实现合并 溯源。后续可在此基础上结合 examples/retrieval 下的查询表达式示例进一步掌握filters过滤表达式的进阶用法。赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen agent-core 检索结果数据模型详解SearchResult / RetrievalResult / MultiKBRetrievalResult 的字段语义与工程实践openJiuwen agent core 检索结果数据模型详解SearchResult / RetrievalResult / MultiKBRetriev人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen Agent-Core 检索数据模型全解Document、TextChunk 与 MultimodalDocument 使用指南openJiuwen Agent Core 检索数据模型全解Document、TextChunk 与 MultimodalDocument 使用指南 本文深入人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 检索模块公共层retrieval.common权威指南配置体系、文档模型与结果数据结构openJiuwen agent core 检索模块公共层retrieval.common权威指南配置体系、文档模型与结果数据结构 本文以 docs/en人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考