Docling Serve Configuration#

Docling Serve configuration operates at two independent levels:

Per-request — callers set pipeline options (OCR engine, table mode, image scale, enrichment flags) in the JSON/multipart request body via ConvertDocumentsOptions.
Server-level — operators control defaults, allowlists, resource limits, and orchestration backends via environment variables (prefix DOCLING_SERVE_) or an optional config file, defined in docling_serve/settings.py.

A ServicePolicy object is derived from server settings at startup and enforces constraints on every incoming request. Server defaults flow into the Docling pipeline through _build_cm_config() in orchestrator_factory.py.

Per-Request Pipeline Options#

All conversion endpoints accept an options object (type ConvertDocumentsOptions) in the request body. Key fields:

OCR#

Field	Default	Notes
`do_ocr`	`true`	Enable OCR on bitmap regions
`force_ocr`	`false`	Replace all existing text with OCR output
`ocr_preset`	`"auto"`	Engine preset: `"auto"`, `"easyocr"`, `"tesseract"`, `"rapidocr"`, etc.
`ocr_lang`	`null`	Language list; format varies by engine
`ocr_custom_config`	`null`	Full engine-specific config dict; mutually exclusive with `ocr_preset`

ocr_engine is deprecated — it is silently synced to ocr_preset when set, but ocr_preset is the canonical field .

Table Structure#

Field	Default	Notes
`do_table_structure`	`true`	Extract table structure
`table_mode`	`"accurate"`	`"fast"` or `"accurate"`
`table_cell_matching`	`true`	Match predicted cells back to PDF cells
`table_structure_preset`	`null`	Named preset e.g. `"tableformer_v1_fast"`, `"tableformer_v2"`
`table_structure_custom_config`	`null`	Custom model config dict; requires server permission

Layout#

Field	Default	Notes
`layout_preset`	`null`	Named preset e.g. `"docling_layout_default"`
`layout_custom_config`	`null`	Custom layout model config dict

Images and Output#

Field	Default	Notes
`images_scale`	`2.0`	Image resolution multiplier; server enforces `max_images_scale`
`include_images`	`true`	Include picture element images in output
`include_page_images`	`false`	Include full-page images
`image_export_mode`	`"placeholder"`	`"placeholder"`, `"embedded"`, or `"referenced"`

When image_export_mode is "placeholder", the server automatically coerces include_images and include_page_images to false to avoid wasted work .

Formula, Code, and Picture Enrichment#

Field	Default	Notes
`do_formula_enrichment`	`false`	LaTeX formula extraction via VLM
`do_code_enrichment`	`false`	Code block enrichment
`code_formula_preset`	`null`	Named preset; `"default"` resolves to `"codeformulav2"`
`do_picture_description`	`false`	Describe pictures using a VLM
`picture_description_preset`	`null`	Named preset e.g. `"smolvlm"`, `"granite_vision"`
`do_picture_classification`	`false`	Classify picture types

VLM Pipeline#

Field	Default	Notes
`pipeline`	`"standard"`	`"standard"` or `"vlm"`
`vlm_pipeline_preset`	`null`	Named preset e.g. `"granite_docling"`
`vlm_pipeline_custom_config`	`null`	Full VLM config; only allowed if `DOCLING_SERVE_ALLOW_CUSTOM_VLM_CONFIG=true`

Preset vs. custom config: for every pipeline stage, *_preset and *_custom_config are mutually exclusive. Custom configs require the corresponding allow_custom_*_config server flag .

Deprecated fields (emit DeprecationWarning): ocr_engine, picture_description_local, picture_description_api, vlm_pipeline_model, vlm_pipeline_model_local, vlm_pipeline_model_api .

Server-Level Environment Variables#

All settings use the prefix DOCLING_SERVE_ and are defined in DoclingServeSettings. List values accept JSON arrays or comma-separated strings; dict values accept JSON objects .

An optional config file (YAML or JSON) can be specified via DOCLING_SERVE_CONFIG_FILE. Priority order: init > env vars > .env dotenv > YAML/JSON config file > file secrets .

Resource Limits & Request Policy#

Variable	Default	Description
`DOCLING_SERVE_MAX_DOCUMENT_TIMEOUT`	604800 (7 days)	Per-document timeout ceiling in seconds
`DOCLING_SERVE_MAX_NUM_PAGES`	unlimited	Cap on pages per document
`DOCLING_SERVE_MAX_FILE_SIZE`	unlimited	Cap on uploaded file size in bytes
`DOCLING_SERVE_MAX_SOURCES_PER_REQUEST`	`3`	Max documents in a single request
`DOCLING_SERVE_MAX_IMAGES_SCALE`	`2.0`	Upper bound on `images_scale`; requests exceeding this get a 422
`DOCLING_SERVE_ALLOWED_IMAGE_EXPORT_MODES`	all	Restrict to `placeholder`, `referenced`, `embedded`
`DOCLING_SERVE_ALLOWED_TARGET_TYPES`	all	Restrict to `inbody`, `zip`, `s3`, `put`, `presigned_url`

Pipeline Defaults & Allowlists#

For each pipeline stage the server exposes three related variables (shown for OCR; analogous for vlm, picture_description, code_formula, table_structure, layout, picture_classification):

Variable	Default	Description
`DOCLING_SERVE_DEFAULT_OCR_PRESET`	`"auto"`	Preset used when request omits `ocr_preset`
`DOCLING_SERVE_ALLOWED_OCR_PRESETS`	all registered	Restrict which presets callers may request
`DOCLING_SERVE_CUSTOM_OCR_PRESETS`	`{}`	Define custom named presets as a JSON object
`DOCLING_SERVE_ALLOW_CUSTOM_OCR_CONFIG`	`false`	Gate whether `ocr_custom_config` in requests is accepted

Other stage defaults and their default preset values :

Stage	Default preset variable	Default value
VLM pipeline	`DOCLING_SERVE_DEFAULT_VLM_PRESET`	`"granite_docling"`
Picture description	`DOCLING_SERVE_DEFAULT_PICTURE_DESCRIPTION_PRESET`	`"smolvlm"`
Code/formula	`DOCLING_SERVE_DEFAULT_CODE_FORMULA_PRESET`	`"default"`
Picture classification	`DOCLING_SERVE_DEFAULT_PICTURE_CLASSIFICATION_PRESET`	`"document_figure_classifier_v2"`
Table structure	`DOCLING_SERVE_DEFAULT_TABLE_STRUCTURE_PRESET`	`"tableformer_v1_accurate"`
Layout	`DOCLING_SERVE_DEFAULT_LAYOUT_PRESET`	`"docling_layout_default"`

Orchestration Backend#

Variable	Default	Description
`DOCLING_SERVE_ENG_KIND`	`"local"`	Backend: `local`, `rq`, or `ray`
`DOCLING_SERVE_ENG_LOC_NUM_WORKERS`	`2`	Worker processes for the local backend
`DOCLING_SERVE_ENG_RQ_REDIS_URL`	(required for rq)	Redis connection URL
`DOCLING_SERVE_ENG_RAY_ADDRESS`	(required for ray)	Ray cluster address (`"auto"`, `"local"`, or URL)
`DOCLING_SERVE_ENG_RAY_REDIS_URL`	(required for ray)	Redis for task state

See .env.example for annotated examples of all variables, including full Ray autoscaling and Redis connection pool tuning.

Policy Enforcement#

build_service_policy() in policy.py derives a frozen ServicePolicy from settings at startup. Every conversion request is validated against it before reaching the orchestrator.

Validation rules enforced by validate_convert_options():

document_timeout must be ≤ max_document_timeout
images_scale must be ≤ max_images_scale (default 2.0); requests over the cap receive HTTP 422
ocr_preset must be in the server-computed allowed_ocr_presets set
image_export_mode must be in allowed_image_export_modes
vlm_pipeline_custom_config is rejected unless allow_custom_vlm_config=true

Source count, target type, and S3 source/target pairing are checked in validate_convert_request().

normalize_convert_options() applies silent fixes before validation: it sets a default document_timeout if omitted, and turns off include_images/include_page_images when image_export_mode is "placeholder" (since those images would be discarded anyway).

Key Source Files#

File	Purpose
`docling/datamodel/service/options.py`	`ConvertDocumentsOptions` — full per-request options schema
`docling_serve/settings.py`	`DoclingServeSettings` — all env-var-backed server settings
`docling_serve/policy.py`	`ServicePolicy`, validation, and normalization logic
`docling_serve/orchestrator_factory.py`	`_build_cm_config()` — maps server settings → `DoclingConverterManagerConfig`
`.env.example`	Annotated reference for all environment variables