Skip to content

feat: expose layout model selection as a per-request option #541

@b-g-d

Description

@b-g-d

Problem

The docling library supports 6 layout analysis models via LayoutOptions.model_spec (docling_layout_heron, docling_layout_heron_101, docling_layout_egret_medium, docling_layout_egret_large, docling_layout_egret_xlarge, docling_layout_v2), but docling-serve has no ergonomic way to select between them per-request.

Users must either:

  • Accept the default (heron)
  • Construct a raw layout_custom_config dict, which is undiscoverable and verbose

By contrast, ocr_engine already has a simple enum field for per-request selection.

Proposal

Add a layout_model enum field to ConvertDocumentsRequestOptions (mirroring the ocr_engine pattern):

{
  "options": {
    "layout_model": "docling_layout_egret_large",
    ...
  }
}

When set, a model validator expands it into the existing layout_custom_config dict, so no changes to docling_jobkit are needed. When layout_custom_config is explicitly provided, it takes precedence.

Additionally, a DOCLING_SERVE_DEFAULT_LAYOUT_MODEL env var would allow setting a server-wide default.

Implementation

PR: #540

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions