AI-Dostar

Закупка начинается с понимания спроса

Большая продажа может оказаться разовым проектом. Низкие продажи — следствием пустого склада. Сезонный рост легко перепутать с постоянным, а уже заказанный товар — не учесть в новой закупке.

AI-Dostar превращает Excel-выгрузки в проверяемую рекомендацию: выделяет регулярный спрос, оценивает влияние дефицита, строит прогноз и рассчитывает заказ с учётом склада, поставок в пути и кратности упаковки. Менеджер видит факторы расчёта, вносит правки и утверждает итог.

Рекомендация → объяснение → решение менеджера → файл заказа. Отправка поставщику остаётся за человеком.

На реальных данных партнёра

Дата расчёта по умолчанию — последняя продажа в наборе, 22 сентября 2026 года. Это историческая выгрузка, не подключение к живому складу.

Шесть экранов, один процесс закупки

В боковой панели настраиваются метод прогноза, сроки поставки, период пересмотра, уровень сервиса, рост категорий и факторы спроса. Новый расчёт запускается кнопкой «Рассчитать».

🤖 «Спросить ассистента» — над всеми вкладками

После расчёта первой на странице стоит панель «Спросить ассистента»: поле для вопроса своими словами, кнопка «Спросить» и готовые примеры-кнопки («Какие позиции IEK заказать в первую очередь и почему?», «Почему по трубе гибкой Ø50 такой большой заказ?», «Дай сводку по заказу Systeme Electric», «Что сделать с этим заказом?», «Какие товары выходят из ассортимента…»). ChatGPT понимает вопрос и выбирает намерение и фильтр по строгой JSON-схеме; ответ и все количества формирует приложение из текущего расчёта — модель не пишет чисел. Под ответом — источник и таблица строк заказа, на которых он основан. После правки количества или пересчёта старый ответ скрывается. Без ключа вопрос разбирается по правилам.

«Покажи критичные УЗО у IEK, где был дефицит» — ассистент превращает запрос в фильтр по рассчитанному заказу. Кандидаты «старая модель → новая» остаются гипотезами для проверки: похожее название не подтверждает замену. Методика ассистента.

Версии (docs/RELEASE.md): v1.1.0 — рабочая версия (запуск через Docker, панель «Спросить ассистента» над вкладками, ответы ассистента из данных расчёта, ML-ноутбук, наглядный ML-гайд и отчёт о проверке системы). v1.0.0 — первая готовая версия.

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

🐳 Docker — рекомендуемый способ

Нужны только Git и Docker (Docker Desktop на Windows/macOS или Docker Engine + Compose v2.24+ на Linux). Python ставить не нужно.

git clone https://github.com/BAITC-Hacks/hack-1404e13c-ai-dostar.git
cd hack-1404e13c-ai-dostar
docker compose up --build

Откройте localhost:8501 и нажмите «Рассчитать». Первая сборка занимает несколько минут: в образ ставятся зависимости, из datasets/ собираются таблицы и обучается ML-модель. Следующие запуски — docker compose up (сразу), остановка — Ctrl+C или docker compose down.

Нужно ~3 ГБ свободного места на диске для образа.

Без Docker · Python 3.12+

Команды выполняются из корня репозитория; OpenAI API-ключ для расчёта и интерфейса не требуется.

Windows · PowerShell

git clone https://github.com/BAITC-Hacks/hack-1404e13c-ai-dostar.git
cd hack-1404e13c-ai-dostar
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe -m app.adapters.build --raw datasets
.venv\Scripts\python.exe -m streamlit run app/ui/app.py

Откройте localhost:8501 и нажмите «Рассчитать». Статистический метод доступен сразу после сборки данных.

git clone https://github.com/BAITC-Hacks/hack-1404e13c-ai-dostar.git
cd hack-1404e13c-ai-dostar
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m app.adapters.build --raw datasets
.venv/bin/python -m streamlit run app/ui/app.py

Исходные книги лежат в datasets/IEK и datasets/Systeme electric. Сборка создаёт восемь таблиц Parquet в data/clean/. Рабочий интерфейс использует реальные данные; при отсутствии таблиц показывает инструкцию по сборке. Для собственных распакованных архивов можно указать --raw data/raw.

Деплой в интернет

Streamlit Community Cloud — ссылка для демонстрации

Понадобятся GitHub-аккаунт с доступом к этому репозиторию и Streamlit Community Cloud. Публикуйте ветку main (или тег рабочей версии v1.1.0).

1. Подготовьте стартовый файл. Облако устанавливает requirements.txt, но не выполняет команду сборки Excel автоматически. data/clean/ и data/models/ исключены из Git, поэтому одного запуска app/ui/app.py на чистом сервере недостаточно.

