You can combine a Retriever with a Reader in your pipeline to speed up the search. The Retriever passes the Documents it selected on to the Reader. This way, it saves the Reader from doing more work than it needs to.

In a query pipeline, when given a query, the Retriever sifts through the Documents in the DocumentStore, scores each Document for its relevance to the query, and returns the top candidates. Retriever and DocumentStore are tightly coupled. When configuring a Retriever, you must always specify its DocumentStore.

When used in indexing pipelines, vector-based Retrievers (DensePassagerRetriever and EmbeddingRetriever) take Documents as input, and for each Document, they calculate its vector representation (embedding). This embedding is stored as part of the Document in the DocumentStore.
If you're using a keyword-based Retriever (BM25Retriever or TfidfRetriever) in your indexing pipeline, no embeddings are calculated, and the Retriever creates a keyword-based index that it then uses to look up the Documents quickly.

Basic Information

• Pipeline type: Used in query pipelines and in indexing pipelines.
• In indexing pipelines:
  • Nodes that can precede it: PreProcessor
  • Nodes that can follow it: DeepsetCloudDocumentStore
  • Node input: Documents
  • Node output: Documents
• In query pipelines:
  • Nodes that can precede it: QueryClassifier
  • Nodes that can follow it: Reader, Ranker, PromptNode, JoinDocuments
  • Node input: Query
  • Node output: Documents
• Available node classes: BM25Retriever, CNStaticFilterRetriever, DensePassageRetriever, EmbeddingRetriever, FilterRetriever, FileSimilarityRetriever, TfidfRetriever

Retrievers Overview

There are two categories of retrievers: vector-based (dense) and keyword-based (sparse) retrievers.

Vector-Based Retrievers

Vector-based retrievers work with document embeddings. They embed both the documents and the query using deep neural networks, and then return the documents most similar to the query as top candidates.

Main features:

• Powerful but more expensive computationally, especially during indexing.
• Trained using labeled datasets.
• Language-specific.
• Use transformer-based encoders that take word order and syntax into account.
• Can build strong semantic representations of text.
• Indexing is done by processing all documents through a neural network and storing the resulting vectors. Requires significant computational power and time.

Available vector-based retrievers:

• EmbeddingRetriever
• CNStaticFilterRetriever
• DensePassageRetriever

Keyword-Based Retrievers

Keyword-based retrievers look for keywords shared between the documents and the query.

Main features:

• Simple but effective.
• Don't need to be trained.
• Work on any language.
• Don't take word order and syntax into account.
• Can't handle out-of-vocabulary words.
• Good for use cases where precise wording matters.
• Indexing is done by creating an inverted index, it's faster and less expensive than in vector-based retrievers.

Available keyword-based retrievers:

• TfidfRetriever
• BM25Retriever
• FilterRetriever

FileSimilarityRetriever

This retriever is flexible - you can configure it as keyword-based, vector-based, or hybrid. This depends on the primary and secondary retrievers you select for it. It compares the similarity of files by using these files as queries. It then generates a list of the most similar documents from each file query. You can configure the query input to accept the file ID, URL, file name, and more. The documents it returns are ranked in order of their similarity to the query file, with the most similar ones listed first.

To determine file similarity, the FileSimilarityRetriever employs a technique known as reciprocal rank fusion. This method takes each document derived from the query and conducts a separate retrieval operation for it. It then analyzes the results from each document query and assesses the overall file similarity. You can read about a similar approach in the PARM paper by Althammer et al. 2022.

Choosing the Right Retriever

Here are a couple of things to consider when choosing a retriever:

• Do you have a GPU available?
  • Yes: We recommend using the EmbeddingRetriever.
  • No: We recommend using the BM25Retriever.

Usage Examples

A Retriever always takes the DeepsetCloudDocumentStore as an argument.

...
components:
	- name: DocumentStore # First, configure the DocumentStore for the Retriever
    type: DeepsetCloudDocumentStore
	- name: Retriever 
    type: EmbeddingRetriever # Uses a Transformer model to encode the document and the query
    params:
      document_store: DocumentStore
      embedding_model: sentence-transformers/multi-qa-mpnet-base-dot-v1 # Model optimized for semantic search
      model_format: sentence_transformers
      top_k: 20 
  ...
  pipelines:
  - name: query
    nodes:
      - name: Retriever
        inputs: [Query]
      - name: Reader
        inputs: [Retriever]
  - name: indexing
    nodes:
      - name: FileTypeClassifier
        inputs: [File]
      - name: TextConverter
        inputs: [FileTypeClassifier.output_1] 
      - name: PDFConverter
        inputs: [FileTypeClassifier.output_2] 
      - name: Preprocessor
        inputs: [TextConverter, PDFConverter]
      - name: Retriever
        inputs: [Preprocessor]
      - name: DocumentStore
        inputs: [Retriever]

components:
  - name: DocumentStore
    type: DeepsetCloudDocumentStore # The only supported document store in deepset Cloud
    params: 
      similarity: cosine
  - name: EmbeddingRetriever # Selects the most relevant documents from the document store
    type: EmbeddingRetriever # Uses one Transformer model to encode the document and the query
    params:
      document_store: DocumentStore
      embedding_model: BAAI/bge-base-en-v1.5 # Model optimized for semantic search
      model_format: sentence_transformers
      top_k: 20 # The number of results to return
  - name: FileSimilarityRetriever
    type: FileSimilarityRetriever
    params:
      document_store: DocumentStore
      primary_retriever: EmbeddingRetriever
      top_k: 4
      file_aggregation_key: file_name
      max_num_queries: 50 
      ....
 pipelines:
  - name: query
    nodes:
      - name: FileSimilarityRetriever
        inputs: [Query]
        
        # Here you'd need to define the indexing pipeline
  

For arguments you can specify for each retriever type, see the Arguments.

Parameters

Here are the parameters each retriever type can take when you configure it in the pipeline YAML.

BM25Retriever Parameters

CNStaticFilterEmbeddingRetriever Parameters

Like EmbeddingRetriever, it requires a model to run. It takes exactly the same parameters as EmbeddingRetriever with an additional one filters.

DensePassageRetriever (DPR) Parameters

You must choose the models you want this retriever to use to convert the documents into embeddings and then another model to convert the query into embeddings.

These are the parameters you can specify for DPR in pipeline YAML:

EmbeddingRetriever Parameters

You must specify the model you want this retriever to use to embed the query and the documents. The embedding model can be a Hugging Face model, an OpenAI model (like "aga", "babbage", "curie"), a Cohere model ("embed-english-v2.0", "embed-english-light-v2.0", "embed-multilingual-v2.0"), or an AWS Bedrock model ("amazon.titan-embed-text-v1", "cohere.embed-english-v3", "cohere.embed-multilingual-v3").

You can also have a look at the list of models that we recommend.

To use models from a provider, Connect to Model Providers first.

These are the parameters you can pass in the pipeline YAML:

FileSimilarityRetriever Parameters

You can configure the following parameters in pipeline YAML:

FilterRetriever Parameters

These are the parameters you can specify in pipeline YAML:

TfidfRetriever Parameters

These are the parameters you can configure in pipeline YAML: