Skip to content
This repository was archived by the owner on Nov 4, 2025. It is now read-only.

FEgor04/moretech-hack

BranchesTags

Repository files navigation

AI HR Система - MoreTech Hack

CI Backend CI Frontend

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

🚀 Ключевые возможности

  • Анализ резюме на базе ИИ: Автоматическое извлечение и анализ информации о кандидатах из PDF резюме
  • Интеллектуальное сопоставление кандидатов: Продвинутая система оценки совместимости с использованием векторных эмбеддингов и анализа навыков на базе LLM
  • Динамическая система собеседований: Вопросы, генерируемые ИИ в реальном времени с поддержкой видео/аудио, распознаванием и синтезом речи
  • Подробные отчеты о совместимости: Детальный анализ с рекомендациями по найму
  • Поддержка множественных ролей: Отдельные интерфейсы для рекрутеров, нанимающих менеджеров и кандидатов
  • Коммуникация в реальном времени: Чат для собеседований на базе WebSocket с распознаванием и синтезом речи

🏗️ Архитектурный обзор

Backend (FastAPI + Python 3.13)

  • Фреймворк: FastAPI с поддержкой async/await
  • База данных: PostgreSQL с расширением pgvector для векторных операций
  • ORM: SQLAlchemy 2.0 с асинхронной поддержкой
  • Миграции: Alembic для управления схемой базы данных
  • Интеграция ИИ: GigaChat API для LLM операций
  • Файловое хранилище: S3-совместимое хранилище для документов
  • Аутентификация: Система аутентификации на базе JWT

Frontend (React + TypeScript)

  • Фреймворк: React 19 с TypeScript
  • Роутинг: TanStack Router для файлового роутинга
  • Управление состоянием: TanStack Query для серверного состояния
  • UI компоненты: shadcn/ui с примитивами Radix UI
  • Стилизация: Tailwind CSS с пользовательской дизайн-системой
  • Инструмент сборки: Vite для быстрой разработки и сборки
  • Качество кода: Biome для линтинга и форматирования

Пайплайн обработки данных

Основной пайплайн анализа кандидатов

graph TD
    A[Загрузка PDF] --> B[Обработка файла GigaChat]
    B --> C[Извлечение и парсинг данных]
    C --> D[Генерация векторных эмбеддингов]
    D --> E[Сохранение в базу данных]
    E --> F[Анализ совместимости]
    F --> G[Сопоставление навыков LLM]
    G --> H[Расчет схожести]
    H --> I[Генерация отчета]
    I --> J[Отображение во фронтенде]
Loading

Пайплайн проведения собеседований

graph TD
    A[Создание собеседования] --> B[Генерация системного промпта]
    B --> C[Инициализация WebSocket соединения]
    C --> D[Отправка приветственного сообщения]
    D --> E[Ожидание ответа кандидата]
    E --> F{Тип ввода}
    F -->|Видео| G[Запись WebRTC потока]
    F -->|Аудио| H[Прямая обработка аудио]
    F -->|Текст| I[Прямая обработка текста]
    G --> J[Извлечение аудио FFmpeg]
    H --> K[Распознавание речи Yandex STT]
    J --> K
    I --> L[Анализ текста GigaChat]
    K --> L
    L --> M[Генерация следующего вопроса]
    M --> N{Собеседование завершено?}
    N -->|Нет| E
    N -->|Да| O[Синтез речи Yandex TTS]
    O --> P[Сохранение результатов]
    P --> Q[Уведомление рекрутера]
Loading

🔧 Основные технологии

Backend стек

  • Python 3.13 - Современный Python с новейшими функциями
  • FastAPI - Высокопроизводительный асинхронный веб-фреймворк
  • SQLAlchemy 2.0 - Современный ORM с асинхронной поддержкой
  • PostgreSQL + pgvector - Векторная база данных для эмбеддингов
  • Alembic - Управление миграциями базы данных
  • GigaChat API - Российский LLM для обработки текста
  • Yandex SpeechKit - Распознавание и синтез речи
  • Boto3 - AWS S3-совместимое хранилище
  • Pydantic - Валидация и сериализация данных
  • uv - Быстрый менеджер пакетов Python

Frontend стек

  • React 19 - Последний React с concurrent функциями
  • TypeScript - Типобезопасный JavaScript
  • TanStack Router - Типобезопасный роутинг
  • TanStack Query - Управление серверным состоянием
  • shadcn/ui - Современная библиотека компонентов
  • Tailwind CSS - Utility-first CSS фреймворк
  • Vite - Быстрый инструмент сборки и dev сервер
  • Biome - Быстрый линтер и форматтер
  • pnpm - Эффективный менеджер пакетов

