final_project_vibecod

Автоматизированная система для классификации сложности вопросов оценки на основе текстовых признаков, времени ответа и точности студентов. Этот инструмент помогает преподавателям и разработчикам тестов:

• Автоматически классифицировать вопросы как легкие, средние или сложные
• Извлекать значимые признаки из текста вопроса (количество слов, сложность, читаемость)
• Использовать метаданные, такие как среднее время ответа и процент правильных ответов
• Обучать ML-модели (Random Forest, Gradient Boosting) с кросс-валидацией
• Генерировать отчеты с важностью признаков и метриками модели

Почему это важно: Создание сбалансированных оценок требует смеси уровней сложности. Ручная классификация сотен вопросов отнимает время и субъективна. Эта система предоставляет обоснованные данными оценки сложности, помогая преподавателям создавать справедливые и хорошо сбалансированные тесты.

Установка

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

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

Настройка

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

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

Обучите классификатор на выборочном наборе данных:

Вывод:

Загрузка данных из data/sample_questions.csv...
Набор данных: 50 образцов, 19 признаков
Обучение модели random_forest...
Выполнение кросс-валидации...

Результаты обучения:
  Точность: 0.9600
  Точность КВ: 0.8200 (+/- 0.0800)
Модель сохранена в models/difficulty_classifier.joblib
Метрики сохранены в models/model_metrics.json
График важности признаков сохранен в models/feature_importance.png

Предсказание сложности вопроса

Классифицируйте новый вопрос:

Вывод:

Вопрос: Какая столица Франции?
Предсказанная сложность: легкая
Уверенность: 0.8542
Вероятности:
  легкая: 0.8542
  средняя: 0.1234
  сложная: 0.0224

Оценка модели

Оцените на наборе данных:

Использование как Python-модуля

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

.
├── src/                          # Исходный код
│   ├── __init__.py
│   ├── main.py                   # Точка входа CLI
│   ├── classifier.py             # Класс DifficultyClassifier
│   └── feature_extractor.py      # Класс QuestionFeatureExtractor
├── tests/                        # Юнит-тесты
│   ├── __init__.py
│   ├── test_feature_extractor.py
│   ├── test_classifier.py
│   └── test_main.py
├── data/                         # Файлы данных
│   └── sample_questions.csv      # Выборочный набор данных (50 вопросов)
├── .github/workflows/            # CI/CD
│   ├── tests.yml                 # Базовый CI: линтинг + тесты
│   └── retrain_model.yml         # Периодическое переобучение модели
├── README.md                     # Этот файл
├── requirements.txt              # Зависимости Python
└── .gitignore                    # Правила игнорирования Git

Требования

• Python: 3.8+
• Основные зависимости:
  • NumPy >= 1.21.0
  • Pandas >= 1.3.0
  • Scikit-learn >= 1.0.0
  • NLTK >= 3.6.0
  • Matplotlib >= 3.4.0
  • Joblib >= 1.1.0

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

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

Запуск с покрытием:

Ожидаемый вывод:

tests/test_feature_extractor.py ..........                             [ 40%]
tests/test_classifier.py ..............                                [ 56%]
tests/test_main.py ..                                                  [  4%]

======================== 26 passed in 3.42s =========================

Рабочие процессы CI/CD

1. Тесты и качество кода (при push/PR)

Автоматически запускается при каждом push и pull request:

• Линтинг: flake8 (соответствие PEP 8)
• Форматирование: проверка black
• Тесты: pytest с покрытием
• Мульти-Python: тесты на Python 3.8, 3.9, 3.10

2. Периодическое переобучение модели (cron: еженедельно)

Автоматически переобучает модель каждый понедельник в 00:00 UTC:

• Устанавливает зависимости
• Обучает модель на последних данных
• Сохраняет модель и метрики как артефакты
• Генерирует отчет важности признаков
• Загружает
  model_metrics.json
  и
  feature_importance.png
  как артефакты

Ручной запуск: Также можно запустить вручную из вкладки Actions с

Извлекаемые признаки

Примеры вопросов по сложности

Легкие

"Какой химический символ у воды?"

Средние

"Объясните разницу между митозом и мейозом."

Сложные

"Выведите формулу объема сферы с помощью интегрирования."

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

После обучения на 50 выборочных вопросах:

• Точность обучения: ~96%
• Точность кросс-валидации: ~82% (+/- 8%)
• Признаков: 19
• Классов: легкая, средняя, сложная

Смотрите

Вклад

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

Автор

Владимир Щербинин

Лицензия

MIT License — См. LICENSE для деталей.