Haystack

https://docs.haystack.deepset.ai/docs
Admin
Haystack is an open-source AI orchestration framework for building production-ready AI Agents,...
Tokens:803,225
Snippets:5,229
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies for pipeline example

Source: https://docs.haystack.deepset.ai/docs/toppsampler

Install the required packages for the pipeline example: sentence-transformers-haystack and serperdev-haystack.

```shell
pip install sentence-transformers-haystack serperdev-haystack  
```

--------------------------------

### Install serperdev-haystack package

Source: https://docs.haystack.deepset.ai/docs/agents

The examples use the SerperDev web search component from the serperdev-haystack package, which must be installed to run them.

```shell
pip install serperdev-haystack  

```

--------------------------------

### Install parallel-haystack and set API key

Source: https://docs.haystack.deepset.ai/docs/parallelchatgenerator

Install the integration and set the PARALLEL_API_KEY environment variable before running the examples.

```bash
pip install parallel-haystack  

export PARALLEL_API_KEY="YOUR_PARALLEL_API_KEY"  

```

--------------------------------

### Install pipeline dependencies

Source: https://docs.haystack.deepset.ai/docs/gotenbergfileconverter

Install the additional dependencies required for the pipeline example: pypdf and nltk.

```shell
pip install gotenberg-haystack pypdf nltk
```

--------------------------------

### Install qdrant-haystack integration

Source: https://docs.haystack.deepset.ai/docs/huggingfaceteisparsetextembedder

Install the additional integration required for using QdrantSparseEmbeddingRetriever in the pipeline example.

```shell
pip install qdrant-haystack  

```

--------------------------------

### Install transformers and transformers-haystack packages

Source: https://docs.haystack.deepset.ai/docs/fastembedlateinteractionranker

Installation commands for the additional packages required by the pipeline example: 'transformers[torch]' and 'transformers-haystack'.

```shell
pip install "transformers[torch]"  
```

```shell
pip install transformers-haystack  
```

--------------------------------

### Run TypeSafeDocumentClassifier with Ollaya locally

Source: https://docs.haystack.deepset.ai/docs/typesafedocumentclassifier

Shows Docker commands to start Ollaya and pull a model, then initializes the classifier with model, local API key, and api_base_url. Ollaya accepts any non-empty API key unless configured.

```shell
docker run -d --name ollaya -p 11435:11435 -v ollaya:/home/ollaya/.ollaya ghcr.io/ollaya-dev/ollaya

docker exec ollaya ollaya pull laya:en
```

```python
from haystack.utils import Secret

from haystack_integrations.components.classifiers.typesafe import (
    TypeSafeDocumentClassifier,
)

classifier = TypeSafeDocumentClassifier(
    questions={
        "refund": {
            "type": "noul",
            "instructions": "Is the customer asking for a refund?",
        }
    },
    model="laya:en",
    api_key=Secret.from_token("local"),
    api_base_url="http://localhost:11435",
)
```

--------------------------------

### Standalone YouComWebSearch usage

Source: https://docs.haystack.deepset.ai/docs/youcomwebsearch

Quick example of using YouComWebSearch to search the web and return a list of Documents. No API key is needed to get started.

```python
from haystack_integrations.components.websearch.youcom import YouComWebSearch

web_search = YouComWebSearch(top_k=5)

query = "What is Haystack by deepset?"

response = web_search.run(query=query)

for doc in response["documents"]:
    print(doc.content)
```

--------------------------------

### Connect components with connect() syntax examples

Source: https://docs.haystack.deepset.ai/docs/creating-pipelines

Shows the syntax for connecting components, including shorthand when components have single inputs/outputs, and specifying inputs when needed. Includes an example for the semantic document search pipeline.

