PD Projects Recommendation System

Рекомендательная система для проектов проектной деятельности на основе интересов пользователя.

Описание

Система анализирует интересы пользователей и теги проектов, используя алгоритм косинусного сходства для предоставления персонализированных рекомендаций. Проект построен на FastAPI и интегрируется с существующим бекендом на NestJS.

Особенности

• 🎯 Персонализированные рекомендации - на основе интересов пользователя
• 🔍 Поиск похожих проектов - на основе тегов проекта
• 📊 Косинусное сходство - точный алгоритм сопоставления интересов и тегов
• 🏷️ Управление интересами и тегами - гибкая система категоризации
• 📝 Автоматическая документация - Swagger UI и ReDoc из коробки
• 🚀 Высокая производительность - благодаря FastAPI и асинхронности

Архитектура

Система состоит из следующих компонентов:

• Модели данных: User, Project, Interest, Tag, Institution
• Рекомендательный движок: Использует scikit-learn для вычисления косинусного сходства
• REST API: Эндпоинты для управления пользователями, проектами и получения рекомендаций

Требования

• Python 3.10+
• PostgreSQL 12+
• pip или poetry

Установка

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

git clone <repository-url>
cd pd-projects-recommended-system

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

python -m venv venv
source venv/bin/activate  # для Linux/Mac
# или
venv\Scripts\activate  # для Windows

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

pip install -r requirements.txt

4. Создайте файл .env на основе .env.example:

cp .env.example .env

5. Настройте переменные окружения в .env:

DATABASE_URL=postgresql://user:password@localhost:5432/pd_projects
API_HOST=0.0.0.0
API_PORT=8000

Запуск

Режим разработки

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

Режим продакшн

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

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

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

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

Основные эндпоинты

Пользователи

• POST /users/ - Создать пользователя
• GET /users/{user_id} - Получить информацию о пользователе
• GET /users/ - Получить список пользователей
• PUT /users/{user_id}/interests - Обновить интересы пользователя

Интересы

• POST /users/interests - Создать новый интерес
• GET /users/interests/ - Получить список всех интересов

Проекты

• POST /projects/ - Создать проект
• GET /projects/{project_id} - Получить информацию о проекте
• GET /projects/ - Получить список проектов
• PUT /projects/{project_id}/tags - Обновить теги проекта

Теги

• POST /projects/tags - Создать новый тег
• GET /projects/tags/ - Получить список всех тегов

Рекомендации

• GET /recommendations/{user_id} - Получить рекомендации для пользователя
  • Параметры:
    • limit - максимальное количество рекомендаций (1-50)
    • min_score - минимальный порог оценки релевантности (0.0-1.0)
• GET /recommendations/similar/{project_id} - Получить похожие проекты
  • Параметры:
    • limit - максимальное количество проектов (1-20)
• GET /recommendations/{user_id}/suggested-interests - Получить предложенные интересы

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

Создание пользователя с интересами

# 1. Создать пользователя
curl -X POST "http://localhost:8000/users/" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "first_name": "Иван",
    "last_name": "Иванов"
  }'

# 2. Создать интересы
curl -X POST "http://localhost:8000/users/interests" \
  -H "Content-Type: application/json" \
  -d '{"name": "AI", "description": "Artificial Intelligence"}'

curl -X POST "http://localhost:8000/users/interests" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web Development", "description": "Web технологии"}'

# 3. Обновить интересы пользователя
curl -X PUT "http://localhost:8000/users/1/interests" \
  -H "Content-Type: application/json" \
  -d '{"interest_ids": [1, 2]}'

Создание проекта с тегами

# 1. Создать теги
curl -X POST "http://localhost:8000/projects/tags" \
  -H "Content-Type: application/json" \
  -d '{"name": "Python", "description": "Python programming"}'

curl -X POST "http://localhost:8000/projects/tags" \
  -H "Content-Type: application/json" \
  -d '{"name": "Machine Learning", "description": "ML technologies"}'

# 2. Создать проект
curl -X POST "http://localhost:8000/projects/" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AI Chatbot",
    "description": "Умный чат-бот на основе GPT",
    "author_id": 1,
    "tag_ids": [1, 2]
  }'

Получение рекомендаций

# Получить рекомендации для пользователя
curl "http://localhost:8000/recommendations/1?limit=10&min_score=0.3"

# Получить похожие проекты
curl "http://localhost:8000/recommendations/similar/1?limit=5"

# Получить предложенные интересы
curl "http://localhost:8000/recommendations/1/suggested-interests"

Алгоритм рекомендаций

Система использует следующий подход:

1. Векторизация: Интересы пользователя и теги проектов преобразуются в векторы
2. Косинусное сходство: Вычисляется угол между векторами интересов и тегов
3. Бонус за совпадения: Добавляется дополнительный вес за количество совпавших тегов
4. Ранжирование: Проекты сортируются по оценке релевантности

Формула оценки:

score = cosine_similarity(user_interests, project_tags) + (matches_count * 0.1)

Интеграция с NestJS Backend

Система может работать параллельно с основным бекендом на NestJS. Рекомендуется:

1. Использовать одну базу данных PostgreSQL
2. Настроить синхронизацию моделей между системами
3. Использовать API Gateway для маршрутизации запросов
4. Настроить CORS для взаимодействия между сервисами

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

pd-projects-recommended-system/
├── app/
│   ├── __init__.py
│   ├── main.py              # Главный файл приложения
│   ├── config.py            # Конфигурация
│   ├── database.py          # Подключение к БД
│   ├── models/
│   │   ├── __init__.py
│   │   └── models.py        # SQLAlchemy модели
│   ├── schemas/
│   │   ├── __init__.py
│   │   └── schemas.py       # Pydantic схемы
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── users.py         # Эндпоинты пользователей
│   │   ├── projects.py      # Эндпоинты проектов
│   │   └── recommendations.py  # Эндпоинты рекомендаций
│   └── services/
│       ├── __init__.py
│       └── recommendation_service.py  # Логика рекомендаций
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

Разработка

Добавление новых интересов/тегов

Интересы и теги можно добавлять через API или напрямую в базу данных. Рекомендуется использовать API для обеспечения целостности данных.

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

# Установить pytest
pip install pytest pytest-asyncio httpx

# Запустить тесты
pytest

Форматирование кода

# Установить инструменты
pip install black isort

# Форматировать код
black app/
isort app/

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

• Использование индексов в базе данных на полях email, name
• Кэширование векторных представлений
• Асинхронные операции для улучшения отзывчивости

Лицензия

MIT

Поддержка

Для вопросов и предложений создавайте Issues в репозитории проекта.