Speeding up first ICR operation by predownloading models

Use warmup to pre-download vision models before processing documents.

Common use cases include:

• Removing first-request latency in user-facing apps
• Preparing batch jobs before processing starts
• Marking containers ready only after dependencies are available
• Preloading models before offline operation
• Meeting latency targets for production APIs

This guide shows how to warm up Vision models so extractContent() runs without initial download delays. In version 2.1.12, local Vision is zero-configuration: required models download automatically on first use, and warmup moves that work to application startup.

How Nutrient helps

Nutrient Java SDK handles model download orchestration and cache management.

The SDK handles:

• AI model downloads, storage locations, and cache invalidation strategies
• Model requirements for specific vision engine configurations (ICR, OCR, VLM-enhanced, and the local VLM provider)
• GPU acceleration preparation when local Vision uses an accelerated backend
• Network failures during model downloads and retry behavior
• Model availability checks with readiness probes and health endpoints

Complete implementation

This example warms up ICR models and then runs extraction:

package io.nutrient.Sample;

Import required classes from the SDK:

import io.nutrient.sdk.Document;
import io.nutrient.sdk.Vision;
import io.nutrient.sdk.enums.VisionEngine;
import io.nutrient.sdk.exceptions.NutrientException;

import java.io.FileWriter;
import java.io.IOException;

public class SpeedUpFirstIcrByDownloadingRequirements {

Create the main method and declare thrown exceptions:

    public static void main(String[] args) throws NutrientException, IOException {

Warming up Vision API

Open a document in try-with-resources, set VisionEngine.Icr, create a vision instance, and call warmup().

In this sample:

• setEngine(VisionEngine.Icr) selects ICR mode.
• vision.warmup() downloads required models for the configured engine and provider.
• Local Vision and VLM-enhanced modes cache downloaded model files for subsequent requests.
• GPU acceleration is prepared when an accelerated backend is available.
• The console output shows progress.

        try (Document document = Document.open("input.png")) {
            // Configure ICR engine
            document.getSettings().getVisionSettings().setEngine(VisionEngine.Icr);

            // Create Vision instance
            Vision vision = Vision.set(document);

            // Pre-download all required models
            // This ensures subsequent extractContent() calls are fast
            System.out.println("Downloading Vision models...");
            vision.warmup();
            System.out.println("Models ready!");

Processing documents after warmup

After warmup, run extractContent() without download latency.

In this sample:

• extractContent() returns a JSON string.
• The JSON output is written to output.json.
• File handling uses try-with-resources.

            // Now extractContent() won't need to download anything
            String contentJson = vision.extractContent();

            try (FileWriter writer = new FileWriter("output.json")) {
                writer.write(contentJson);
            }
        }
    }
}

Best practices

Apply these patterns for using warmup effectively in production environments:

• Application startup — Run warmup before accepting requests.
• Background thread — Run warmup asynchronously during initialization.
• Health checks — Expose warmup status in readiness probes.
• Deployment pipelines — Validate model availability during deployment.
• Offline environments — Download models while connected, then process offline.

What gets downloaded?

Warmup downloads model sets based on VisionSettings.engine and the selected VLM provider:

• ICR mode (VisionEngine.Icr) — Layout, text, tables, equations, barcode, and key-value detection models.
• OCR mode (VisionEngine.AdaptiveOcr) — OCR language and text recognition resources.
• VLM-enhanced mode (VisionEngine.VlmEnhancedIcr) — ICR resources plus VLM-related resources.
• Local provider (VlmProvider.Local) — In-process vision model files used by local VLM description, classification, and VLM-enhanced workflows.

Downloaded models are cached locally and reused across restarts until the cache is cleared or models are updated. GPU-capable builds prepare the accelerated runtime during warmup when the configured workflow uses it.

Conclusion

Use this workflow to pre-download ICR requirements:

1. Open a document using try-with-resources for automatic resource cleanup after warmup and processing complete.
2. The SDK supports multiple document formats, including PNG, JPEG, PDF, and TIFF for vision operations.
3. Retrieve the vision settings with document.getSettings().getVisionSettings() to configure the vision engine.
4. Set the engine to ICR with setEngine(VisionEngine.Icr) to enable advanced document understanding with layout detection, text recognition, table extraction, equation recognition, and key-value pair detection.
5. Alternative engines include OCR mode for basic text extraction and VLM-enhanced mode for semantic understanding with vision language models.
6. Create a vision instance with Vision.set() bound to the document with configured engine settings.
7. Call vision.warmup() to trigger pre-download of all AI models required for the configured vision engine, fetching models from the SDK’s model repository and caching them locally.
8. Warmup downloads different model sets based on engine configuration — ICR downloads comprehensive document understanding models, OCR downloads text recognition models, and VLM downloads ICR models plus semantic understanding resources.
9. Console output provides feedback during model downloads, informing users about download progress and completion status for potentially multi-second operations.
10. After warmup completes, call vision.extractContent() to perform ICR operations without model download delays, ensuring predictable and fast processing for all subsequent requests.
11. The extractContent() method returns extracted content as JSON, including document structure (headings, paragraphs, tables, lists), textual content, table structures, equations, and key-value pairs.
12. Write the extracted JSON to a file using try-with-resources with FileWriter for automatic resource cleanup after writing completes.
13. Handle NutrientException for vision processing failures, including model download errors, processing failures, or configuration issues.
14. Handle IOException for file operations, including read failures or write errors when saving extracted content.

For related image extraction workflows, refer to the Java SDK guides.

Download this ready-to-use sample package to integrate warmup into application startup.