docling-project / docling-project/docling-serve

feat: Add DOCLING_SERVE_DEFAULT_OCR_ENGINE environment variable for deploy-level OCR engine configuration

Open Beginner friendly
#554 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1.8k
Forks
340
Avg merge
6d 11h
Merged PRs (30d)
8

Description

## Summary

There is currently no way to configure the default OCR engine at deploy time. The `ocr_engine` parameter only exists at the request level, meaning every client must explicitly pass `ocr_engine=tesseract` (or whichever engine) on every request, or they silently get EasyOCR regardless of the server environment.

## Expected behaviour

A new environment variable — `DOCLING_SERVE_DEFAULT_OCR_ENGINE` — should allow operators to set the OCR engine server-wide at deploy time, so that requests which do not specify an `ocr_engine` fall back to the configured default rather than always defaulting to EasyOCR.

```bash
DOCLING_SERVE_DEFAULT_OCR_ENGINE=tesseract
```

## Motivation

- In many deployment environments (CPU-only, FIPS-compliant, lightweight containers), EasyOCR is undesirable or broken, while Tesseract is the preferred engine.
- The pattern already exists in the codebase for other pipeline components — `DOCLING_SERVE_DEFAULT_TABLE_STRUCTURE_KIND` and default layout kind are both configurable at the server level. OCR is a notable omission.
- Forcing every downstream client to pass `ocr_engine` on every request is not practical when docling-serve is used as infrastructure (e.g. behind Open WebUI or other integrations that don't expose this parameter).

## Suggested implementation

Follow the same pattern as the existing default table/layout settings in `docling_serve/settings.py` — add a `default_ocr_engine` field to `DoclingServeSettings` with `DOCLING_SERVE_DEFAULT_OCR_ENGINE` as its env var, and apply it as the fallback when no `ocr_engine` is provided in the request options.

Contributor guide

Open the contributing guide

Research direction

Start in docling_serve/settings.py and compare the existing default table-structure and layout settings. Trace how request options apply their OCR engine fallback. Done means DOCLING_SERVE_DEFAULT_OCR_ENGINE configures the server-wide default while an explicitly provided request value still takes precedence.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
2/5
Estimated time
Half a day
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.