Pipeline Configuration API

Relevant source files

• CHANGELOG.md
• docling/cli/main.py
• docling/datamodel/base_models.py
• docling/datamodel/document.py
• docling/datamodel/pipeline_options.py
• docling/datamodel/pipeline_options_vlm_model.py
• docling/document_converter.py
• docling/models/base_model.py
• docling/models/utils/generation_utils.py
• docling/utils/api_image_request.py
• docling/utils/layout_postprocessor.py
• docs/examples/post_process_ocr_with_vlm.py
• pyproject.toml
• uv.lock

This page explains how to configure document processing pipelines programmatically when using Docling as a Python library. It covers the configuration classes, their relationships, and how to customize pipeline behavior for different input formats.

For information about using the DocumentConverter class itself, see DocumentConverter API. For conceptual information about pipeline architecture, see Processing Pipelines.

Configuration Hierarchy

Docling's configuration system is hierarchical, with PipelineOptions as the base class and format-specific options that map input formats to pipelines and their configurations.

Core Configuration Classes

Sources: docling/datamodel/pipeline_options.py70-74 docling/datamodel/base_models.py37-43 docling/document_converter.py75-85

Configuration Flow

The configuration system connects input formats to processing pipelines through the FormatOption class, which specifies:

• pipeline_cls: The pipeline class to use (e.g., StandardPdfPipeline, SimplePipeline)
• pipeline_options: Configuration for the pipeline instance
• backend: The document backend class for parsing
• backend_options: Configuration for the backend

Sources: docling/document_converter.py75-85 docling/document_converter.py249-257

Format Options

Format options map input formats to their processing configuration. The DocumentConverter accepts a format_options dictionary in its constructor.

FormatOption Structure

The base FormatOption class contains:

Key attributes:

• pipeline_cls: Pipeline class reference (not an instance)
• pipeline_options: Configuration instance for the pipeline
• backend: Backend class reference
• backend_options: Configuration for backend behavior

Sources: docling/document_converter.py75-85

Built-in Format Option Classes

Docling provides pre-configured format option classes for common formats:

Format Option Class	Input Format	Default Pipeline	Default Backend
PdfFormatOption	PDF	StandardPdfPipeline	DoclingParseDocumentBackend
ImageFormatOption	IMAGE	StandardPdfPipeline	ImageDocumentBackend
WordFormatOption	DOCX	SimplePipeline	MsWordDocumentBackend
ExcelFormatOption	XLSX	SimplePipeline	MsExcelDocumentBackend
PowerpointFormatOption	PPTX	SimplePipeline	MsPowerpointDocumentBackend
HTMLFormatOption	HTML	SimplePipeline	HTMLDocumentBackend
MarkdownFormatOption	MD	SimplePipeline	MarkdownDocumentBackend
AudioFormatOption	AUDIO	AsrPipeline	NoOpBackend

Sources: docling/document_converter.py87-156

Default Format Options

If you don't provide custom format options, DocumentConverter uses defaults from the _get_default_option() function:

Sources: docling/document_converter.py158-186

PDF Pipeline Configuration

The PdfPipelineOptions class configures the StandardPdfPipeline, which performs multi-stage processing including OCR, layout detection, and table structure extraction.

PdfPipelineOptions Class

Sources: docling/datamodel/pipeline_options.py1010-1243

Key Configuration Options

OCR Configuration (ocr_options):

• Controls optical character recognition behavior
• Multiple OCR engine options: OcrAutoOptions, TesseractOcrOptions, EasyOcrOptions, RapidOcrOptions, OcrMacOptions
• Each engine has specific configuration (languages, confidence thresholds, etc.)
• force_full_page_ocr: Forces OCR on all pages regardless of embedded text

Layout Detection (layout_options):

• Configures document layout analysis models
• Can specify model variants (e.g., DOCLING_LAYOUT_EGRET_LARGE)
• Controls confidence thresholds and post-processing behavior
• Engine options for inference framework (HuggingFace Transformers, ONNX Runtime)

Table Structure (table_structure_options):

• Uses TableFormer model for table extraction
• mode: TableFormerMode.ACCURATE or TableFormerMode.FAST
• do_cell_matching: Aligns detected cells with content

Acceleration (accelerator_options):

• device: CPU, CUDA, MPS, XPU for hardware acceleration
• num_threads: Controls parallelization

