WindTrace AI — прогнозирование выработки ВЭС

Трек: Энергетика. Кейс: Agentic AI для прогнозирования выработки ВЭС.

1. Задача и пользователи

WindTrace AI помогает оператору ветропарка оценить нормализованную мощность двух ветротурбин на следующие 24–48 часов и увидеть, как прогноз меняется при поступлении нового погодного выпуска. Источники, время данных и допущения видны рядом с результатом.

Прогноз выражается в диапазоне [0, 1], а не в МВт или МВт·ч. В исходных CSV нет фактической выработки за февраль и не определён часовой пояс. Поэтому февральскую точность мы не заявляем, а трактовку времени задаём явно.

2. Что реализовано

• Чтение и аудит двух CSV организаторов: временные метки, повторы, шаг измерений и корректность значений.
• Автоматическое получение архивных прогнозов ECMWF IFS через Open-Meteo Single Runs API с локальным кешем.
• Обучение отдельной эмпирической кривой мощности для каждой турбины на данных не позже выбранного выпуска.
• Почасовой прогноз на 24 или 48 часов и графики обеих турбин.
• Ежедневные исторические выпуски с 31 января по 28 февраля 2026 года: 29 выпусков.
• Сравнение соседних выпусков по общим часам, включая изменение прогнозного ветра и максимальный пересмотр мощности.
• Окна низкой выработки для проверки оператором; автоматические команды управления не отправляются.
• CSV текущего выпуска, паспорт JSON с источниками и допущениями, а также командный экспорт всего периода с контрольными суммами.
• Контроллер наблюдает изменения содержимого локальных CSV и выбранных погодных кешей, автоматически пересчитывает период и сохраняет версии с журналом причин.
• Русские пояснения, явная маркировка синтетического демо и блокировка выгрузки устаревшего результата.
• Подробное объяснение выбранного выпуска по проверяемым фактам: OpenAI или NVIDIA AI по кнопке при наличии ключа, иначе локальный текст.

3. Основной сценарий

1. Оператор выбирает время исторического выпуска по UTC и горизонт 24/48 часов.
2. API проверяет локальные CSV, получает подходящий архивный погодный запуск либо читает его из кеша.
3. Модель каждой турбины использует только доступную к выбранному времени историю, рассчитывает мощность и отмечает окна низкой выработки.
4. Интерфейс показывает прогноз, источники и ограничения. При переходе на следующий день сравниваются совпадающие будущие часы.
5. Оператор может сохранить результат и его метаданные.

Это автоматизированный контур с фиксированной последовательностью действий. Контроллер forecast.agent принимает решения по правилам: новые входы → проверка → расчёт → проверка результата → публикация версии; неизменные входы → пропуск; ошибка → сохранение прошлого результата и повторная попытка. Дополнительный ИИ-помощник объясняет уже рассчитанный результат по собранным сервером фактам. Codex использовался как AI-агент при разработке. LLM не управляет обучением и не меняет числовой прогноз; для основного расчёта ключи OpenAI/NVIDIA не требуются.

4. Технологии и модель

Компонент	Реализация
API и проверка запросов	Python 3.12, FastAPI, Pydantic, Uvicorn
Данные и модель	Pandas, NumPy, tzdata
Интерфейс	React 19, Vite 8, SVG-графики
Погода	Open-Meteo Single Runs API, ECMWF IFS
Необязательное объяснение	OpenAI Responses API (gpt-4.1-mini) или NVIDIA NIM (meta/llama-3.3-70b-instruct) через серверный API
Проверки	pytest, Node.js test runner, oxlint, Vite build

Модель строит медианную нормализованную мощность в интервалах скорости ветра шириной 0,5 м/с с интерполяцией и температурной поправкой как приближением изменения плотности воздуха. При прогнозировании используется ветер на высоте 100 м; высота датчика в CSV неизвестна. Это обучаемая базовая модель, а не полноценная физическая модель турбины. GPU не нужен.

5. Архитектура

React / Vite
    -> POST /api/forecast/run или /api/forecast/rolling
    -> FastAPI: проверка запроса и аудит CSV
    -> forecast.service: получение архивной погоды + модель каждой турбины
    -> анализ окон низкой выработки / сравнение выпусков
    -> JSON -> графики, пояснения, CSV и паспорт результата

