CohereRanker

Ranks documents by their semantic similarity to the query using Cohere models. Documents are ordered from most to least relevant.

Key Features

• Ranks documents using Cohere's reranking models.
• Returns documents in descending order of semantic relevance.
• Configurable top_k to limit the number of returned documents.
• Supports embedding meta fields for richer reranking context.
• For a list of supported models, see the Cohere documentation.
• Works in hybrid retrieval pipelines alongside BM25 and embedding retrievers.

Configuration

Authentication

To use this component, connect Haystack Platform with Cohere first. For detailed instructions, see Use Cohere Models.

1. Drag the CohereRanker component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. On the General tab:
   1. Enter the model name, for example rerank-v3.5.
4. Go to the Advanced tab to configure the API key, API base URL, top_k, and maximum tokens per document.

Connections

CohereRanker accepts a query string, a list of Document objects (documents), and an optional top_k integer as inputs. It outputs a ranked list of Document objects (documents).

Connect a retriever's documents output to the documents input. Connect the ranked documents output to a PromptBuilder or other downstream components.

Usage Example

Using the Component in a Pipeline

This is an example of a document search pipeline where CohereRanker receives joined documents from both a keyword and a semantic retriever. It then ranks the documents based on their similarity to the user query and outputs them as the final result.

components:
  bm25_retriever:
    type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          use_ssl: true
          verify_certs: false
          hosts:
          - ${OPENSEARCH_HOST}
          http_auth:
          - ${OPENSEARCH_USER}
          - ${OPENSEARCH_PASSWORD}
          embedding_dim: 768
          similarity: cosine
          index: ''
          max_chunk_bytes: 104857600
          return_embedding: false
          method:
          mappings:
          settings:
          create_index: true
          timeout:
      top_k: 20
  embedding_retriever:
    type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          use_ssl: true
          verify_certs: false
          hosts:
          - ${OPENSEARCH_HOST}
          http_auth:
          - ${OPENSEARCH_USER}
          - ${OPENSEARCH_PASSWORD}
          embedding_dim: 768
          similarity: cosine
          index: ''
          max_chunk_bytes: 104857600
          return_embedding: false
          method:
          mappings:
          settings:
          create_index: true
          timeout:
      top_k: 20
  document_joiner:
    type: haystack.components.joiners.document_joiner.DocumentJoiner
    init_parameters:
      join_mode: concatenate
  DeepsetNvidiaTextEmbedder:
    type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
    init_parameters:
      model: intfloat/multilingual-e5-base
      prefix: ''
      suffix: ''
      truncate:
      normalize_embeddings: false
      timeout:
      backend_kwargs:
  CohereRanker:
    type: haystack_integrations.components.rankers.cohere.ranker.CohereRanker
    init_parameters:
      model: rerank-v3.5
      top_k: 10
      api_key:
        type: env_var
        env_vars:
        - COHERE_API_KEY
        - CO_API_KEY
        strict: false
      api_base_url: https://api.cohere.com
      meta_fields_to_embed:
      meta_data_separator: \n
      max_tokens_per_doc: 4096

connections:
- sender: bm25_retriever.documents
  receiver: document_joiner.documents
- sender: embedding_retriever.documents
  receiver: document_joiner.documents
- sender: DeepsetNvidiaTextEmbedder.embedding
  receiver: embedding_retriever.query_embedding
- sender: document_joiner.documents
  receiver: CohereRanker.documents

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - bm25_retriever.query
  - DeepsetNvidiaTextEmbedder.text
  - CohereRanker.query
  filters:
  - bm25_retriever.filters
  - embedding_retriever.filters

outputs:
  documents: CohereRanker.documents

Parameters

Inputs

Parameter	Type	Default	Description
query	str		The user query.
documents	List[Document]		The documents to rank.
top_k	Optional[int]	None	The maximum number of documents you want the Ranker to return.

Outputs

Parameter	Type	Default	Description
documents	List[Document]		List of Documents most similar to the given query in descending order of similarity.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
model	str	rerank-v3.5	Cohere model name. Check the list of supported models in the Cohere documentation.
top_k	int	10	The maximum number of documents to return.
api_key	Secret	Secret.from_env_var(['COHERE_API_KEY', 'CO_API_KEY'])	Cohere API key.
api_base_url	str	https://api.cohere.com	The base URL of the Cohere API.
meta_fields_to_embed	Optional[List[str]]	None	List of meta fields that should be concatenated with the document content for reranking.
meta_data_separator	str	\n	Separator used to concatenate the meta fields to the Document content.
max_tokens_per_doc	int	4096	The maximum number of tokens to embed for each document defaults to 4096.

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		Query string.
documents	List[Document]		List of documents to rank.
top_k	Optional[int]	None	The maximum number of documents you want the Ranker to return.