EventMatch — объяснимый ИИ-подбор подрядчиков

Готовый прототип для задачи #79-lite. Пользователь задаёт условия мероприятия и описывает пожелания своими словами. Сервис возвращает до трёх доступных профилей, показывает основания выбора и предлагает проверенные изменения условий, если никто не подошёл.

Это работающий локальный AI-поиск, а не имитация. В комплекте модель multilingual-e5-small в формате ONNX, векторный индекс и исходные 66 профилей. Ключ OpenAI, платный API, GPU и отдельный сервер базы данных не требуются. Данные хранятся в файлах; PostgreSQL здесь не подключён и для этого объёма не нужен.

Быстрый запуск на Windows

Frontend, backend и ИИ запускаются вместе через START.cmd. Отдельно поднимать три программы не нужно.

Что понадобится

• Обычный 64-битный CPython 3.12 или 3.13. Проверено на Windows / Python 3.12.14. MSYS/MinGW Python не подходит для ONNX.
• Интернет для первой установки Python-зависимостей. Веса ИИ-модели уже включены в полный архив.
• Браузер. Node.js, npm, Docker, GPU и платный API-ключ не нужны.

Если Python не установлен, скачайте его с python.org. В установщике отметьте Add Python to PATH. После установки откройте новое окно терминала, если будете запускать проект командой.

Запуск без команд

1. Нажмите правой кнопкой на EventMatch-final.zip → «Извлечь всё». Распакуйте весь архив, а не только HTML-файл.
2. Откройте распакованную папку hackathon-contractor-ai. Внутри должны находиться START.cmd, run.py и папки backend, frontend, docs.
3. Дважды нажмите START.cmd. Откроется окно сервера. При первом запуске дождитесь установки зависимостей; при следующих они не устанавливаются заново, если список зависимостей не изменился.
4. Дождитесь сообщения Application startup complete. Браузер откроется автоматически. Если не открылся, перейдите на http://127.0.0.1:8000/app/.
5. Нажмите «01 · Спокойный ведущий» над формой. Должны появиться три карточки с объяснениями и выделенными цитатами.

Не закрывайте окно сервера, пока пользуетесь сайтом. Для остановки нажмите в этом окне Ctrl+C. Для повторного запуска снова откройте START.cmd.

Не запускайте файлы прямо внутри ZIP. Не открывайте frontend/index.html отдельно для основного сценария: страница сама по себе не запускает backend и ИИ. Правильная точка входа — адрес /app/ работающего сервера.

После установки зависимостей подбор работает без интернета: запросы и описания не отправляются во внешний AI-сервис.

Запуск через PowerShell

Откройте папку проекта в Проводнике, введите powershell в адресную строку и нажмите Enter. В открывшемся окне выполните:

python run.py

Если команда python не найдена, но установлен Python Launcher, можно выполнить:

py -3.12 run.py

Если порт 8000 занят, выберите другой:

python run.py --port 8001

Тогда сайт будет доступен на http://127.0.0.1:8001/app/. Используйте порт, указанный в окне запуска.

Как убедиться, что всё работает

• Сайт: http://127.0.0.1:8000/app/ — форма и карточки рекомендаций.
• Состояние: http://127.0.0.1:8000/health — ожидаются status: "ok", contractors_count: 66, semantic_ready: true.
• Документация API: http://127.0.0.1:8000/docs.

Для проверки смыслового поиска сначала нажмите «01 · Спокойный ведущий», затем замените пожелание на «Без долгих речей, только развлечения и танцы» и повторите подбор. При неизменных остальных условиях порядок должен измениться; первым станет профиль Аня Форджер.

Если не запускается

Что произошло	Что сделать
python не найден или требуется Python 3.12+	Установите обычный 64-битный Python 3.12/3.13 с опцией Add Python to PATH и повторите запуск.
Ошибка установки зависимостей	Проверьте интернет и последние строки сообщения об ошибке. После устранения причины повторно откройте START.cmd.
Порт занят / WinError 10048	Возможно, проект уже запущен. Откройте его адрес либо выполните python run.py --port 8001.
Сайт сообщает «Нет связи с сервером»	Проверьте, что окно сервера не закрыто и запуск завершился без ошибки. Открывайте /app/ на порту из окна запуска.
ИИ не загружен или HTTP 503	Восстановите модель по разделу «Повторная загрузка модели» ниже и перезапустите сервер.
Дата не принимается	Используйте дату с 23 сентября по 31 декабря 2026 года: только этот период есть в датасете.
Нет подходящих подрядчиков	Это не обязательно ошибка. Проверьте условия и предложенные сервисом альтернативы; для контрольного примера используйте демо-кнопки.