Путь	Назначение
backend/app.py, backend/schemas.py	HTTP API и схемы
backend/explanation.py	Факты для объяснения, локальный текст и необязательный вызов OpenAI или NVIDIA
backend/data.py, backend/weather.py	Аудит CSV, архивная погода и кеш
forecast/power_curve.py	Обучение и прогноз нормализованной мощности
forecast/service.py, forecast/insights.py	Выпуски, пересчёт и операторский анализ
forecast/agent.py	Наблюдение за входами, автоматический пересчёт, журнал и версии результатов
forecast/validation.py, forecast/export.py	Январская диагностика и экспорт периода
frontend/	Интерфейс, проверка ответа и выгрузка текущего выпуска
tests/, frontend/src/*.test.js	Автоматические проверки

Контракт: docs/api-contract.md. Подробнее о передаче данных: ML handoff. Владение компонентами команды: AGENTS.md.

6. Данные и внешние сервисы

Скачайте выданные организаторами файлы и разместите их локально:

Файл организаторов	Путь в проекте
Турбина 1	data/input/turbine-1.csv
Турбина 2	data/input/turbine-2.csv

Если Drive запрашивает доступ, его предоставляет организатор. CSV не включены в Git: без них доступны синтетическое демо и автоматические тесты, но не расчёт по данным организаторов. История содержит десятиминутные измерения и заканчивается 31 января 2026 года, 23:50 по неопределённому времени CSV.

Погодный клиент обращается к single-runs-api.open-meteo.com за прогнозами, а не за фактической погодой или реанализом. Выбирается запуск, инициализированный минимум за 12 часов до времени выпуска. Это допущение о запасе доступности, а не подтверждение фактического времени публикации. В ответ сохраняются источник, модель, запуск и время действия прогноза.

Первое получение отсутствующих погодных запусков требует интернета; ответы кешируются в data/cache/weather/. Полный период требует больше запросов, чем один выпуск. Ошибки или ограничения внешнего сервиса могут помешать расчёту.

Исходные CSV, кеш, .env, ключи и outputs/ исключены из Git. Ключи нельзя публиковать. Необязательные подготовительные ноутбуки находятся в notebooks/legacy; они не используются для рабочего прогноза.

В submission/ включены готовые прогнозы для двух сценариев времени CSV и их паспорта. Это производные прогнозы, не исходные измерения. Их можно проверить без зависимостей и доступа к погодному API: python submission/verify.py. Эти файлы сохраняют версию ранее выполненного расчёта и не обновляются автоматически при изменении кода.

7. Установка и запуск

Проверенный локальный вариант: Windows, Python 3.12, Node.js 22.12+ из ветки 22. Все команды ниже выполняются в PowerShell из корня репозитория.

git clone https://github.com/BAITC-Hacks/hack-97280b7c-zhubanov-team.git
cd hack-97280b7c-zhubanov-team
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
npm --prefix frontend ci

Поместите два CSV по путям из раздела выше, затем:

.\start_hackalem.ps1 -SourceTimezone UTC

Откройте http://127.0.0.1:5173, выберите Backend API и нажмите «Пересчитать прогноз». Пока успешного запроса нет, интерфейс показывает явно помеченное синтетическое демо.

Запускатор проверяет зависимости и файлы, запускает API на порту 8000 и Vite с локальным прокси на порту 5173. Остановка — Ctrl+C; в командном окне может потребоваться подтвердить завершение npm. Логи API: outputs/backend.stdout.log и outputs/backend.stderr.log.

Полезные варианты:

# Проверить предпосылки, не запуская серверы:
.\start_hackalem.ps1 -SourceTimezone UTC -CheckOnly
# Другой сценарий неопределённого времени CSV:
.\start_hackalem.ps1 -SourceTimezone Asia/Almaty
# Своя папка CSV или свободные порты:
.\start_hackalem.ps1 -DataDir 'C:\path\to\csv' -ApiPort 8001 -UiPort 5174

UTC и Asia/Almaty — сценарии, а не подтверждённый часовой пояс. Не запускайте второй экземпляр на уже занятом порту. Дополнительная инструкция: INSTALL.md.

Подробное объяснение с ИИ

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

Чтобы включить OpenAI, сохраните секрет локально в .env в корне проекта:

OPENAI_API_KEY=<ваш ключ OpenAI>

Также можно задать OPENAI_API_KEY в окружении процесса перед запуском. Если обоих ключей нет, появится помеченное локальное объяснение. При наличии обоих ключей выбирается OpenAI; если ключа OpenAI нет, используется NVIDIA. При ошибке выбранного сервиса показывается локальное объяснение без скрытого переключения на другой платный API. Ключ не добавляйте в Git и не вставляйте в браузер. Вызов происходит только по нажатию кнопки и расходует API-кредиты. После добавления ключа перезапустите сервер. Формат запроса следует OpenAI Responses API; для NVIDIA используется NIM API.

Текст модели может ошибаться: интерфейс показывает источник ответа, а числовой прогноз и исходные временные метки остаются в отдельных блоках. ИИ не заявляет февральскую точность, МВт или доказанную публикацию погодного запуска.

Автоматический пересчёт при изменении входов

Запускайте из корня репозитория, в отдельном терминале. Один процесс контроллера должен владеть одной папкой результатов:

# Рассчитать все 29 выпусков, затем проверять входные файлы каждые 60 секунд:
.\.venv\Scripts\python.exe -m forecast.agent --source-timezone UTC --watch
# Один расчёт без постоянного наблюдения:
.\.venv\Scripts\python.exe -m forecast.agent --source-timezone UTC --output-dir outputs/agent-once

Контроллер проверяет SHA-256 двух CSV и погодных файлов выбранных исторических запусков. При первом запуске отсутствующая погода скачивается обычным сервисом. Изменение содержимого запускает аудит, повторное обучение/прогноз, анализ и экспорт всего выбранного периода. Неизменные файлы повторный расчёт не вызывают. Если данные изменились во время расчёта или проверка не прошла, новая версия не публикуется; в режиме наблюдения попытка повторяется на следующей проверке.

• outputs/agent/events.jsonl — фактические события проверки, расчёта, публикации или ошибки.
• outputs/agent/latest.json — указатель на последнюю успешно опубликованную версию, причина пересчёта, хеши входов и величина пересмотра прогноза.
• outputs/agent/<revision_id>/ — полный JSON, CSV с паспортом и описание версии; прежние версии сохраняются.

Остановка — Ctrl+C. Для ограниченного прогона добавьте --max-checks 3 --poll-seconds 2 --watch. Период меняется через --first-issue-date, --last-issue-date, горизонт — через --horizon-hours; CSV — через --data-dir. При перезапуске контроллер выполняет новый начальный расчёт.

Это наблюдение за локальными историческими входами, а не фоновая подписка на новые выпуски онлайн-погоды. Даты исторического воспроизведения фиксированы настройками; соседние дни автоматически рассчитываются внутри каждого прогона. Позднее исправление CSV/кеша создаёт новую версию воспроизведения, но не доказывает, что исправленные данные были доступны в прошлом. Интерфейс работает через отдельный API и не читает latest.json; после обновления входов в интерфейсе нужен новый запрос. Подробная проверка: docs/agent-verification.md.

Для просмотра только синтетического интерфейса без CSV и API:

npm --prefix frontend run dev -- --host 127.0.0.1

Ручной запуск API

$env:SOURCE_TIMEZONE = 'UTC'
$env:DATA_DIR = 'data/input'
.\.venv\Scripts\python.exe -m uvicorn backend.app:app --host 127.0.0.1 --port 8000

В другом терминале из корня проекта запустите npm --prefix frontend run dev -- --host 127.0.0.1. По умолчанию Vite перенаправляет /api на порт 8000. Кросс-доменный production-деплой требует отдельной настройки; этот запуск предназначен для локальной проверки.

8. Как жюри проверить решение

1. Запустите приложение с CSV, выберите Backend API, выпуск 31.01.2026 12:00 UTC, горизонт 48 ч.
2. Нажмите «Пересчитать прогноз». Ожидаются две серии по 48 точек в [0, 1], источник Open-Meteo и погодная модель ecmwf_ifs.
3. Проверьте блок «Как получен прогноз»: он показывает метаданные результата, а не имитацию живого журнала выполнения.
4. Нажмите «Следующий». Для 1 февраля появится новый выпуск и сравнение по 24 общим часам каждой турбины. Сравнение не является оценкой точности.
5. Нажмите «Объяснить этот выпуск»: без API-ключа появится подробное локальное объяснение с явной пометкой; с рабочим ключом — текст модели OpenAI или NVIDIA по тем же фактам. Числа прогноза и паспорт не изменяются.
6. Нажмите «Скачать CSV» или «Паспорт JSON». CSV одного 48-часового выпуска содержит 96 строк. Если встроенный браузер не сохраняет файл, раскройте «Показать содержимое файла» и скопируйте текст.
7. Смените горизонт на 24 ч: до пересчёта выгрузка и объяснение блокируются. После успешного пересчёта каждая турбина должна иметь 24 точки.

Можно проверить API без интерфейса в отдельном терминале:

Invoke-RestMethod http://127.0.0.1:8000/health
Invoke-RestMethod http://127.0.0.1:8000/api/forecast/run `
  -Method Post -ContentType 'application/json' `
  -Body '{"issue_time_utc":"2026-01-31T12:00:00Z","horizon_hours":48}'

/health подтверждает работу процесса; наличие и качество CSV проверяются при запросе прогноза.

Полный период и выгрузка

.\.venv\Scripts\python.exe -m forecast.service --source-timezone UTC --output outputs/rolling-utc.json
.\.venv\Scripts\python.exe -m forecast.export --input outputs/rolling-utc.json --output-dir outputs/monthly-utc

Ожидаются 29 выпусков, 2 784 строки прогноза и 28 сравнений соседних выпусков. Горизонты перекрываются: это не 2 784 различных календарных часа. Экспорт создаёт forecasts.csv и manifest.json с метаданными и SHA-256. Каталог экспорта должен быть новым. Сам экспорт не обучает модель и не обращается к сети; поле exporter_git_revision относится к версии экспортера, не обязательно к генератору исходного JSON.

Для сценария Asia/Almaty повторите генерацию с другим --source-timezone и отдельными именами файлов/папок. Данные за февраль в результате — прогнозы, не фактическая выработка.

Автоматические проверки

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q
npm --prefix frontend test
npm --prefix frontend run lint
npm --prefix frontend run build

Проверки используют синтетические данные, не требуют закрытых CSV или API-ключей. Интеграционный тест проверяет 29 выпусков через API и модель. Тесты контроллера проходят через настоящие модель, сервис и экспорт: проверяют изменение CSV/погоды, отсутствие лишнего пересчёта, повтор после ошибки и сохранение прошлого результата. Актуальные результаты проверки этой доработки приведены в docs/agent-verification.md.

Workflow GitHub Actions настроен на те же проверки, но на 23.09.2026 задания не запускались из-за блокировки оплаты аккаунта владельца репозитория. Это не успешный CI-прогон; восстановление требует действий администратора организации.

9. Проверка модели

Отчёт проверки модели содержит исследовательскую январскую диагностику по 10 временам выпуска и 960 часам двух турбин. Метрика MAE измеряется в нормализованной мощности:

Сценарий времени CSV	Модель: MAE	Простой прогноз по последним 6 часам: MAE
Asia/Almaty	0,173	0,337
UTC	0,206	0,295

Это зависимые от допущения результаты разработки, а не независимый benchmark или официальный балл. Выбирать часовой пояс по меньшей ошибке нельзя. Воспроизведение требует CSV и архивной погоды:

.\.venv\Scripts\python.exe -m forecast.validation --source-timezone UTC --schedule broad
.\.venv\Scripts\python.exe -m forecast.validation --source-timezone Asia/Almaty --schedule broad

10. Ограничения

• Февральских фактических значений мощности нет: февральская ошибка не измерена.
• Временная зона CSV неизвестна. Неоднозначные локальные времена исключаются; подробности — аудит данных.
• Фактическое время публикации архивной погоды не проверено; используется 12-часовой запас относительно инициализации модели.
• Высота датчика ветра, давление и номинальные мощности турбин неизвестны. Ветер 100 м и температурная поправка — приближения; МВт/МВт·ч и денежный эффект не рассчитываются.
• Январские даты использовались при разработке. Диагностика не подтверждает качество на неизвестных данных.
• Интерфейс показывает точечный прогноз; калиброванные интервалы неопределённости не реализованы.
• Низкая выработка и эквивалентные часы полной нагрузки — информационные показатели сценария, а не команды диспетчеризации.
• Нет автономного управления турбинами, фонового промышленного планировщика, учётных записей и промышленного мониторинга.
• CSV и погодный кеш остаются локально; для проверки другим человеком их нужно подготовить отдельно.

11. Развёрнутая версия и материалы

Публичная развёрнутая версия в репозитории не указана. http://127.0.0.1:5173 — адрес локального запуска, не ссылка для удалённого доступа жюри.

• Соответствие кейсу
• Данные и аудит
• Модель и диагностика
• Готовые месячные прогнозы для жюри
• Проверка автоматического пересчёта
• Контракт API
• Сценарий демонстрации пересчёта
• Инструкция организаторов по сдаче

По инструкции организаторов итоговый код отправляется в выданный репозиторий команды, затем на странице выбранного кейса нажимается «Сдать решение» и заполняются название и описание. Обновлять решение можно до дедлайна хакатона. Обновление GitHub само по себе не подтверждает отправку формы на платформе.