sensory-detector 0.2.1

Async ML service and client for sensory detection

Sensory Detector: Высокомасштабируемый Асинхронный CV/ML Микросервис

Обзор Проекта

Sensory Detector — это production-grade асинхронный микросервис, разработанный для высокопроизводительного и масштабируемого анализа изображений и видео. Сервис предоставляет унифицированные API для ключевых задач компьютерного зрения и машинного обучения, таких как:

• Обнаружение объектов (Object Detection) с использованием YOLOv8 (Ultralytics).
• Оптическое распознавание символов (OCR) с поддержкой EasyOCR и Tesseract.
• Генерация векторных эмбеддингов (Embeddings) с использованием OpenCLIP.

Проект ориентирован на обеспечение безопасности, производительности, масштабируемости и максимальной гибкости для интеграции в распределенные мультимодальные инфраструктуры.

Ключевые Возможности

• Асинхронность: Построен на FastAPI и asyncio для максимальной пропускной способности и неблокирующего I/O.
• Модульность и Расширяемость: Лёгкая интеграция новых ML-моделей и типов задач через унифицированные интерфейсы (Detector).
• Гибкость ввода данных: Поддержка прямой загрузки файлов (upload), обработки файлов по пути на серверной файловой системе (path-based), а также WebSocket для потокового анализа.
• Предобработка изображений: Встроенные опции предобработки (изменение размера, бинаризация, добавление границ) для оптимизации инференса.
• Управление моделями: Эффективное кеширование моделей (LRU с TTL), горячая подгрузка и выгрузка, мониторинг использования для оптимизации памяти (включая GPU).
• Безопасность: Строгий контроль доступа к файловой системе, валидация всех входящих данных.
• DevOps-готовность: Конфигурируемость через переменные окружения, поддержка Docker и Docker Compose, автоматическая OpenAPI/Swagger документация, структурированное логирование и метрики.

Архитектурный Обзор

Сервис спроектирован как модульное FastAPI-приложение. Входящие запросы обрабатываются асинхронно, а ресурсоёмкие операции инференса ML-моделей выносятся из основного event loop в отдельные потоки или процессы для повышения производительности и отзывчивости. ModelCache динамически управляет загруженными ML-моделями, оптимизируя использование памяти и ресурсов.

flowchart TD
  A[Клиент REST/WS] -->|HTTP upload или path| B[FastAPI Сервис]
  B --> C{Менеджер Кэша Моделей - ModelCache}
  C --> D[ML-Модели - YOLO, OCR, CLIP]
  B -- опционально --> E[Модуль Предобработки Изображений]
  B -->|Upload files| F[Временное Хранилище - InMemory/Disk]
  B -->|Analyze by path| G[FILES_PATH - Смонтированный Том]
  D --> H[Результаты - Pydantic Models]
  H --> B
  B -->|WebSocket Stream| I[WebSocket Обработчик]
  I --> D
  C -->|LRU Eviction/TTL| J[Выгрузка Модели - Освобождение VRAM/RAM]

Ключевые Компоненты:

• FastAPI Сервис: Основной HTTP/WebSocket интерфейс.
• Менеджер Кэша Моделей (ModelCache): Отвечает за загрузку, хранение и выгрузку ML-моделей. Использует LRU-алгоритм для эффективного управления памятью и позволяет "горячую" перезагрузку/выгрузку моделей.
• ML-Модели (Детекторы): Каждая ML-модель (YOLOv8, EasyOCR, Tesseract, CLIP) обёрнута в унифицированный интерфейс (Detector), что облегчает их интеграцию и расширение.
• Ввод Данных: Сервис поддерживает загрузку файлов напрямую или их обработку по пути на файловой системе сервера (если настроен FILES_PATH).
• Модуль Предобработки Изображений: Позволяет применять операции, такие как изменение размера, бинаризация и добавление рамок, перед подачей изображения в ML-модель.
• WebSocket Обработчик: Обеспечивает возможность потоковой обработки данных (например, кадров видео) через двустороннее соединение.

Быстрый Старт (Клиент)

Для взаимодействия с сервисом Sensory Detector используйте предоставленный асинхронный Python-клиент.

Установка Клиента

Установите необходимые зависимости, указанные в requirements.txt:

pip install -r requirements.txt

Пример Использования Клиента (Асинхронный)

Предполагается, что сервис запущен и доступен по адресу http://localhost:8000.

import asyncio
from src.sensory_detector.yolo_client.client import SensoryAPIClient
from src.sensory_detector.models.models import DetectionSeries, OCRSeries

async def main():
    client = SensoryAPIClient(base_url="http://localhost:8000")

    print("--- Пример: Обнаружение объектов (YOLOv8) ---")
    try:
        # Обнаружение объектов в изображении, загруженном с локального пути
        detection_result: DetectionSeries = await client.detect_objects(
            images="tests/data/test.jpg",
            model_name="yolov8s"
        )
        print(f"Обнаружено объектов: {detection_result.total_items}")
        for frame in detection_result.results:
            for obj in frame.detections[:3]: # Показать первые 3 объекта
                print(f"  - {obj.label} (уверенность: {obj.confidence:.2f}) в {obj.box.x1},{obj.box.y1},{obj.box.x2},{obj.box.y2}")
    except Exception as e:
        print(f"Ошибка при обнаружении объектов: {e}")

    print("\n--- Пример: Распознавание текста (EasyOCR) ---")
    try:
        # Распознавание текста в изображении
        ocr_result: OCRSeries = await client.recognize_texts(
            images="tests/data/test.png",
            model_name="easyocr"
        )
        print(f"Распознанный текст: '{ocr_result.results[0].full_text}'")
    except Exception as e:
        print(f"Ошибка при распознавании текста: {e}")

    print("\n--- Пример: Получение списка доступных моделей ---")
    try:
        models_info = await client.get_available_models()
        print(f"Доступные модели для детекции: {models_info.available_models.get('detection', 'N/A')}")
        print(f"Доступные модели для OCR: {models_info.available_models.get('ocr', 'N/A')}")
    except Exception as e:
        print(f"Ошибка при получении списка моделей: {e}")

if __name__ == "__main__":
    asyncio.run(main())

Подробная Документация

• Документация Клиента: Для получения детальной информации о параметрах, типах входных и выходных данных, а также о расширенных возможностях (таких как предобработка изображений, режимы работы с файлами и WebSocket), пожалуйста, обратитесь к файлу: src/sensory_detector/yolo_client/README_CLI.MD

• Документация Сервера: Для получения информации о конфигурации сервера, его развёртывании (включая Docker и переменные окружения), а также о принципах расширения и внутренних компонентах, обратитесь к файлу: src/sensory_detector/yolo_server/README_SRV.MD

---