Spam Classification

Система классификации спама на основе BERT с FastAPI интерфейсом

Особенности • Установка • Использование • Архитектура • API • Обучение

---

Описание

Современная система для классификации SMS-сообщений как спам или не-спам (ham), построенная на базе предобученной модели BERT. Проект включает в себя полный цикл обработки данных, обучения модели и развертывания через REST API.

Особенности

• BERT-based классификация — использование state-of-the-art трансформерной архитектуры
• FastAPI интерфейс — быстрое и современное REST API
• Полная предобработка — лемматизация, стемминг, удаление стоп-слов
• Готовая к продакшену — структурированный код и модульная архитектура
• Быстрое обучение — оптимизированный процесс fine-tuning
• Легкое развертывание — минимальные зависимости

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

Компонент	Технология
ML Framework	PyTorch
Model	BERT (Transformers)
API Framework	FastAPI
Text Processing	NLTK
Data Processing	Pandas

Установка

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

• Python 3.8 или выше
• pip

Шаги установки

1. Клонируйте репозиторий

git clone https://github.com/Kairatzh/Spam-Classification.git
cd Spam-Classification

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

python -m venv venv

3. Активируйте виртуальное окружение

Windows:

venv\Scripts\activate

Linux/MacOS:

source venv/bin/activate

4. Установите зависимости

pip install -r requirements.txt

5. Настройте конфигурацию (опционально)

cp .env.example .env
# Отредактируйте .env под свои нужды

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

Запуск API сервера

python main.py

Или через uvicorn:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

После запуска API будет доступен по адресу: http://localhost:8000

Документация API

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

Примеры использования

Healthcheck

curl http://localhost:8000/healthcheck

Response:

{
  "status": "ok",
  "app_name": "Spam Classification API",
  "version": "1.0.0",
  "model_loaded": true
}

Предсказание спама

curl -X POST "http://localhost:8000/predict" \
     -H "Content-Type: application/json" \
     -d '{"text": "Congratulations! You won $1000! Click here now!"}'

Response:

{
  "text": "Congratulations! You won $1000! Click here now!",
  "prediction": 1,
  "confidence": 0.95,
  "label": "spam"
}

Python пример

import requests

response = requests.post(
    "http://localhost:8000/predict",
    json={"text": "Congratulations! You won $1000!"}
)

result = response.json()
print(f"Label: {result['label']}")
print(f"Confidence: {result['confidence']:.2%}")

Запуск тестов

# Запуск всех тестов
pytest tests/ -v

# Запуск с coverage
pytest tests/ --cov=. --cov-report=html

# Запуск конкретного теста
pytest tests/test_api.py -v

Архитектура проекта

Spam-Classification/
│
├── 📁 data/                    # Данные для обучения
│   └── combined_data.csv       # Датасет SMS
│
├── 📁 tests/                   # Unit тесты
│   ├── __init__.py
│   ├── test_api.py            # Тесты API endpoints
│   └── test_model.py          # Тесты модели
│
├── 📁 logs/                    # Логи (создается автоматически)
│
├── 📄 config.py               # Конфигурация приложения
├── 📄 logger.py               # Настройка логирования
├── 📄 schemas.py              # Pydantic модели для API
│
├── 📄 data_preprocess.py      # Препроцессинг текста
├── 📄 model.py                # SpamClassifier класс
├── 📄 model_training.py       # Обучение модели
├── 📄 main.py                 # FastAPI приложение
│
├── 📄 .env.example            # Пример конфигурации
├── 📄 requirements.txt        # Зависимости
├── 📄 .gitignore             # Git ignore
├── 📄 LICENSE                # MIT License
└── 📄 README.md              # Документация

Компоненты

1. Конфигурация (config.py)

• Централизованные настройки через Pydantic Settings
• Поддержка переменных окружения из .env
• Параметры модели, API, обучения

2. Логирование (logger.py)

