MLOps Docflow - Промышленная MLOps-платформа для классификации документов

Полноценная production-ready MLOps платформа для распознавания и классификации документов с использованием современных инструментов машинного обучения и оркестрации.

📋 Содержание

Возможности
Архитектура
Технологический стек
Установка и запуск
Использование API
Структура проекта
Мониторинг
Разработка

🚀 Возможности

Загрузка документов: Автоматическая загрузка и валидация документов (изображения, PDF)
OCR обработка: Извлечение текста с помощью Tesseract и EasyOCR
Классификация ML: Обучение и инференс моделей классификации документов
MLOps инфраструктура:
- Трекинг экспериментов через MLflow
- Оркестрация пайплайнов через Airflow
- Версионирование моделей
Мониторинг: Prometheus + Grafana для отслеживания метрик
REST API: FastAPI для интеграции с внешними системами
Хранилище: MinIO (S3-совместимое) для документов и артефактов

🏗️ Архитектура

Проект построен на микросервисной архитектуре:

┌─────────────────┐
│   FastAPI API   │  ← HTTP запросы
└────────┬────────┘
         │
    ┌────┴────┐
    │  Airflow │  ← Оркестрация
    └────┬────┘
         │
    ┌────┴──────────────────────────┐
    │                               │
┌───▼────┐  ┌──────┐  ┌─────────┐ ┌▼────────┐
│Ingestion│  │ OCR  │  │Training │ │Inference│
└───┬────┘  └──┬───┘  └────┬────┘ └────┬────┘
    │          │           │           │
    └──────────┴───────────┴───────────┘
               │
    ┌──────────┴───────────┐
    │                      │
┌───▼────┐  ┌─────────┐  ┌▼──────┐
│PostgreSQL│  │  MinIO  │  │MLflow │
└─────────┘  └─────────┘  └───────┘

Модули

Ingestion - Загрузка и валидация документов
OCR - Извлечение текста (Tesseract/EasyOCR)
Training - Обучение моделей классификации
Inference - Предсказание классов документов
Monitoring - Сбор метрик и мониторинг

🛠️ Технологический стек

Backend & ML

Python 3.11 - Основной язык
FastAPI - REST API
PyTorch - Deep Learning фреймворк
Scikit-learn - ML алгоритмы
Tesseract/EasyOCR - OCR движки

MLOps

Apache Airflow - Оркестрация пайплайнов
MLflow - Трекинг экспериментов и версионирование моделей
Prometheus - Сбор метрик
Grafana - Визуализация метрик

Инфраструктура

Docker & Docker Compose - Контейнеризация
PostgreSQL - Основная БД
MinIO - S3-совместимое хранилище
Nginx (опционально) - Reverse proxy

🚀 Установка и запуск

Предварительные требования

Docker 20.10+
Docker Compose 2.0+
8 GB RAM минимум
20 GB свободного места на диске

Быстрый старт

Клонирование репозитория

git clone https://github.com/shuldeshoff/doc-mlops-pipeline.git
cd doc-mlops-pipeline

Настройка переменных окружения

cp .env.example .env
# Отредактируйте .env файл при необходимости

Запуск сервисов

# Запуск всех сервисов
docker-compose up -d

# Проверка статуса
docker-compose ps

Ожидание инициализации

Первый запуск может занять 5-10 минут для инициализации всех сервисов.

# Проверка логов
docker-compose logs -f

Доступ к сервисам

После запуска доступны следующие интерфейсы:

Сервис	URL	Логин/Пароль
API Documentation	http://localhost:8000/docs	-
Airflow	http://localhost:8080	admin/admin
MLflow	http://localhost:5000	-
MinIO Console	http://localhost:9001	minioadmin/minioadmin123
Prometheus	http://localhost:9090	-
Grafana	http://localhost:3000	admin/admin

📖 Использование API

Swagger UI

Полная документация API доступна по адресу: http://localhost:8000/docs

Примеры запросов

1. Health Check

curl -X GET "http://localhost:8000/health"

2. Загрузка документа

curl -X POST "http://localhost:8000/upload" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@document.jpg"

Ответ:

{
  "success": true,
  "document_id": 1,
  "filename": "document.jpg",
  "storage_path": "raw/20241029_120000_abc12345.jpg",
  "file_size": 2048576,
  "timestamp": "2024-10-29T12:00:00"
}

3. Предсказание по тексту

curl -X POST "http://localhost:8000/predict/text" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Текст документа для классификации",
    "return_all_scores": true
  }'

Ответ:

{
  "success": true,
  "predicted_class": "invoice",
  "confidence_score": 0.95,
  "is_confident": true,
  "model_name": "document_classifier",
  "model_version": "latest",
  "all_scores": {
    "invoice": 0.95,
    "contract": 0.03,
    "receipt": 0.02
  }
}

4. Загрузка и предсказание (одним запросом)

curl -X POST "http://localhost:8000/upload-and-predict?ocr_language=eng" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@document.jpg"

5. Предсказание по ID документа

curl -X POST "http://localhost:8000/predict/document/1?ocr_language=eng&return_all_scores=true"

6. Получение истории предсказаний

curl -X GET "http://localhost:8000/prediction/history/1?limit=10"

Python клиент

import requests
from pathlib import Path

# URL API
API_URL = "http://localhost:8000"

# Загрузка и предсказание
def upload_and_predict(file_path: str):
    with open(file_path, 'rb') as f:
        files = {'file': f}
        response = requests.post(
            f"{API_URL}/upload-and-predict",
            files=files,
            params={'ocr_language': 'eng', 'return_all_scores': True}
        )
    
    return response.json()

# Использование
result = upload_and_predict("my_document.jpg")
print(f"Predicted class: {result['prediction']['predicted_class']}")
print(f"Confidence: {result['prediction']['confidence_score']}")

📁 Структура проекта

doc-mlops-pipeline/
├── airflow/                    # Airflow DAGs
│   └── dags/
│       └── document_processing_pipeline.py
├── config/                     # Конфигурационные файлы
│   ├── init-db.sql            # Инициализация БД
│   ├── prometheus.yml         # Конфиг Prometheus
│   └── grafana-datasources.yml
├── data/                       # Данные (git ignored)
│   ├── raw/                   # Сырые документы
│   ├── processed/             # Обработанные документы
│   └── models/                # Обученные модели
├── docker/                     # Dockerfile'ы
│   ├── airflow.Dockerfile
│   ├── inference.Dockerfile
│   └── mlflow.Dockerfile
├── logs/                       # Логи приложений
├── services/                   # Микросервисы
│   ├── ingestion/             # Модуль загрузки документов
│   │   ├── __init__.py
│   │   ├── ingestion_service.py
│   │   ├── storage.py
│   │   └── database.py
│   ├── ocr/                   # Модуль OCR
│   │   ├── __init__.py
│   │   ├── ocr_service.py
│   │   ├── ocr_engines.py
│   │   └── database.py
│   ├── training/              # Модуль обучения
│   │   ├── __init__.py
│   │   ├── training_service.py
│   │   ├── models.py
│   │   └── database.py
│   ├── inference/             # Модуль inference
│   │   ├── __init__.py
│   │   ├── main.py           # FastAPI приложение
│   │   ├── inference_service.py
│   │   ├── model_loader.py
│   │   └── database.py
│   └── monitoring/            # Модуль мониторинга
│       ├── __init__.py
│       ├── metrics_service.py
│       ├── performance_monitor.py
│       └── database.py
├── .env                        # Переменные окружения
├── .gitignore
├── docker-compose.yml          # Docker Compose конфигурация
├── requirements.txt            # Python зависимости
└── README.md                   # Этот файл

📊 Мониторинг

Prometheus метрики

Доступны следующие метрики:

documents_uploaded_total - Количество загруженных документов
documents_processed_total - Количество обработанных документов
ocr_processing_seconds - Время обработки OCR
ocr_confidence_score - Confidence score OCR
prediction_confidence_score - Confidence score предсказаний
predictions_total - Количество предсказаний по классам
model_accuracy - Текущая точность модели
api_request_duration_seconds - Длительность API запросов

Grafana Dashboard

Откройте Grafana: http://localhost:3000
Войдите (admin/admin)
Добавьте дашборд для визуализации метрик
Используйте Prometheus как источник данных

Логи

Просмотр логов сервисов:

# Все сервисы
docker-compose logs -f

# Конкретный сервис
docker-compose logs -f inference-api
docker-compose logs -f airflow-scheduler
docker-compose logs -f mlflow

🔧 Разработка

Локальная разработка

Установка зависимостей

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Запуск API локально

cd services/inference
python main.py

Запуск тестов (при наличии)

pytest tests/

Добавление нового модуля

Создайте директорию в services/
Добавьте __init__.py и основные файлы
Обновите requirements.txt при необходимости
Добавьте интеграцию в Airflow DAG

Обучение модели

Модель обучается автоматически через Airflow DAG, но можно запустить вручную:

from services.training.training_service import TrainingService

service = TrainingService()
texts, labels = service.load_training_data()
result = service.train_model(texts, labels, epochs=50)
print(f"Model accuracy: {result['accuracy']:.4f}")

🔒 Безопасность

🐛 Troubleshooting

Проблемы с запуском

Ошибка: "port already allocated"

# Остановите конфликтующие сервисы или измените порты в docker-compose.yml
docker-compose down

Ошибка: "no space left on device"

# Очистите неиспользуемые Docker ресурсы
docker system prune -a

Airflow задачи не запускаются

# Перезапустите scheduler
docker-compose restart airflow-scheduler

Проблемы с моделью

Модель не загружается

Проверьте наличие файлов модели в data/models/
Проверьте логи inference API

Низкая точность модели

Увеличьте размер обучающей выборки
Настройте гиперпараметры в training_service.py

📚 Дополнительные ресурсы

📝 Лицензия

MIT License

👥 Автор

Шульдешов Юрий Леонидович

Telegram: @shuldeshoff
GitHub: @shuldeshoff

🤝 Contributing

Pull requests are welcome!
Please open an issue first to discuss proposed changes.
Follow code style and use clear commit messages.

Подробнее о процессе участия читайте в CONTRIBUTING.md.

Создано с ❤️ для MLOps сообщества

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
airflow/dags		airflow/dags
config		config
data		data
docker		docker
logs		logs
services		services
.dockerignore		.dockerignore
.gitignore		.gitignore
AUTHOR.md		AUTHOR.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
OPENSOURCE_SETUP_COMPLETE.md		OPENSOURCE_SETUP_COMPLETE.md
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
WIKI_HOME.md		WIKI_HOME.md
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt

License

shuldeshoff/doc-mlops-pipeline

Folders and files

Latest commit

History

Repository files navigation