Python OCR Microservice

Microservice OCR sử dụng PaddleOCR được tối ưu hóa để nhận dạng tiếng Việt.

🚀 Features

• OCR PDF tiếng Việt với độ chính xác cao
• Sử dụng PaddleOCR (State-of-the-art OCR)
• Hỗ trợ training/fine-tuning mô hình cho tiếng Việt
• API RESTful (FastAPI) với Swagger UI
• Hỗ trợ cả CPU và GPU

📁 Project Structure

examio-python-ocr/
├── app/
│   ├── main.py              # FastAPI entry point
│   ├── ocr_service.py       # OCR logic
│   ├── pdf_processor.py     # PDF to images
│   ├── preprocessor.py      # Image preprocessing
│   ├── models/
│   │   ├── default/         # Base models
│   │   └── custom_vi/       # Trained models
│   └── utils/
│       └── logger.py
├── training/
│   ├── prepare_dataset.py
│   ├── train_rec.sh
│   ├── train_det.sh
│   ├── config_rec_vi.yml
│   └── config_det_vi.yml
├── requirements.txt
├── Dockerfile
└── README.md

🛠️ Installation

Prerequisites

• Python 3.9+
• poppler-utils (for PDF processing)

Quick Start

# 1. Di chuyển vào thư mục dự án
cd examio-python-ocr

# 2. Tạo virtual environment
python3 -m venv venv

# 3. Kích hoạt virtual environment
source venv/bin/activate

# 4. Cài đặt dependencies
pip install fastapi uvicorn python-multipart pillow numpy opencv-python-headless pdf2image pymupdf paddlepaddle paddleocr

# 5. Chạy server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Install từ requirements.txt

cd examio-python-ocr
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install paddlepaddle paddleocr
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

🚀 Running the Service

Development (với auto-reload)

cd examio-python-ocr
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Production

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Docker

# Build CPU image
docker build --target runtime -t python-ocr:cpu .

# Build GPU image
docker build --target gpu -t python-ocr:gpu .

# Run
docker run -p 8000:8000 python-ocr:cpu

📚 API Documentation

Sau khi chạy server, truy cập:

URL	Mô tả
http://localhost:8000/docs	Swagger UI - Interactive API docs
http://localhost:8000/redoc	ReDoc - Alternative API docs
http://localhost:8000/health	Health check endpoint

📡 API Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "service": "python-ocr"
}

OCR PDF

POST /ocr/pdf
Content-Type: multipart/form-data

Parameters:

Name	Type	Required	Description
file	file	Yes	PDF file to process
lang	string	No	Language (default: "vi")

Response:

{
  "text": "Nội dung văn bản...",
  "pages": [
    {
      "page": 1,
      "lines": [
        {
          "text": "Dòng văn bản",
          "box": [x1, y1, x2, y2],
          "confidence": 0.9876
        }
      ]
    }
  ],
  "total_pages": 1
}

OCR Image

POST /ocr/image
Content-Type: multipart/form-data

Parameters:

Name	Type	Required	Description
file	file	Yes	Image file (jpg, png, etc.)
lang	string	No	Language (default: "vi")

🎯 Training Custom Model

1. Prepare Dataset

train_data/
├── images/
│   ├── 0001.jpg
│   └── 0002.jpg
└── labels/
    ├── 0001.txt
    └── 0002.txt

Label format (mỗi file .txt):

Nội dung text trong ảnh

2. Process Dataset

python training/prepare_dataset.py \
  --images train_data/images \
  --labels train_data/labels \
  --output train_data

3. Train Recognition Model

chmod +x training/train_rec.sh
./training/train_rec.sh

4. Train Detection Model (Optional)

chmod +x training/train_det.sh
./training/train_det.sh

Trained models will be saved to app/models/custom_vi/.

📊 Performance

• PDF 10-50 trang: 4-6 giây (tùy GPU/CPU)
• Model được load một lần khi khởi động
• Tự động giải phóng bộ nhớ sau khi xử lý

🔧 Configuration

Environment variables:

Variable	Description	Default
PADDLE_OCR_HOME	PaddleOCR cache directory	~/.paddleocr
CUDA_VISIBLE_DEVICES	GPU device IDs	0

📝 Example Usage

Python

import requests

# OCR PDF
with open("document.pdf", "rb") as f:
    response = requests.post(
        "http://localhost:8000/ocr/pdf",
        files={"file": f},
        data={"lang": "vi"}
    )
    result = response.json()
    print(result["text"])

cURL

curl -X POST "http://localhost:8000/ocr/pdf" \
  -F "file=@document.pdf" \
  -F "lang=vi"

NestJS Integration

import axios from 'axios';
import * as FormData from 'form-data';
import * as fs from 'fs';

async function ocrPdf(filePath: string): Promise<string> {
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));
  form.append('lang', 'vi');

  const response = await axios.post(
    'http://localhost:8000/ocr/pdf',
    form,
    { headers: form.getHeaders() }
  );

  return response.data.text;
}

📄 License

MIT License