```python
# This is the syntax to connect components. Here you're connecting output1 of component1 to input1 of component2:  
pipeline.connect("component1.output1", "component2.input1")  
  
# If both components have only one output and input, you can just pass their names:  
pipeline.connect("component1", "component2")  
  
# If one of the components has only one output but the other has multiple inputs,  
# you can pass just the name of the component with a single output, but for the component with  
# multiple inputs, you must specify which input you want to connect  
  
# Here, component1 has only one output, but component2 has multiple inputs:  
pipeline.connect("component1", "component2.input1")  
  
# And here's how it should look like for the semantic document search pipeline we're using as an example:  
pipeline.connect("text_embedder.embedding", "retriever.query_embedding")  
# Because the InMemoryEmbeddingRetriever only has one input, this is also correct:  
pipeline.connect("text_embedder.embedding", "retriever")  
```

--------------------------------

### Install transformers-haystack

Source: https://docs.haystack.deepset.ai/docs/device-management

Install the transformers-haystack integration required for the examples using TransformersChatGenerator.

```bash
pip install transformers-haystack
```

--------------------------------

### Example output of libomp.dylib locations

Source: https://docs.haystack.deepset.ai/docs/faissdocumentstore

Example output showing multiple libomp.dylib copies in a virtual environment.

```text
.venv/lib/pythonX.Y/site-packages/torch/lib/libomp.dylib
.venv/lib/pythonX.Y/site-packages/sklearn/.dylibs/libomp.dylib
.venv/lib/pythonX.Y/site-packages/faiss/.dylibs/libomp.dylib
```

--------------------------------

### Install nvidia-haystack package

Source: https://docs.haystack.deepset.ai/docs/nvidiadocumentembedder

Install the nvidia-haystack package to start using NvidiaDocumentEmbedder.

```shell
pip install nvidia-haystack  
```

--------------------------------

### Manual Tool initialization example with output

Source: https://docs.haystack.deepset.ai/docs/tool

Construct a Tool directly with Tool(...) when you need full control over the JSON schema. The example defines a function, a parameters dict, and creates a Tool, then prints the tool_spec and invokes it. The output shows the tool spec and the result 25.

```python
from haystack.tools import Tool  

  

  

def add(a: int, b: int) -> int:  
    return a + b  

  

  

parameters = {  
    "type": "object",  
    "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},  
    "required": ["a", "b"],  
}  

  

add_tool = Tool(  
    name="addition_tool",  
    description="This tool adds two numbers",  
    parameters=parameters,  
    function=add,  
)  

  

print(add_tool.tool_spec)  

  

print(add_tool.invoke(a=15, b=10))  
```

```text
{  
    ‘name’: ‘addition_tool’,  
    ‘description’: ‘This tool adds two numbers’,  
    ‘parameters’: {  
        ‘type’: ‘object’,  
        ‘properties’: {‘a’: {‘type’: ‘integer’}, ‘b’: {‘type’: ‘integer’}},  
        ‘required’: [‘a’, ‘b’]  
    }  
}  

  

25  
```

--------------------------------

### Installation

Source: https://docs.haystack.deepset.ai/docs/qdrantsparseembeddingretriever

Install the qdrant-haystack package to use the QdrantSparseEmbeddingRetriever.

```APIDOC
## Installation

### Description
Install the qdrant-haystack package to use the QdrantSparseEmbeddingRetriever.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
pip install qdrant-haystack
```

### Response
#### Success Response (200)
No response body.