ИИ и ML компоненты

  • Векторные эмбеддинги - 1024-мерные эмбеддинги для семантической схожести
  • Косинусная схожесть - Расчеты схожести векторов
  • Сопоставление навыков LLM - Анализ навыков на базе GigaChat
  • Обработка PDF - Автоматический парсинг резюме
  • Распознавание речи - Интеграция Yandex SpeechKit
  • Синтез текста - Вопросы для собеседований, генерируемые ИИ

📊 Ключевые сервисы и компоненты

1. Сервис анализа совместимости

# backend/app/services/compatibility_service.py
class CompatibilityService:
    async def analyze_compatibility(
        self, session: AsyncSession, candidate_id: str, vacancy_id: int
    ) -> Optional[CompatibilityReport]:
        # Объединяет схожесть эмбеддингов с анализом навыков LLM
        # Генерирует подробные рекомендации по найму

Возможности:

  • Схожесть эмбеддингов: 40% веса в общем балле
  • Сопоставление навыков: 60% веса с использованием анализа LLM
  • Анализ опыта: Оценка лет опыта работы
  • Уровни совпадения: Отличное (80%+), Хорошее (65%+), Удовлетворительное (45%+), Плохое (<45%)

2. Сервис эмбеддингов

# backend/app/services/embedding_service.py
class EmbeddingService:
    async def generate_candidate_embedding(self, candidate: Candidate) -> str:
        # Генерирует 1024-мерные векторные эмбеддинги
        # Сохраняет в PostgreSQL с поддержкой pgvector

Возможности:

  • Векторное хранилище: Расширение pgvector для PostgreSQL
  • Поиск схожести: Быстрые расчеты косинусной схожести
  • Пакетная обработка: Эффективные массовые операции
  • Поддержка fallback: TEXT колонки для тестовых сред

3. Система собеседований с ИИ

# backend/app/services/interview_messages.py
class InterviewMessagesService:
    async def create_message(
        self, session: AsyncSession, interview_id: str, payload: InterviewMessageCreateRequest
    ) -> List[InterviewMessage]:
        # Управление AI разговором в реальном времени
        # Динамическая генерация вопросов на основе контекста

Возможности:

  • Чат в реальном времени: Коммуникация на базе WebSocket
  • Генерация вопросов ИИ: Контекстно-зависимые вопросы для собеседований
  • Интеграция речи: Обработка и синтез аудио
  • Управление состоянием: Контроль потока собеседования

Пайплайн обработки собеседований

graph TD
    A[Начало собеседования] --> B[Генерация системного промпта]
    B --> C[Создание приветственного сообщения]
    C --> D[Ожидание ответа пользователя]
    D --> E{Тип ввода}
    E -->|Видео/Аудио| F[Обработка медиа]
    E -->|Текст| G[Прямая обработка]
    F --> H[Извлечение аудио из видео]
    H --> I[Распознавание речи Yandex STT]
    I --> J[Текстовый ответ кандидата]
    G --> J
    J --> K[Анализ ответа GigaChat]
    K --> L[Генерация следующего вопроса]
    L --> M{Интервью завершено?}
    M -->|Нет| D
    M -->|Да| N[Синтез речи Yandex TTS]
    N --> O[Отправка финального сообщения]
    O --> P[Сохранение результатов]
Loading

Интеграция TTS/STT

Yandex SpeechKit STT (Speech-to-Text):

# backend/app/clients/yandex.py
def get_yandex_speech_recognition_model() -> RecognitionModel:
    model.model = "general"
    model.language = "ru-RU"
    model.audio_processing_type = AudioProcessingType.Full
    return model

Yandex SpeechKit TTS (Text-to-Speech):

# backend/app/clients/yandex.py
def get_yandex_speech_synthesis_client() -> SynthesisModel:
    model.voice = "yulduz_ru"
    model.role = "friendly"
    model.unsafe_mode = True
    return model

Состояния собеседования:

  • AWAITING_USER_ANSWER - Ожидание ответа пользователя
  • SPEECH_RECOGNITION - Обработка аудио через STT
  • GENERATING_RESPONSE - Генерация ответа ИИ
  • SPEECH_SYNTHESIS - Синтез речи через TTS

Обработка медиа-контента

Видео обработка:

  • Запись WebRTC потока в WebM формате
  • Автоматическое извлечение аудио с помощью FFmpeg
  • Обрезка фрагментов по временным маркерам
  • Конвертация в формат, поддерживаемый Yandex STT

