Docling (document conversion)

Module id: docling · Kind: sidecar · Configured by: DOCLING_BASE_URL

Docling converts PDFs and Office files into Markdown with tables, headings and reading order intact. Synaplan chunks that Markdown heading-aware — a table stays one chunk, an oversized table repeats its header row — so a question answered by a single table cell retrieves the row instead of a paragraph near it. Off by default; an operator adds it.

What it adds#

• A docling adapter for the Documents extraction chain, usually placed in front of tika.
• Layout-preserving text for invoices, spec sheets, financial reports, forms and scanned documents (Docling runs OCR when a page has no text layer).
• Better RAG hits on tabular content: "what is the unit price in row 4?" returns the row.

Without it#

Documents are extracted by Tika and the other adapters of the chain exactly as before. Docling is never on a fresh install's chain, so nothing degrades until you add it — and once added, a Docling that is stopped or slow never fails an upload: the chain falls through to Tika and Test with a file reports "Docling unavailable — Tika used instead".

How to enable#

1. Start the sidecar#

Developer / evaluation stack (docker-compose.yml ships a docling profile with the CPU image, about 4.4 GB to pull and up to 4 GB of RAM during OCR):

docker compose --profile docling up -d

Production (deploy/compose.yaml carries no Docling service): run docling-serve yourself, on the same host or a machine with more CPU, and keep it off the public internet:

docker run -d --name docling \
  -e DOCLING_SERVE_ENABLE_UI=0 \
  -p 127.0.0.1:5001:5001 \
  ghcr.io/docling-project/docling-serve-cpu:v1.32.0

2. Tell the backend where it is#

The dev Compose file already injects DOCLING_BASE_URL=http://docling:5001 into backend and worker. Everywhere else set it explicitly and restart both:

DOCLING_BASE_URL=http://docling:5001      # or http://host.docker.internal:5001, https://docling.internal…
DOCLING_TIMEOUT_MS=120000
DOCLING_MAX_BYTES=52428800                 # 50 MB; larger files skip Docling and go to Tika

URL, timeout and size limit can also be edited under Operate → System configuration → Processing → Docling, with a Test connection button — the same controls Tika has.

3. Put it on the chain#

Operate → AI infrastructure → Extraction: on the Documents family choose Add → docling, move it above tika, Save chain. The next upload uses it; no restart.

Check it works#

• Operate → Feature Status → Docling shows Available / Docling is running. Docling is not reachable means the URL is set but GET /health did not answer — the sidecar is still pulling the image, still loading models (start-up can take two minutes), or the URL is wrong. DOCLING_BASE_URL is unset or disabled means the module is off.
• AI infrastructure → Extraction → Test with a file with a PDF that contains a table: the winner should be docling, and the preview shows a Markdown table.
• From the host, the sidecar has no published port in the dev stack; probe it through the backend:

docker compose exec -T backend curl -sS http://docling:5001/health

Configuration reference#

Chain membership lives in BCONFIG as PLUGS → EXTRACTION.CHAIN.document; edit it on the Extraction tab rather than by hand.

Troubleshooting#

• Everything still says tika won. Docling is running but not on the chain, or it is behind tika in the order. Check the Documents chain on the Extraction tab.
• Docling is not reachable for minutes after start. Normal on first start (model download inside the container). docker compose logs -f docling shows progress.
• Large PDFs skip Docling. Raise DOCLING_MAX_BYTES — and DOCLING_TIMEOUT_MS with it.
• Memory pressure on a small host. OCR is the expensive part. Run docling-serve on another machine and point DOCLING_BASE_URL at it; the backend only needs HTTP access.

Related#

• AI infrastructure — extraction chains, the quality gate, Test with a file
• Apache Tika module — the fallback behind Docling
• Feature modules — states, gates, the CLI