• Настройка логирования в файлы и консоль
• Ротация файлов логов (10MB макс)
• Разделение по модулям

3. API Schemas (schemas.py)

• Pydantic модели для валидации
• Request/Response типы
• Встроенные примеры для документации

4. Предобработка данных (data_preprocess.py)

• TextPreprocessor класс для обработки текста
• load_data() - загрузка CSV данных
• preprocess_data() - пайплайн обработки
• Очистка, токенизация, лемматизация, стемминг

5. Модель (model.py)

• SpamClassifier класс с lazy loading
• Поддержка batch предсказаний
• Автоматическая загрузка pretrained/custom моделей
• Расчет confidence scores

6. Обучение (model_training.py)

• Train/validation split (80/20)
• Метрики: Accuracy, F1-score
• Learning rate scheduler
• Сохранение лучших чекпоинтов
• Progress bars с tqdm

7. API (main.py)

• FastAPI с async/await
• Dependency injection для модели
• CORS middleware
• Обработка ошибок и логирование
• Lifespan events для инициализации

8. Тесты (tests/)

• Unit тесты для API (test_api.py)
• Unit тесты для модели (test_model.py)
• Покрытие edge cases

API

Endpoints

Method	Endpoint	Описание
GET	/healthcheck	Проверка работоспособности сервиса
POST	/predict	Классификация текста

Модель данных

Request Body (/predict)

{
  "text": "Your message text here",
  "prediction": 0
}

Response

{
  "text": "Your message text here",
  "prediction": 1
}

Prediction values:

• 0 — Ham (не спам)
• 1 — Spam (спам)

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

Параметры обучения

Параметры можно изменить в config.py или через .env:

LEARNING_RATE=2e-5      # Learning rate для Adam
NUM_EPOCHS=3            # Количество эпох
TRAIN_BATCH_SIZE=8      # Batch size
MAX_LENGTH=64           # Максимальная длина текста

Процесс обучения

1. Подготовьте данные

   • Поместите CSV файл в папку data/
   • Формат: text,label (где label: 0=ham, 1=spam)

2. Запустите обучение

python model_training.py

3. Модель сохранится в ./saved_model/

Метрики

Во время обучения отслеживаются:

• Training Loss (каждый batch)
• Validation Loss, Accuracy, F1-score (каждую эпоху)
• Сохраняется модель с лучшим F1-score

Использование кастомной модели

После обучения установите путь в .env:

MODEL_PATH=./saved_model

Датасет

Проект использует комбинированный датасет SMS сообщений для классификации спама. Данные находятся в data/combined_data.csv.

Формат данных:

Колонка	Описание
text	Текст SMS сообщения
label	Метка класса (0 или 1)

🔬 Производительность

Модель базируется на fine-tuned BERT и показывает высокую точность классификации SMS-сообщений:

• Быстрый инференс
• Предобработка текста
• Поддержка batch-предсказаний

Вклад в проект

Мы приветствуем любые улучшения! Чтобы внести вклад:

1. Форкните проект
2. Создайте ветку для фичи (git checkout -b feature/AmazingFeature)
3. Закоммитьте изменения (git commit -m 'Add some AmazingFeature')
4. Запушьте в ветку (git push origin feature/AmazingFeature)
5. Откройте Pull Request

TODO

• Добавить метрики качества (accuracy, precision, recall, F1)
• Реализовать логирование
• Добавить Docker контейнеризацию
• Расширить тестовое покрытие
• Добавить мониторинг производительности
• Реализовать batch-prediction endpoint
• Добавить фронтенд интерфейс

Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

Автор

Kairatzh

• GitHub: @Kairatzh
• Проект: Spam-Classification

Благодарности

• Hugging Face за библиотеку Transformers
• FastAPI за отличный фреймворк
• Сообщество PyTorch за поддержку
• Создателям BERT архитектуры

---

Сделано с любовью и Python

⭐ Поставьте звезду, если проект был полезен!