Quora Question Pairs — Duplicate Questions Detection Service

Проєкт присвячений розробці, оцінці та розгортанню високоефективної системи виявлення дублікатів запитань на платформі Quora Question Pairs.

Система дозволяє визначати, чи мають два різні питання однаковий семантичний зміст, що дає змогу запобігати дублюванню контенту, покращувати пошук відповідностей та економити час користувачів.

---

🎯 Мета проєкту

1. Feature Engineering & NLP: Побудувати багаторівневу систему витягання ознак (текстових, статистичних, семантичних на базі SBERT та графових).
2. Ансамблювання моделей: Навчити та порівняти сучасні алгоритми градієнтного бустингу (LightGBM, CatBoost) і об'єднати їх у Weighted Blend Ensemble.
3. Production-Ready API: Обгорнути модель у FastAPI сервіс з підтримкою одиночних і пакетних Parquet-запитів, упакувати у Docker та надати зручний Makefile для автоматизації.

---

📊 Датасет та аналіз даних

В основі дослідження — класичний датасет Quora Question Pairs, що містить понад 400,000 пар запитань із бінарною міткою is_duplicate.

Розподіл даних та ключові спостереження

1. Частота появи питань (Log Scale): Більшість запитань зустрічаються у датасеті від 1 до 3 разів, проте присутні й "популярні" питання-вузли, які повторюються понад 50-100 разів. Це дало змогу створити графові фічі (частотність та зв'язність).
2. Розподіл Word Share Index: Показник перетину слів (word_share) є чітким розділителем між дублікатами (зелений) та не-дублікатами (червоний). Для дублікатів середній шар слів значно вищий, що робить цю фічу однією з найважливіших.

---

🔬 Експерименти та порівняльна таблиця

Процес розробки відбувався в 5 етапів з поступовим ускладненням конвеєра Feature Engineering:

Experiment	Features Count	Description	OOF LogLoss	Test LogLoss	OOF ROC-AUC
1. Baseline (V1)	12	Basic lengths, word_share, question frequencies	0.34683	0.34588	0.91487
2. Advanced (V2)	18	+ RapidFuzz, TF-IDF Cosine, Graph Neighbors	0.26834	0.26631	0.94747
3. SBERT (V3 - LGBM)	22	+ SBERT (all-MiniLM-L6-v2) Embeddings & Distances	0.20757	0.20577	0.97096
4. CatBoost (V3)	22	CatBoost Classifier on V3 SBERT Features	0.20683	0.20585	0.97112
5. Blend Ensemble (V3)	22	Weighted Blend (0.50 LGBM + 0.50 CatBoost)	0.20624	0.20525	0.97134

---

📈 Динаміка метрик та Важливість Ознак

1. Динаміка зниження LogLoss

Впровадження SBERT-ембедингів та нечіткого порівняння рядків (RapidFuzz) забезпечило кардинальне падіння помилки з 0.34588 до 0.20525.

2. Топ-15 Важливих Фіч (Feature Importance)

Найбільший вклад у рішення LightGBM роблять:

• word_share — частка спільних слів.
• fuzz_partial_ratio та tfidf_cosine_sim — синтаксична та векторна схожість.
• sbert_manhattan_dist, sbert_euclidean_dist, sbert_cosine_sim — глибинна семантична схожість контексту від SentenceTransformers.

---

🛠️ FastAPI & Docker Deployment

Сервіс оформлено у вигляді асинхронного FastAPI веб-додатку, ізольованого у Docker-контейнері.

Основні Ендпоінти:

• POST /predict — оцінка однієї пари питань (JSON).
• POST /predict-parquet — пакетна обробка .parquet файлів у стрімінговому режимі.
• GET /health — перевірка статусу сервісу та завантаження моделей.

---

⚡ Управління проєктом через Makefile

Для спрощення розгортання та керування сервісом додано Makefile.

Команда	Опис
make help	Показати список усіх доступних команд
make build	Побудувати Docker-образ сервісу
make up	Запустити сервіс у фоновому режимі
make up-build	Перезбирати Docker-образ та запустити контейнери
make down	Зупинити та видалити контейнери
make restart	Перезапустити контейнер
make logs	Переглянути логи додатку в реальному часі
make clean	Очистити застарілі та невикористовувані Docker-образи
make lint	Перевірити якість коду через ruff
make run-local	Запустити FastAPI локально для відлагодження

---

🚀 Швидкий запуск

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

   git clone https://github.com/e1ephntbrd/quora-bert-ml-fastapi.git
   cd quora-bert-ml-fastapi

2. Запустіть сервіс у Docker:

   make up-build

3. Відкрийте Swagger UI для тестування: Перейдіть за адресою: http://localhost:8000/docs