MastersThesis/src

OCR Hyperparameter Tuning with Ray Tune

This directory contains the Docker setup for running automated hyperparameter optimization on OCR services using Ray Tune with Optuna.

Prerequisites

• Docker with NVIDIA GPU support (nvidia-container-toolkit)
• NVIDIA GPU with CUDA support

Quick Start

cd src

# Start PaddleOCR service and run tuning (images pulled from registry)
docker compose -f docker-compose.tuning.paddle.yml up -d paddle-ocr-gpu
docker compose -f docker-compose.tuning.paddle.yml run raytune --service paddle --samples 64

Available Services

Service	Port	Compose File
PaddleOCR	8002	docker-compose.tuning.paddle.yml
DocTR	8003	docker-compose.tuning.doctr.yml
EasyOCR	8002	docker-compose.tuning.easyocr.yml

Note: PaddleOCR and EasyOCR both use port 8002. Run them separately.

Usage Examples

PaddleOCR Tuning

# Start service
docker compose -f docker-compose.tuning.paddle.yml up -d paddle-ocr-gpu

# Wait for health check (check with)
curl http://localhost:8002/health

# Run tuning (64 samples)
docker compose -f docker-compose.tuning.paddle.yml run raytune --service paddle --samples 64

# Stop service
docker compose -f docker-compose.tuning.paddle.yml down

DocTR Tuning

docker compose -f docker-compose.tuning.doctr.yml up -d doctr-gpu
curl http://localhost:8003/health
docker compose -f docker-compose.tuning.doctr.yml run raytune --service doctr --samples 64
docker compose -f docker-compose.tuning.doctr.yml down

EasyOCR Tuning

docker compose -f docker-compose.tuning.easyocr.yml up -d easyocr-gpu
curl http://localhost:8002/health
docker compose -f docker-compose.tuning.easyocr.yml run raytune --service easyocr --samples 64
docker compose -f docker-compose.tuning.easyocr.yml down

Run Multiple Services (PaddleOCR + DocTR)

# Start both services
docker compose -f docker-compose.tuning.yml up -d paddle-ocr-gpu doctr-gpu

# Run tuning for each
docker compose -f docker-compose.tuning.yml run raytune --service paddle --samples 64
docker compose -f docker-compose.tuning.yml run raytune --service doctr --samples 64

# Stop all
docker compose -f docker-compose.tuning.yml down

Command Line Options

docker compose -f <compose-file> run raytune --service <service> --samples <n>

Option	Description	Default
--service	OCR service: paddle, doctr, easyocr	Required
--samples	Number of hyperparameter trials	64

Output

Results are saved to src/results/ as CSV files:

• raytune_paddle_results_<timestamp>.csv
• raytune_doctr_results_<timestamp>.csv
• raytune_easyocr_results_<timestamp>.csv

Correlation Analysis

Correlation tables used in the thesis are derived from the CSV results with a local script:

source .venv/bin/activate
python tem/scripts/compute_correlations_all.py

Outputs are written to src/results/correlations/:

• paddle_correlations.csv
• doctr_correlations.csv
• easyocr_correlations.csv

These files are computed from the corresponding inputs:

• src/results/raytune_paddle_results_20260119_122609.csv
• src/results/raytune_doctr_results_20260119_121445.csv
• src/results/raytune_easyocr_results_20260119_120204.csv

Directory Structure

src/
├── docker-compose.tuning.yml          # All services (PaddleOCR + DocTR)
├── docker-compose.tuning.paddle.yml   # PaddleOCR only
├── docker-compose.tuning.doctr.yml    # DocTR only
├── docker-compose.tuning.easyocr.yml  # EasyOCR only
├── raytune/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── raytune_ocr.py
│   └── run_tuning.py
├── dataset/                           # Input images and ground truth
├── results/                           # Output CSV files
└── debugset/                          # Debug output

Docker Images

All images are pre-built and pulled from registry:

• seryus.ddns.net/unir/raytune:latest - Ray Tune tuning service
• seryus.ddns.net/unir/paddle-ocr-gpu:latest - PaddleOCR GPU
• seryus.ddns.net/unir/doctr-gpu:latest - DocTR GPU
• seryus.ddns.net/unir/easyocr-gpu:latest - EasyOCR GPU

Build locally (development)

# Build raytune image locally
docker build -t seryus.ddns.net/unir/raytune:latest ./raytune

Troubleshooting

Service not ready

Wait for the health check to pass before running tuning:

# Check service health
curl http://localhost:8002/health
# Expected: {"status": "ok", "model_loaded": true, ...}

GPU not detected

Ensure nvidia-container-toolkit is installed:

nvidia-smi  # Should show your GPU
docker run --rm --gpus all nvidia/cuda:12.4.1-base nvidia-smi

Port already in use

Stop any running OCR services:

docker compose -f docker-compose.tuning.paddle.yml down
docker compose -f docker-compose.tuning.easyocr.yml down