Docling (docling-serve, self-hosted)#

Status: verified locally (a self-hosted engine, so there is no hosted API to verify against). docling-serve 1.35.0 (docling 2.130.0, docling-core 2.98.0) was installed with pip install docling-serve (CPU torch) and run with docling-serve run in the development sandbox on 2026-09-24. The #[ignore]d live test in providers/docling.rs passes, and both fixtures (docling_multipage.json for multipage_001.pdf, docling_headings.json for headings_001.png, from benchmark/datasets/synthetic-v1) are real GET /v1/result/{task_id} responses from that server.

1. Summary#

Start a server:

docker run -p 5001:5001 quay.io/docling-project/docling-serve        # or docling-serve-cpu / -cu128
# without Docker (≈2.3 GB with CPU-only torch; models download on first use):
pip install docling-serve --extra-index-url https://download.pytorch.org/whl/cpu
docling-serve run --port 5001

Docling runs a layout model, TableFormer for table structure and an OCR engine for bitmap text, all locally. On a 4-core CPU a one-page image took ~30 s and a 2-page digital PDF ~20 s (first-request model loading excluded); a GPU image is much faster.

2. Models exposed by PuffinParse#

default is docling's standard pipeline with the server's defaults (OCR on, table structure accurate). Other pipelines and presets (pipeline: "vlm", ocr_preset, table_mode: "fast") are reachable through provider_options.

3. Request flow PuffinParse uses#

Asynchronous, because the synchronous /v1/convert/source is capped by the server's DOCLING_SERVE_MAX_SYNC_WAIT (120 s by default) and long documents exceed it.

1. POST {base}/v1/convert/source/async, JSON:

json { "options": { "to_formats": ["json"], "image_export_mode": "placeholder", "include_images": false, "page_range": [first, last], "ocr_lang": ["<language>"] }, "sources": [{"kind": "file", "base64_string": "<base64>", "filename": "<name>"}] }

URL inputs are sent as {"kind": "http", "url": "..."} and fetched by the server. page_range is only set when pages is given (docling takes one span; PuffinParse requests the span covering the selection and drops the other pages); ocr_lang only when language is set. provider_options are deep-merged into options. → {"task_id", "task_status": "pending", "task_position", ...} 2. GET {base}/v1/status/poll/{task_id} every 0.5 s growing to 5 s until task_status is success / partial_success / failure / skipped. 3. GET {base}/v1/result/{task_id} → ConvertDocumentResponse: {document: {filename, md_content, json_content, ...}, status, errors[], processing_time, timings, confidence}.

4. Response mapping#

json_content is a DoclingDocument: body.children (and furniture.children) are the reading order as {"$ref": "#/texts/3"} pointers into texts[], tables[], pictures[] and groups[]. PuffinParse walks body depth-first through groups, so blocks come out in docling's reading order.

• Boxes: each item's prov[].bbox is {l, t, r, b, coord_origin}. With the usual coord_origin: "BOTTOMLEFT" (PDF convention, y up) PuffinParse converts y0 = (H − t) / H, y1 = (H − b) / H; TOPLEFT boxes are only divided. H/W come from pages[n].size (PDF points for PDFs, pixels for images).
• An item with several prov entries (a paragraph continuing on the next page) is split into one block per page using each entry's charspan.
• Page.markdown is the page's blocks joined; docling's own md_content is not used because it has no page boundaries.
• Usage.pages = pages in json_content.pages (after page selection); pages without content are kept as empty pages.
• Metadata: docling_status, docling_processing_time_s, docling_confidence (docling's layout_score / ocr_score / mean_grade report) and docling_errors on partial_success.
• Block confidence is not set: docling reports quality per page/document, not per item.
• provider_job_id = the docling-serve task_id; raw = the whole result JSON.

5. Errors and limits#

5xx and network errors are retried with backoff like every HTTP provider. Results are single-use by default (DOCLING_SERVE_SINGLE_USE_RESULTS=true, removed DOCLING_SERVE_RESULT_REMOVAL_DELAY = 300 s after completion), so a result fetch that is retried after a dropped connection can 404; rerun the call. DOCLING_SERVE_MAX_DOCUMENT_TIMEOUT bounds processing time server-side.

6. Gotchas#

• The first request after start-up downloads and loads the models and can take minutes; the benchmark's latency numbers exclude that only if you warm the server first.
• The docs at docs/usage.md in docling-serve still show file_sources / http_sources in some examples; servers ≥ 1.x reject those with 422. PuffinParse sends sources with kind.
• include_images: false is sent so picture crops are not embedded in the JSON (they are unused and make results large). Override it in provider_options if you want them in raw.
• Heading levels are flat (level 1) unless you pass do_pdf_heading_hierarchy: true.

7. provider_options examples#

import puffinparse

puffinparse.parse("report.pdf", model="docling")                                   # standard pipeline
puffinparse.parse("report.pdf", model="docling", provider_options={"table_mode": "fast"})
puffinparse.parse("scan.pdf", model="docling",
              provider_options={"force_ocr": True, "ocr_preset": "tesseract"})
puffinparse.parse("paper.pdf", model="docling",
              provider_options={"do_formula_enrichment": True, "do_pdf_heading_hierarchy": True})
puffinparse.parse("doc.pdf", model="docling", base_url="http://gpu-box:5001")

Any ConvertDocumentsOptions field from the docling-serve API reference is accepted.

8. Links#

• docling-serve: https://github.com/docling-project/docling-serve — usage: docs/usage.md, configuration: docs/configuration.md; live OpenAPI at {base}/docs
• DoclingDocument format: https://docling-project.github.io/docling/concepts/docling_document/