Configuration Guide

Complete reference for all Duckling configuration options.

Environment Variables

Create a .env file in the backend directory:

# Flask Configuration
FLASK_ENV=development          # development | production | testing
SECRET_KEY=your-secret-key     # Required for production
DEBUG=True                     # Enable debug mode

# File Handling
MAX_CONTENT_LENGTH=104857600   # Max upload size in bytes (100MB default)

# Database (optional - defaults to SQLite)
DATABASE_URL=sqlite:///history.db

Production Environment

FLASK_ENV=production
SECRET_KEY=your-very-secure-random-key-here
DEBUG=False
MAX_CONTENT_LENGTH=209715200   # 200MB for production

OCR Settings

OCR (Optical Character Recognition) extracts text from images and scanned documents.

Configuration Options

OCR Backends

{
  "ocr": {
    "backend": "easyocr",
    "use_gpu": true,
    "language": "en"
  }
}

{
  "ocr": {
    "backend": "tesseract",
    "language": "eng"
  }
}

{
  "ocr": {
    "backend": "ocrmac",
    "language": "en"
  }
}

{
  "ocr": {
    "backend": "rapidocr",
    "language": "en"
  }
}

Supported Languages

Table Settings

Configure how tables are detected and extracted from documents.

Configuration Options

Detection Modes

{
  "tables": {
    "enabled": true,
    "mode": "accurate",
    "do_cell_matching": true
  }
}

{
  "tables": {
    "enabled": true,
    "mode": "fast",
    "do_cell_matching": false
  }
}

Image Settings

Configure image extraction and processing.

Configuration Options

Example Configurations

{
  "images": {
    "extract": true,
    "classify": true,
    "generate_page_images": true,
    "generate_picture_images": true,
    "generate_table_images": true,
    "images_scale": 2.0
  }
}

{
  "images": {
    "extract": false,
    "classify": false,
    "generate_page_images": false,
    "generate_picture_images": false,
    "generate_table_images": false
  }
}

Performance Settings

Optimize processing speed and resource usage.

Configuration Options

Device Options

Example Configurations

{
  "performance": {
    "device": "cuda",
    "num_threads": 8,
    "document_timeout": null
  }
}

{
  "performance": {
    "device": "cpu",
    "num_threads": 2,
    "document_timeout": 60
  }
}

{
  "performance": {
    "device": "mps",
    "num_threads": 4,
    "document_timeout": null
  }
}

Chunking Settings

Configure document chunking for RAG applications.

Configuration Options

Example Configurations

{
  "chunking": {
    "enabled": true,
    "max_tokens": 512,
    "merge_peers": true
  }
}

{
  "chunking": {
    "enabled": true,
    "max_tokens": 2048,
    "merge_peers": false
  }
}

Output Settings

Configure default output format.

Complete Configuration Example

{
  "ocr": {
    "enabled": true,
    "backend": "easyocr",
    "language": "en",
    "mode": "default",
    "scale": 3.0,
    "force_full_page_ocr": false,
    "use_gpu": false,
    "confidence_threshold": 0.5
  },
  "tables": {
    "enabled": true,
    "structure_extraction": true,
    "mode": "accurate",
    "do_cell_matching": true
  },
  "images": {
    "extract": true,
    "classify": true,
    "generate_page_images": false,
    "generate_picture_images": true,
    "generate_table_images": true,
    "images_scale": 1.0
  },
  "performance": {
    "device": "auto",
    "num_threads": 4,
    "document_timeout": null
  },
  "chunking": {
    "enabled": false,
    "max_tokens": 512,
    "merge_peers": true
  },
  "output": {
    "default_format": "markdown"
  }
}

Configuration via API

Get Current Settings

curl http://localhost:5001/api/settings

Update Settings

curl -X PUT http://localhost:5001/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "ocr": {"backend": "tesseract"},
    "performance": {"num_threads": 8}
  }'

Reset to Defaults

curl -X POST http://localhost:5001/api/settings/reset

Server configuration (deploy-time)

Per-session settings below are stored in Duckling's database. Deploy-time options (API key, orchestration engine, structured logging) use DUCKLING_* environment variables and optional DUCKLING_CONFIG_FILE.

Full reference: Server Configuration.

Pipeline settings

Choose how Docling processes documents. Configure in Settings → Pipeline or via GET/PUT /api/settings/pipeline.

• Standard — default Docling PDF/document pipeline (OCR, tables, layout).
• VLM — vision-language model pipeline for PDFs and images.
• ASR — automatic speech recognition for audio/video inputs (.wav, .mp3, .mp4, etc.).

PDF settings

Configure in Settings → PDF or GET/PUT /api/settings/pdf.

Advanced chunking

Beyond enabled, max_tokens, and merge_peers in the UI, the API supports docling-serve–aligned chunker options via GET/PUT /api/settings/chunking:

See Settings API for examples.

Per-job overrides

When calling conversion APIs programmatically, you can override session settings for a single job:

• page_range — [start, end] 1-based PDF pages (UI: drop zone page fields)
• to_formats — export only selected formats for this job

See Conversion API.

Troubleshooting

OCR Not Working

1. EasyOCR initialization error: Switch to ocrmac (macOS) or tesseract
2. GPU errors: Set use_gpu: false
3. Low confidence results: Lower confidence_threshold

Slow Processing

1. Reduce images_scale to 0.5
2. Use mode: "fast" for tables
3. Disable generate_page_images
4. Increase num_threads

Memory Issues

1. Enable document_timeout (e.g., 120 seconds)
2. Process fewer files in batch
3. Reduce images_scale
4. Disable chunking if not needed