LLMMetadataExtractor

Automatically extract and enrich document metadata using a large language model. LLMMetadataExtractor sends each document to an LLM with a prompt you define, then parses the LLM's response to add new metadata fields to the document.

Use this component in indexing pipelines where you want to generate structured metadata from unstructured document content—for example, extracting topics, sentiment, named entities, or any other information your prompt targets.

---

Key Features

• Enriches documents with LLM-generated metadata during indexing. The metadata is generated based on the document content.
• Supports any model provider you have connected to the platform.
• Lets you define a custom prompt to control what metadata is extracted.
• Handles JSON parsing of the LLM response and maps fields directly to document metadata.
• Works with all major providers, including Amazon Bedrock, OpenAI, Azure OpenAI, and others.

Configuration

1. In Builder, click Add and find LLMMetadataExtractor in the list of components.

2. Drag and drop the component onto the canvas.

3. Click the component to open its configuration.

4. On the General tab, configure the following:

   • Model: The model to use for the LLM.
   • Prompt: The prompt instructing the LLM what to extract. Write a prompt that instructs the model to return a JSON object whose keys become the metadata fields added to each document. Use {{ document.content }} in the prompt to reference the document content. Example:

   Extract the following from the document and return as JSON:
   - topic: the main subject of the document
   - sentiment: positive, negative, or neutral
   - language: the language the document is written in

5. Go to the Advanced tab to configure additional settings:

   • Raise on Failure: If enabled, raises an exception when extraction fails for a document instead of routing it to failed_documents. It's disabled by default.
   • Max workers: The maximum number of workers to use in the thread pool executor. Use this setting to limit the maximum number of requests allowed to run concurrently.
   • Expected Keys: The JSON keys expected in the LLM response. These become the metadata field names.
   • Page range: The range of pages to extract metadata from. Use this setting to limit the number of pages the LLM processes.

Connections

LLMMetadataExtractor is designed for indexing pipelines. Typical connections:

• Input: Receives documents from a Converter or DocumentSplitter.
• Output: Passes enriched documents to a DocumentWriter or another processing component.

Source Code

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

Usage Examples

Basic Configuration

  LLMMetadataExtractor:
    type: haystack.components.extractors.llm_metadata_extractor.LLMMetadataExtractor
    init_parameters:
      chat_generator:
        type: haystack.components.generators.chat.openai.OpenAIChatGenerator
        init_parameters:
          api_key:
            type: env_var
            env_vars:
            - OPENAI_API_KEY
            strict: true
          model: gpt-4o-mini
          generation_kwargs:
            max_tokens: 500
            temperature: 0.0
            response_format:
              type: json_object
      prompt: |
        Extract the following metadata from the document and return it as JSON:
        - "title": The title or main topic of the document
        - "entities": A list of named entities (people, organizations, locations) mentioned
        - "summary": A brief one-sentence summary of the content

        Document content:
        {{ document.content }}

        Return only valid JSON with the keys: title, entities, summary
      expected_keys:
      - title
      - entities
      - summary
      raise_on_failure: false
      max_workers: 3

Using the Component in an Index

This index uses LLMMetadataExtractor to extract structured metadata from documents before splitting and storing them:

