Running the PaddleOCR PDF OCR service as a one-shot job, locally and on Azure Container Apps

paddleocr-pdf-api runs as an HTTP server that accepts PDF uploads and returns markdown. Setting RUN_MODE=job runs the same OCR pipeline on a single file and exits. This post runs it that way with docker run and as an Azure Container Apps job.

Using a Self-Hosted PDF OCR API with PaddleOCR describes the server and its endpoints. Deploying PaddleOCR PDF OCR service on Azure Container Apps runs it on Container Apps as a server.

What job mode does

RUN_MODE=job does not start the HTTP server. The process reads the file from standard input and identifies its type. It saves the file to /data/uploads/<job_id>/ and records a queued job in the same database the server uses. The OCR then runs page by page, and each page is written to the database as it finishes.

When the last page is done, the pages are joined in order and printed as the command's output. Redirected to a file, that output is the finished document.

Everything else is log output: the generated job id, the per-page progress lines, and whatever the OCR libraries print. A > redirect does not capture it, so it appears in the terminal while the file receives the markdown alone.

The process exits with one of three codes:

Exit code	Meaning
0	All pages processed. The markdown is printed.
1	The job did not reach completed. No markdown is printed.
2	No input arrived, or the file is not a type the API accepts.

Accepted input is the same set the service accepts: PDF, PNG, JPEG, BMP, TIFF and WEBP. A file is identified by content, not by name, because the job never sees a filename.

Running a single file

docker run --rm -i \
  -e RUN_MODE=job \
  edgaras0x4e/paddleocr-pdf-api:latest-text-baked \
  < document.pdf > document.md

-i is required. Without it the container has no standard input to read and exits with code 2. Do not add -t: with standard input redirected from a file, Docker prints the input device is not a TTY and does not start the container.

latest-text-baked is one of multiple images; Docker Hub lists the tags. The same run with a GPU image:

docker run --rm -i --gpus all \
  -e RUN_MODE=job \
  edgaras0x4e/paddleocr-pdf-api:latest-vl-baked \
  < document.pdf > document.md

Every run loads the model into memory. With the non-baked latest tag it is also downloaded first, into a container that is discarded when the run ends, so the download repeats on every run.

What survives the run

--rm with no volume discards /data, which holds the SQLite database and the stored copy of the input. The printed markdown is then the only result, and the job id in the log refers to a row that no longer exists.

Mounting the volume keeps both:

docker run --rm -i \
  -e RUN_MODE=job \
  -v ocr-data:/data \
  edgaras0x4e/paddleocr-pdf-api:latest-text-baked \
  < document.pdf > document.md

A server container started on the same volume then serves that job through the API, so GET /jobs lists it and GET /ocr/<job_id>/result returns the pages.

Do not run a job container and a server container on the same volume at the same time. Job mode inserts a queued row before it starts work, and a running server polls the same table for queued rows. The server can claim that row first, and then both processes run the same file.

With DATABASE_URL set, the rows are stored in PostgreSQL instead of inside the container:

docker run --rm -i \
  -e RUN_MODE=job \
  -e DATABASE_URL=postgresql://user:password@host:5432/ocr \
  edgaras0x4e/paddleocr-pdf-api:latest-text-baked \
  < document.pdf > document.md

Several job containers can then write to one database, and a server container on the same database serves all their jobs through the API. The double processing above cannot happen here: job mode locks the row before it starts, and a server skips rows it cannot lock.

A directory of files

for f in *.pdf; do
  docker run --rm -i -e RUN_MODE=job \
    edgaras0x4e/paddleocr-pdf-api:latest-text-baked \
    < "$f" > "${f%.pdf}.md"
done

Each iteration starts a container and loads the model again.

Azure Container Apps jobs

A Container Apps job cannot receive a file: it has no HTTP endpoint, and nothing arrives on its standard input. Instead, an Azure Files share is mounted into the job. Input files are uploaded there, and the replica writes the markdown back to the same share.

The environment

RG=rg-paddleocr
LOC=swedencentral
ENV=env-paddleocr
JOB=ocr-job

az group create --name $RG --location $LOC

az containerapp env create \
  --name $ENV \
  --resource-group $RG \
  --location $LOC \
  --enable-workload-profiles

The share

STORAGE=stpaddleocr$RANDOM

