OpenViking 检索机制深度解析：意图分析 + 层级检索 + Rerank 的三阶段召回管线

OpenViking 检索机制深度解析意图分析 层级检索 Rerank 的三阶段召回管线【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 面向 AI Agent 提供了统一的自进化上下文数据库Unify Agent Memory, Knowledge RAG and Skills其检索机制是连接用户查询与记忆、资源、技能三层上下文的枢纽。本文基于 docs/zh/concepts/07-retrieval.md 展开系统讲解find()与search()的差异、IntentAnalyzer 意图分析、HierarchicalRetriever 层级递归检索与 Rerank 精排的完整调用链并结合 openviking/retrieve/ 目录下的源码实现与配置指南给出可直接落地的配置示例。读完本文你将掌握 OpenViking 检索的完整数据流、关键参数调优方法以及如何用少量配置让检索同时获得“高召回”与“精排序”。一、整体架构三阶段检索管线OpenViking 的检索机制采用经典的三阶段设计意图分析 → 层级检索 → Rerank。原始查询首先被拆解为多个带类型与优先级的子查询随后按上下文类型确定根目录并递归搜索目录树最后在 THINKING 模式下由精排模型对候选结果重新打分。查询 → 意图分析 → 层级检索 → Rerank → 结果 ↓ ↓ ↓ TypedQuery 目录递归 精排评分该流程的每一环都有独立模块承担分布在 openviking/retrieve/ 目录下intent_analyzer.pyIntentAnalyzer负责把会话上下文交给 LLM 生成查询计划hierarchical_retriever.pyHierarchicalRetriever用优先队列实现目录树递归检索与分数传播retrieval_stats.py检索统计收集器记录每次查询的结果数、分数与延迟context_assembler/上下文组装管线把检索结果按预算、层级组装成最终注入 Agent 的上下文。此外核心数据结构TypedQuery、QueryPlan、MatchedContext、QueryResult、FindResult、ThinkingTrace等定义在 openviking_cli/retrieve/types.py 中供检索服务与 SDK 共享。二、两个入口find() 与 search()OpenViking 面向客户端提供两个检索入口分别对应“简单查询”与“复杂任务”两类场景。两者在是否依赖会话上下文、是否使用 LLM 意图分析、查询数量与延迟上有本质区别特性find()search()会话上下文不需要需要意图分析不使用使用 LLM 分析查询数量单一查询0-5 个 TypedQuery延迟低较高适用场景简单查询复杂任务从服务端实现看二者在 openviking/service/search_service.py 中分属两条路径find()L139是无会话的语义搜索直接以原始查询执行向量召回而search()L91在传入session且启用意图分析时会先调用session.get_context_for_search(query)获取会话压缩摘要再进入viking_fs.search。该开关由配置项retrieval.enable_intent控制关闭后search()会跳过会话加载与IntentAnalyzer退化为与无会话搜索相同的原始查询路径见 retrieval_config.py。SDK 层的两个异步入口位于 sdk/python/openviking_sdk/client.pyfind()请求/api/v1/search/findL1361search()请求/api/v1/search/searchL1384并支持target_uri、limit、image与FindOptions/SearchOptions扩展参数。使用示例# find(): 简单查询无需会话 results await client.find( queryOAuth 认证, target_uriviking://resources/, ) # search(): 复杂任务需要会话上下文 session_info await client.create_session() results await client.search( query帮我创建一个 RFC 文档, session_idsession_info[session_id], )create_session()同样来自 SDKL1487请求POST /api/v1/sessions返回的session_id即search()的会话凭证。需要说明search()返回的FindResult由total、memories、resources、skills四部分组成其中total在FindResult.__post_init__中被自动计算为三类上下文数量之和见 openviking_cli/retrieve/types.py。三、意图分析从一句话到 0-5 个 TypedQuery3.1 IntentAnalyzer 的职责IntentAnalyzer位于 openviking/retrieve/intent_analyzer.py其核心职责有三条源码 docstring 明确声明整合会话上下文压缩摘要 最近消息 当前消息调用 LLM 分析意图生成面向 memory / resources / skill 的多个 TypedQuery。它通过get_openviking_config().get_query_planner()获取规划模型未配置query_planner时回退到vlm。该阶段使用的模型可由query_planner配置项单独指定意图分析会完整消费以下三部分输入会话压缩摘要compression_summary超过 30000 字符会被截断对应MAX_COMPRESSION_SUMMARY_CHARS约为 10000 token 的预算最近 5 条消息messages[-5:]max_recent_messages默认值为 5当前查询current_message。3.2 输出TypedQuery 与 QueryPlan意图分析的输出是QueryPlan其中包含 0-5 个TypedQuery。两者的字段定义在 openviking_cli/retrieve/types.pydataclass class TypedQuery: query: str # 重写后的查询 context_type: ContextType # MEMORY/RESOURCE/SKILL intent: str # 查询目的 priority: int # 1-5 优先级 target_directories: List[str] # LLM 定位的目录 URI可空源码中的ContextType是字符串枚举MEMORY memory、RESOURCE resource、SKILL skilltypes.py#L16-L21。TypedQuery.priority默认值为 3范围 1-5数字越小优先级越高。QueryPlan额外携带session_context会话上下文摘要与reasoningLLM 推理过程前者会作为session_context返回给上层后者可透出到FindResult.to_dict()的query_plan字段用于检索可观测性。从源码实现看LLM 返回的 JSON 被parse_json_from_response解析后若顶层是数组会被包装为{reasoning: , queries: [...]}每个查询项的context_type通过ContextType(...)严格校验非法值回退为RESOURCEpriority缺失时取默认值 3intent_analyzer.py#L89-L123。3.3 查询风格与特殊情况意图分析会根据查询的语言形态决定context_type官方文档给出如下风格约定类型风格示例skill动词开头创建 RFC 文档、提取 PDF 表格resource名词短语RFC 文档模板、API 使用指南memory用户XX用户的代码规范偏好两种特殊情况需要特别注意0 个查询闲聊、问候等不需要检索的场景。此时QueryPlan.queries为空检索管线直接短路避免不必要的记忆注入与 token 消耗——这正是推荐用轻量小模型承担意图分析的核心价值之一。多个查询复杂任务可能需要技能 资源 记忆三类上下文例如“帮我创建一个 RFC 文档”可能同时生成 resource 查询RFC 模板与 skill 查询文档创建技能。3.4 query_planner 配置用小模型承担检索规划意图分析默认走vlm但官方强烈建议为search()单独配置一个轻量的本地 query planner 模型以降低延迟与成本。推荐模型为 Ollama 上的guoxuter/ov_intent_analysis_sft:v7_q8基于 Qwen3.5-0.8B 微调此前版本v4_q8仍作为可选项支持。ollama pull guoxuter/ov_intent_analysis_sft:v7_q8然后在 OpenViking 配置中追加完整配置说明见 query_planner 配置{ query_planner: { provider: litellm, model: ollama/guoxuter/ov_intent_analysis_sft:v7_q8, api_base: http://127.0.0.1:11434, temperature: 0.0, timeout: 60, extra_request_body: { think: false } } }一个值得关注的实现细节OpenViking 内置了按模型映射的 prompt 选择机制。QUERY_PLANNER_PROMPT_BY_MODEL表intent_analyzer.py#L24-L27把ollama/guoxuter/ov_intent_analysis_sft:v7_q8与v4_q8分别映射到retrieval.ov_intent_analysis_sft_v7与retrieval.ov_intent_analysis_sft_v4内置 prompt未映射的模型继续使用默认的retrieval.intent_analysisprompt。因此使用官方推荐模型时不需要替换 prompt 文件也无需设置prompts.templates_dir。该方案让 0.8B 级小模型承担检索规划同时保留更强的vlm处理语义提取、记忆提取与多模态内容。四、层级检索用优先队列递归搜索目录树4.1 五步流程HierarchicalRetriever位于 openviking/retrieve/hierarchical_retriever.py实现“目录树优先队列 分数传播 收敛检测”的递归检索。其整体流程为Step 1: 根据 context_type 确定根目录 ↓ Step 2: 全局向量搜索定位起始目录 ↓ Step 3: 合并起始点 Rerank 评分 ↓ Step 4: 递归搜索优先队列 ↓ Step 5: 转换为 MatchedContext结合源码retrieve()L101-L351的实现比文档描述更细致Step 1 在target_dirs显式指定时直接作为根目录集合否则调用default_target_directories(ctx, context_type...)定义于 openviking/core/retrieval_targets.py按租户与 peer 解析默认目录Step 2 的全局搜索限定level[0, 1]即只召回目录层 L0/L1步长取max(limit, GLOBAL_SEARCH_TOPK)。4.2 根目录映射context_type根目录MEMORYviking://~/memoriesRESOURCEviking://resourcesSKILLviking://~/skills实际解析时default_target_directories会结合用户身份做更精细的展开retrieval_targets.py#L60-L83MEMORY 展开为{user_root}/memories有 peer 时追加{user_root}/peers/{peer}/memoriesRESOURCE 展开为viking://resources、{user_root}/resources与 peer 资源目录SKILL 展开为viking://agent/skills与用户技能目录并去重。4.3 递归搜索算法与分数传播递归搜索的核心逻辑在_recursive_search()L421-L588文档给出的伪代码与源码高度一致while dir_queue: current_uri, parent_score heapq.heappop(dir_queue) # 搜索子节点 results await search(parent_uricurrent_uri) for r in results: # 分数传播 final_score score_propagation_alpha * embedding_score (1 - score_propagation_alpha) * parent_score if final_score threshold: collected.append(r) if not r.is_leaf: # 目录继续递归 heapq.heappush(dir_queue, (r.uri, final_score)) # 收敛检测 if topk_unchanged_for_3_rounds: break从源码可以看到几个文档之外的工程细节并行扇出每轮从优先队列取出MAX_PARALLEL_CHILD_SEARCHES 4个目录用asyncio.gather并发搜索子节点控制对远程向量库的并发请求量L495-L513分数传播公式final_score alpha * score (1 - alpha) * current_score if current_score else score——当父节点分数为 0如显式根目录时直接使用子节点自身分数L531-L533只对目录递归r.get(level, 2) ! 2才入队继续展开L2 文件是终端命中L555-L556按 URI 去重同一 URI 只保留最高分候选collected_by_uri字典双重收敛检测除了“topk 连续 3 轮不变”还有“候选池规模停滞 3 轮”的stagnant_rounds兜底二者任一达到MAX_CONVERGENCE_ROUNDS 3即提前终止L558-L581。4.4 关键参数参数值说明retrieval.score_propagation_alpha1.0分数传播混合中子节点自身分数的权重1.0表示仅使用子节点自身分数忽略父节点分数MAX_CONVERGENCE_ROUNDS3收敛检测轮数GLOBAL_SEARCH_TOPK10全局搜索候选数score_propagation_alpha是唯一暴露到配置中的检索行为参数实际读取路径为retrieval_config.py→HierarchicalRetriever.__init__的self.score_propagation_alphahierarchical_retriever.py#L81-L83。其完整取值语义retrieval_config.py#L19-L281.0忽略父节点分数只使用子节点自身语义相似度默认0.5与父节点分数等权混合0.0只使用父节点分数。其余两个参数是源码中的类常量MAX_CONVERGENCE_ROUNDS 3、GLOBAL_SEARCH_TOPK 10L56-L59。同处还有两个工程常量值得了解DIRECTORY_DOMINANCE_RATIO 1.2目录分数须超过子节点最高分与MAX_PARALLEL_CHILD_SEARCHES 4。4.5 两种检索模式与分数阈值RetrieverMode枚举定义在 hierarchical_retriever.py#L48-L50QUICK快速模式mode未指定且未配置 rerank 时自动选择只做一次直接的向量召回search_in_tenant不进行递归展开与分数传播延迟最低THINKING思考模式配置了 rerank 时默认启用执行完整的多阶段流程全局搜索定位起始点 → 递归搜索 → Rerank 精排search()默认走此模式。此外retrieve()支持score_threshold与score_gte两个阈值参数前者可覆盖配置阈值后者控制比较符True用False用相关测试见 tests/retrieve/test_hierarchical_retriever_rerank.py。五、Rerank 策略THINKING 模式下的精排5.1 触发条件与回退机制Rerank 在 THINKING 模式下对候选结果精排触发需同时满足配置了 Rerank AK/SK或 OpenAI 兼容凭据使用 THINKING 模式search()默认。若 rerank 返回无效结果或 API 调用失败会自动回退到向量分数。回退逻辑在_rerank_scores()L371-L419中实现调用异常、返回空结果、长度不匹配三种情况都会logger.warning后原样返回fallback_scores即使部分文档为空串也会先过滤再调用空文档的位置保留原向量分数。对应测试test_rerank_scores_preserves_fallbacks_for_empty_documentstests/retrieve/test_hierarchical_retriever_rerank.py#L282验证了这一行为。5.2 评分方式if rerank_client and mode THINKING: scores rerank_client.rerank_batch(query, documents) else: scores [r[_score] for r in results] # 向量分数Rerank 打分被用在两处与文档描述一致起始点评估对全局搜索召回的所有目录候选global_results按 abstract 重新打分作为递归搜索的入口优先级递归搜索对每层子节点的 abstract 重新打分再与父节点分数做传播混合。一个额外的工程细节当max_input_tokens 0时_rerank_scores会对 query 与 document 做 token 预算截断——query 占用max_input_tokens * 3 // 4其余预算分给 document超长文本“保留开头和结尾”式截断L388-L396。5.3 后端支持后端模型Volcenginedoubao-seed-rerank从 openviking/models/rerank/ 目录看Rerank 客户端实际支持四类统一派发volcengine_rerank.pyVikingDB、cohere_rerank.pyCohere、openai_rerank.pyOpenAI 兼容接口与litellm_rerank.pyLiteLLM 聚合。RerankClient.from_config(rerank_config)会按配置的 provider 自动选择实现hierarchical_retriever.py#L88-L99。官方文档主推的火山引擎配置rerank 配置{ rerank: { provider: vikingdb, ak: your-access-key, sk: your-secret-key, model_name: doubao-seed-rerank, model_version: 251028 } }OpenAI 兼容提供方如 DashScope示例{ rerank: { provider: openai, api_key: your-api-key, api_base: https://dashscope.aliyuncs.com/compatible-api/v1/reranks, model: qwen3-rerank, timeout: 120, max_input_tokens: 2048, threshold: 0.1 } }关键参数说明参数类型说明providerstrvikingdb、cohere或openai。省略时基于字段自动识别。ak/skstrVikingDB Access Key / Secret Key仅vikingdb提供方使用model_namestr模型名称仅vikingdb提供方使用默认doubao-seed-rerankapi_keystrAPI Key用于openai或cohere提供方api_basestr接口地址用于openai提供方modelstr模型名称用于openai提供方timeoutfloatOpenAI 兼容 provider 的 HTTP 超时默认30.0本地冷启动 rerank 可调大max_input_tokensint每个 query-document 对的最大估算 token 数0表示不截断默认0thresholdfloat分数阈值0.0-1.0低于此值的结果被过滤默认0.1注意如果未配置 Rerank搜索仅使用向量相似度QUICK 模式此时threshold退化为 0。六、检索结果的数据结构6.1 MatchedContext递归搜索与精排结束后候选结果经_convert_to_matched_contexts()L590-L658转换为统一的MatchedContextdataclass class MatchedContext: uri: str # 资源 URI context_type: ContextType is_leaf: bool # 是否文件 abstract: str # L0 摘要 score: float # 最终分数源码中该数据类的字段更完整level0L0 摘要、1L1 概览、2L2 文件、category、match_reason、search_tagstypes.py#L276-L289。转换时有几个值得留意的行为分数混合THINKING 模式下若hotness_alpha 0最终分数 (1 - alpha) * 语义分数 alpha * hotness_score其中 hotness 由active_count与updated_at经hotness_score()计算memory_lifecycle.py随后按混合分数重新排序L0/L1 预览净化L0/L1 记录的 abstract 会经body_for_preview()只保留正文剔除完整 OKF 文档内容L2 用户 Markdown 保持原样URI 后缀重建_append_level_suffix按层级为展示 URI 补上.abstract.mdL0或.overview.mdL1后缀L660-L672阈值校验_finite_score会把 inf/nan 分数收敛为 0.0避免向量库异常分数污染排序。6.2 FindResultfind()与search()最终都返回FindResultdataclass class FindResult: memories: List[MatchedContext] resources: List[MatchedContext] skills: List[MatchedContext] query_plan: Optional[QueryPlan] # search() 时有 query_results: Optional[List[QueryResult]] total: intFindResult同时实现了__iter__按 memories → resources → skills 顺序迭代全部命中与to_dict(include_provenanceFalse)types.py#L344-L410query_plan输出reasoning与各 TypedQuery 明细include_provenanceTrue时额外输出provenance内含每个查询的searched_directories、命中层级L0/L1/L2前缀、match_reason与thinking_trace用于检索过程的可视化与审计。ThinkingTrace是线程安全的队列式事件记录器queue.Queue可输出事件列表、统计信息搜索目录数、候选收集/排除数、收敛轮数与简单消息列表types.py#L131-L235。七、检索可观测性统计与调优依据OpenViking 为检索提供了两层可观测能力RetrievalStatsCollectoropenviking/retrieve/retrieval_stats.py在retrieve()结束处调用record_query()hierarchical_retriever.py#L338-L345按 context_type 累计查询次数、命中数、分数分布、延迟avg/max并标记rerank_used可据此评估某类上下文的召回质量与 Rerank 的收益ThinkingTraceQueryResult.thinking_trace保留完整的搜索决策链配合to_dict(include_provenanceTrue)可在应用层做召回过程审计。调优时建议按“先看 stats、再调参数”的顺序若某类上下文的avg_latency_ms明显偏高可考虑为search()配置本地 query planner 小模型若希望高频访问或最近更新的上下文获得排序提升可将retrieval.hotness_alpha从默认0.0调高此时最终分数不再是纯语义相似度若递归展开过深导致延迟上升可调整limit或依赖收敛检测提前终止。完整配置项及默认值见 docs/zh/guides/01-configuration.md{ retrieval: { hotness_alpha: 0.0, score_propagation_alpha: 1.0, recall_intent_timeout_s: 5.0, recall_rewrite_timeout_s: 30.0 } }参数类型说明默认值hotness_alphafloathotness 分数在最终召回分数中的混合权重。0.0关闭 hotness boost1.0只使用 hotness。范围0.0-1.0。0.0score_propagation_alphafloat层级检索中子节点自身分数权重。1.0忽略父节点分数0.5等权混合0.0只使用父节点分数。1.0recall_intent_timeout_sfloat会话感知查询扩展超时超时回退为用户原查询5.0recall_rewrite_timeout_sfloatdigest 重写超时超时后digest为空并照常返回rendered30.0八、调用链总结与延伸阅读把本文内容串成一条完整的调用链SDKclient.search()sdk/python/openviking_sdk/client.py→ HTTP/api/v1/search/search→SearchService.search()openviking/service/search_service.py→ 会话上下文加载 →IntentAnalyzer.analyze()openviking/retrieve/intent_analyzer.py生成 0-5 个 TypedQuery →HierarchicalRetriever.retrieve()按 QUICK/THINKING 模式执行向量召回 递归搜索 Rerank →_convert_to_matched_contexts()组装MatchedContext→ 汇总为FindResult返回。find()则跳过意图分析直接走向量召回路径。相关的源码与测试可继续深入探索检索实现openviking/retrieve/hierarchical_retriever.py、openviking/retrieve/intent_analyzer.py、openviking/retrieve/retrieval_stats.py数据结构openviking_cli/retrieve/types.pyRerank 客户端openviking/models/rerank/服务入口openviking/service/search_service.py、openviking/core/retrieval_targets.py测试用例tests/retrieve/test_hierarchical_retriever_rerank.py、tests/retrieve/test_intent_analyzer_query_planner.py关联文档架构概述、存储架构、上下文层级、上下文类型、配置指南。理解了三阶段管线的每个环节你就能根据实际任务复杂度、延迟预算与排序精度要求在find()/search()、QUICK/THINKING 模式、query planner 与 rerank 模型之间做出合理取舍让 OpenViking 的记忆、知识与技能检索真正服务于 Agent 任务。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考