Создайте streamlit_app.py в корне репозитория со следующим содержимым. Это пример для добавления перед деплоем; готового файла в текущей версии нет.

import os
import runpy
import subprocess
import sys
from pathlib import Path

import streamlit as st

ROOT = Path(__file__).resolve().parent


@st.cache_resource(show_spinner="Подготовка данных для демонстрации…")
def prepare(build_ml: bool):
    subprocess.run(
        [sys.executable, "-m", "app.adapters.build", "--raw", "datasets"],
        cwd=ROOT, check=True,
    )
    if build_ml:
        subprocess.run(
            [sys.executable, "-m", "app.ml.train"], cwd=ROOT, check=True,
        )
    return True


prepare(os.environ.get("BUILD_ML", "0") == "1")
runpy.run_path(str(ROOT / "app/ui/app.py"), run_name="__main__")

Подготовка кешируется между сессиями и повторными запусками страницы в одном процессе. После перезапуска сервера данные собираются заново. При обновлении Excel в datasets/ перезагрузите приложение через Reboot, чтобы очистить кеш подготовки.

Проверьте запуск локально и отправьте новый файл в ветку деплоя:

.venv\Scripts\python.exe -m streamlit run streamlit_app.py
# После проверки остановите сервер сочетанием Ctrl+C.
git add streamlit_app.py
git commit -m "deploy: add Streamlit Cloud entrypoint"
git push origin main

2. Создайте приложение. В Community Cloud нажмите Create app, подключите GitHub и заполните:

При необходимости предоставьте Streamlit доступ к репозиторию организации. После Deploy сервис выдаст HTTPS-ссылку вида https://<выбранное-имя>.streamlit.app. Подробности полей — в официальной инструкции Streamlit.

3. Настройте ИИ и ML. Для первого запуска достаточно статистического метода без API-ключа. В Advanced settings → Secrets можно задать:

COPILOT_ENABLED = "0"
BUILD_ML = "0"

Чтобы включить ИИ, замените настройки на следующие и подставьте свой ключ непосредственно в панели облака:

OPENAI_API_KEY = "ваш-ключ"
OPENAI_MODEL = "gpt-4o-mini"
COPILOT_ENABLED = "1"
BUILD_ML = "0"

Параметры задаются на верхнем уровне TOML, без секции [openai]: приложение читает переменные окружения, а Streamlit экспортирует в них корневые значения Secrets. Не добавляйте ключ в стартовый файл или Git. См. управление секретами Streamlit.

Для ML установите BUILD_ML = "1" и перезагрузите приложение. Стартовый файл обучит модель в том же окружении и на тех же таблицах, где она будет использоваться. Обучение увеличивает время старта и потребление ресурсов; после перезапуска процесса оно повторяется. Если облако завершает процесс из-за нехватки памяти, верните BUILD_ML = "0" и используйте статистический метод либо сервер с большими ресурсами. При BUILD_ML = "0" выбирайте статистику: наличие актуальной ML-модели не гарантируется.

4. Проверьте опубликованную версию. Откройте ссылку, нажмите «Рассчитать», проверьте вкладки «Товар» и «Ассистент», затем утверждение и скачивание тестового заказа. Ошибки установки, чтения Excel и обучения смотрите в логах приложения. Изменения опубликованной ветки подхватываются облаком; после обновления данных делайте Reboot.

Данные и сохранение заказов на сервере

Текущая версия рассчитана на совместное демо: авторизации и разделения заказов по пользователям нет, файл data/state/approvals.json общий для посетителей одного экземпляра приложения. Выбирайте доступ к приложению с учётом того, кому можно видеть выгрузки и менять утверждения.

Не используйте локальный диск Community Cloud как единственное хранилище утверждений: сохраняйте экспортированные заказы отдельно. Для постоянной работы нужны контроль доступа и устойчивое хранилище состояния. На собственном сервере сохраняйте data/state/ на постоянном диске и запускайте один экземпляр приложения, пока состояние хранится в JSON.

Два метода прогноза

Обучить ML-модель

Наглядный разбор: как модель учится на CPU, графики, узлы деревьев и Gym · Jupyter notebook · готовая HTML-страница.

.venv\Scripts\python.exe -m app.ml.train

В Docker модель обучается автоматически при сборке образа (TRAIN_ML=1 по умолчанию). Выберите «Метод прогноза → ML — обученный бустинг», затем «Рассчитать». Обучение — отдельный шаг; оно не требуется для статистического режима.

Артефакты сохраняются локально в data/models/. После изменения данных или версии scikit-learn модель нужно переобучить. Для горизонта дальше третьего месяца используется явно отмеченный статистический прогноз. Семь сценариев отключения факторов относятся к статистическому методу.

