🎓 Student Performance Prediction API

REST API для предсказания успеваемости студентов на основе демографических и социальных факторов. Модель обучена на данных португальских школ и предсказывает финальную оценку (G3) по 20-балльной шкале.

📊 О проекте

Этот проект использует машинное обучение для предсказания академической успеваемости студентов. Модель анализирует 30+ признаков:

• Демография: возраст, пол, размер семьи
• Социальные факторы: образование и профессия родителей
• Поведение: время на учебу, прогулки, потребление алкоголя
• Школа: пропуски, дополнительная поддержка, внеклассные активности

📈 Метрики модели

Метрика	Значение
MAE (Test)	~2.0 балла
RMSE (Test)	~2.8 балла
R² (Test)	~0.25

🚀 Быстрый старт

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

• Docker (рекомендуется)
• или Python 3.12+

Запуск через Docker (рекомендуется)

# 1. Сборка образа
docker build -t student-performance-api .

# 2. Запуск контейнера
docker run -p 8000:8000 student-performance-api

# API доступен по адресу: http://localhost:8000

Запуск локально

# 1. Клонирование репозитория
git clone https://github.com/Reactivity512/student-performance-prediction.git
cd student-performance-prediction

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

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

# 3. Установка зависимостей
pip install -r requirements.txt

# 4. Запуск сервера
python main.py

# или
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

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

После запуска сервера доступна интерактивная документация:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Эндпоинты

Метод	URL	Описание
GET	/	Информация о сервисе
GET	/health	Проверка состояния
GET	/model-info	Информация о модели
POST	/predict	Предсказание оценки

Пример запроса

POST /predict

{
  "age": 18,
  "Medu": 3,
  "Fedu": 2,
  "traveltime": 2,
  "studytime": 2,
  "failures": 0,
  "famrel": 4,
  "freetime": 3,
  "goout": 3,
  "Dalc": 1,
  "Walc": 2,
  "health": 5,
  "absences": 4,
  "school": "GP",
  "sex": "F",
  "address": "U",
  "famsize": "GT3",
  "Pstatus": "T",
  "Mjob": "teacher",
  "Fjob": "other",
  "reason": "course",
  "guardian": "mother",
  "schoolsup": "no",
  "famsup": "yes",
  "paid": "no",
  "activities": "yes",
  "nursery": "yes",
  "higher": "yes",
  "internet": "yes",
  "romantic": "no"
}

Пример ответа

{
  "predicted_grade": 12.45,
  "grade_category": "Хорошо (B)",
  "processing_time_ms": 15.42
}

Категории оценок

Баллы	Категория
0-7	Неудовлетворительно (F)
8-9	Ниже среднего (D)
10-11	Средне (C)
12-13	Хорошо (B)
14-15	Очень хорошо (A)
16-20	Отлично (A+)

🧪 Тестирование

cURL (Windows CMD)

@echo off
echo Sending request to Student Performance API...

curl.exe -X POST "http://localhost:8000/predict" ^
  -H "Content-Type: application/json" ^
  -d "{\"age\":18,\"Medu\":3,\"Fedu\":2,\"traveltime\":2,\"studytime\":2,\"failures\":0,\"famrel\":4,\"freetime\":3,\"goout\":3,\"Dalc\":1,\"Walc\":2,\"health\":5,\"absences\":4,\"school\":\"GP\",\"sex\":\"F\",\"address\":\"U\",\"famsize\":\"GT3\",\"Pstatus\":\"T\",\"Mjob\":\"teacher\",\"Fjob\":\"other\",\"reason\":\"course\",\"guardian\":\"mother\",\"schoolsup\":\"no\",\"famsup\":\"yes\",\"paid\":\"no\",\"activities\":\"yes\",\"nursery\":\"yes\",\"higher\":\"yes\",\"internet\":\"yes\",\"romantic\":\"no\"}"

echo.
pause

Описание признаков

Числовые признаки

Признак	Диапазон	Описание
age	15-22	Возраст студента
Medu	0-4	Образование матери
Fedu	0-4	Образование отца
traveltime	1-4	Время в пути до школы
studytime	1-4	Время на учебу в неделю
failures	0-4	Количество несданных предметов
famrel	1-5	Качество семейных отношений
freetime	1-5	Свободное время
goout	1-5	Частота прогулок с друзьями
Dalc	1-5	Потребление алкоголя в будни
Walc	1-5	Потребление алкоголя в выходные
health	1-5	Состояние здоровья
absences	0-93	Количество пропусков

Категориальные признаки

Признак	Значения	Описание
school	GP, MS	Школа
sex	F, M	Пол
address	U, R	Тип адреса (город/село)
famsize	LE3, GT3	Размер семьи
Pstatus	T, A	Статус родителей (вместе/раздельно)
Mjob	teacher, health, services, at_home, other	Профессия матери
Fjob	teacher, health, services, at_home, other	Профессия отца
reason	home, reputation, course, other	Причина выбора школы
guardian	mother, father, other	Опекун
schoolsup	yes, no	Доп. поддержка в школе
famsup	yes, no	Семейная поддержка
paid	yes, no	Платные занятия
activities	yes, no	Внеклассные активности
nursery	yes, no	Посещал детский сад
higher	yes, no	Планирует высшее образование
internet	yes, no	Доступ в интернет
romantic	yes, no	В отношениях

🐳 Docker команды

# Сборка
docker build -t student-api .

# Запуск
docker run -p 8000:8000 student-api

# Запуск в фоне
docker run -d -p 8000:8000 --name student-api student-api

# Просмотр логов
docker logs -f student-api

# Остановка
docker stop student-api

# Удаление
docker rm student-api

📄 Лицензия

MIT License. См. файл LICENSE.

👤 Автор

Reactivity512

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

• Данные: UCI Machine Learning Repository
• Авторы датасета: P. Cortez and A. Silva
• Kaggle: Student Performance Data Set