Docling Document Extraction

warning

This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial.

🐤 Docling Document Extraction

This documentation provides a step-by-step guide to integrating Docling with Open WebUI. Docling is a document processing library designed to transform a wide range of file formats (including PDFs, Word documents, spreadsheets, HTML, and images) into structured data such as JSON or Markdown. With built-in support for layout detection, table parsing, and language-aware processing, Docling streamlines document preparation for AI applications like search, summarization, and retrieval-augmented generation, all through a unified and extensible interface.

Prerequisites

• Open WebUI instance
• Docker installed on your system
• Docker network set up for Open WebUI

Integration Steps

Step 1: Run Docling-Serve Container

Basic CPU deployment:

docker run -p 5001:5001 \
  -e DOCLING_SERVE_ENABLE_UI=true \
  quay.io/docling-project/docling-serve

GPU deployment (NVIDIA CUDA):

docker run --gpus all -p 5001:5001 \
  -e DOCLING_SERVE_ENABLE_UI=true \
  quay.io/docling-project/docling-serve-cu128

Recommended production deployment with Docker Compose:

services:
  docling-serve:
    image: quay.io/docling-project/docling-serve-cu128:latest
    container_name: docling-serve
    ports:
      - "5001:5001"
    environment:
      # Enable the web UI for testing
      - DOCLING_SERVE_ENABLE_UI=true
      # CRITICAL: Required for picture description with external LLM APIs
      - DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true
      # Maximum wait time for sync requests (seconds) - increase for large documents
      - DOCLING_SERVE_MAX_SYNC_WAIT=600
      # Number of local engine workers
      - DOCLING_SERVE_ENG_LOC_NUM_WORKERS=2
      # CPU thread configuration
      - OMP_NUM_THREADS=4
      - MKL_NUM_THREADS=4
      # IMPORTANT: Keep at 1 to avoid "Task Not Found" errors
      - UVICORN_WORKERS=1
    restart: unless-stopped
    # For GPU support with NVIDIA:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Important: UVICORN_WORKERS Setting

When using UVICORN_WORKERS greater than 1 with the default LocalOrchestrator, you will encounter "Task Not Found (404)" errors. This happens because each worker maintains its own in-memory task store, making tasks created by one worker inaccessible to another.

Always use UVICORN_WORKERS=1 unless you have configured a shared state mechanism like Redis.

Step 2: Configure Open WebUI

1. Log in to your Open WebUI instance
2. Navigate to Settings → Admin → Documents
3. Change the Default content extraction engine dropdown to Docling
4. Set Docling Server URL to http://host.docker.internal:5001 (Docker) or http://localhost:5001 (native). The default is http://docling:5001.
5. Optionally set API Key (DOCLING_API_KEY), which is sent to docling-serve as the X-Api-Key header
6. Save the changes

Step 3: Configure Picture Description (Optional)

To enable AI-powered image description within documents, add the picture description options to the Parameters JSON field under the Docling settings in the Documents tab. Two modes are available:

• local: Vision model runs within the Docling container itself, configured via picture_description_local
• API: Docling calls an external service (e.g., Ollama, OpenAI-compatible endpoint), configured via picture_description_api

Required for API Mode

When using API mode (calling external services like Ollama), you MUST set the following environment variable on docling-serve:

DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true

Without this, Docling will reject requests to external services with an OperationNotAllowed error.

JSON Configuration Examples

Make sure your configuration is valid JSON!

Nested objects must be written as JSON strings

Open WebUI forwards the Docling Parameters values to docling-serve as multipart form fields exactly as you enter them, without re-encoding. Docling parses its nested options (picture_description_local, picture_description_api, picture_description_custom_config) from a JSON string, so an object written inline is not transmitted correctly and the upload fails with an Invalid JSON for field ... error on the docling-serve side. Write these values as escaped JSON strings, as shown below. Plain values, booleans and lists need no escaping.

Local Model Configuration:

{
  "do_picture_description": true,
  "picture_description_local": "{\"repo_id\": \"HuggingFaceTB/SmolVLM-256M-Instruct\", \"generation_config\": {\"max_new_tokens\": 200, \"do_sample\": false}, \"prompt\": \"Describe this image in a few sentences.\"}"
}

API Configuration (Ollama):

