Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Pipeline YAML Format

You can build pipelines in the visual Builder by dragging and dropping components onto the canvas. However, the underlying YAML code is the source of truth for the pipeline. You can edit the YAML code to make changes to the pipeline.

Top-Level Keys​

The top-level keys you can use in a pipeline YAML are:

KeyRequiredDescription
componentsYesDefines the components that make up the pipeline, their types, and initialization parameters.
connectionsYesSpecifies how component outputs connect to component inputs.
inputsNoMaps external pipeline inputs to component inputs (used in indexing pipelines).
outputsNoMaps component outputs to external pipeline outputs (used in query pipelines).
dependenciesNoDeclares the Haystack Open Source version and extra Python packages this pipeline needs. Use valid Python requirement strings, for example haystack-ai==2.14.0. For details, see Pipeline Dependencies.
Pipeline YAML format
# haystack-pipeline
components:
  retriever:
    type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          embedding_dim: 768
          index: Standard-Index
          settings:
            index.knn: true
          create_index: true
      top_k: 20
      embedder:
        type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
        init_parameters:
          normalize_embeddings: true
          model: intfloat/e5-base-v2

  ranker:
    type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
    init_parameters:
      model: intfloat/simlm-msmarco-reranker
      top_k: 8

  llm:
    type: haystack.components.generators.chat.llm.LLM
    init_parameters:
      chat_generator:
        type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
        init_parameters:
          model: "gpt-5.4"
      user_prompt: >-
        {% message role="user" %}
        Answer the question using the documents below.

        {% for document in documents %}
        Document [{{ loop.index }}]: {{ document.content }}
        {% endfor %}

        Question: {{ question }}
        {% endmessage %}
      required_variables: "*"

connections:
- sender: retriever.documents
  receiver: ranker.documents
- sender: ranker.documents
  receiver: llm.documents

inputs:
  query:
  - retriever.query
  - ranker.query
  - llm.question
  filters:
  - retriever.filters_bm25
  - retriever.filters_embedding

outputs:
  documents: ranker.documents
  messages: llm.messages

dependencies:
  - haystack-ai==2.14.0

Inputs​

Pipelines always take Input as the first component. When working in Builder, click Add to open the component library, drag Input onto the canvas, and connect it to the components that should receive its outputs.

When working in the YAML editor, you must explicitly specify the inputs and the components that receive them:

inputs:  # Define the inputs for your pipeline
  query:  # These components will receive the query as input
  - "bm25_retriever.query"
  - "query_embedder.text"
  - "ranker.query"

  filters:  # These components will receive a potential query filter as input
  - "bm25_retriever.filters"
  - "embedding_retriever.filters"

Filters are documents' metadata keys by default. This means that if your documents have the following metadata: {"category": "news"}, when searching in Playground, users can narrow down the search to the documents matching this category. You can also pass filters at search time with the Search endpoint. For more information about filters, see Working with Metadata.

Outputs​

The output of a pipeline matches the output of the last component. However, it must be one of the following data classes:

  • List of Document objects (usually document search pipelines)
  • List of Answer objects, including the following subclasses:
    • List of ExtractedAnswer objects (usually extractive question answering pipelines)
    • List of GeneratedAnswer objects (pipelines that use Generator components)
  • List of ChatMessage objects (usually pipelines that use large language models to generate answers)

The output can be a list of documents, a list of answers, a list of chat messages, or all of them. Make sure the last component in your pipeline produces at least one of these outputs.

In Builder, to finalize the pipeline with the correct output, drag the Output component onto the canvas and connect it to the components that produce the outputs you want to include.

When working in the YAML editor, you must explicitly specify the outputs and the components that provide them:

outputs:  # Defines the output of your pipeline
  documents: "ranker.documents"  # The output of the pipeline is the retrieved documents
  messages: "llm.messages"  # The output of the pipeline is the generated answers