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

Variable Default Meaning
DOCLING_BASE_URL empty (dev Compose: http://docling:5001) Base URL of docling-serve. Empty or disabled = module off.
DOCLING_TIMEOUT_MS 120000 Per-document timeout. OCR of a long scan can legitimately need this.
DOCLING_MAX_BYTES 52428800 Files above this size are not sent to Docling; the chain continues with Tika.

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