{
  "do_picture_description": true,
  "picture_description_api": "{\"url\": \"http://host.docker.internal:11434/v1/chat/completions\", \"params\": {\"model\": \"llava:7b\"}, \"timeout\": 60, \"prompt\": \"Describe this image in great detail.\"}"
}

Docling-Serve Environment Variables Reference

Variable	Default	Description
DOCLING_SERVE_ENABLE_UI	false	Enable the web UI at /ui endpoint
DOCLING_SERVE_ENABLE_REMOTE_SERVICES	false	Required for API-based picture description
DOCLING_SERVE_MAX_SYNC_WAIT	120	Max seconds to wait for synchronous requests
DOCLING_SERVE_ENG_LOC_NUM_WORKERS	1	Number of local engine workers
DOCLING_SERVE_ARTIFACTS_PATH	/app/data	Path to store model artifacts
UVICORN_WORKERS	1	Number of Uvicorn workers (keep at 1!)
OMP_NUM_THREADS	4	OpenMP thread count for CPU processing
MKL_NUM_THREADS	4	Intel MKL thread count

Docling Parameters Reference (Open WebUI)

Configure via DOCLING_PARAMS JSON in Settings > Admin > Documents or via environment variable.

Parameter	Type	Description	Allowed Values
pdf_backend	string	PDF parsing engine	dlparse_v1, dlparse_v2, dlparse_v4, pypdfium2
table_mode	string	Table extraction quality	fast, accurate
ocr_engine	string	OCR library	tesseract, easyocr, ocrmac, rapidocr
do_ocr	bool	Enable OCR	true, false
force_ocr	bool	Force OCR on digital PDFs	true, false
pipeline	string	Processing complexity	standard, fast
ocr_lang	list[string]	OCR languages	See note below

Language Codes

• Tesseract: 3-letter ISO 639-2 (e.g., eng, deu, fra)
• EasyOCR: 2-letter ISO 639-1 (e.g., en, de, fr)

Example Configuration:

{
  "do_ocr": true,
  "pdf_backend": "dlparse_v4",
  "table_mode": "accurate",
  "ocr_engine": "tesseract",
  "ocr_lang": ["eng"]
}

Verifying the Integration

1. Access the Docling UI at http://127.0.0.1:5001/ui
2. Upload a test document and verify it returns markdown output
3. In Open WebUI, upload a file to a knowledge base and confirm processing completes

Troubleshooting

"Task result not found. Please wait for a completion status."

Cause: Multiple Uvicorn workers with in-memory task storage.

Solution: Set UVICORN_WORKERS=1 in your docling-serve configuration.

"Connections to remote services is only allowed when set explicitly"

Cause: Picture description API mode requires explicit opt-in.

Solution: Add DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true to your docling-serve environment.

404 Not Found on /v1alpha/convert/file

Cause: Using outdated docling-serve version or Open WebUI version.

Solution:

• Update Open WebUI to the latest version (uses /v1/convert/file)
• Update docling-serve to v1.0+ (uses /v1 API)

"Invalid JSON for field ..." in the docling-serve logs

Cause: A nested Docling parameter was written as an inline object. Open WebUI passes Docling Parameters through as form fields unchanged, so Docling receives the object's keys instead of the object.

Solution: Write nested values such as picture_description_api as escaped JSON strings. See JSON Configuration Examples.

Timeout errors on large documents

Cause: DOCLING_SERVE_MAX_SYNC_WAIT is too low for document processing time.

Solution: Increase DOCLING_SERVE_MAX_SYNC_WAIT (e.g., 600 for 10 minutes).

OCR not working or incorrect language detection

Cause: Wrong ocr_lang format for the selected OCR engine.

Solution:

• Tesseract uses 3-letter codes: ["eng", "deu"]
• EasyOCR uses 2-letter codes: ["en", "de"]

"Error calling Docling" with no specific details

Steps to diagnose:

1. Check docling-serve logs: docker logs docling-serve
2. Test Docling directly via the UI at http://localhost:5001/ui
3. Verify network connectivity between Open WebUI and docling-serve containers

Conclusion

Integrating Docling with Open WebUI enhances document processing capabilities significantly. Key points to remember:

• Always set UVICORN_WORKERS=1 to avoid task routing issues
• Enable DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true when using API-based picture description
• Increase DOCLING_SERVE_MAX_SYNC_WAIT for large documents
• Validate JSON syntax in all configuration fields