#### Response Example
```
Successfully installed qdrant-haystack
```
```

--------------------------------

### Install dependencies for MultiFileConverter

Source: https://docs.haystack.deepset.ai/docs/documentpreprocessor

Installs the additional dependencies required for the MultiFileConverter used in the pipeline example.

```shell
pip install pypdf markdown-it-py  mdit_plain trafilatura python-pptx python-docx jq openpyxl tabulate pandas  
```

--------------------------------

### Example agent response

Source: https://docs.haystack.deepset.ai/docs/githubissueviewertool

Example output from the Agent when using GitHubIssueViewerTool, summarizing the GitHub issue.

```bash
The GitHub issue titled "SentenceTransformer no longer accepts 'gpu' as argument" (issue \#123) discusses a problem encountered when using the `EmbeddingRetriever()` function. The user reports that passing the argument `gpu=True` now causes an error because the method that processes this argument does not accept "gpu" anymore; instead, it previously accepted "cuda" without issues.  

  

The user indicates that this change is problematic since it prevents users from instantiating the embedding model with GPU support, forcing them to default to using only the CPU for model execution.  

  

The issue was later closed with a comment indicating it was fixed in another pull request (#124).  
```

--------------------------------

### Install langdetect-haystack package

Source: https://docs.haystack.deepset.ai/docs/branchjoiner

Installs the langdetect-haystack package, which is required to run the language classification examples on this page.

```shell
pip install langdetect-haystack  
```

--------------------------------

### Initialize FAISSDocumentStore and write documents

Source: https://docs.haystack.deepset.ai/docs/faissdocumentstore

Create a FAISSDocumentStore instance with optional index_path for persistence, write documents with embeddings, and save the index.

```python
from haystack import Document

from haystack.document_stores.types import DuplicatePolicy

from haystack_integrations.document_stores.faiss import FAISSDocumentStore


document_store = FAISSDocumentStore(
    index_path="my_faiss_index",  # Optional: enables persistence on disk
    index_string="Flat",
    embedding_dim=768,
)

document_store.write_documents(
    [
        Document(content="This is first", embedding=[0.1] * 768),
        Document(content="This is second", embedding=[0.2] * 768),
    ],
    policy=DuplicatePolicy.OVERWRITE,
)

print(document_store.count_documents())

# Persist index and metadata files (`.faiss` and `.json`)
document_store.save("my_faiss_index")
```

--------------------------------

### Install sentence-transformers-haystack

Source: https://docs.haystack.deepset.ai/docs/alloydbembeddingretriever

Install the sentence-transformers-haystack package to use the Sentence Transformers embedders used in the examples on this page.

```shell
pip install sentence-transformers-haystack
```

--------------------------------

### Example: Combining inputs and outputs

Source: https://docs.haystack.deepset.ai/docs/state

Demonstrates a tool that reads from state via inputs_from_state and writes to state via outputs_to_state, enabling tool chaining.

```APIDOC
## Example: Combining inputs and outputs

### Description
This example builds on the `retrieve_documents` tool. The `process_documents` tool reads `documents` from state via `inputs_from_state` and writes `final_docs` and `final_count` to state via `outputs_to_state`.

### Code
```python
@tool(
    inputs_from_state={"documents": "documents"},
    outputs_to_state={
        "final_docs": {"source": "processed_docs"},
        "final_count": {"source": "processed_count"},
    },
)
def process_documents(
    max_results: Annotated[int, "Maximum number of documents to return"],
    documents: list = None,  # injected from state; LLM does not provide this
) -> dict:
    """Process retrieved documents and return a filtered subset."""
    processed = (documents or [])[:max_results]
    return {"processed_docs": processed, "processed_count": len(processed)}

agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
    tools=[retrieve_documents, process_documents],  # chained through state
    system_prompt="Use the available tools to retrieve and process documents.",
    streaming_callback=print_streaming_chunk,
    state_schema={
        "documents": {"type": list},
        "result_count": {"type": int},
        "last_query": {"type": str},
        "final_docs": {"type": list},
        "final_count": {"type": int},
    },
)

result = agent.run(
    messages=[ChatMessage.from_user("Find and process 3 documents about Python")],
)
print(f"Processed {result['final_count']} documents")
```
```

--------------------------------

### Install arcadedb-haystack integration with pip

Source: https://docs.haystack.deepset.ai/docs/arcadedbdocumentstore

Installs the Haystack ArcadeDB integration package. Run after starting ArcadeDB.

```shell
pip install arcadedb-haystack
```

--------------------------------

### Set up OpenSearchDocumentStore and run OpenSearchMetadataRetriever

Source: https://docs.haystack.deepset.ai/docs/opensearchmetadataretriever

Initializes an OpenSearchDocumentStore with connection parameters, writes three documents with categorical metadata, and runs a metadata retriever in strict mode. The output shows only the metadata fields specified in metadata_fields, excluding content and other metadata.

```python
from haystack import Document  

from haystack_integrations.components.retrievers.opensearch import (  
    OpenSearchMetadataRetriever,  
)  

from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore  

from haystack.document_stores.types import DuplicatePolicy  

  

document_store = OpenSearchDocumentStore(  
    hosts="http://localhost:9200",  
    index="my_index",  
    use_ssl=True,  
    verify_certs=False,  
    http_auth=("admin", "<custom-admin-password>"),  
)  

  

documents = [  
    Document(  
        content="Python programming guide",  
        meta={  
            "category": "Python",  
            "status": "active",  
            "priority": 1,  
            "author": "John Doe",  
        },  
    ),  
    Document(  
        content="Java tutorial",  
        meta={  
            "category": "Java",  
            "status": "active",  
            "priority": 2,  
            "author": "Jane Smith",  
        },  
    ),  
    Document(  
        content="Python advanced topics",  
        meta={  
            "category": "Python",  
            "status": "inactive",  
            "priority": 3,  
            "author": "John Doe",  
        },  
    ),  
]  

  

document_store.write_documents(documents=documents, policy=DuplicatePolicy.SKIP)  

  

retriever = OpenSearchMetadataRetriever(  
    document_store=document_store,  
    metadata_fields=["category", "status"],  
    mode="strict",  
    top_k=10,  
)  

  

result = retriever.run(query="Python")  

  

print(result)  
# {  
#     "metadata": [  
#         {"category": "Python", "status": "active"},  
#         {"category": "Python", "status": "inactive"},  
#     ]  
# }  
```

--------------------------------

### Initialize components

Source: https://docs.haystack.deepset.ai/docs/creating-pipelines

Initialize the Document Store, text embedder, and retriever with any parameters you want to configure.

```python
document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")

text_embedder = SentenceTransformersTextEmbedder()

retriever = InMemoryEmbeddingRetriever(document_store=document_store)
```

--------------------------------

### Create a document store and add documents (LangChain)

Source: https://docs.haystack.deepset.ai/docs/migrating-from-langgraphlangchain-to-haystack

Sets up an in-memory vector store, embeds documents using HuggingFaceEmbeddings, and adds documents. Requires installing langchain-community, langchain-huggingface, and sentence-transformers.

```python
# pip install langchain-community langchain-huggingface sentence-transformers  

  

from langchain_huggingface import HuggingFaceEmbeddings  

from langchain_community.vectorstores import InMemoryVectorStore  

from langchain_core.documents import Document  

  

# Embed and add documents to the vector store  

embeddings = HuggingFaceEmbeddings(  

  model_name="sentence-transformers/all-MiniLM-L6-v2"  

)  

vectorstore = InMemoryVectorStore(embedding=embeddings)  

vectorstore.add_documents([  

  Document(page_content="Paris is the capital of France."),  

  Document(page_content="Berlin is the capital of Germany."),  

  Document(page_content="Tokyo is the capital of Japan."),  

])  

```

--------------------------------

### Create a document store and add documents (Haystack)

Source: https://docs.haystack.deepset.ai/docs/migrating-from-langgraphlangchain-to-haystack

Sets up an in-memory document store, embeds documents using SentenceTransformers, and writes them to the store. Requires installing haystack-ai and sentence-transformers-haystack.

```python
# pip install haystack-ai sentence-transformers-haystack  

  

from haystack import Document  

from haystack.document_stores.in_memory import InMemoryDocumentStore  

from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersDocumentEmbedder  

  

# Embed and write documents to the document store  

document_store = InMemoryDocumentStore()  

  

doc_embedder = SentenceTransformersDocumentEmbedder(  

  model="sentence-transformers/all-MiniLM-L6-v2"  

)  

  

docs = [  

  Document(content="Paris is the capital of France."),  

  Document(content="Berlin is the capital of Germany."),  

  Document(content="Tokyo is the capital of Japan."),  

]  

docs_with_embeddings = doc_embedder.run(docs)["documents"]  

document_store.write_documents(docs_with_embeddings)  

```

--------------------------------

### Install and start Hayhooks MCP server

Source: https://docs.haystack.deepset.ai/docs/hayhooks

Installs the optional MCP extra and starts the Hayhooks MCP server. The server automatically lists deployed pipelines and agents as MCP Tools over Streamable HTTP (recommended) and SSE (backward compatibility).

```shell
pip install "hayhooks[mcp]"
```

```shell
hayhooks mcp run
```

--------------------------------

### Install alloydb-haystack with pip

Source: https://docs.haystack.deepset.ai/docs/alloydbkeywordretriever

Install the alloydb-haystack integration using pip. Requires an AlloyDB cluster and instance set up per the AlloyDB quickstart.

```shell
pip install alloydb-haystack  
```

--------------------------------

### Initialize VespaDocumentStore and write documents

Source: https://docs.haystack.deepset.ai/docs/vespadocumentstore

Create a VespaDocumentStore instance and write documents with metadata. The HTTP client is created lazily on first use.

```python
from haystack import Document  

from haystack_integrations.document_stores.vespa import VespaDocumentStore  

  

document_store = VespaDocumentStore(  
    url="http://localhost",  
    schema="doc",  
    namespace="doc",  
    content_field="content",  
    embedding_field="embedding",  
    metadata_fields=["category"],  
)  

  

document_store.write_documents(  
    [  
        Document(  
            content="Haystack integrates with Vespa for search.",  
            meta={"category": "docs"},  
        ),  
        Document(  
            content="Vespa supports lexical and vector retrieval.",  
            meta={"category": "docs"},  
        ),  
    ],  
)  

print(document_store.count_documents())  
```

--------------------------------

### Run FAISSEmbeddingRetriever standalone

Source: https://docs.haystack.deepset.ai/docs/faissembeddingretriever

Initialize a FAISSDocumentStore and FAISSEmbeddingRetriever, then run with a query embedding. The retriever returns documents from the store.

```python
from haystack_integrations.document_stores.faiss import FAISSDocumentStore

from haystack_integrations.components.retrievers.faiss import FAISSEmbeddingRetriever


document_store = FAISSDocumentStore(embedding_dim=768)
retriever = FAISSEmbeddingRetriever(document_store=document_store, top_k=5)

# Example query embedding
result = retriever.run(query_embedding=[0.1] * 768)
print(result["documents"])
```

--------------------------------

### Install anthropic-haystack and configure QueryExpander with AnthropicChatGenerator

Source: https://docs.haystack.deepset.ai/docs/queryexpander

Install the anthropic-haystack package and create a QueryExpander with an AnthropicChatGenerator. The example sets n_expansions to 3 and uses the claude-sonnet-4-20250514 model.

```shell
pip install anthropic-haystack
```

```python
from haystack.components.query import QueryExpander

from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator


expander = QueryExpander(
    chat_generator=AnthropicChatGenerator(model="claude-sonnet-4-20250514"),
    n_expansions=3,
)
```

--------------------------------

### Example result of TransformersNamedEntityExtractor

Source: https://docs.haystack.deepset.ai/docs/transformersnamedentityextractor

Example output showing documents with named entity annotations, including entity types, start and end positions, and confidence scores.

```text
[Document(id=aec840d1b6c85609f4f16c3e222a5a25fd8c4c53bd981a40c1268ab9c72cee10, content: 'My name is Clara and I live in Berkeley, California.', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=11, end=16, score=np.float32(0.99641764)), NamedEntityAnnotation(entity='LOC', start=31, end=39, score=np.float32(0.996198)), NamedEntityAnnotation(entity='LOC', start=41, end=51, score=np.float32(0.9990196))]}),  
Document(id=98f1dc5d0ccd9d9950cd191d1076db0f7af40c401dd7608f11c90cb3fc38c0c2, content: 'I'm Merlin, the happy pig!', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=4, end=10, score=np.float32(0.99054915))]}),  
Document(id=44948ea0eec018b33aceaaedde4616eb9e93ce075e0090ec1613fc145f84b4a9, content: 'New York State is home to the Empire State Building.', meta: {'named_entities': [NamedEntityAnnotation(entity='LOC', start=0, end=14, score=np.float32(0.9989541)), NamedEntityAnnotation(entity='LOC', start=30, end=51, score=np.float32(0.9574631))]})]  
```

--------------------------------

### Use ChromaQueryTextRetriever standalone

Source: https://docs.haystack.deepset.ai/docs/chromaqueryretriever

Initializes a ChromaDocumentStore and a ChromaQueryTextRetriever, then runs a query. Requires the ChromaDocumentStore and indexed documents to run.

```python
from haystack_integrations.document_stores.chroma import ChromaDocumentStore  

