Implementation:Run llama Llama index RouterRetriever

Overview

The RouterRetriever selects one or more candidate retrievers to execute a query based on a selector component. It wraps multiple retrievers behind a routing layer that uses metadata descriptions to determine which retriever(s) are most appropriate for a given query. Both synchronous and asynchronous retrieval are supported, with asynchronous multi-retriever queries executing in parallel via asyncio.gather.

Source File: llama-index-core/llama_index/core/retrievers/router_retriever.py (142 lines)

Module: llama_index.core.retrievers.router_retriever

Class Definition

class RouterRetriever(BaseRetriever):
    """
    Router retriever.

    Selects one (or multiple) out of several candidate retrievers to execute a query.
    """

Dependencies

Module	Import
`llama_index.core.base.base_retriever`	`BaseRetriever`
`llama_index.core.base.base_selector`	`BaseSelector`
`llama_index.core.callbacks.schema`	`CBEventType`, `EventPayload`
`llama_index.core.llms.llm`	`LLM`
`llama_index.core.prompts.mixin`	`PromptMixinType`
`llama_index.core.schema`	`IndexNode`, `NodeWithScore`, `QueryBundle`
`llama_index.core.selectors.utils`	`get_selector_from_llm`
`llama_index.core.settings`	`Settings`
`llama_index.core.tools.retriever_tool`	`RetrieverTool`

Constructor

def __init__(
    self,
    selector: BaseSelector,
    retriever_tools: Sequence[RetrieverTool],
    llm: Optional[LLM] = None,
    objects: Optional[List[IndexNode]] = None,
    object_map: Optional[dict] = None,
    verbose: bool = False,
) -> None

Parameter	Type	Default	Description
`selector`	`BaseSelector`	required	The selector component that chooses retrievers based on metadata and query
`retriever_tools`	`Sequence[RetrieverTool]`	required	Candidate retrievers wrapped as tools to expose metadata for the selector
`llm`	`Optional[LLM]`	`None`	Optional LLM instance (defaults to `Settings.llm`)
`objects`	`Optional[List[IndexNode]]`	`None`	Optional index node objects
`object_map`	`Optional[dict]`	`None`	Optional object map
`verbose`	`bool`	`False`	Whether to enable verbose logging

The constructor extracts .retriever and .metadata from each RetrieverTool into separate lists for internal use.

Factory Method

from_defaults

@classmethod
def from_defaults(
    cls,
    retriever_tools: Sequence[RetrieverTool],
    llm: Optional[LLM] = None,
    selector: Optional[BaseSelector] = None,
    select_multi: bool = False,
) -> "RouterRetriever"

Convenience constructor that auto-creates a selector using get_selector_from_llm() when no explicit selector is provided. The select_multi flag controls whether the selector can choose multiple retrievers.

Core Methods

_retrieve (synchronous)

def _retrieve(self, query_bundle: QueryBundle) -> List[NodeWithScore]

Fires a CBEventType.RETRIEVE callback event.
Calls self._selector.select() with the retriever metadata and query.
Single selection: If only one retriever is selected, calls selected_retriever.retrieve(query_bundle).
Multi selection: If multiple retrievers are selected, calls each sequentially and merges results into a dictionary keyed by node ID (deduplicating).
Returns the merged results as a list.

_aretrieve (asynchronous)

async def _aretrieve(self, query_bundle: QueryBundle) -> List[NodeWithScore]

Async variant with the same logic, except:

Uses self._selector.aselect() for async selection.
When multiple retrievers are selected, all aretrieve() calls are gathered in parallel using asyncio.gather(*tasks).
Single retriever case uses await selected_retriever.aretrieve().

_get_prompt_modules

def _get_prompt_modules(self) -> PromptMixinType

Returns the selector as a prompt sub-module under the key "selector".

Result Deduplication

Both sync and async paths store results in a dictionary keyed by n.node.node_id. This ensures that if multiple selected retrievers return the same node, only one copy is kept (the last one encountered).

Retrieval Flow

Query
  -> Selector chooses retriever(s) based on metadata descriptions
     -> Single retriever: execute directly
     -> Multiple retrievers: execute all (parallel in async), merge results
  -> Return deduplicated NodeWithScore list

Design Notes

The RetrieverTool wrapper is essential because the selector needs access to retriever metadata (name, description) to make routing decisions.
The selector can be any implementation of BaseSelector -- LLM-based, embedding-based, or pydantic-based.
Results are logged with the selector's reason for the chosen retriever index.
The callback manager wraps the entire retrieval (including selection) in a single event span.

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment