Core Pipeline Arguments for olmOCR: Complete Configuration Guide

The olmOCR pipeline is controlled through a comprehensive set of command-line arguments defined in olmocr/pipeline.py, including required workspace paths, model selection, worker concurrency settings, VLLM server options, and Beaker cluster execution parameters.

The olmOCR pipeline from the Allen Institute for AI (allenai/olmocr) provides a robust command-line interface for processing PDFs and images through optical character recognition. Understanding the core pipeline arguments is essential for tuning performance, managing GPU resources, and configuring output formats. This guide covers the essential parameters defined in the argparse configuration at lines 1201–1270 of olmocr/pipeline.py.

Required Arguments

The pipeline requires exactly one positional argument that serves as the foundation for all file operations.

workspace

The workspace parameter (defined at line 1201) is a required positional argument specifying the base directory where the pipeline stores its work-queue, intermediate files, and final results. This path can reference a local filesystem location or an S3 URI (e.g., s3://bucket-name/workspace).

Input and Model Configuration

These arguments control what documents are processed and which model checkpoint performs the OCR inference.

--pdfs

The --pdfs argument (line 1207) accepts a list of S3 glob patterns, file paths, or text files containing PDF locations. The pipeline supports processing both PDF documents and image files through this interface.

--model

The --model argument (line 1213) specifies the path to the model checkpoint and defaults to allenai/olmOCR-2-7B-1025-FP8. You can provide a local directory, S3 location, or Hugging Face repository identifier.

Worker Concurrency and Retry Logic

These settings manage parallelization and error handling during document processing.

--workers

The --workers argument (line 1224) controls the number of concurrent worker coroutines that pull items from the queue and invoke the model. The default value is 20, which balances throughput against GPU memory constraints.

--max_page_retries

Set via --max_page_retries (line 1221), this argument defines how many times a single page may be retried (for example, when applying rotation fixes). The default is 8 attempts per page.

--max_page_error_rate

The --max_page_error_rate argument (line 1222) specifies the maximum fraction of pages in a document that may fall back to the OCR-fallback path before the entire document is discarded. The default threshold is 0.004 (0.4%).

--max_concurrent_requests

The --max_concurrent_requests argument (line 1224) sets an upper bound on simultaneous HTTP calls to the VLLM server. The default of 1600 protects GPU resources from overload while maintaining high throughput.

Image Processing and Output Options

These flags control preprocessing dimensions and auxiliary output formats.

--target_longest_image_dim

The --target_longest_image_dim argument (line 1229) defines the desired pixel size of the longest side when rasterizing PDF pages to PNG format before model ingestion. The default is 1288 pixels.

--guided_decoding

When enabled via --guided_decoding (line 1231), this flag activates guided-regex decoding mode that forces the model to emit a structured YAML front-matter block, ensuring consistent output formatting.

--apply_filter

The --apply_filter flag (line 1226) enables a language filter implemented in olmocr/filter/filter.py that skips non-English PDFs and obvious spam or form PDFs before processing.

--markdown

The --markdown flag (line 1228) instructs the pipeline to write extracted natural-language text to a parallel Markdown file tree preserving the original folder hierarchy, in addition to the standard JSONL Dolma output.

--disk_logging

The --disk_logging argument (line 1233) enables writing a full debug log to disk (default filename olmocr-pipeline-debug.log) for troubleshooting complex ingestion workflows.

VLLM Server Configuration

These parameters configure the inference backend, supporting both local VLLM instances and remote API endpoints.

--server and --api_key

The --server argument (line 1244) specifies the URL of an external VLLM-compatible inference server. When provided, the pipeline disables automatic local VLLM launch. Use --api_key (line 1247) to authenticate with remote services like DeepInfra.

GPU and Memory Settings

The pipeline passes these arguments directly to the VLLM server subprocess:

• --gpu-memory-utilization (line 1253): Fraction of GPU memory allocated for KV-cache
• --max_model_len (line 1255): Maximum sequence length in tokens (default 16384)
• --tensor-parallel-size or -tp (line 1256): Number of tensor-parallel replicas (default 1)
• --data-parallel-size or -dp (line 1257): Number of data-parallel replicas (default 1)
• --port (line 1258): Local VLLM server port (default 30024)

Beaker Cluster Execution

For distributed execution on AI2's Beaker platform, the pipeline provides specific orchestration arguments.

--beaker

The --beaker flag (line 1262) submits the job to a Beaker cluster instead of running locally.

Beaker Resource Allocation

• --beaker_workspace (line 1263): Target workspace (default ai2/olmocr)
• --beaker_cluster (line 1265): List of clusters (defaults to jupiter, ceres, neptune, saturn)
• --beaker_gpus (line 1269): GPU replicas per task (default 1)
• --beaker_priority (line 1270): Job priority level (default normal)

Usage Examples

Basic Local Execution with GPU

python -m olmocr.pipeline \
    /data/olmocr_workspace \
    --pdfs s3://my-bucket/pdfs/*.pdf \
    --workers 12 \
    --max_page_retries 6 \
    --target_longest_image_dim 1024 \
    --markdown

This configuration processes S3 PDFs using twelve concurrent workers, limits retries to six per page, renders pages at 1024px maximum dimension, and outputs parallel Markdown files.

External VLLM Server Configuration

python -m olmocr.pipeline \
    s3://my-bucket/olmocr_workspace \
    --pdfs my-pdf-list.txt \
    --server https://api.deepinfra.com/v1/predictions \
    --api_key $DEEPINFRA_API_KEY \
    --workers 8 \
    --max_concurrent_requests 500 \
    --guided_decoding

This example connects to a remote DeepInfra endpoint with reduced concurrency limits and structured YAML output enabled.

Beaker Cluster Submission

python -m olmocr.pipeline \
    s3://my-bucket/olmocr_workspace \
    --pdfs s3://my-bucket/pdfs/*.pdf \
    --beaker \
    --beaker_cluster ai2/jupiter \
    --beaker_gpus 2 \
    --workers 20 \
    --apply_filter

This submits the job to the Jupiter cluster with two GPUs per task, twenty workers, and the spam-filter enabled.

Summary

• The workspace positional argument is required and supports both local paths and S3 URIs
• Concurrency is controlled through --workers (default 20) and --max_concurrent_requests (default 1600)
• The --model argument defaults to allenai/olmOCR-2-7B-1025-FP8 but accepts custom checkpoints
• Image dimensions are controlled via --target_longest_image_dim (default 1288px)
• Structured output requires --guided_decoding while --markdown enables parallel text export
• Remote inference servers are supported via --server and --api_key
• Beaker cluster execution uses --beaker along with resource-specific flags like --beaker_gpus

Frequently Asked Questions

What is the default model used by olmOCR?

According to the source code in olmocr/pipeline.py at line 1213, the default model is allenai/olmOCR-2-7B-1025-FP8. You can override this with the --model argument to use local directories, S3 paths, or other Hugging Face repositories.

How do I connect to an external VLLM server instead of running locally?

Specify the --server argument with your endpoint URL (for example, https://api.deepinfra.com/v1/predictions) and provide authentication via --api_key. When these arguments are present, the pipeline disables automatic local VLLM launch and routes all inference requests to the specified remote server.

What does the --apply_filter flag do?

The --apply_filter flag enables a language-based filtering system implemented in olmocr/filter/filter.py that automatically detects and skips non-English PDFs, spam documents, and form-heavy PDFs before they reach the model inference stage, improving processing efficiency and output quality.

How many workers should I use with olmOCR?

The default of 20 workers is optimized for most GPU configurations, but you should adjust --workers based on your available VRAM and the setting of --max_concurrent_requests. For remote APIs, reduce workers to 8 or fewer to respect rate limits, while local VLLM instances can scale up based on your --gpu-memory-utilization and tensor-parallel configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}