from haystack_integrations.components.retrievers.chroma import ChromaQueryTextRetriever  

  

document_store = ChromaDocumentStore()  

  

retriever = ChromaQueryTextRetriever(document_store=document_store)  

  

# example run query  

retriever.run(query="How does Chroma Retriever work?")  
```

--------------------------------

### Optional dependency import error example

Source: https://docs.haystack.deepset.ai/docs/installation

Example error message shown when an optional dependency is missing. Haystack raises an ImportError instructing you to install the missing dependency, such as 'pypdf'.

```shell
ImportError: "Haystack failed to import the optional dependency 'pypdf'. Run 'pip install pypdf'.
```

--------------------------------

### Example output of GitHubIssueViewer

Source: https://docs.haystack.deepset.ai/docs/githubissueviewer

Example output showing the documents returned by GitHubIssueViewer, including metadata for the issue and comments.

```bash
{'documents': [Document(id=3989459bbd8c2a8420a9ba7f3cd3cf79bb41d78bd0738882e57d509e1293c67a, content: 'sentence-transformers = 0.2.6.1
haystack = latest
farm = 0.4.3 latest branch

In the call to Emb...', meta: {'type': 'issue', 'title': 'SentenceTransformer no longer accepts \'gpu" as argument', 'number': 123, 'state': 'closed', 'created_at': '2020-05-28T04:49:31Z', 'updated_at': '2020-05-28T07:11:43Z', 'author': 'predoctech', 'url': 'https://github.com/deepset-ai/haystack/issues/123'}), Document(id=a8a56b9ad119244678804d5873b13da0784587773d8f839e07f644c4d02c167a, content: 'Thanks for reporting!
Fixed with #124 ', meta: {'type': 'comment', 'issue_number': 123, 'created_at': '2020-05-28T07:11:42Z', 'updated_at': '2020-05-28T07:11:42Z', 'author': 'tholor', 'url': 'https://github.com/deepset-ai/haystack/issues/123#issuecomment-635153940'})]}
```

--------------------------------

### Installation

Source: https://docs.haystack.deepset.ai/docs/qdranthybridretriever

Install the qdrant-haystack package to use QdrantHybridRetriever.

```APIDOC
## Installation

### Description
Install the qdrant-haystack package to use QdrantHybridRetriever.

### Command
```shell
pip install qdrant-haystack
```
```

--------------------------------

### Run Ollama with Docker

Source: https://docs.haystack.deepset.ai/docs/ollamachatgenerator

Starts an Ollama server container on port 11434. Requires Docker to be installed.

```bash
docker run -d -p 11434:11434 --name ollama ollama/ollama:latest
```

--------------------------------

### Start DoclingServe Docker container

Source: https://docs.haystack.deepset.ai/docs/doclingserveconverter

Run a DoclingServe instance locally using Docker. Requires Docker to be installed and running.

```shell
docker run -p 5001:5001 ghcr.io/docling-project/docling-serve-cpu:latest  
```

--------------------------------

### Example format for LLMEvaluator few-shot examples

Source: https://docs.haystack.deepset.ai/docs/llmevaluator

Shows the expected format for the 'examples' parameter when the evaluator is declared with inputs=[("responses", list[str])] and outputs=["score"]. Each example is a dictionary with 'inputs' and 'outputs' keys.

```python
[

    {

        "inputs": {"responses": "Damn, this is straight outta hell!!!"},

        "outputs": {"score": 1},

    },

    {

        "inputs": {"responses": "Football is the most popular sport."},

        "outputs": {"score": 0},

    },

]
```
Tokens:
Raw