Structured Information Extraction#

Docling's structured information extraction is a distinct capability from document conversion. Where DocumentConverter transforms documents into Docling's intermediate representation (markdown, JSON, etc.), the extraction subsystem uses a Vision-Language Model (VLM) to pull specific structured fields from a document page — returning typed, schema-driven data rather than a converted document.

The two subsystems share infrastructure (backends, InputDocument, pipeline caching) but are intentionally separate classes with separate APIs 1 2.

Entry Point: DocumentExtractor#

DocumentExtractor in docling/document_extractor.py is the top-level class. It mirrors the DocumentConverter interface but exposes:

• extract(source, template, ...) — single-document extraction, returns ExtractionResult
• extract_all(source, template, ...) — batch extraction, returns Iterator[ExtractionResult]

Both methods require a template argument of type ExtractionTemplateType (see below). Supported input formats are PDF and IMAGE only. 3

Pipeline instances are cached by (pipeline_class, options_hash), so repeated calls with the same options reuse the same model. 4

Template: ExtractionTemplateType#

ExtractionTemplateType (in docling/datamodel/extraction.py) is a Union type alias:

Union[str, Dict[str, Any], BaseModel, Type[BaseModel]]

Four template forms are accepted:

Serialization logic lives in ExtractionVlmPipeline._serialize_template(). When passing a Pydantic class, Field(examples=[...]) values are used to generate representative JSON, which the VLM uses as a schema hint. 5

Pipeline: ExtractionVlmPipeline#

ExtractionVlmPipeline (in docling/pipeline/extraction_vlm_pipeline.py) is the default (and currently only) extraction pipeline. It:

1. Renders each document page to an image via the PDF/image backend.
2. Serializes the template into a prompt string.
3. Feeds (image, prompt) into a TransformersExtractionModel.
4. Attempts json.loads() on the VLM output; falls back to raw_text if not valid JSON. 6

It does not support ThreadedDoclingParseDocumentBackend. 7

Default model: NU_EXTRACT_2B_TRANSFORMERS (NuExtract-2B). An alternative is GRANITE_VISION_4_1_TRANSFORMERS. Both are configured via VlmExtractionPipelineOptions.

Configuration: VlmExtractionPipelineOptions#

Located in docling/datamodel/pipeline_options.py 8:

• vlm_options (InlineVlmOptions): which VLM model to load; defaults to NU_EXTRACT_2B_TRANSFORMERS
• extraction_prompt_style (ExtractionPromptStyle): prompt format; NUEXTRACT (default) or GRANITE_VISION 9

Pass a custom VlmExtractionPipelineOptions via ExtractionFormatOption when constructing DocumentExtractor:

from docling.document_extractor import DocumentExtractor, ExtractionFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import VlmExtractionPipelineOptions
from docling.pipeline.extraction_vlm_pipeline import ExtractionVlmPipeline

extractor = DocumentExtractor(
    extraction_format_options={
        InputFormat.PDF: ExtractionFormatOption(
            pipeline_cls=ExtractionVlmPipeline,
            pipeline_options=VlmExtractionPipelineOptions(...),
        )
    }
)

10

Output: ExtractionResult#

ExtractionResult contains:

• status: ConversionStatus (SUCCESS, PARTIAL_SUCCESS, FAILURE)
• errors: document-level ErrorItem list
• pages: list of ExtractedPageData, each with:
  • page_no: 1-indexed page number
  • extracted_data: parsed Dict[str, Any] (populated when VLM output is valid JSON)
  • raw_text: raw VLM output string (always populated)
  • errors: page-level error strings

To load structured data back into a Pydantic model:

invoice = Invoice.model_validate(result.pages[0].extracted_data)

PARTIAL_SUCCESS is set when the VLM hits a token-length or stop-sequence limit. 11

Key Source Files#

Install note: The VLM extraction feature requires pip install docling[vlm]. 12