Если ошибка осталась, сохраните последние строки или скриншот окна сервера, а не только страницы браузера: там указана причина.

Что отличает решение

• Смысловой поиск: пожелания вроде «спокойная ненавязчивая подача» влияют на порядок, даже если слова не совпали буквально.
• Условия важнее AI: город, категория, свободная дата, формат, бюджет, язык и длительность остаются жёсткими ограничениями. Высокая смысловая близость не вернёт занятого или слишком дорогого подрядчика.
• Доказательства рядом с ответом: цитата выделена дословно; в «Профиль и факты» можно увидеть её в исходном описании.
• Проверенные альтернативы: при пустом результате показывается конкретное изменение бюджета, даты или других условий и число действительно доступных вариантов. Изменение применяется только по нажатию пользователя.
• Сравнение дат: при изменении только даты интерфейс объясняет, кто из прошлой выдачи стал занят и кто появился благодаря календарю.
• Прозрачный порядок: раскрывающийся блок показывает вклад смысла и бюджета. Баллы не выдаются за вероятность успеха.
• Честные данные: видны флаги синтетического профиля, проставленной цены и города. 13 синтетических профилей уже были в предоставленном датасете; мы не добавляли выдуманных подрядчиков.
• Проверяемость: 31 автоматическая проверка, воспроизводимый диагностический набор и пять готовых демонстраций в интерфейсе.

Что показать жюри

Откройте приложение и последовательно нажмите пять кнопок над формой. Они заполняют форму и отправляют настоящий запрос к API.

1. Спокойный ведущий: три профиля с индивидуальными цитатами, соответствующими пожеланию.
2. Другая дата: календарь меняет выдачу; отдельная плашка объясняет изменения.
3. Редкая категория: два флориста, честное объяснение «почему не три», отметки качества данных.
4. Нет совпадений: при бюджете 100 000 ₸ на 31 декабря появляется проверенное предложение увеличить его до 250 000 ₸. Нажмите предложение — будет найден один профиль.
5. Нет категории: отдельный бизнес-исход, а не ошибка сервера; можно применить доступную альтернативу по городу.

Подробный трёхминутный сценарий — docs/demo.md.

Как устроен поиск

Модель multilingual-e5-small преобразует пожелание и фрагменты описаний в векторы. Используется локальный ONNX int8-экспорт Xenova, закреплённая ревизия 761b726dd34fb83930e26aab4e9ac3899aa1fa78. Индекс содержит 262 дословных фрагмента из 66 профилей, размерность — 384.

После обязательных фильтров профили получают оценку:

смысловой вклад = 85 × clamp((cosine_similarity − 0.65) / 0.30, 0, 1)
вклад бюджета  = 15 × (1 − price_from_kzt / budget)
итог           = смысловой вклад + вклад бюджета

Это фиксированная эвристика ранжирования, а не обученная вероятность. Если пожелание пустое, используется только запас по стартовой цене (100 баллов). Равенство разрешается по цене и затем по id.

Объяснение собирается из полей профиля и точной цитаты, без генеративной LLM. Модель выбирает релевантный фрагмент, но не переписывает его. Подробнее — docs/architecture.md.

API

• GET /health — состояние, число профилей, semantic_ready, версия модели и календарь.
• GET /catalog — города, категории, форматы, языки и счётчики происхождения данных.
• POST /recommend — подбор.
• /docs — интерактивная документация FastAPI.
• /app/ — интерфейс.

Пример тела запроса:

{
  "city": "Алматы",
  "date": "2026-10-15",
  "event_format": "корпоратив",
  "category": "Ведущий",
  "budget": 2000000,
  "duration": 6,
  "language": "русский",
  "preferences": "Спокойная ненавязчивая подача, интеллигентный юмор и уютная атмосфера"
}

language, duration, preferences и compare_date опциональны. Последнее поле — предыдущая дата для сравнения при остальных неизменных условиях. Календарь датасета: 23.09.2026–31.12.2026. Бюджет — целое число от 1 до 1 000 000 000 ₸; длительность — целое от 1 до 24 часов; пожелание — до 600 символов.

HTTP 200 содержит один из трёх бизнес-исходов:

• ok: до трёх элементов results, персональные explanation, точные evidence с позициями в описании, score, флаги данных;
• category_not_found: в выбранном городе нет такой категории;
• no_matches: категория есть, но никто не прошёл все условия.

Дополнительно возвращаются stats, rejected, suggestions, ranking, date_comparison. Счётчики причин относятся только к выбранным городу и категории и могут пересекаться: один профиль может нарушить несколько условий.