Аудио обработка:

  • Поддержка различных аудио форматов
  • Автоматическая нормализация звука
  • Обработка шумов и артефактов
  • Пакетная обработка для оптимизации

Умная генерация вопросов

Системный промпт для ИИ:

def _create_system_prompt(self, candidate: Candidate, vacancy: Vacancy) -> str:
    return f"""
    Ты — ассистент HR. Проводишь первичное интервью с кандидатом.
    
    Твоя цель:
    - собрать краткую информацию о кандидате,
    - оценить его профессиональный опыт,
    - проверить знания и умения, специфичные для вакансии,
    - оценить коммуникацию и общую культуру
    """

Адаптивные вопросы:

  • Анализ профиля кандидата и требований вакансии
  • Генерация контекстно-зависимых вопросов
  • Оценка технических навыков через практические вопросы
  • Проверка soft skills и мотивации
  • Автоматическое завершение при достаточном объеме информации

WebSocket интеграция

Реальное время коммуникации:

@router.websocket("/ws/{interview_id}/video")
async def websocket_video_stream(websocket: WebSocket, interview_id: str):
    # Обработка видео потока
    # Синхронизация состояний
    # Управление медиа-контентом

Функции WebSocket:

  • Передача видео потока в реальном времени
  • Обработка аудио маркеров для обрезки
  • Синхронизация состояний между клиентом и сервером
  • Поддержка текстового режима для отладки
  • Автоматическое восстановление соединения

4. Сервис парсера PDF

# backend/app/services/pdf_parser.py
class PDFParserService:
    async def parse_candidate(self, pdf_file: BinaryIO) -> tuple[CandidateCreate, str]:
        # Извлекает структурированные данные из PDF резюме
        # Использует GigaChat для интеллектуального парсинга

Возможности:

  • Интеграция GigaChat: Продвинутый анализ PDF
  • Структурированное извлечение: Парсит навыки, опыт, образование
  • Обработка ошибок: Надежный парсинг с fallback
  • Управление файлами: Интеграция S3 хранилища

🛠️ API эндпоинты

Аутентификация

  • POST /auth/signin - Аутентификация пользователя
  • GET /auth/me - Получение информации о текущем пользователе

Кандидаты

  • GET /candidates/ - Список всех кандидатов
  • POST /candidates/ - Создание нового кандидата
  • GET /candidates/{id} - Детали кандидата
  • PUT /candidates/{id} - Обновление кандидата
  • DELETE /candidates/{id} - Удаление кандидата
  • POST /candidates/upload-cv - Загрузка PDF резюме

Вакансии

  • GET /vacancies/ - Список всех вакансий
  • POST /vacancies/ - Создание новой вакансии
  • GET /vacancies/{id} - Детали вакансии
  • PUT /vacancies/{id} - Обновление вакансии
  • DELETE /vacancies/{id} - Удаление вакансии
  • POST /vacancies/upload-pdf - Загрузка PDF описания вакансии

Собеседования

  • GET /interviews/ - Список всех собеседований
  • POST /interviews/ - Создание нового собеседования
  • GET /interviews/{id} - Детали собеседования
  • GET /interviews/{id}/messages - Сообщения собеседования
  • POST /interviews/{id}/messages - Отправка сообщения

Анализ совместимости

  • GET /compatibility/candidate/{candidate_id}/vacancy/{vacancy_id}/report - Генерация отчета о совместимости
  • GET /compatibility/candidate/{candidate_id}/top-vacancies - Поиск лучших подходящих вакансий
  • GET /compatibility/vacancy/{vacancy_id}/top-candidates - Поиск лучших подходящих кандидатов

WebSocket

  • WS /ws/{interview_id}/video - Коммуникация собеседования в реальном времени

🚀 Настройка локальной разработки

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

  • Docker & Docker Compose - Для контейнеризованных сервисов
  • Node.js 24+ - Для разработки фронтенда
  • Python 3.13+ - Для разработки бэкенда
  • uv - Менеджер пакетов Python
  • pnpm - Менеджер пакетов Node.js

Быстрый старт с Docker

  1. Клонируйте репозиторий
git clone https://github.com/FEgor04/moretech-hack.git
cd moretech-hack
  1. Настройте переменные окружения
cp docker.env.example docker.env
# Отредактируйте docker.env с вашей конфигурацией
  1. Запустите все сервисы
docker-compose up --build
  1. Доступ к приложению

Ручная настройка разработки

Настройка Backend

