project111
Study Material Recommender System
Интеллектуальная система рекомендации учебных материалов студентам на основе их предпочтений, уровня знаний и истории обучения.
✨ Особенности
- 🤝 Collaborative Filtering - рекомендации на основе похожих студентов
- 📚 Content-Based Filtering - анализ характеристик материалов
- 🔀 Гибридный подход - комбинирование методов
- 📊 Оценка качества - RMSE, Precision@k, Recall@k
- 🔧 REST API на FastAPI
- 🔄 Автоматическое переобучение через CI/CD
🏗️ Архитектура
project111/
├── src/ # Исходный код
│ ├── api.py # FastAPI приложение
│ ├── collaborative_filtering.py
│ ├── content_based.py
│ ├── data_loader.py
│ ├── evaluation.py
│ ├── hybrid_model.py # Гибридная модель
│ ├── preprocessing.py
│ └── utils.py
├── tests/ # Тесты
├── data/ # Данные
├── docs/ # Документация
├── scripts/ # Вспомогательные скрипты
└── .github/workflows/ # CI/CD пайплайны
🚀 Быстрый старт
Предварительные требования
- Python 3.8+
- pip
Установка
# 1. Клонируйте репозиторий
git clone https://github.com/your-username/study-material-recommender.git
cd study-material-recommender
# 2. Установите зависимости
pip install -r requirements.txt
# 3. Настройте окружение
cp .env.example .env
# Отредактируйте .env при необходимости
Запуск
uvicorn src.api:app --reload
# Или через скрипт
python scripts/run_api.py
📖 Использование
Пример API запроса
import requests
response = requests.post(
"http://localhost:8000/recommend",
json={
"student_id": "student_001",
"n_recommendations": 5
}
)
print(response.json())
Основные эндпоинты API
-
GET /health - проверка здоровья системы
-
POST /recommend - получение рекомендаций
-
GET /similar/{material_id} - похожие материалы
-
POST /rate - добавление оценки
-
GET /metrics - метрики модели
🧪 Тестирование
# Запуск всех тестов
pytest
# Запуск с покрытием кода
pytest --cov=src --cov-report=html
# Запуск конкретного модуля
pytest tests/test_hybrid.py -v
# Проверка стиля кода
flake8 src
black src --check
🐳 Docker
# Сборка и запуск
docker-compose up --build
# Только сборка
docker build -t material-recommender .
🔧 Настройка окружения
Создайте .env файл на основе .env.example:
env
# Настройки приложения
ENVIRONMENT=development
DEBUG=True
LOG_LEVEL=INFO
# Настройки модели
MODEL_PATH=models/hybrid_model.pkl
DATA_PATH=data/sample_data.csv
# Настройки API
API_HOST=0.0.0.0
API_PORT=8000
API_WORKERS=4
📊 Метрики
Метод RMSE Precision@10 Recall@10
Collaborative 0.92 0.68 0.60
Content-Based 0.98 0.62 0.55
Hybrid 0.85 0.72 0.65
🤝 Вклад в проект
-
Форкните репозиторий
-
Создайте ветку (git checkout -b feature/amazing-feature)
-
Зафиксируйте изменения (git commit -m 'Add amazing feature')
-
Запушьте ветку (git push origin feature/amazing-feature)
-
Откройте Pull Request
Требования к коду
-
Соответствие PEP 8
-
Тесты для новой функциональности
-
Обновленная документация
-
Использование Black для форматирования
📄 Лицензия
Этот проект лицензирован под MIT License - см. файл LICENSE.