Ошибочный запрос — HTTP 422. Если модель отсутствует или не загрузилась, поиск с пожеланием возвращает HTTP 503 с понятным сообщением; простой подбор без пожелания остаётся доступен. Сервис не подменяет AI-поиск незаметной имитацией. Время обработки вынесено в заголовок X-Response-Time-Ms, чтобы тело одинаковых запросов оставалось одинаковым.

Технологии

• Интерфейс: обычные HTML, CSS и JavaScript, без сборки и frontend-фреймворка.
• Сервер: Python, FastAPI, Uvicorn; проверка запросов — Pydantic.
• ИИ-поиск: multilingual-e5-small, ONNX Runtime, Tokenizers и NumPy; вычисления на CPU.
• Хранение: локальный каталог JSON/JSONL и JSON-файл векторного индекса, без отдельной СУБД.
• Проверки: pytest и FastAPI TestClient. Версии прямых зависимостей закреплены в backend/requirements.txt.

Структура

hackathon-contractor-ai/
├── START.cmd, run.py, README.md, pytest.ini, .gitignore, .env.example
├── THIRD_PARTY_NOTICES.md
├── backend/
│   ├── main.py, requirements.txt, download_model.py
│   ├── recommender/
│   │   ├── semantic.py, generate_embeddings.py, config.py
│   │   ├── models.py, data_loader.py, filters.py
│   │   └── ranking.py, explanations.py, alternatives.py
│   ├── data/contractors.jsonl, embeddings.json
│   ├── models/multilingual-e5-small/
│   ├── tests/
│   └── evaluation/queries.json, run_evaluation.py
├── frontend/index.html, style.css, app.js
└── docs/architecture.md, demo.md, evaluation.md, evaluation.json

contractors.jsonl сохранён под исходным именем, но его содержимое — JSON-массив; загрузчик поддерживает и этот формат, и настоящий JSONL. При изменении описаний/категорий индекс пересобирается автоматически по отпечатку данных.

Проверки и измерения

После первого запуска, из корня проекта в PowerShell:

.venv\Scripts\python.exe -B -m pytest backend/tests -q -p no:cacheprovider
.venv\Scripts\python.exe backend/evaluation/run_evaluation.py

В этой поставке 31 тест прошёл: фильтры, занятость, три исхода, реальные эмбеддинги, изменение порядка от пожеланий, точность цитат, проверяемость альтернатив, сравнение дат, детерминизм и валидация.

На 12 вручную размеченных диагностических запросах поиск нашёл подходящий профиль в топ-3 в 12 случаях; простое совпадение слов — в 6. Это небольшой подобранный smoke-набор, не независимый бенчмарк и не заявление о 100% качестве. Числа и методика: docs/evaluation.md; все запросы и ожидаемые ID доступны для проверки. В отчёте также измерены 20 повторов пяти API-сценариев; это локальный TestClient, включая кэш, не нагрузочный тест.

Ручная проверка включает пять сценариев с живым API, применение альтернативы, модальное окно профиля и мобильную/настольную вёрстку.

Повторная загрузка модели

Полный ZIP уже содержит веса. Если вы клонировали только код, первый запуск загрузит модель из Hugging Face. Для восстановления файлов нужен интернет. После первого запуска проекта откройте PowerShell в его корневой папке и выполните:

.venv\Scripts\python.exe backend/download_model.py
.venv\Scripts\python.exe backend/recommender/generate_embeddings.py

После восстановления остановите работающий сервер через Ctrl+C и снова откройте START.cmd. Параметр semantic_ready по адресу /health должен стать true.

Версия зафиксирована, SHA-256 файлов перечислены в backend/models/multilingual-e5-small/manifest.json. Загрузчик не отправляет датасет или запросы. Уведомления и лицензия — THIRD_PARTY_NOTICES.md.

Честные ограничения

• Это хакатон-прототип, не система бронирования. Доступность означает отсутствие даты в календаре датасета, а не подтверждение живого подрядчика.
• Цены указаны «от», часть проставлена составителями датасета. Попадание в бюджет по стартовой цене не гарантирует итоговую стоимость.
• Пожелание — мягкий сигнал ранжирования. Отрицания, сложные сочетания и субъективные требования модель может понять неточно. Обязательные требования задаются структурированными полями. Цитата не доказывает все пожелания сразу.
• Цитаты подтверждают, что так написано в профиле, но не являются независимой проверкой правдивости профиля. Шаблонные объяснения не добавляют новых фактов.
• Нет новых выдуманных кандидатов, выдуманных рейтингов, отзывов или опыта. Синтетические записи исходного датасета явно помечены.
• Работает на CPU; на другом компьютере время запуска и ответа может отличаться. Промышленная авторизация, лимиты запросов и нагрузочное масштабирование не включены. Сервер по умолчанию слушает только 127.0.0.1.