MastersThesis/src/README.md

# 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

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

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

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

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

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

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

## 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)

```bash
# 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:
```bash
# Check service health
curl http://localhost:8002/health
# Expected: {"status": "ok", "model_loaded": true, ...}
```

### GPU not detected
Ensure `nvidia-container-toolkit` is installed:
```bash
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:
```bash
docker compose -f docker-compose.tuning.paddle.yml down
docker compose -f docker-compose.tuning.easyocr.yml down
```