# haystack-pipeline
components:
  TextFileToDocument:
    type: haystack.components.converters.txt.TextFileToDocument
    init_parameters:
      encoding: utf-8

  LLMMetadataExtractor:
    type: haystack.components.extractors.llm_metadata_extractor.LLMMetadataExtractor
    init_parameters:
      chat_generator:
        type: haystack.components.generators.chat.openai.OpenAIChatGenerator
        init_parameters:
          api_key:
            type: env_var
            env_vars:
              - OPENAI_API_KEY
            strict: true
          model: gpt-4o-mini
          generation_kwargs:
            max_tokens: 500
            temperature: 0.0
            response_format:
              type: json_object
      prompt: |
        Extract the following metadata from the document and return it as JSON:
        - "title": The title or main topic of the document
        - "entities": A list of named entities (people, organizations, locations) mentioned
        - "summary": A brief one-sentence summary of the content

        Document content:
        {{ document.content }}

        Return only valid JSON with the keys: title, entities, summary
      expected_keys:
        - title
        - entities
        - summary
      raise_on_failure: false
      max_workers: 3

  DocumentSplitter:
    type: haystack.components.preprocessors.document_splitter.DocumentSplitter
    init_parameters:
      split_by: sentence
      split_length: 5
      split_overlap: 1

  document_embedder:
    type: haystack.components.embedders.sentence_transformers_document_embedder.SentenceTransformersDocumentEmbedder
    init_parameters:
      model: sentence-transformers/all-mpnet-base-v2

  DocumentWriter:
    type: haystack.components.writers.document_writer.DocumentWriter
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
            - ${OPENSEARCH_HOST}
          http_auth:
            - ${OPENSEARCH_USER}
            - ${OPENSEARCH_PASSWORD}
          use_ssl: true
          verify_certs: false
      policy: OVERWRITE

connections:
  - sender: TextFileToDocument.documents
    receiver: LLMMetadataExtractor.documents
  - sender: LLMMetadataExtractor.documents
    receiver: DocumentSplitter.documents
  - sender: DocumentSplitter.documents
    receiver: document_embedder.documents
  - sender: document_embedder.documents
    receiver: DocumentWriter.documents

inputs:
  files:
    - TextFileToDocument.sources

Parameters

Inputs

Parameter	Type	Default	Description
documents	List[Document]	—	List of documents to extract metadata from.
page_range	List[str | int] | None	None	A range of pages to extract metadata from. For example, ['1', '3'] extracts metadata from the first and third pages of each document. Also accepts printable range strings, for example ['1-3', '5', '8', '10-12'] extracts from pages 1, 2, 3, 5, 8, 10, 11, and 12. If None, metadata is extracted from the entire document.

Outputs

Parameter	Type	Description
documents	List[Document]	Documents that were successfully updated with the extracted metadata.
failed_documents	List[Document]	Documents that failed to extract metadata. These documents have metadata_extraction_error and metadata_extraction_response in their metadata and can be re-run with the extractor.

Init Parameters

Parameter	Type	Default	Description
prompt	str	—	The prompt sent to the LLM for each document. It must contain exactly one variable called document, which points to a single document in the list. For example, use {{ document.content }} to access the document content.
chat_generator	ChatGenerator	—	A ChatGenerator instance representing the LLM. The LLM must be configured to return a JSON object. For example, when using OpenAIChatGenerator, pass {"response_format": {"type": "json_object"}} in generation_kwargs.
expected_keys	List[str]	None	The keys expected in the JSON output from the LLM. These become the metadata field names added to each document.
page_range	List[str | int] | None	None	A range of pages to extract metadata from. For example, ['1', '3'] extracts metadata from the first and third pages of each document. Also accepts printable range strings, for example ['1-3', '5', '8', '10-12'] extracts from pages 1, 2, 3, 5, 8, 10, 11, and 12. If None, metadata is extracted from the entire document. Can be overridden in the run method.
raise_on_failure	bool	False	Whether to raise an error on failure during the execution of the generator or validation of the JSON output. If False, failed documents are returned in failed_documents.
max_workers	int	3	The maximum number of workers to use in the thread pool executor. Limits the maximum number of requests allowed to run concurrently when using the run_async method.

Run Method Parameters

Parameter	Type	Default	Description
documents	List[Document]	—	The documents to process.
page_range	List[str | int] | None	None	A range of pages to extract metadata from. Overrides the page_range set at initialization. If None, uses the init parameter value, or extracts metadata from the entire document when not set.

Related Information

• Connect to Model and Service Providers
• Troubleshoot Pipelines and Indexes
• LLM