LlamaIndex 中基于檢索器的路由查詢引擎RetrieverRouterQueryEngine 深度解析【免費下載鏈接】llama_indexLlamaIndex is the leading document agent and OCR platform項目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技術(shù)指南圍繞 LlamaIndex 核心庫中RetrieverRouterQueryEngine基于檢索器的路由查詢引擎展開講解它如何借助檢索器Retriever從候選 Node 中篩選出目標查詢引擎、將 Node 映射為 QueryEngine 并完成最終查詢的完整機制。讀完本文你將掌握該 API 的構(gòu)造參數(shù)、底層執(zhí)行鏈路、異步行為理解它為何被標記為 beta 并在后續(xù)演進中被ToolRetrieverRouterQueryEngine取代以及如何根據(jù)倉庫源碼判斷何時該使用它、何時應(yīng)遷移到推薦的替代方案。從一個 API 引用出發(fā)該引擎是什么關(guān)聯(lián)文檔是 LlamaIndex 自動生成的 API Reference 頁它通過 mkdocstrings 指令把llama_index.core.query_engine模塊中RetrieverRouterQueryEngine類的完整簽名、文檔字符串與成員索引渲染出來。其技術(shù)本體位于核心庫源碼 router_query_engine.py。要理解該引擎需要先區(qū)分兩類路由范式RouterQueryEngine基于 Selector 路由給定一批已包裝為QueryEngineTool的候選查詢引擎用一個BaseSelector通常是 LLM selector根據(jù)每個候選的元數(shù)據(jù)與用戶查詢選擇一個或多個引擎執(zhí)行查詢見 router.md。RetrieverRouterQueryEngine基于 Retriever 路由不預(yù)先固定候選引擎列表而是先用一個BaseRetriever去檢索出相關(guān) Node每個 Node 再被轉(zhuǎn)換為ToolMetadata并據(jù)此取回對應(yīng)的查詢引擎構(gòu)成QueryEngineTool最終只執(zhí)行被選中引擎的查詢見 retriever_router.md 所述內(nèi)容。從源碼的類注釋可以確認其定位Use a retriever to select a set of Nodes. Each node will be converted into a ToolMetadata object, and also used to retrieve a query engine, to form a QueryEngineTool.同時源碼明確標注了兩條重要狀態(tài)信息已棄用deprecated注釋指明please use our new ToolRetrieverRouterQueryEnginebeta 特性注釋提示W(wǎng)e are figuring out the right interface between the retriever and query engine即檢索器與查詢引擎之間的接口仍處于探索期。因此把它當作理解 LlamaIndex 路由演進歷史、以及閱讀舊版代碼時的關(guān)鍵 API 最合適新代碼應(yīng)優(yōu)先考慮替代實現(xiàn)。構(gòu)造簽名與參數(shù)語義該類繼承自BaseQueryEngine構(gòu)造器接收三個參數(shù)RetrieverRouterQueryEngine( retriever: BaseRetriever, # 檢索器負責根據(jù)查詢?nèi)〕龊蜻x Node node_to_query_engine_fn: Callable, # 將單個 Node 映射為查詢引擎的回調(diào)函數(shù) callback_manager: Optional[CallbackManager] None, )各參數(shù)在源碼中的實際作用如下retriever一個BaseRetriever實例_query執(zhí)行時首先調(diào)用self._retriever.retrieve(query_bundle)得到帶分數(shù)的 Node 列表NodeWithScore。node_to_query_engine_fn可調(diào)用對象接收一個BaseNode返回一個QueryEngine。它是Node → 查詢引擎的橋接邏輯典型實現(xiàn)是根據(jù) Node 的內(nèi)容、元數(shù)據(jù)或tool_name從本地注冊表/對象索引中取出對應(yīng)引擎其底層思想與default_node_to_metadata_fn中依賴 Node 元數(shù)據(jù)tool_name的思路一致見 router_query_engine.py 中對 ToolMetadata 構(gòu)造的約定。callback_manager可選的回調(diào)管理器_get_prompt_modules會把self._retriever作為可提示子模塊暴露出去說明該引擎的提示詞體系主要來自其內(nèi)部檢索器。構(gòu)造器直接保存上述參數(shù)并調(diào)用super().__init__(callback_manager)完成基類初始化本身不引入額外狀態(tài)邏輯非常輕量。底層執(zhí)行鏈路從檢索到查詢的一步路由該引擎的查詢過程非常短平快核心邏輯集中在_query方法router_query_engine.pynodes_with_score self._retriever.retrieve(query_bundle) if len(nodes_with_score) 1: raise ValueError(Retrieved more than one node.) node nodes_with_score[0].node query_engine self._node_to_query_engine_fn(node) return query_engine.query(query_bundle)整個鏈路可以拆解為四步檢索把用戶的QueryBundle包含查詢字符串及可選的自定義嵌入/節(jié)點過濾器交給retriever.retrieve()得到候選NodeWithScore列表強制單選當前實現(xiàn)只支持檢索出恰好一個 Node一旦超過一個便拋出ValueError(Retrieved more than one node.)。源碼中以# TODO: for now we only support retrieving one node明確標注了這一限制——這是該實現(xiàn)半成品屬性的最直接體現(xiàn)Node → QueryEngine 映射調(diào)用node_to_query_engine_fn(node)取回真正要執(zhí)行的查詢引擎執(zhí)行查詢返回query_engine.query(query_bundle)的結(jié)果。值得注意的是_query全程沒有回調(diào)事件包裝對比同一文件里RouterQueryEngine._query會觸發(fā)CBEventType.QUERY事件并把selector_result寫入響應(yīng)元數(shù)據(jù)router_query_engine.py說明該引擎在可觀測性上是相對薄弱的雛形實現(xiàn)。異步路徑同步的封裝異步方法_aquery的實現(xiàn)更簡練——它直接委托給同步_queryasync def _aquery(self, query_bundle: QueryBundle) - RESPONSE_TYPE: return self._query(query_bundle)即調(diào)用await engine.aquery(...)時實際是在事件循環(huán)里同步執(zhí)行檢索、映射與查詢內(nèi)部并不會并發(fā)調(diào)用檢索器或子引擎。這意味著在異步應(yīng)用中使用它時檢索/查詢階段會阻塞事件循環(huán)不適合高并發(fā)場景。說明性的端到端用法下面的示例基于上述構(gòu)造語義演示一種自洽的組裝方式不依賴未公開接口僅用于說明回調(diào)函數(shù)的典型形態(tài)from llama_index.core.query_engine import RetrieverRouterQueryEngine # registry: dict[str, QueryEngine] —— 按 node.metadata[tool_name] 索引的引擎表 def node_to_query_engine(node): tool_name node.metadata[tool_name] return registry[tool_name] router RetrieverRouterQueryEngine( retrievermy_retriever, # 保證只召回 1 個 node 的 BaseRetriever node_to_query_engine_fnnode_to_query_engine, ) response router.query(What is LlamaIndex?) print(response)需要再次強調(diào)當前實現(xiàn)要求檢索結(jié)果恰好為一個 Node因此配套的檢索器必須在召回層就做好 top-1 截斷或保證相關(guān)性唯一否則引擎會直接拋錯。模塊同源的兄弟引擎與演進路線RetrieverRouterQueryEngine與另外兩個引擎同處一個文件router_query_engine.py共同構(gòu)成了 LlamaIndex 查詢引擎多選一/多選多的完整能力帶RouterQueryEngineSelector 驅(qū)動的精確路由RouterQueryEngine把候選引擎包裝為QueryEngineTool交給BaseSelectorselect_multiFalse時單選擇器基于各引擎的ToolMetadata描述與用戶查詢做 LLM 判斷from_defaults通過get_selector_from_llm(llm, is_multiselect_multi)自動創(chuàng)建選擇器。當選擇器命中多個引擎時會逐一執(zhí)行并用TreeSummarizecombine_responses/acombine_responses合并多個子響應(yīng)最后把selector_result掛到響應(yīng)metadata上。異步路徑_aquery使用asyncio.gather并行執(zhí)行所有被選中子引擎。它是當前文檔對應(yīng)類同目錄下的正式替代方向之一參見 router.md。ToolRetrieverRouterQueryEngine官方推薦的演進替代這正是棄用注釋中點名的新實現(xiàn)參見 tool_retriever_router.md。它的關(guān)鍵差異在于構(gòu)造參數(shù)從BaseRetriever node_to_query_engine_fn變?yōu)镺bjectRetriever[QueryEngineTool]即直接檢索已包裝好的工具對象工具本身攜帶query_engine與metadata徹底消除了手寫 Node→Engine 回調(diào)的環(huán)節(jié)檢索返回的是多個QueryEngineTool引擎會把它們?nèi)繄?zhí)行同步串行、異步asyncio.gather并發(fā)超過一個結(jié)果時交給內(nèi)置TreeSummarize匯總響應(yīng)metadata中記錄retrieved_tools字段可觀測性優(yōu)于舊實現(xiàn)combine_responses/acombine_responses兩個模塊級函數(shù)負責統(tǒng)一合并邏輯收集各子響應(yīng)的source_nodes與文本調(diào)用 summarizer 得到最終響應(yīng)支持Response/PydanticResponse/StreamingResponse等形態(tài)見 router_query_engine.py。從源碼演進看官方把檢索 路由的范式收斂為檢索對象Tool 而非裸 Node 批量執(zhí)行 匯總即ObjectRetriever方案RetrieverRouterQueryEngine是這一范式定型前的中間形態(tài)。三者選型速覽引擎決策依據(jù)候選來源執(zhí)行策略狀態(tài)RetrieverRouterQueryEngineRetriever 召回單個 NodeNode →node_to_query_engine_fn回調(diào)僅執(zhí)行命中的 1 個引擎超過 1 個拋錯beta、已棄用RouterQueryEngineLLM Selector 讀元數(shù)據(jù)選擇預(yù)置QueryEngineTool列表單選或全選多選時 TreeSummarize 匯總穩(wěn)定路徑ToolRetrieverRouterQueryEngineObjectRetriever 召回工具可檢索的QueryEngineTool對象庫召回即執(zhí)行多結(jié)果匯總推薦替代與相關(guān) API 文檔及測試的關(guān)系相關(guān) API Reference本引擎與 router.mdRouterQueryEngine、tool_retriever_router.mdToolRetrieverRouterQueryEngine、retriever.mdRetrieverQueryEngine構(gòu)成同一 API 組的完整參照可在閱讀時相互對照。測試覆蓋情況倉庫測試 test_router_query_engine.py 僅直接測試了RouterQueryEngine與ToolRetrieverRouterQueryEngine的異步非阻塞特性例如通過后臺任務(wù)計時斷言aquery不長時間霸占事件循環(huán)并未為RetrieverRouterQueryEngine編寫專門測試——這與它 beta/棄用的定位一致。若你在舊代碼庫中遇到它可把它視為一個僅具單節(jié)點路由能力的過渡組件在升級路徑上應(yīng)優(yōu)先遷移到ToolRetrieverRouterQueryEngine。小結(jié)RetrieverRouterQueryEngine是 LlamaIndex 路由查詢引擎家族中一個具有歷史意義的 API它首次把檢索器召回 Node 元數(shù)據(jù) 查詢引擎路由串成一條管線但其單 Node 限制、無回調(diào)事件包裝、異步同步化等特征都表明它只是一個未定型的 beta 實現(xiàn)。理解它的源碼實現(xiàn)有助于看清后續(xù)RouterQueryEngineSelector 路由與ToolRetrieverRouterQueryEngine對象檢索路由各自解決的問題邊界前者解決候選引擎元數(shù)據(jù)如何被 LLM 閱讀后者解決大量引擎如何被高效檢索與批量執(zhí)行。在新的代碼中應(yīng)遵循源碼中的棄用指引優(yōu)先使用 ToolRetrieverRouterQueryEngine?！久赓M下載鏈接】llama_indexLlamaIndex is the leading document agent and OCR platform項目地址: https://gitcode.com/GitHub_Trending/ll/llama_index創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 LlamaIndex 中基于檢索器的路由查詢引擎：RetrieverRouterQueryEngine 深度解析
LlamaIndex 中基于檢索器的路由查詢引擎RetrieverRouterQueryEngine 深度解析【免費下載鏈接】llama_indexLlamaIndex is the leading document agent and OCR platform項目地址: https://gitcode.com/GitHub_Trending/ll/llama_index本篇技術(shù)指南圍繞 LlamaIndex 核心庫中RetrieverRouterQueryEngine基于檢索器的路由查詢引擎展開講解它如何借助檢索器Retriever從候選 Node 中篩選出目標查詢引擎、將 Node 映射為 QueryEngine 并完成最終查詢的完整機制。讀完本文你將掌握該 API 的構(gòu)造參數(shù)、底層執(zhí)行鏈路、異步行為理解它為何被標記為 beta 并在后續(xù)演進中被ToolRetrieverRouterQueryEngine取代以及如何根據(jù)倉庫源碼判斷何時該使用它、何時應(yīng)遷移到推薦的替代方案。從一個 API 引用出發(fā)該引擎是什么關(guān)聯(lián)文檔是 LlamaIndex 自動生成的 API Reference 頁它通過 mkdocstrings 指令把llama_index.core.query_engine模塊中RetrieverRouterQueryEngine類的完整簽名、文檔字符串與成員索引渲染出來。其技術(shù)本體位于核心庫源碼 router_query_engine.py。要理解該引擎需要先區(qū)分兩類路由范式RouterQueryEngine基于 Selector 路由給定一批已包裝為QueryEngineTool的候選查詢引擎用一個BaseSelector通常是 LLM selector根據(jù)每個候選的元數(shù)據(jù)與用戶查詢選擇一個或多個引擎執(zhí)行查詢見 router.md。RetrieverRouterQueryEngine基于 Retriever 路由不預(yù)先固定候選引擎列表而是先用一個BaseRetriever去檢索出相關(guān) Node每個 Node 再被轉(zhuǎn)換為ToolMetadata并據(jù)此取回對應(yīng)的查詢引擎構(gòu)成QueryEngineTool最終只執(zhí)行被選中引擎的查詢見 retriever_router.md 所述內(nèi)容。從源碼的類注釋可以確認其定位Use a retriever to select a set of Nodes. Each node will be converted into a ToolMetadata object, and also used to retrieve a query engine, to form a QueryEngineTool.同時源碼明確標注了兩條重要狀態(tài)信息已棄用deprecated注釋指明please use our new ToolRetrieverRouterQueryEnginebeta 特性注釋提示W(wǎng)e are figuring out the right interface between the retriever and query engine即檢索器與查詢引擎之間的接口仍處于探索期。因此把它當作理解 LlamaIndex 路由演進歷史、以及閱讀舊版代碼時的關(guān)鍵 API 最合適新代碼應(yīng)優(yōu)先考慮替代實現(xiàn)。構(gòu)造簽名與參數(shù)語義該類繼承自BaseQueryEngine構(gòu)造器接收三個參數(shù)RetrieverRouterQueryEngine( retriever: BaseRetriever, # 檢索器負責根據(jù)查詢?nèi)〕龊蜻x Node node_to_query_engine_fn: Callable, # 將單個 Node 映射為查詢引擎的回調(diào)函數(shù) callback_manager: Optional[CallbackManager] None, )各參數(shù)在源碼中的實際作用如下retriever一個BaseRetriever實例_query執(zhí)行時首先調(diào)用self._retriever.retrieve(query_bundle)得到帶分數(shù)的 Node 列表NodeWithScore。node_to_query_engine_fn可調(diào)用對象接收一個BaseNode返回一個QueryEngine。它是Node → 查詢引擎的橋接邏輯典型實現(xiàn)是根據(jù) Node 的內(nèi)容、元數(shù)據(jù)或tool_name從本地注冊表/對象索引中取出對應(yīng)引擎其底層思想與default_node_to_metadata_fn中依賴 Node 元數(shù)據(jù)tool_name的思路一致見 router_query_engine.py 中對 ToolMetadata 構(gòu)造的約定。callback_manager可選的回調(diào)管理器_get_prompt_modules會把self._retriever作為可提示子模塊暴露出去說明該引擎的提示詞體系主要來自其內(nèi)部檢索器。構(gòu)造器直接保存上述參數(shù)并調(diào)用super().__init__(callback_manager)完成基類初始化本身不引入額外狀態(tài)邏輯非常輕量。底層執(zhí)行鏈路從檢索到查詢的一步路由該引擎的查詢過程非常短平快核心邏輯集中在_query方法router_query_engine.pynodes_with_score self._retriever.retrieve(query_bundle) if len(nodes_with_score) 1: raise ValueError(Retrieved more than one node.) node nodes_with_score[0].node query_engine self._node_to_query_engine_fn(node) return query_engine.query(query_bundle)整個鏈路可以拆解為四步檢索把用戶的QueryBundle包含查詢字符串及可選的自定義嵌入/節(jié)點過濾器交給retriever.retrieve()得到候選NodeWithScore列表強制單選當前實現(xiàn)只支持檢索出恰好一個 Node一旦超過一個便拋出ValueError(Retrieved more than one node.)。源碼中以# TODO: for now we only support retrieving one node明確標注了這一限制——這是該實現(xiàn)半成品屬性的最直接體現(xiàn)Node → QueryEngine 映射調(diào)用node_to_query_engine_fn(node)取回真正要執(zhí)行的查詢引擎執(zhí)行查詢返回query_engine.query(query_bundle)的結(jié)果。值得注意的是_query全程沒有回調(diào)事件包裝對比同一文件里RouterQueryEngine._query會觸發(fā)CBEventType.QUERY事件并把selector_result寫入響應(yīng)元數(shù)據(jù)router_query_engine.py說明該引擎在可觀測性上是相對薄弱的雛形實現(xiàn)。異步路徑同步的封裝異步方法_aquery的實現(xiàn)更簡練——它直接委托給同步_queryasync def _aquery(self, query_bundle: QueryBundle) - RESPONSE_TYPE: return self._query(query_bundle)即調(diào)用await engine.aquery(...)時實際是在事件循環(huán)里同步執(zhí)行檢索、映射與查詢內(nèi)部并不會并發(fā)調(diào)用檢索器或子引擎。這意味著在異步應(yīng)用中使用它時檢索/查詢階段會阻塞事件循環(huán)不適合高并發(fā)場景。說明性的端到端用法下面的示例基于上述構(gòu)造語義演示一種自洽的組裝方式不依賴未公開接口僅用于說明回調(diào)函數(shù)的典型形態(tài)from llama_index.core.query_engine import RetrieverRouterQueryEngine # registry: dict[str, QueryEngine] —— 按 node.metadata[tool_name] 索引的引擎表 def node_to_query_engine(node): tool_name node.metadata[tool_name] return registry[tool_name] router RetrieverRouterQueryEngine( retrievermy_retriever, # 保證只召回 1 個 node 的 BaseRetriever node_to_query_engine_fnnode_to_query_engine, ) response router.query(What is LlamaIndex?) print(response)需要再次強調(diào)當前實現(xiàn)要求檢索結(jié)果恰好為一個 Node因此配套的檢索器必須在召回層就做好 top-1 截斷或保證相關(guān)性唯一否則引擎會直接拋錯。模塊同源的兄弟引擎與演進路線RetrieverRouterQueryEngine與另外兩個引擎同處一個文件router_query_engine.py共同構(gòu)成了 LlamaIndex 查詢引擎多選一/多選多的完整能力帶RouterQueryEngineSelector 驅(qū)動的精確路由RouterQueryEngine把候選引擎包裝為QueryEngineTool交給BaseSelectorselect_multiFalse時單選擇器基于各引擎的ToolMetadata描述與用戶查詢做 LLM 判斷from_defaults通過get_selector_from_llm(llm, is_multiselect_multi)自動創(chuàng)建選擇器。當選擇器命中多個引擎時會逐一執(zhí)行并用TreeSummarizecombine_responses/acombine_responses合并多個子響應(yīng)最后把selector_result掛到響應(yīng)metadata上。異步路徑_aquery使用asyncio.gather并行執(zhí)行所有被選中子引擎。它是當前文檔對應(yīng)類同目錄下的正式替代方向之一參見 router.md。ToolRetrieverRouterQueryEngine官方推薦的演進替代這正是棄用注釋中點名的新實現(xiàn)參見 tool_retriever_router.md。它的關(guān)鍵差異在于構(gòu)造參數(shù)從BaseRetriever node_to_query_engine_fn變?yōu)镺bjectRetriever[QueryEngineTool]即直接檢索已包裝好的工具對象工具本身攜帶query_engine與metadata徹底消除了手寫 Node→Engine 回調(diào)的環(huán)節(jié)檢索返回的是多個QueryEngineTool引擎會把它們?nèi)繄?zhí)行同步串行、異步asyncio.gather并發(fā)超過一個結(jié)果時交給內(nèi)置TreeSummarize匯總響應(yīng)metadata中記錄retrieved_tools字段可觀測性優(yōu)于舊實現(xiàn)combine_responses/acombine_responses兩個模塊級函數(shù)負責統(tǒng)一合并邏輯收集各子響應(yīng)的source_nodes與文本調(diào)用 summarizer 得到最終響應(yīng)支持Response/PydanticResponse/StreamingResponse等形態(tài)見 router_query_engine.py。從源碼演進看官方把檢索 路由的范式收斂為檢索對象Tool 而非裸 Node 批量執(zhí)行 匯總即ObjectRetriever方案RetrieverRouterQueryEngine是這一范式定型前的中間形態(tài)。三者選型速覽引擎決策依據(jù)候選來源執(zhí)行策略狀態(tài)RetrieverRouterQueryEngineRetriever 召回單個 NodeNode →node_to_query_engine_fn回調(diào)僅執(zhí)行命中的 1 個引擎超過 1 個拋錯beta、已棄用RouterQueryEngineLLM Selector 讀元數(shù)據(jù)選擇預(yù)置QueryEngineTool列表單選或全選多選時 TreeSummarize 匯總穩(wěn)定路徑ToolRetrieverRouterQueryEngineObjectRetriever 召回工具可檢索的QueryEngineTool對象庫召回即執(zhí)行多結(jié)果匯總推薦替代與相關(guān) API 文檔及測試的關(guān)系相關(guān) API Reference本引擎與 router.mdRouterQueryEngine、tool_retriever_router.mdToolRetrieverRouterQueryEngine、retriever.mdRetrieverQueryEngine構(gòu)成同一 API 組的完整參照可在閱讀時相互對照。測試覆蓋情況倉庫測試 test_router_query_engine.py 僅直接測試了RouterQueryEngine與ToolRetrieverRouterQueryEngine的異步非阻塞特性例如通過后臺任務(wù)計時斷言aquery不長時間霸占事件循環(huán)并未為RetrieverRouterQueryEngine編寫專門測試——這與它 beta/棄用的定位一致。若你在舊代碼庫中遇到它可把它視為一個僅具單節(jié)點路由能力的過渡組件在升級路徑上應(yīng)優(yōu)先遷移到ToolRetrieverRouterQueryEngine。小結(jié)RetrieverRouterQueryEngine是 LlamaIndex 路由查詢引擎家族中一個具有歷史意義的 API它首次把檢索器召回 Node 元數(shù)據(jù) 查詢引擎路由串成一條管線但其單 Node 限制、無回調(diào)事件包裝、異步同步化等特征都表明它只是一個未定型的 beta 實現(xiàn)。理解它的源碼實現(xiàn)有助于看清后續(xù)RouterQueryEngineSelector 路由與ToolRetrieverRouterQueryEngine對象檢索路由各自解決的問題邊界前者解決候選引擎元數(shù)據(jù)如何被 LLM 閱讀后者解決大量引擎如何被高效檢索與批量執(zhí)行。在新的代碼中應(yīng)遵循源碼中的棄用指引優(yōu)先使用 ToolRetrieverRouterQueryEngine?！久赓M下載鏈接】llama_indexLlamaIndex is the leading document agent and OCR platform項目地址: https://gitcode.com/GitHub_Trending/ll/llama_index創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考