# AI Moderation Service

Сервис автоматической модерации пользовательского контента на базе **FastAPI** и моделей машинного обучения. Позволяет проверять тексты и изображения на наличие недопустимого контента:

- **Тексты** — токсичность (нейросетевая модель BERT) и нецензурная лексика (словарь + морфологический анализ `pymorphy3`).
- **Изображения** — NSFW-контент (нейросетевая модель `Falconsai/nsfw_image_detection`), оружие (zero-shot детектор **OWLv2**) и запрещённые категории (марихуана, наркотики, порнография, насилие) через мультимодальную модель CLIP.

Сервис предоставляет REST API и возвращает вердикт (`approved`), оценку уверенности (`score`), причину отказа (`reason`) и дополнительную диагностическую информацию.

---

## Оглавление

- [Возможности](#возможности)
- [Технологический стек](#технологический-стек)
- [Структура проекта](#структура-проекта)
- [Установка и запуск](#установка-и-запуск)
- [Конфигурация](#конфигурация)
- [API](#api)
  - [POST /api/v1/moderation/text](#post-apiv1moderationtext)
  - [POST /api/v1/moderation/image](#post-apiv1moderationimage)
- [Модели данных](#модели-данных)
- [Архитектура и слои](#архитектура-и-слои)
- [Логика модерации текста](#логика-модерации-текста)
- [Логика модерации изображений](#логика-модерации-изображений)
- [Обработка ошибок](#обработка-ошибок)
- [Диагностика и логирование](#диагностика-и-логирование)
- [Известные особенности](#известные-особенности)

---

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

- **Модерация текста**:
  - Проверка на нецензурную лексику по словарю из ~7 350 слов (включая транслит и цифро-замены вроде «6ля»);
  - Лемматизация русских слов через `pymorphy3` для поиска всех словоформ;
  - Нейросетевая оценка токсичности мультиязычной моделью `textdetox/bert-multilingual-toxicity-classifier`;
  - Настраиваемый порог токсичности (по умолчанию `0.90`).
- **Модерация изображений**:
  - Проверка формата (JPEG/PNG/WebP) и размера файла (до 5 МБ);
  - Валидация геометрии изображения (50×50 … 10000×10000 пикселей);
  - Комбинированная проверка: модель NSFW-классификации + CLIP-классификация по запрещённым категориям (наркотики, насилие);
  - Отдельный детектор оружия на базе **OWLv2** (zero-shot object detection) — замена ненадёжной CLIP-проверке категории `weapons`;
  - Комбинированный вердикт на основе нескольких моделей.
- **Готовый REST API** с автоматической документацией **Swagger UI** (`/docs`) и **ReDoc** (`/redoc`).
- **Автоматическая загрузка ML-моделей** при старте приложения (кэшируются локально).
- **Автовыбор устройства** выполнения инференса: CUDA, если доступен, иначе CPU.

---

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

| Компонент | Технология |
|---|---|
| Веб-фреймворк | FastAPI 0.139 |
| ASGI-сервер | Uvicorn 0.51 |
| Валидация данных | Pydantic 2.13, Pydantic-Settings |
| Работа с переменными окружения | python-dotenv |
| Нейросетевые модели | Transformers (Hugging Face), PyTorch |
| Мультимодальная модель | OpenAI CLIP (ViT-B/32) |
| Детектор оружия | OWLv2 (`google/owlv2-base-patch16-ensemble`) |
| Морфология русского языка | pymorphy3 |
| Обработка изображений | Pillow (PIL) |
| Язык | Python 3.12 |

> **Примечание.** В файле `ai-moderation/requirements.txt` перечислены только базовые зависимости веб-фреймворка. Зависимости машинного обучения (`transformers`, `torch`, `Pillow`, `pymorphy3` и др.) в этом файле **отсутствуют** и должны быть установлены дополнительно — см. раздел [Установка и запуск](#установка-и-запуск).

---

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

```
moderation-post/
├── .env                              # Конфигурация приложения (переменные окружения)
├── moderation-post.iml               # Файл модуля PyCharm (IDEA)
├── .idea/                            # Настройки IDE
├── readme.md                         # Данный документ
└── ai-moderation/                    # Корень Python-приложения
    ├── requirements.txt              # Базовые зависимости (без ML-пакетов)
    ├── models/                       # Локальный кэш моделей Hugging Face
    ├── app/
    │   ├── main.py                   # Точка входа: создание FastAPI-приложения
    │   ├── container.py              # Ручной DI-контейнер (словарь + детектор)
    │   ├── lifespan.py               # Жизненный цикл: загрузка моделей при старте
    │   ├── config/
    │   │   ├── settings.py           # Настройки (pydantic-settings), чтение .env
    │   │   ├── logging.py            # Настройка логирования
    │   │   └── image_policy.py       # Список запрещённых категорий для изображений
    │   ├── core/
    │   │   └── dependencies.py       # DI-фабрики (lru_cache) для сервисов/классификаторов
    │   ├── exceptions/
    │   │   ├── moderation_exception.py      # Базовое исключение модерации
    │   │   ├── invalid_text_exception.py    # Ошибка «некорректный текст»
    │   │   ├── invalid_image_exception.py   # Ошибка «некорректное изображение»
    │   │   └── handlers.py                  # Обработчики ошибок → JSON
    │   ├── ml/
    │   │   ├── base_classifier.py           # Абстрактный базовый классификатор
    │   │   ├── model_manager.py             # Синглтон загрузки и хранения моделей
    │   │   ├── prediction_result.py         # Результат классификации текста
    │   │   ├── text_classifier.py           # Классификатор токсичности текста
    │   │   └── image/
    │   │       ├── image_classifier.py           # Классификатор NSFW изображений
    │   │       ├── image_prediction_result.py    # Результат классификации изображений
    │   │       ├── clip_classifier.py            # CLIP-классификатор по категориям
    │   │       ├── clip_prediction_result.py     # Результат CLIP-классификации
    │   │       ├── weapon_detector.py            # Детектор оружия (OWLv2)
    │   │       └── weapon_prediction_result.py   # Результат детекции оружия
    │   ├── models/
    │   │   ├── dto/
    │   │   │   └── text_request.py      # DTO запроса модерации текста
    │   │   └── response/
    │   │       ├── moderation_response.py        # Ответ для текста
    │   │       ├── image_moderation_response.py  # Ответ для изображения
    │   │       └── error_response.py             # Универсальный ответ об ошибке
    │   ├── moderation/
    │   │   ├── image/
    │   │   │   └── validator.py        # Проверка размеров изображения
    │   │   └── profanity/
    │   │       ├── dictionary.py       # Загрузка словаря нецензурной лексики
    │   │       ├── lemmatizer.py       # Лемматизация через pymorphy3
    │   │       └── detector.py         # Детектор нецензурной лексики в тексте
    │   ├── resources/
    │   │   └── profanity_words.txt     # Словарь нецензурных слов (~7 350 записей)
    │   ├── routers/
    │   │   ├── text_moderation_router.py   # Эндпоинт POST /api/v1/moderation/text
    │   │   └── image_moderation_router.py  # Эндпоинт POST /api/v1/moderation/image
    │   └── services/
    │       ├── text_moderation_service.py  # Бизнес-логика модерации текста
    │       └── image_moderation_service.py # Бизнес-логика модерации изображений
    └── venv/                          # Виртуальное окружение Python
```

---

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

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

```bash
git clone <url-репозитория>
cd moderation-post
```

### 2. Создание виртуального окружения

```bash
cd ai-moderation
python -m venv venv

# Активация (Windows)
venv\Scripts\activate
# или (Linux/macOS)
source venv/bin/activate
```

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

Файл `requirements.txt` содержит только веб-зависимости. Поскольку в `requirements.txt` не входят ML-пакеты, установите зависимости полностью:

```bash
pip install -r requirements.txt
```

Дополнительно (необходимо для работы ML-части, но не перечислено в `requirements.txt`):

```bash
pip install torch
pip install transformers
pip install Pillow
pip install pymorphy3
```

> **Важно.** Для работы на GPU установите `torch` с соответствующим индексом CUDA (см. официальную документацию PyTorch), либо оставьте CPU-версию — сервис автоматически выберет доступное устройство.

### 4. Настройка окружения

Создайте файл `.env` в корне проекта (рядом с каталогом `ai-moderation`) или в самом каталоге приложения. Минимальный рабочий конфиг:

```dotenv
APP_NAME=AI Moderation Service
APP_VERSION=1.0.0
HOST=0.0.0.0
PORT=8000
DEBUG=true

# ===== AI =====
TEXT_MODEL=textdetox/bert-multilingual-toxicity-classifier
IMAGE_MODEL=Falconsai/nsfw_image_detection
IMAGE_CLIP_MODEL=openai/clip-vit-base-patch32
WEAPON_MODEL=google/owlv2-base-patch16-ensemble
MODEL_CACHE_DIR=./models
DEVICE=auto
HF_TOKEN=<ваш HF-токен>
```

> **Внимание:** в файле `.env` и в `settings.py` по умолчанию уже вписаны значения `HF_TOKEN`, в том числе **реальный токен**. Рекомендуется не публиковать его и заменить на собственный. Публиковать секреты в репозиторий недопустимо.

### 5. Запуск сервера

Из каталога `ai-moderation`:

```bash
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

или через FastAPI CLI:

```bash
fastapi run app/main.py --host 0.0.0.0 --port 8000
```

При старте сервис скачает указанные модели в каталог `MODEL_CACHE_DIR` (если их ещё нет) и загрузит их в память. На машине без GPU первая загрузка может занять несколько минут.

### 6. Проверка работоспособности

- Интерактивная документация API: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

---

## Конфигурация

Настройки определяются классом `Settings` в `app/config/settings.py` (pydantic-settings) и читаются из файла `.env`. Все параметры имеют значения по умолчанию.

| Переменная | Тип | По умолчанию | Описание |
|---|---|---|---|
| `APP_NAME` | str | `AI Moderation` | Название сервиса (отображается в Swagger) |
| `APP_VERSION` | str | `1.0.0` | Версия сервиса |
| `HOST` | str | `0.0.0.0` | Хост для запуска Uvicorn |
| `PORT` | int | `8000` | Порт для запуска Uvicorn |
| `DEBUG` | bool | `True` | Режим отладки |
| `TEXT_TOXIC_THRESHOLD` | float | `0.90` | Порог токсичности текста: если вероятность «токсично» ≥ порога — текст отклоняется |
| `TEXT_MODEL` | str | `textdetox/bert-multilingual-toxicity-classifier` | Модель классификации токсичности текста |
| `IMAGE_MODEL` | str | `Falconsai/nsfw_image_detection` | Модель NSFW-классификации изображений |
| `NSFW_THRESHOLD` | float | `0.85` | Порог уверенности NSFW-модели |
| `IMAGE_CLIP_MODEL` | str | `openai/clip-vit-base-patch32` | Мультимодальная модель CLIP |
| `CLIP_THRESHOLD` | float | `0.75` | Порог уверенности CLIP-классификатора |
| `WEAPON_MODEL` | str | `google/owlv2-base-patch16-ensemble` | Модель zero-shot детекции оружия (OWLv2) |
| `WEAPON_THRESHOLD` | float | `0.40` | Порог уверенности детектора оружия |
| `WEAPON_MIN_AREA_FRACTION` | float | `0.005` | Минимальная доля площади изображения для бокса (0.5%), отсекает мелкие ложные срабатывания |
| `HF_TOKEN` | str | — | Токен Hugging Face (подписанный/приватные модели) |
| `MODEL_CACHE_DIR` | str | `./models` | Каталог локального кэша моделей |
| `DEVICE` | str | `auto` | Устройство инференса: `auto`, `cpu`, `cuda` и т.д. |

---

## API

Все эндпоинты находятся под префиксом `/api/v1/moderation`. Сервис не содержит авторизации — эндпоинты открыты.

### POST /api/v1/moderation/text

Модерация текста. Запрос принимает JSON.

**Тело запроса** (модель `TextRequest`):

```json
{
  "text": "Пример проверяемого текста"
}
```

| Поле | Тип | Ограничения |
|---|---|---|
| `text` | string | обязательное, длина от 1 до 5000 символов |

**Успешный ответ — `200 OK`** (модель `ModerationResponse`):

```json
{
  "approved": true,
  "score": 0.015,
  "reason": "OK"
}
```

| Поле | Тип | Описание |
|---|---|---|
| `approved` | boolean | `true` — контент разрешён, `false` — отклонён |
| `score` | float | Уровень токсичности (0.0 … 1.0) |
| `reason` | string | Причина решения: `OK`, `TOXIC`, `PROFANITY` |

**Коды ошибок:**

- `400` — пустой текст / невалидная длина (`INVALID_TEXT`).

---

### POST /api/v1/moderation/image

Модерация изображения. Запрос — `multipart/form-data` с полем `file` (тип `UploadFile`).

**Ограничения загрузки:**

- Допустимые MIME-типы: `image/jpeg`, `image/png`, `image/webp`;
- Максимальный размер файла: 5 МБ;
- Допустимые размеры изображения: ширина и высота от 50 до 10000 пикселей.

**Успешный ответ — `200 OK`** (модель `ImageModerationResponse`):

```json
{
  "approved": true,
  "score": 1.0,
  "reason": "OK",
  "label": "normal",
  "detected_labels": []
}
```

Пример ответа при отклонении:

```json
{
  "approved": false,
  "score": 0.93,
  "reason": "NSFW",
  "label": "nsfw",
  "detected_labels": ["nsfw"]
}
```

| Поле | Тип | Описание |
|---|---|---|
| `approved` | boolean | Разрешено ли изображение |
| `score` | float | Уверенность модели, на которой принято решение |
| `reason` | string | Причина: `OK`, `NSFW`, `FORBIDDEN_CONTENT` |
| `label` | string | Наиболее вероятная метка (например, `normal`, `nsfw` или метка CLIP) |
| `detected_labels` | array of strings | Список обнаруженных запрещённых категорий |

**Коды ошибок:**

- `400` — недопустимый формат (`Unsupported image format`), битый файл (`Invalid image`), слишком маленькое/большое изображение (`INVALID_IMAGE`);
- `413` — файл больше 5 МБ (`Image too large`).

---

## Модели данных

### Запросы (DTO)

**`TextRequest`** (`app/models/dto/text_request.py`)

```python
class TextRequest(BaseModel):
    text: str = Field(min_length=1, max_length=5000)
```

### Ответы

**`ModerationResponse`** (`app/models/response/moderation_response.py`) — ответ для текста:

```python
class ModerationResponse(BaseModel):
    approved: bool
    score: float
    reason: str
```

**`ImageModerationResponse`** (`app/models/response/image_moderation_response.py`) — ответ для изображения:

```python
class ImageModerationResponse(BaseModel):
    approved: bool
    score: float
    reason: str
    label: str
    detected_labels: List[str]
```

**`ErrorResponse`** (`app/models/response/error_response.py`) — универсальный ответ об ошибке:

```python
class ErrorResponse(BaseModel):
    code: str
    message: str
```

### Внутренние структуры (ML)

**`PredictionResult`** (`app/ml/prediction_result.py`) — результат классификации текста:

```python
@dataclass(slots=True)
class PredictionResult:
    label: str
    score: float
    approved: bool
    raw_scores: list[float]
    reason: str = ""
    detected_words: list[str] = field(default_factory=list)
```

**`ImagePredictionResult`** (`app/ml/image/image_prediction_result.py`) — результат классификации изображения:

```python
@dataclass(slots=True)
class ImagePredictionResult:
    label: str
    score: float
    approved: bool
    raw_scores: list[float] = field(default_factory=list)
    reason: str = ""
    detected_labels: list[str] = field(default_factory=list)
```

**`ClipPredictionResult`** (`app/ml/image/clip_prediction_result.py`) — результат CLIP-классификации:

```python
@dataclass(slots=True)
class ClipPredictionResult:
    label: str            # метка с максимальной вероятностью
    score: float          # вероятность метки
    detected_labels: list[str]  # метки выше порога CLIP_THRESHOLD
    scores: dict[str, float]    # все метки → вероятности
```

---

## Архитектура и слои

Проект построен по классической слоистой схеме:

```
Роутеры (routers)
    ↓
Сервисы (services) — бизнес-логика модерации
    ↓
Классификаторы (ml) + Правила (moderation)
    ↓
Модели Hugging Face / словарь нецензурной лексики
```

Зависимости компонентов внедряются через фабрики с декоратором `@lru_cache` (`app/core/dependencies.py`), поэтому в рамках одного процесса создаётся по одному экземпляру каждого классификатора и сервиса. Загрузка моделей выполняется один раз в `lifespan` при старте приложения.

### Точка входа — `app/main.py`

- Создаёт экземпляр `FastAPI` с названием и версией из настроек;
- Подключает роутеры модерации текста и изображений;
- Регистрирует глобальные обработчики исключений `InvalidTextException` и `InvalidImageException`;
- Жизненный цикл приложения задан в `lifespan`.

### Жизненный цикл — `app/lifespan.py`

При старте:
1. Если задан `HF_TOKEN`, он экспортируется в переменную окружения `HF_TOKEN`;
2. Вызывается `model_manager.initialize()` — загрузка устройства, токенизатора, текстовой и графической моделей.

При остановке сервис просто логирует завершение работы (освобождение GPU-памяти реализовано на уровне процесса/ОС).

### Конфигурация — `app/config/`

- **`settings.py`** — класс `Settings` (pydantic-settings) + экземпляр `settings`. Загружает `.env`, игнорирует лишние ключи (`extra="ignore"`).
- **`logging.py`** — конфигурация логирования в stdout (`logging.INFO`), логгер `ai-moderation`.
- **`image_policy.py`** — множество `FORBIDDEN_IMAGE_LABELS` с запрещёнными категориями CLIP:
  - `a photo containing marijuana`
  - `a photo containing drugs`
  - `a photo containing violence`

  Порнография и оружие в этот список не входят: первая обрабатывается NSFW-моделью (шаг 1), второе — отдельным детектором на базе OWLv2 (шаг 2).

### DI-фабрики — `app/core/dependencies.py`

Использует `@lru_cache`, что превращает фабрики в синглтоны:

| Фабрика | Возвращает |
|---|---|
| `get_text_classifier` | `TextClassifier` |
| `get_clip_classifier` | `ClipClassifier` |
| `get_image_classifier` | `ImageClassifier` |
| `get_weapon_detector` | `WeaponDetector` (OWLv2) |
| `get_profanity_detector` | `ProfanityDetector` (словарь + лемматизатор) |
| `get_text_moderation_service` | `TextModerationService` |
| `get_image_moderation_service` | `ImageModerationService` (классификатор + валидатор + CLIP + детектор оружия) |
| `get_image_validator` | `ImageValidator` |

> Файл `app/container.py` содержит аналогичный, но неиспользуемый «ручной» контейнер, создающий детектор нецензурной лексики. Основной путь внедрения зависимостей — через `core/dependencies.py`.

### Слой ML — `app/ml/`

- **`base_classifier.py`** — абстрактный класс `BaseClassifier` с методом `predict(value)`;
- **`model_manager.py`** — синглтон `model_manager`, который:
  - выбирает устройство (`auto` → CUDA при доступности, иначе CPU);
  - загружает токенизатор и текстовую модель (`AutoTokenizer`, `AutoModelForSequenceClassification`);
  - загружает процессор и модель изображений (`AutoImageProcessor`, `AutoModelForImageClassification`);
  - переводит модели в режим `eval()`;
- **`text_classifier.py`** — `TextClassifier.predict(text)`:
  - токенизирует текст (макс. 512 токенов, `truncation`, `padding`);
  - прогоняет через модель без градиентов (`torch.no_grad`);
  - применяет `softmax` к логитам;
  - возвращает `PredictionResult` со `score = вероятность класса 1` (токсичный);
- **`image/image_classifier.py`** — `ImageClassifier.predict(image)`:
  - обрабатывает изображение процессором модели;
  - возвращает `ImagePredictionResult` с меткой из `id2label` (обычно `nsfw`/`normal`);
- **`image/clip_classifier.py`** — `ClipClassifier`:
  - загружает CLIP-модель и процессор сразу в конструкторе (при первом обращении);
  - задаёт список из 4 текстовых меток (`a normal photo` + 3 запрещённые: наркотики, насилие). Порнография отдельно обрабатывается NSFW-моделью на шаге 1;
  - считает вероятности соответствия изображения каждой метке;
  - собирает метки, превышающие `CLIP_THRESHOLD`, и возвращает `ClipPredictionResult`;
- **`image/weapon_detector.py`** — `WeaponDetector`:
  - загружает OWLv2-модель и процессор (zero-shot object detection) при первом обращении;
  - ищет по 15 текстовым запросам: `gun`, `pistol`, `rifle`, `shotgun`, `knife`, `machete`, `sword`, `bomb`, `grenade` и др.;
  - через `post_process_object_detection` получает боксы и уверенность по каждой запрошенной категории;
  - отсеивает боксы меньше `WEAPON_MIN_AREA_FRACTION` от площади изображения и с уверенностью ниже `WEAPON_THRESHOLD`;
  - возвращает `WeaponPredictionResult` с найденными категориями.

### Слой правил — `app/moderation/`

**Нецензурная лексика (`profanity/`):**

- **`dictionary.py`** — `ProfanityDictionary` загружает словарь из текстового файла в множество (`set`), убирает BOM и пустые строки, приводит к нижнему регистру. Метод `contains(word)` проверяет точное вхождение.
- **`lemmatizer.py`** — `Lemmatizer` на базе `pymorphy3.MorphAnalyzer`, метод `normalize(word)` возвращает нормальную форму (лемму) слова.
- **`detector.py`** — `ProfanityDetector.detect(text)`:
  1. регулярным выражением `[а-яА-ЯёЁ]+` извлекает русскоязычные слова (после приведения к нижнему регистру);
  2. каждое слово лемматизирует;
  3. проверяет, начинается ли лемма с какого-либо слова из словаря (префиксное сравнение через `startswith`);
  4. возвращает список найденных слов в исходном виде.

**Валидация изображений (`image/validator.py`):**

`ImageValidator.validate(image)` проверяет размеры изображения и выбрасывает `InvalidImageException` с описанием проблемы, если:
- ширина/высота меньше `MIN_WIDTH/MIN_HEIGHT` (50);
- ширина/высота больше `MAX_WIDTH/MAX_HEIGHT` (10000).

---

## Логика модерации текста

`TextModerationService.moderate(text)` (`app/services/text_moderation_service.py`):

1. **Проверка входа.** Если текст `None` или состоит из пробелов — выбрасывается `InvalidTextException("Text is empty")` → HTTP 400.
2. **Детектор нецензурной лексики.** `profanity_detector.detect(text)`:
   - если найдены запрещённые слова, сразу возвращается `PredictionResult(label="PROFANITY", score=1.0, approved=False, reason="PROFANITY", detected_words=[...])` — нейросеть не вызывается (экономия ресурсов);
3. **Нейросетевая оценка.** Иначе вызывается `TextClassifier.predict(text)`:
   - `approved = score < TEXT_TOXIC_THRESHOLD`;
   - `reason = "OK"` при одобрении, иначе `"TOXIC"`.

Итоговое решение передаётся в роутер и маппится в `ModerationResponse`.

---

## Логика модерации изображений

`ImageModerationService.moderate(image)` (`app/services/image_moderation_service.py`):

1. **Валидация.** `ImageValidator.validate(image)` — проверка размеров (см. выше).
2. **Шаг 1 — NSFW-модель.** `ImageClassifier.predict(image)`:
   - если метка `nsfw` и уверенность ≥ `NSFW_THRESHOLD` (0.85) → решение **отклонить**: `reason="NSFW"`, `detected_labels=["nsfw"]`;
3. **Шаг 2 — детектор оружия.** `WeaponDetector.predict(image)`:
   - zero-shot детекция по запросам оружия (OWLv2, боксы + уверенность);
   - если найдена категория с уверенностью ≥ `WEAPON_THRESHOLD` и боксом больше `WEAPON_MIN_AREA_FRACTION` → решение **отклонить**: `reason="FORBIDDEN_CONTENT"`, `detected_labels=[...]`;
4. **Шаг 3 — CLIP-модель.** `ClipClassifier.predict(image)`:
   - из меток, превысивших `CLIP_THRESHOLD`, отбираются только те, что входят в `FORBIDDEN_IMAGE_LABELS` (наркотики, насилие);
   - если такие категории найдены → решение **отклонить**: `reason="FORBIDDEN_CONTENT"`, `detected_labels=[...]`;
5. **Шаг 4 — «нормальное» изображение.** Если ни одно из правил не сработало → `approved=True`, `reason="OK"`, `label="normal"`, `score=1.0`.

Таким образом, изображение одобряется только если оно прошло и NSFW-модель, и детектор оружия, и CLIP-проверку по запрещённым категориям.

---

## Обработка ошибок

| Класс | Наследует | Назначение |
|---|---|---|
| `ModerationException` | `Exception` | Базовый класс, хранит поле `message` |
| `InvalidTextException` | `ModerationException` | Некорректный текст (пустой) |
| `InvalidImageException` | `ModerationException` | Некорректное изображение (размеры) |

Обработчики в `app/exceptions/handlers.py` преобразуют исключения в HTTP-ответ:

| Исключение | HTTP-код | `code` в теле |
|---|---|---|
| `InvalidTextException` | 400 | `INVALID_TEXT` |
| `InvalidImageException` | 400 | `INVALID_IMAGE` |

Тело ошибки всегда в формате `ErrorResponse`:

```json
{
  "code": "INVALID_IMAGE",
  "message": "Image width is too small: 10"
}
```

Ошибки загрузки файла (формат/размер) обрабатываются в роутере напрямую через `HTTPException` с соответствующими кодами (`400`, `413`).

---

## Диагностика и логирование

- Логи пишутся в stdout с уровнем `INFO` в формате `время уровень сообщение`.
- При старте логируются шаги загрузки моделей и выбранное устройство.
- В классификаторах присутствуют отладочные `print`-вызовы:
  - `TextClassifier` печатает входные тензоры, логиты и вероятности;
  - `ImageClassifier` печатает метки, предсказание и вероятности;
  - `ClipClassifier` печатает выбранное устройство при инициализации.

---

## Известные особенности

1. **Неполный `requirements.txt`.** В файл не включены ML-зависимости (`torch`, `transformers`, `Pillow`, `pymorphy3`), хотя они обязательны для работы. Для воспроизводимой установки их следует добавить в `requirements.txt`.
2. **`HF_TOKEN` зашит по умолчанию.** Токен присутствует и в `.env`, и как значение по умолчанию в `settings.py`. Его необходимо заменить/вычистить перед публикацией проекта.
3. **Отладочный вывод.** Классификаторы содержат `print()`-вызовы; в «боевом» режиме их стоит заменить на логирование через `logger`.
4. **Дублирование DI.** Логика внедрения зависимостей дублируется в `app/container.py` (не используется) и в `app/core/dependencies.py` (основной путь).
5. **Производительность.** Модели загружаются в память целиком; на CPU инференс CLIP-модели может быть медленным. Загрузка моделей происходит при старте приложения (см. `lifespan`), первое обращение к CLIP-эндпоинту также выполняет инициализацию модели.