cd backend

# Создайте виртуальное окружение
python -m venv .venv
source .venv/bin/activate  # На Windows: .venv\Scripts\activate

# Установите зависимости
uv sync

# Настройте переменные окружения
cp .env.example .env
# Отредактируйте .env с вашей конфигурацией

# Запустите миграции базы данных
uv run alembic upgrade head

# Запустите сервер разработки
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Настройка Frontend

cd frontend

# Установите зависимости
pnpm install

# Запустите сервер разработки
pnpm dev

Настройка базы данных

# Запустите PostgreSQL с pgvector
docker run --name postgres-pgvector -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres -p 5432:5432 -d pgvector/pgvector:pg17

# Запустите миграции
cd backend
uv run alembic upgrade head

Конфигурация окружения

Backend (.env)

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/postgres
AUTH_SECRET=your-secret-key
GIGACHAT_CREDENTIALS=your-gigachat-credentials
YANDEX_SPEECH_KEY=your-yandex-speech-key
S3_ENDPOINT_URL=https://s3.cloud.ru
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET_NAME=your-bucket-name

Frontend

Фронтенд автоматически подключается к API бэкенда по адресу http://localhost:8000.

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

Тесты Backend

cd backend

# Запустите все тесты
uv run pytest

# Запустите с покрытием
uv run pytest --cov=app --cov-report=html

# Запустите интеграционные тесты (требует Docker)
uv run pytest tests/integration

Тесты Frontend

cd frontend

# Запустите тесты
pnpm test

# Запустите линтинг
pnpm lint

# Запустите проверку форматирования
pnpm format

Качество кода

# Backend
cd backend
uv run black .          # Форматирование кода
uv run ruff check .     # Линтинг кода

# Frontend
cd frontend
pnpm format            # Форматирование кода
pnpm lint              # Линтинг кода

📈 Производительность и масштабируемость

Оптимизация базы данных

  • Векторная индексация: Индексы pgvector для быстрого поиска схожести
  • Пул соединений: Пул соединений AsyncPG
  • Оптимизация запросов: Эффективные запросы SQLAlchemy

Стратегия кэширования

  • Кэширование запросов: TanStack Query для кэширования фронтенда
  • Кэширование эмбеддингов: Сохраненные эмбеддинги для повторного использования
  • Управление сессиями: Эффективная обработка сессий

Мониторинг

  • Проверки здоровья: Встроенные эндпоинты здоровья
  • Логирование: Структурированное логирование во всем приложении
  • Отслеживание ошибок: Комплексная обработка ошибок

🔒 Функции безопасности

  • JWT аутентификация: Безопасная аутентификация на основе токенов
  • Валидация входных данных: Модели Pydantic для валидации данных
  • Защита от SQL инъекций: Защита ORM SQLAlchemy
  • Безопасность загрузки файлов: Валидация типов и размеров файлов
  • Конфигурация CORS: Правильный обмен ресурсами между источниками

🌐 Развертывание

Настройка Docker для продакшена

# Соберите продакшен образы
docker-compose -f docker-compose.prod.yml build

# Разверните в продакшене
docker-compose -f docker-compose.prod.yml up -d

Переменные окружения для продакшена

  • Установите все необходимые переменные окружения
  • Настройте правильные учетные данные базы данных
  • Настройте учетные данные S3 хранилища
  • Настройте учетные данные GigaChat API
  • Настройте учетные данные Yandex SpeechKit

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

  • Документация API: Доступна по эндпоинту /docs
  • Схема базы данных: Управляется через миграции Alembic
  • Документация компонентов: Компоненты фронтенда документированы с TypeScript
  • Документация сервисов: Сервисы бэкенда с docstrings

🤝 Участие в разработке

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

Руководящие принципы разработки

  • Следуйте существующему стилю кода
  • Пишите тесты для новых функций
  • Обновляйте документацию по мере необходимости
  • Убедитесь, что все проверки CI проходят

📄 Лицензия

Этот проект лицензирован под лицензией MIT - см. файл LICENSE для деталей.

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

  • GigaChat - За продвинутые возможности ИИ
  • Yandex SpeechKit - За обработку речи
  • FastAPI - За отличный веб-фреймворк
  • React - За мощную библиотеку фронтенда
  • PostgreSQL + pgvector - За возможности векторной базы данных

📞 Поддержка

Для поддержки и вопросов:

  • Создайте issue в GitHub репозитории
  • Свяжитесь с командой разработки
  • Проверьте документацию и API docs

Создано с ❤️ командой SLON

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages