sensory-detector 0.2.4
Async ML service and client for sensory detection
License: MIT License
Requires Python: >=3.10
Keywords: computer-vision, machine-learning, yolo, ocr, embeddings, fastapi, async

# 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-моделями, оптимизируя использование памяти и ресурсов.

```mermaid
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`:
```bash
pip install -r requirements.txt
```
### Пример Использования Клиента (Асинхронный)

Предполагается, что сервис запущен и доступен по адресу `http://localhost:8000`.
```py
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`**](src/sensory_detector/yolo_client/README_CLI.MD)

*   **Документация Сервера**: Для получения информации о конфигурации сервера, его развёртывании (включая Docker и переменные окружения), а также о принципах расширения и внутренних компонентах, обратитесь к файлу:
    [**`src/sensory_detector/yolo_server/README_SRV.MD`**](src/sensory_detector/yolo_server/README_SRV.MD)

---