VespaEmbeddingRetriever

Retrieve documents from a VespaDocumentStore using dense vector similarity. Use this component in query pipelines to find semantically similar documents stored in Vespa, a high-performance search engine built for large-scale vector and hybrid retrieval.

Embedding Models in Pipelines and Indexes

The embedding model you use to embed documents in your index must be the same as the embedding model you use to embed the query in your pipeline.

This means the embedders for your indexes and pipelines must match. For example, if you use CohereDocumentEmbedder to embed your documents, you should use CohereTextEmbedder with the same model to embed your queries.

Key Features

• Performs nearest-neighbor vector search using Vespa's nearestNeighbor YQL operator.
• Configurable Vespa rank profile for post-retrieval scoring (for example semantic using closeness(field, embedding)).
• Configurable targetHits parameter to control the number of candidates considered per content node.
• Supports Haystack metadata filters translated into Vespa YQL.
• Designed to work with your own Vespa application schema.

Configuration

Add Workspace-Level Integration

1. Click your profile icon and choose Settings.
2. Go to Workspace>Integrations.
3. Find the provider you want to connect and click Connect next to them.
4. Enter the API key and any other required details.
5. Click Connect. You can use this integration in pipelines and indexes in the current workspace.

Add Organization-Level Integration

1. Click your profile icon and choose Settings.
2. Go to Organization>Integrations.
3. Find the provider you want to connect and click Connect next to them.
4. Enter the API key and any other required details.
5. Click Connect. You can use this integration in pipelines and indexes in all workspaces in the current organization.

1. Deploy a Vespa application with a schema that includes a tensor field for embeddings and a rank profile for semantic retrieval.
2. Configure a VespaDocumentStore in your pipeline, specifying the Vespa url, schema, and namespace matching your application.
3. Drag the VespaEmbeddingRetriever component onto the canvas from the Component Library.
4. Connect an embedder component to provide query_embedding as input.
5. Connect the retriever output to downstream components such as PromptBuilder.

Connections

VespaEmbeddingRetriever receives a query_embedding (list of floats) from a text embedder such as SentenceTransformersTextEmbedder. It outputs a list of Document objects you can connect to PromptBuilder or other downstream components.

Source Code

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

Usage Examples

Basic Configuration

  VespaEmbeddingRetriever:
    type: haystack_integrations.components.retrievers.vespa.embedding_retriever.VespaEmbeddingRetriever
    init_parameters:
      document_store: VespaDocumentStore
      top_k: 5
      ranking: semantic

Using the Component in a Pipeline

# haystack-pipeline
components:
  text_embedder:
    type: haystack_integrations.components.embedders.sentence_transformers.SentenceTransformersTextEmbedder
    init_parameters:
      model: sentence-transformers/all-MiniLM-L6-v2

  document_store:
    type: haystack_integrations.document_stores.vespa.document_store.VespaDocumentStore
    init_parameters:
      url: http://localhost:8080
      schema: doc
      namespace: doc

  retriever:
    type: haystack_integrations.components.retrievers.vespa.embedding_retriever.VespaEmbeddingRetriever
    init_parameters:
      document_store: document_store
      top_k: 5
      ranking: semantic
      query_tensor_name: query_embedding
      target_hits: 100

connections:
- sender: text_embedder.embedding
  receiver: retriever.query_embedding

inputs:
  query:
  - text_embedder.text

outputs:
  documents: retriever.documents

Parameters

Inputs

Parameter	Type	Description
query_embedding	List[float]	The query embedding vector to search for similar documents.
filters	Optional[Dict[str, Any]]	Filters to apply when retrieving documents.
top_k	Optional[int]	The maximum number of documents to retrieve. Overrides the init-time value.

Outputs

Parameter	Type	Description
documents	List[Document]	A list of the most similar documents from the document store.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	VespaDocumentStore		The Vespa document store to retrieve documents from.
filters	Optional[Dict[str, Any]]	None	Default filters to apply when retrieving documents.
top_k	int	10	The maximum number of documents to retrieve.
ranking	Optional[str]	"semantic"	Vespa rank profile to use after nearest-neighbor retrieval. Pass None to use the schema default.
query_tensor_name	str	"query_embedding"	Name of the query tensor in YQL and in your rank profile's input.query(...) expression.
target_hits	Optional[int]	None	Number of candidates considered per content node before first-phase ranking. Higher values improve recall at the cost of performance.

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_embedding	List[float]		The embedding vector to search with.
filters	Optional[Dict[str, Any]]	None	Runtime filters to apply.
top_k	Optional[int]	None	Maximum number of documents to retrieve. Overrides the init-time value.

Related Information

• VespaKeywordRetriever
• Pipeline Components