# Core Pipeline Arguments for olmOCR: Complete Configuration Guide

> Explore the core pipeline arguments for olmOCR in this complete configuration guide. Learn about workspace paths, model selection, worker concurrency, VLLM, and Beaker cluster options.

- Repository: [Ai2/olmocr](https://github.com/allenai/olmocr)
- Tags: configuration-guide
- Published: 2026-07-02

---

**The olmOCR pipeline is controlled through a comprehensive set of command-line arguments defined in [`olmocr/pipeline.py`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1201)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1207)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1213)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1224)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1221)), 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1222)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1224)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1229)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1231)), 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1226)) enables a language filter implemented in [`olmocr/filter/filter.py`](https://github.com/allenai/olmocr/blob/main/olmocr/filter/filter.py) that skips non-English PDFs and obvious spam or form PDFs before processing.

### --markdown

The `--markdown` flag ([line 1228](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1228)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1233)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1244)) specifies the URL of an external VLLM-compatible inference server. When provided, the pipeline disables automatic local VLLM launch. Use `--api_key` ([line 1247](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1247)) 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1253)): Fraction of GPU memory allocated for KV-cache
- **`--max_model_len`** ([line 1255](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1255)): Maximum sequence length in tokens (default **16384**)
- **`--tensor-parallel-size`** or `-tp` ([line 1256](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1256)): Number of tensor-parallel replicas (default **1**)
- **`--data-parallel-size`** or `-dp` ([line 1257](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1257)): Number of data-parallel replicas (default **1**)
- **`--port`** ([line 1258](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1258)): 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](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1262)) submits the job to a Beaker cluster instead of running locally.

### Beaker Resource Allocation

- **`--beaker_workspace`** ([line 1263](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1263)): Target workspace (default `ai2/olmocr`)
- **`--beaker_cluster`** ([line 1265](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1265)): List of clusters (defaults to jupiter, ceres, neptune, saturn)
- **`--beaker_gpus`** ([line 1269](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1269)): GPU replicas per task (default **1**)
- **`--beaker_priority`** ([line 1270](https://github.com/allenai/olmocr/blob/main/olmocr/pipeline.py#L1270)): Job priority level (default `normal`)

## Usage Examples

### Basic Local Execution with GPU

```bash
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

```bash
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

```bash
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`](https://github.com/allenai/olmocr/blob/main/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`](https://github.com/allenai/olmocr/blob/main/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.