Enabling Remote Services in Docling Serve#

1. Set Environment Variables Before Starting the Server#

export DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true
export DOCLING_SERVE_ALLOW_CUSTOM_PICTURE_DESCRIPTION_CONFIG=true
export DOCLING_SERVE_ALLOW_CUSTOM_CODE_FORMULA_CONFIG=true

The enable_remote_services flag is not passed via API request — it must be set as an environment variable before launching Docling Serve.

2. For Docker#

docker run -e DOCLING_SERVE_ENABLE_REMOTE_SERVICES=true \
           -e DOCLING_SERVE_ALLOW_CUSTOM_PICTURE_DESCRIPTION_CONFIG=true \
           -e DOCLING_SERVE_ALLOW_CUSTOM_CODE_FORMULA_CONFIG=true \
           quay.io/docling-project/docling-serve-cpu

3. Configuration File Support#

Docling Serve supports loading configuration from YAML or JSON files via the DOCLING_SERVE_CONFIG_FILE environment variable. This is particularly useful for complex configurations with nested structures:

export DOCLING_SERVE_CONFIG_FILE=/path/to/config.yaml

Environment variables take precedence over config file values. See docs/configuration.md for the complete configuration file format and examples.

4. Custom Presets and Engine Restrictions#

Administrators can define custom presets using environment variables:

• DOCLING_SERVE_CUSTOM_PICTURE_DESCRIPTION_PRESETS: JSON object mapping preset IDs to picture description configuration options
• DOCLING_SERVE_CUSTOM_CODE_FORMULA_PRESETS: JSON object mapping preset IDs to code/formula configuration options

Example:

export DOCLING_SERVE_CUSTOM_PICTURE_DESCRIPTION_PRESETS='{"my_api": {"engine_options": {"engine_type": "api"}, "api_overrides": {...}}}'

Important: Server administrators may restrict which engine types are allowed via:

• DOCLING_SERVE_ALLOWED_PICTURE_DESCRIPTION_ENGINES
• DOCLING_SERVE_ALLOWED_CODE_FORMULA_ENGINES

If engine restrictions are in place, custom configurations using external APIs (with engine_type: "api") may not work unless "api" is explicitly included in the allowed engines list.

See docs/configuration.md for complete details on preset management and configuration options.

Using External API for Picture Description#

{
  "options": {
    "do_picture_description": true,
    "picture_description_custom_config": {
      "engine_options": {"engine_type": "api"},
      "api_overrides": {
        "api": {
          "url": "https://your-openai-compatible-api/v1/chat/completions",
          "headers": {"Authorization": "Bearer YOUR_API_KEY"},
          "params": {"model": "your-model"},
          "timeout": 90
        }
      }
    }
  }
}

Filtering Pictures by Classification#

Three optional filtering parameters allow you to control which pictures get sent to the external API for description:

• classification_allow (List[PictureClassificationLabel] or NoneType): Only describe pictures whose predicted class is in this allow-list. This can be used to limit descriptions to specific types of pictures.
• classification_deny (List[PictureClassificationLabel] or NoneType): Do not describe pictures whose predicted class is in this deny-list. This can be used to exclude certain types of pictures from receiving descriptions.
• classification_min_confidence (float): Minimum classification confidence required before a picture can be described. This allows filtering based on the classification model's confidence level.

Example with classification filters:

{
  "options": {
    "do_picture_description": true,
    "picture_description_custom_config": {
      "engine_options": {"engine_type": "api"},
      "api_overrides": {
        "api": {
          "url": "https://your-openai-compatible-api/v1/chat/completions",
          "headers": {"Authorization": "Bearer YOUR_API_KEY"},
          "params": {"model": "your-model"},
          "timeout": 90
        }
      },
      "classification_allow": ["Figure", "Chart"],
      "classification_min_confidence": 0.7
    }
  }
}

This example will only describe pictures classified as "Figure" or "Chart" with at least 70% confidence.

Using External API for Formula Enrichment#

You can use an external OpenAI-compatible API for formula enrichment via code_formula_custom_config with engine_type: "api":

{
  "options": {
    "to_formats": ["md"],
    "do_formula_enrichment": true,
    "do_code_enrichment": true,
    "code_formula_custom_config": {
      "engine_options": {
        "engine_type": "api",
        "url": "https://api.polza.ai/v1/chat/completions",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        },
        "params": {
          "model": "gpt-4o-mini",
          "max_completion_tokens": 4096
        },
        "timeout": 90
      },
      "model_spec": {
        "name": "gpt-4o-mini",
        "default_repo_id": "openai/gpt-4o-mini",
        "prompt": "",
        "response_format": "text"
      },
      "scale": 2.0,
      "extract_code": true,
      "extract_formulas": true
    }
  }
}

Note: Do not attempt to run the local CodeFormulaV2 model on a 4-core CPU / 8 GB RAM server. It requires ~15.5 GB RAM and benchmarks show ~743 seconds for 10 documents at 316% CPU usage. Using an external API is the recommended approach for this hardware configuration.

Performance Tips for 4 CPU / 8 GB RAM#

• Set UVICORN_WORKERS=1 (required at 8 GB RAM)
• Set DOCLING_NUM_THREADS=4 and OMP_NUM_THREADS=4
• Disable unused features in requests (do_ocr=false, do_table_structure=false, etc.) unless explicitly needed
• Use external APIs for formula and picture enrichment instead of local models