AzureAISearchHybridRetriever

Retrieve documents from an AzureAISearchDocumentStore using a combination of BM25 keyword search and vector similarity search.

Key Features

• Hybrid retrieval combining BM25 keyword search and dense vector search from Azure AI Search.
• Configurable number of results with top_k.
• Supports metadata filtering to narrow down the search space.
• Supports advanced Azure AI Search options including semantic ranking.
• Configurable filter policy (replace or merge) for runtime filters.

Configuration

1. Drag the AzureAISearchHybridRetriever component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   • Configure the AzureAISearchDocumentStore with your Azure AI Search instance details.
   • Set top_k to control the maximum number of documents to retrieve.
4. Go to the Advanced tab to configure filter_policy and additional Azure AI Search options.

Connections

AzureAISearchHybridRetriever receives both a text query string and a query embedding vector as inputs. Connect these from the Input component and a text embedder respectively. It sends retrieved documents to downstream components such as PromptBuilder or a ranker.

Source Code

To check this component's source code, open hybrid_retriever.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  AzureAISearchHybridRetriever:
    type: haystack_integrations.components.retrievers.azure_ai_search.hybrid_retriever.AzureAISearchHybridRetriever
    init_parameters:
      top_k: 10
      document_store:
        type: haystack_integrations.document_stores.azure_ai_search.document_store.AzureAISearchDocumentStore
        init_parameters:
          api_key:
            type: env_var
            env_vars:
            - AZURE_SEARCH_API_KEY
            strict: false
          azure_endpoint:
            type: env_var
            env_vars:
            - AZURE_SEARCH_SERVICE_ENDPOINT
            strict: false
          index_name: my-index

Parameters

Inputs

Parameter	Type	Description
query	str	The text query for keyword-based search.
query_embedding	List[float]	The embedding of the query for vector-based search.
filters	Optional[Dict[str, Any]]	Filters to apply to the search results.
top_k	Optional[int]	The maximum number of documents to return.

Outputs

Parameter	Type	Description
documents	List[Document]	The retrieved documents.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	AzureAISearchDocumentStore		An instance of AzureAISearchDocumentStore.
filters	Optional[Dict[str, Any]]	None	Default filters applied when running the retriever.
top_k	int	10	The maximum number of documents to retrieve.
filter_policy	Union[str, FilterPolicy]	FilterPolicy.REPLACE	Policy for how runtime filters are applied relative to init-time filters.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
query	str		The text query for keyword-based search.
query_embedding	List[float]		The embedding of the query for vector-based search.
filters	Optional[Dict[str, Any]]	None	Filters to apply at query time.
top_k	Optional[int]	None	Override the init-time top_k setting.

Related Information

• AzureAISearchEmbeddingRetriever
• AzureAISearchBM25Retriever
• Pipeline Components