Timing and Resource Control:

• document_timeout: Maximum processing time in seconds (default: 180)
• Batch sizes for different stages (OCR, layout, table structure)

Sources: docling/datamodel/pipeline_options.py1010-1243 docling/datamodel/pipeline_options.py121-461 docling/datamodel/pipeline_options.py76-118

Basic PDF Configuration Example

Sources: docling/document_converter.py209-260 docling/datamodel/pipeline_options.py1010-1243

VLM Pipeline Configuration

Vision-Language Model (VLM) pipelines process documents using multimodal AI models. The configuration system supports both inline models (running locally) and API-based models (remote inference).

VlmPipelineOptions Structure

Sources: docling/datamodel/pipeline_options.py1360-1449 docling/datamodel/pipeline_options_vlm_model.py1-320

VLM Configuration with Presets

The VlmConvertOptions.from_preset() method provides pre-configured VLM setups:

Available presets can be listed with:

Sources: docling/datamodel/pipeline_options.py1360-1449 docling/datamodel/stage_model_specs.py50-89

Inline VLM Configuration

For local model inference using HuggingFace models:

Key parameters:

• repo_id: HuggingFace model identifier
• inference_framework: MLX (Apple Silicon), TRANSFORMERS (general), VLLM (high-throughput)
• response_format: Expected output format (DOCTAGS, MARKDOWN, HTML, OTSL)
• load_in_8bit: Quantization to reduce memory usage
• temperature: 0.0 for deterministic output

Sources: docling/datamodel/pipeline_options_vlm_model.py120-320

API-based VLM Configuration

For remote inference through OpenAI-compatible APIs:

Key parameters:

• url: API endpoint (OpenAI-compatible)
• model: Model identifier for the API
• concurrency: Maximum concurrent API requests
• timeout: Request timeout in seconds
• headers: Custom HTTP headers (e.g., authentication)

Sources: docling/datamodel/pipeline_options_vlm_model.py322-462

Other Pipeline Options

SimplePipeline Options

For formats that don't require complex multi-stage processing (DOCX, XLSX, HTML, etc.):

Sources: docling/datamodel/pipeline_options.py1005-1008

AsrPipeline Options

For audio and video transcription:

Sources: docling/datamodel/pipeline_options.py1246-1282 docling/datamodel/pipeline_options_asr_model.py1-34

Backend Options

Backend options control the behavior of document parsers independently from pipeline processing.

PDF Backend Options

Sources: docling/datamodel/backend_options.py11-28

HTML Backend Options

Sources: docling/datamodel/backend_options.py31-43

Markdown Backend Options

Sources: docling/datamodel/backend_options.py46-58

Enrichment Model Configuration

Enrichment models add additional processing after initial document parsing (e.g., picture classification, description, chart extraction).

Picture Description Configuration

Sources: docling/datamodel/pipeline_options.py464-655

Picture Classification Configuration

Sources: docling/datamodel/pipeline_options.py679-745 docling/datamodel/picture_classification_options.py1-31

Chart Extraction Configuration

Sources: docling/datamodel/pipeline_options.py1010-1243

Complete Configuration Example

Here's a comprehensive example showing multiple configuration aspects:

Sources: docling/datamodel/pipeline_options.py1010-1243 docling/document_converter.py209-260

Configuration Validation and Defaults

Automatic Default Setting

When pipeline_options is not provided in a FormatOption, the pipeline's default options are automatically set:

Sources: docling/document_converter.py79-84

Model Validator

The FormatOption class uses Pydantic's model_validator to ensure pipeline options are initialized:

Sources: docling/document_converter.py79-84

Pipeline Options Hashing

The DocumentConverter caches pipeline instances by hashing their options to avoid redundant initialization:

Sources: docling/document_converter.py267-272

Configuration Pattern Summary

Key principles:

1. Options are configuration, not instances: Pass configuration objects, not model instances
2. Pipeline class references: Use pipeline_cls=StandardPdfPipeline, not StandardPdfPipeline()
3. Backend class references: Use backend=DoclingParseDocumentBackend, not DoclingParseDocumentBackend()
4. Format mapping: Map InputFormat enums to FormatOption instances
5. Validation: Pydantic validates all options at creation time
6. Caching: Pipeline instances are cached based on options hash

Sources: docling/document_converter.py209-293 docling/document_converter.py75-85