What is the optimal number of cpu cores to use?

[ofcat]

@dosu hi :) What is the optimal number of cpu cores to use when working with simple pdf pipeline on a cpu only machine? I am working with single digital pdf with around 300 pages on average.

pipeline_options = PdfPipelineOptions(
do_ocr=False,
accelerator_options=AcceleratorOptions(
device="cpu", num_threads=multiprocessing.cpu_count()
),
)

[dosubot[bot]]

Hi! 👋

For your setup (digital PDFs, no OCR, ~300 pages), setting num_threads equal to your CPU core count is a reasonable starting point. So multiprocessing.cpu_count() is a sensible default.

However, there are a couple things to keep in mind:

1. Diminishing returns: Testing on modern machines shows that increasing CPU cores doesn't significantly improve throughput due to Python's concurrency limitations. The threading helps with parallel internal tasks, but gains may be modest.

2. Also set OMP_NUM_THREADS: For a more consistent setup, set the OMP_NUM_THREADS environment variable to match your thread count. For example, on a 4-core machine:

   import os
   os.environ["OMP_NUM_THREADS"] = "4"

3. Consider your available RAM: More threads mean more memory usage. If you're memory-constrained, you might want to start with fewer threads and experiment.

Your current config looks fine. If you want to experiment, try starting with half your core count and work up to see if there's any noticeable improvement—but don't be surprised if doubling threads doesn't double performance.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[ofcat]

@dosu i have experimented and found out that using 10 cores yields the best speed, here is the profiling result:
pipeline_total: 25.61s
page_parse: 0.78s
layout: 6.20s
table_structure: 23.48s
page_assemble: 0.00s
doc_assemble: 0.55s
reading_order: 0.54s
doc_enrich: 0.02s

However, i wonder if 25 seconds for a 5 page pdf is a good speed on my cpu only machine?

Would you please advice how can i achieve faster speeds for my pipeline? I was thinking of splitting pdf into multiple chunks and then creating multiple processes that are going to convert those pdf chunks in parallel. Thank you

[dosubot[bot]]

Your timing is actually pretty typical for CPU-only processing—similar machines show comparable speeds for equivalent workloads.

The profiling shows table_structure is your bottleneck (23.48s out of 25.61s total). Here are your best options:

1. Use TableFormer FAST mode (easiest win):

from docling.datamodel.pipeline_options import TableStructureOptions, TableFormerMode

pipeline_options.table_structure_options = TableStructureOptions(
    mode=TableFormerMode.FAST
)

This trades some accuracy for significantly faster processing.

2. Disable table structure entirely if you don't need it:

pipeline_options = PdfPipelineOptions(
    do_ocr=False,
    do_table_structure=False,  # Skip table extraction
    ...
)

Regarding PDF chunking/parallel processing:

Unfortunately, Python's concurrency limitations mean increasing workers doesn't significantly improve throughput. Splitting PDFs into chunks and processing in parallel is possible, but be aware it can break multi-page tables, lists, and heading context.

If you do go that route, use a separate DocumentConverter instance per process to avoid race conditions.

For true high throughput, consider GPU acceleration (if available) or a distributed setup with docling-serve.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[ofcat]

@dosu would you know how much RAM would each instance of DocumentConverter use?

[dosubot[bot]]

The recommended baseline is at least 8GB of RAM per DocumentConverter instance for stable PDF processing.

Keep in mind that actual usage can vary depending on PDF complexity (especially tables and images). Recent versions have improved memory management with mimalloc to reduce memory growth during processing.

If you're planning to run multiple instances in parallel, note that Python's GIL will likely limit your throughput gains more than memory will—so you may not get linear scaling even with enough RAM for multiple instances.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[ofcat]

@dosu Hi again, sorry for so many questions. I’m exploring the idea of combining DocLing with a faster PDF parser. My goal is to optimize parsing by:
Using a fast PDF parser to scan the document and identify pages that contain tables.
Storing the page numbers of those pages.
Applying DocLing only on the pages that contain tables, so I can extract clean Markdown tables for my RAG workflow.
Parsing all other pages with the standard parser.

I’m looking for guidance or code examples on how to implement this workflow efficiently. Specifically: Detecting whether a page contains a table Selectively applying DocLing only to those pages Thanks for any advice!

[dosubot[bot]]

No worries, happy to help! Your hybrid approach is smart—Docling natively supports page_range for selective page processing, which fits your workflow perfectly.

Here's how to implement it:

from docling.document_converter import DocumentConverter

converter = DocumentConverter()

# After your fast parser identifies table pages (e.g., [3, 5, 7])
table_pages = [3, 5, 7]

# Process only those pages with Docling
for page in table_pages:
    result = converter.convert("document.pdf", page_range=(page, page))
    # Extract markdown tables
    md = result.document.export_to_markdown()

The page_range uses 1-based inclusive indexing, so (3, 7) processes pages 3, 4, 5, 6, and 7.

For extracting tables from specific pages, you can filter by provenance metadata:

# Get tables from a specific page in the result
tables_on_page = [
    t for t in result.document.tables 
    if t.prov and t.prov[0].page_no == page
]

Important note: Docling doesn't have a "detection-only" mode for tables—the detection happens during full processing. So your plan to use an external fast parser (like PyMuPDF or pdfplumber) to identify table pages first, then pass only those to Docling, is the right approach.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.