Skip to content

Vlm page range assembly

Convert a PDF in page ranges with the VLM pipeline, then assemble one document.

What this example does - Converts a PDF in separate page ranges with the VLM pipeline. - Checks that the ranges cover every page exactly once. - Concatenates the range documents into one complete DoclingDocument.

Why - An external scheduler can send each range to a different worker, each with its own converter. This example runs the ranges one after the other.

Prerequisites - Install Docling with VLM extras and a backend (Transformers or MLX). - Ensure your environment can download model weights (e.g., from Hugging Face).

How to run - From the repository root, run: python docs/examples/vlm_page_range_assembly.py. - The script prints the page numbers of the assembled document and its Markdown.

Notes - page_range=(first, last) uses inclusive, one-based page numbers. The VLM pipeline keeps the source page numbers in the returned document and its provenance. - DoclingDocument.concatenate renumbers documents into a continuous sequence. For an ordered partition without gaps that starts at page 1, each offset is zero, so the source page numbers stay the same. - The VLM pipeline interprets each page independently. Range conversion keeps the page-local reading order, lists, tables, headers, footers, and key/value cell provenance of a whole conversion with the same page responses. It does not join a table or list that continues onto another page. Model responses can change with inference batching, so the predictions can differ. - Do not concatenate an incomplete set of ranges as a complete document. A subset that starts after page 1, a missing page, or a failed range closes gaps and shifts page numbers and provenance without an error. - Concatenation does not set origin, and it does not copy the conversion status, errors, timings, or input metadata. Handle them separately. - Each range opens the source again. Measure the extra backend and rendering work when you select a range size.

from collections.abc import Iterable
from pathlib import Path

from docling_core.types.doc import DoclingDocument

from docling.datamodel.base_models import ConversionStatus, InputFormat
from docling.datamodel.document import ConversionResult
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.pipeline.vlm_pipeline import VlmPipeline


def assemble_complete_document(
    results: Iterable[ConversionResult],
) -> DoclingDocument:
    """Concatenate range results that cover every source page exactly once."""
    results = list(results)
    if not results:
        raise ValueError("No ranges to assemble")
    for result in results:
        if result.status != ConversionStatus.SUCCESS:
            raise ValueError("A range did not complete successfully")
        if not result.document.pages:
            raise ValueError("A range has no pages")
    source_page_count = results[0].input.page_count
    results.sort(key=lambda result: min(result.document.pages))
    next_page = 1
    for result in results:
        pages = sorted(result.document.pages)
        if pages != list(range(next_page, next_page + len(pages))):
            raise ValueError("Missing, overlapping, or unordered pages")
        next_page += len(pages)
    if next_page != source_page_count + 1:
        raise ValueError("The final range is missing pages")
    return DoclingDocument.concatenate([result.document for result in results])


def main() -> None:
    data_folder = Path(__file__).parent / "../../tests/data"
    source = data_folder / "pdf/sources/2206.01062.pdf"

    # Each worker uses the same source and the same VLM configuration.
    converter = DocumentConverter(
        format_options={
            InputFormat.PDF: PdfFormatOption(pipeline_cls=VlmPipeline),
        }
    )

    # The page ranges are inclusive and one-based.
    ranges = [(1, 3), (4, 6), (7, 9)]
    results = [converter.convert(source, page_range=span) for span in ranges]

    document = assemble_complete_document(results)
    print(f"Assembled pages: {sorted(document.pages)}")
    print(document.export_to_markdown())


if __name__ == "__main__":
    main()