Измеренный результат

В сохранённом эксперименте модель обучена по август 2026 года: 86 094 примера, 2 523 товара. По отчёту эксперимента, средняя нормированная абсолютная ошибка на 20 507 проверочных примерах снизилась:

Это снижение ошибки, а не процент точности. Метрика нормирует ошибку на предыдущий средний объём каждого товара. Проверочные горизонты частично пересекаются; результат не является независимым внешним испытанием. По объёмно-взвешенной метрике WAPE группа IEK / штуки ухудшилась: 33,72% → 35,93%. Поэтому улучшение не заявляется для каждого товара. Процедура и ограничения — в методике ML.

Как получается заказ

flowchart LR
    A["Excel партнёра"] --> B["Адаптеры · 8 таблиц"]
    B --> C["Разовые продажи и дефицит"]
    C --> D{"Метод прогноза"}
    D --> E["Сезонность и тренд"]
    D --> F["Обученный бустинг"]
    E --> G["Запас · склад · в пути · кратность"]
    F --> G
    G --> H["Проверка менеджера"]
    H --> I["Утверждённый XLSX / CSV"]

Горизонт = срок поставки + период пересмотра
Потребность = прогноз на горизонт + страховой запас
Заказ = max(0, потребность − свободный остаток − поставки в пределах горизонта)
Итоговая рекомендация округляется вверх до кратности поставщика.

Покажите ценность за три минуты

Числа приведены для контрольного статистического расчёта на 22.09.2026 с параметрами по умолчанию; при смене метода или параметров результат изменится. Последовательность экранов и тайминг — в сценарии демонстрации.

Решение остаётся у менеджера

1. Проверить рекомендации и предупреждения по данным.
2. Изменить количество при необходимости — с обязательной причиной. Нулевое количество сохраняется как исключение из заказа.
3. Утвердить весь заказ выбранного поставщика, включая скрытые фильтрами строки.
4. Скачать XLSX или CSV с кодом 1С, артикулом, количеством, складом и обоснованием.

Экспорт включает только утверждённые положительные строки и перечитывает состояние при скачивании. Изменённый расчёт требует нового утверждения. Причина менеджера попадает в файл; значения, похожие на Excel-формулы, экранируются.

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

ИИ-объяснения без самостоятельного изменения чисел

Copilot объясняет готовый расчёт и делает сводку по итоговым количествам менеджера. Он не прогнозирует спрос и не утверждает заказ: модель выбирает идентификаторы фактов, а приложение формирует предложения из проверенного каталога. В «Спросить ассистента» модель только понимает вопрос и выбирает данные, ответ собирает приложение. Произвольный текст модели с числами не показывается нигде. Без ключа, при ошибке API или неполных данных используется шаблон.

Для включения скопируйте .env.example в .env и заполните OPENAI_API_KEY (в Docker файл подхватывается docker compose up автоматически). Настройка OPENAI_MODEL задаёт текстовую модель; текущий вариант по умолчанию в коде — gpt-4o-mini. COPILOT_ENABLED=0 включает постоянный шаблонный режим. Ключи не коммитятся.

Проверка и воспроизводимость

После подготовки данных:

.venv\Scripts\python.exe -m pytest -q

Проверки на реальных данных требуют data/clean; без него часть тестов пропускается. Тесты утверждений используют изолированные временные файлы. Результаты обучения — в ml-evaluation.json; история проверок команды — в team-memory.md.

Границы текущего MVP

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

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

app/
├── adapters/          Excel → таблицы единого контракта
├── engine/            Разовые продажи, спрос, прогноз и пополнение
├── ml/                Обучение и применение бустинга
├── ui/                Streamlit и сохранение утверждений
├── copilot.py         Объяснения на проверенных фактах
├── assistant.py       Поиск и рекомендации по заказу
├── export.py          XLSX / CSV
├── pipeline.py        Единый запуск расчёта
└── schema.py          Контракты и параметры
datasets/              Исходные данные партнёра (Excel + CSV-копии)
docs/                  Методики, демо, проверки и память команды
notebooks/             Разбор ML-модели (ipynb + HTML)
scripts/               Проверка системы, браузерный прогон, xlsx → csv
tests/                 Модульные и интеграционные проверки
Dockerfile             Образ: зависимости, сборка данных, обучение ML
docker-compose.yml     Запуск: docker compose up --build

data/clean/, data/models/, data/state/ и .env — локальные данные и настройки, исключённые из Git. CSV-копии в datasets/*_CSV вспомогательные: pipeline читает исходные Excel.

Полная проверка системы одной командой: python scripts/verify_real_system.py (пересобирает таблицы, переобучает ML, сверяет прогнозы, утверждение и экспорт в изолированном хранилище).