az storage account create \
  --name $STORAGE \
  --resource-group $RG \
  --location $LOC \
  --sku Standard_LRS \
  --kind StorageV2

az storage share-rm create \
  --name ocr-work \
  --storage-account $STORAGE \
  --resource-group $RG \
  --quota 100

STORAGE_KEY=$(az storage account keys list \
  --account-name $STORAGE \
  --resource-group $RG \
  --query "[0].value" -o tsv)

az storage directory create --share-name ocr-work --name in \
  --account-name $STORAGE --account-key "$STORAGE_KEY"

az storage directory create --share-name ocr-work --name out \
  --account-name $STORAGE --account-key "$STORAGE_KEY"

az containerapp env storage set \
  --name $ENV \
  --resource-group $RG \
  --storage-name ocrwork \
  --azure-file-account-name $STORAGE \
  --azure-file-account-key "$STORAGE_KEY" \
  --azure-file-share-name ocr-work \
  --access-mode ReadWrite

The job

# job.yaml
properties:
  environmentId: /subscriptions/<subscription-id>/resourceGroups/rg-paddleocr/providers/Microsoft.App/managedEnvironments/env-paddleocr
  workloadProfileName: Consumption
  configuration:
    triggerType: Manual
    replicaTimeout: 1800
    replicaRetryLimit: 0
    manualTriggerConfig:
      parallelism: 1
      replicaCompletionCount: 1
  template:
    containers:
      - name: main
        image: docker.io/edgaras0x4e/paddleocr-pdf-api:latest-text-baked
        resources:
          cpu: 4.0
          memory: 8.0Gi
        command: ["/bin/sh"]
        args:
          - -c
          - >
            for f in /work/in/*.pdf; do
              [ -e "$f" ] || continue;
              python3 -m app.api < "$f" > "/work/out/$(basename "$f" .pdf).md" && rm "$f";
            done
        env:
          - name: RUN_MODE
            value: job
          - name: DB_PATH
            value: /tmp/ocr.db
          - name: UPLOAD_DIR
            value: /tmp/uploads
        volumeMounts:
          - volumeName: ocr-work
            mountPath: /work
    volumes:
      - name: ocr-work
        storageName: ocrwork
        storageType: AzureFile

az containerapp job create --name $JOB --resource-group $RG --yaml job.yaml

One execution processes every PDF in in/, one process and one model load per file. A file is deleted after its markdown is written, so the next execution processes only the files uploaded since the last one.

DB_PATH and UPLOAD_DIR are paths on the replica's own filesystem rather than on the share. SQLite locks its database with byte-range locks, which fail over SMB, so a database file on an Azure Files mount needs nobrl in the mount options.

replicaTimeout: 1800 ends the replica after 30 minutes, whether or not the batch is finished. It has to exceed the time the whole batch takes, not the time one document takes. replicaRetryLimit: 0 means a failed replica is not retried.

Starting an execution

az storage file upload \
  --account-name $STORAGE \
  --account-key "$STORAGE_KEY" \
  --share-name ocr-work \
  --source document.pdf \
  --path in/document.pdf

az containerapp job start --name $JOB --resource-group $RG

The start command has override flags (--image, --command, --args, --env-vars) that replace the job's whole template for one execution. There is no flag for the volume mount, so an overridden execution has no /work and cannot read the uploaded files. Every execution therefore runs the template as created.

The same two steps from Python:

import subprocess

RG = "rg-paddleocr"
JOB = "ocr-job"
STORAGE = "<storage-account-name>"
STORAGE_KEY = "<storage-account-key>"


def submit(pdf_path, name):
    subprocess.run(
        ["az", "storage", "file", "upload",
         "--account-name", STORAGE, "--account-key", STORAGE_KEY,
         "--share-name", "ocr-work",
         "--source", pdf_path, "--path", f"in/{name}"],
        check=True, capture_output=True, text=True,
    )
    return subprocess.run(
        ["az", "containerapp", "job", "start",
         "--name", JOB, "--resource-group", RG],
        check=True, capture_output=True, text=True,
    ).stdout

Uploading several files before starting one execution processes them all in that execution. Two executions running at once read the same directory, and both can process the same file.

Following the execution

az containerapp job execution list --name $JOB --resource-group $RG -o table

The markdown is a file in out/ on the share:

az storage file download \
  --account-name $STORAGE \
  --account-key "$STORAGE_KEY" \
  --share-name ocr-work \
  --path out/document.md \
  --dest ./document.md

Logs of finished executions are in the environment's Log Analytics workspace, in the ContainerAppConsoleLogs_CL table:

WS_ID=$(az containerapp env show --name $ENV --resource-group $RG \
  --query "properties.appLogsConfiguration.logAnalyticsConfiguration.customerId" -o tsv)

az monitor log-analytics query -w $WS_ID \
  --analytics-query "ContainerAppConsoleLogs_CL | where ContainerGroupName_s startswith '<execution-name>' | project TimeGenerated, Log_s | order by TimeGenerated asc" \
  -o table

Those lines are what to read when an execution ends with a failure.

Conclusion

Job mode runs the OCR pipeline once and exits. Locally that is one docker run per document, with a volume or PostgreSQL added when the job records are needed after the container is removed.

On Container Apps the same mode is a manual job and an Azure Files share. An execution converts every file in in/, writes the markdown to out/, and stops, and nothing runs until the next start. That is the form for occasional batches of documents.

Bicep template

The template deploys the storage account, the share, the environment, the share registration and the job:

// main.bicep
param location string = resourceGroup().location
param storageAccountName string = 'stpaddleocr${uniqueString(resourceGroup().id)}'
param image string = 'docker.io/edgaras0x4e/paddleocr-pdf-api:latest-text-baked'

var jobCommand = 'for f in /work/in/*.pdf; do [ -e "$f" ] || continue; python3 -m app.api < "$f" > "/work/out/$(basename "$f" .pdf).md" && rm "$f"; done'

resource storage 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  sku: { name: 'Standard_LRS' }
  kind: 'StorageV2'
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-05-01' = {
  name: '${storage.name}/default/ocr-work'
  properties: { shareQuota: 100 }
}

resource env 'Microsoft.App/managedEnvironments@2024-03-01' = {
  name: 'env-paddleocr'
  location: location
  properties: {
    workloadProfiles: [
      { name: 'Consumption', workloadProfileType: 'Consumption' }
    ]
  }
}

resource envStorage 'Microsoft.App/managedEnvironments/storages@2024-03-01' = {
  parent: env
  name: 'ocrwork'
  properties: {
    azureFile: {
      accountName: storage.name
      accountKey: storage.listKeys().keys[0].value
      shareName: 'ocr-work'
      accessMode: 'ReadWrite'
    }
  }
  dependsOn: [ share ]
}

resource job 'Microsoft.App/jobs@2024-03-01' = {
  name: 'ocr-job'
  location: location
  properties: {
    environmentId: env.id
    workloadProfileName: 'Consumption'
    configuration: {
      triggerType: 'Manual'
      replicaTimeout: 1800
      replicaRetryLimit: 0
      manualTriggerConfig: {
        parallelism: 1
        replicaCompletionCount: 1
      }
    }
    template: {
      containers: [
        {
          name: 'main'
          image: image
          resources: {
            cpu: json('4.0')
            memory: '8.0Gi'
          }
          command: [ '/bin/sh' ]
          args: [ '-c', jobCommand ]
          env: [
            { name: 'RUN_MODE', value: 'job' }
            { name: 'DB_PATH', value: '/tmp/ocr.db' }
            { name: 'UPLOAD_DIR', value: '/tmp/uploads' }
          ]
          volumeMounts: [
            { volumeName: 'ocr-work', mountPath: '/work' }
          ]
        }
      ]
      volumes: [
        {
          name: 'ocr-work'
          storageName: envStorage.name
          storageType: 'AzureFile'
        }
      ]
    }
  }
}

output storageAccountName string = storage.name

Deploy the template, then create the in and out directories on the new account:

az group create --name $RG --location $LOC

STORAGE=$(az deployment group create \
  --resource-group $RG \
  --template-file main.bicep \
  --query properties.outputs.storageAccountName.value -o tsv)

STORAGE_KEY=$(az storage account keys list \
  --account-name $STORAGE \
  --resource-group $RG \
  --query "[0].value" -o tsv)

az storage directory create --share-name ocr-work --name in \
  --account-name $STORAGE --account-key "$STORAGE_KEY"

az storage directory create --share-name ocr-work --name out \
  --account-name $STORAGE --account-key "$STORAGE_KEY"