WindFlow AI

Система почасового прогноза мощности двух турбин ВЭС на 24–48 часов по архивным прогнозам погоды.

Доведённый продукт

HackAlem ML Дашборды Энергетика

GitHub

Команда «kokcit» 4💬 0 комментариевс 23 сентября 2026 г.

О проекте

Команда: kokcit
Кейс HackAlem.ai: Энергетика — Самрук-Казына
Стадия: Доведённый продукт

Задача кейса: AI-агент, прогнозирующий выработку ветровой электростанции по погодным данным

Суть

Система почасового прогноза мощности двух турбин ВЭС на 24–48 часов по архивным прогнозам погоды. Включает агентный пайплайн из 7 этапов, дашборд, экспорт в PDF/Excel/CSV и полный прогноз на февраль 2026.

Как устроено

Архивные прогнозы Open-Meteo Previous Runs с фиксированным упреждением 24/48 ч проходят проверку временной сетки. Затем по турбине и горизонту выбирается своя модель (день 1 или день 2), строятся признаки: скорость ветра, температура, изменения погоды внутри горизонта, календарь. Сравнивались HistGradientBoosting, ExtraTrees и ансамбли, конфигурация выбиралась на временной валидации. Будущие фактические показания турбин не используются. FastAPI ставит фоновые задания, результат и журнал этапов пишутся в SQLite, React-дашборд показывает графики, метрики и историю запусков.

Ключевые решения

HistGradientBoosting
ExtraTrees
ансамбли
XGBoost (CUDA, обучение)
отдельные модели на день 1 и день 2
хронологическая валидация
baseline по кривой мощности
7-этапный детерминированный агентный пайплайн
SHA-256 проверка архива погоды

Метрики

Январь 2026, нормированная мощность: T1 ч1–24 MAE 0.146, RMSE 0.201, R² 0.646 (−18.16% MAE к кривой мощности); T1 ч25–48 MAE 0.189, R² 0.484; T2 ч1–24 MAE 0.151, R² 0.634; T2 ч25–48 MAE 0.188, R² 0.478

Особенности

Корректно избегают утечки: берут архивные прогнозы погоды с тем упреждением, какое было на момент выпуска, а не фактическую погоду. Модели обучены отдельно по турбине и дню горизонта. Всё работает офлайн с включёнными моделями и архивом. Пайплайн идемпотентен, есть планировщик ежедневного запуска и выгрузка 672 часов февраля с манифестом и SHA-256. В README есть GIF и видео-демо.

Стек

Python · FastAPI · Pydantic · scikit-learn · XGBoost · pandas · NumPy · joblib · SQLite · ReportLab · OpenPyXL · React · Vite · Recharts · Docker Compose · uv · PowerShell

Проект создан за 5 часов на финале хакатона HackAlem.ai (23 сентября 2026, Астана). Код — BAITC-Hacks/hack-e4239371-kokcit.

README

README.md

WindFlow AI

WindFlow AI — система почасового прогнозирования нормализованной мощности ветроэлектростанции на горизонте 24–48 часов. Она получает архивные прогнозы погоды по координатам турбин, проверяет данные, выбирает ML-модель, формирует прогноз и сохраняет результат вместе с журналом выполнения.

Что решает продукт

Для планирования работы ВЭС важно заранее знать ожидаемую выработку. Ручной расчёт трудно регулярно повторять, а использование фактической будущей погоды даёт некорректную оценку модели. WindFlow AI автоматизирует полный цикл:

получает архивный прогноз погоды с фиксированным упреждением 24/48 часов;
проверяет полноту и корректность почасовых данных;
выбирает модель для нужной турбины и части горизонта;
прогнозирует мощность на следующие 24 или 48 часов;
анализирует результат и сохраняет происхождение данных;
повторяет расчёт при обновлении входных данных;
формирует полный почасовой прогноз за февраль 2026 года.

Dashboard показывает графики мощности и погоды, диапазон ошибки, этапы агента, метрики моделей, историю запусков и почасовую таблицу. PDF предназначен для руководителя, Excel и CSV — для аналитической и статистической работы.

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

Готовые модели windflow-v3 находятся в backend/models/, архив прогнозов погоды — в backend/demo/. Они скачиваются вместе с репозиторием. Для расчёта достаточно CPU: повторное обучение, видеокарта и API-ключи не нужны.

Windows

Требования:

Python 3.11 или новее;
uv;
Node.js 22.12 или новее.

Из корня репозитория:

.\run.ps1

После сборки приложение будет доступно по адресу http://127.0.0.1:8000, документация API — по адресу http://127.0.0.1:8000/docs.

Повторный запуск без переустановки зависимостей:

.\run.ps1 -SkipInstall

Проверка backend-тестов и production-сборки frontend:

.\run.ps1 -SkipInstall -Check

Docker — альтернативный запуск

Если установлен Docker, Python и Node.js на компьютере отдельно не нужны. Один контейнер запускает backend и собранный сайт с готовыми моделями:

docker compose up --build

Приложение откроется на http://localhost:8000. SQLite и кэш погоды сохраняются в именованном Docker-томе.

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

Backend:

cd backend
uv sync --locked
uv run uvicorn app.main:app --reload

Frontend в отдельном терминале:

cd frontend
npm ci
npm run dev

Frontend будет доступен на http://localhost:5173, backend — на http://localhost:8000.

Как проверить решение

После установки зависимостей и запуска приложения этот сценарий работает без интернета: обученные модели и архивы погоды января и февраля включены в репозиторий.

WindFlow AI: расчёт прогноза, полный февраль и PDF-отчёт
Скачать видео в полном качестве · 25 секунд
_{Расчёт прогноза → полный февраль → PDF-отчёт}

1. Расчёт прогноза и журнал агента

Задайте параметры и нажмите «Рассчитать прогноз»:

Параметр	Значение для проверки
Турбина	1 или 2
Дата выпуска	`2026-01-29`
Горизонт	48 часов
Погода	Только сохранённый архив

В журнале должны завершиться семь этапов — от получения погоды до сохранения прогноза. Для каждого этапа видны статус, длительность и результат.

_{Журнал агента и краткий итог сохранённого прогноза. Нажмите на снимок, чтобы открыть его крупнее.}

2. График, почасовые данные и отчёты

Проверьте график мощности и ветра, диапазон ошибки и 48 почасовых значений за 30–31 января. Скачайте PDF, Excel или CSV кнопками над графиком. В боковой панели выберите завершённый запуск, чтобы открыть его из истории.

_{Сохранённый прогноз на 48 часов, почасовые значения и экспорт отчётов.}

3. Проверка качества модели

Откройте вкладку «Проверка качества» и сравните прогноз с фактом и простой кривой мощности. Для каждой турбины доступны MAE, RMSE и R². Горизонт 24 часа показывает оценку первого дня, 48 часов — второго дня прогноза.

_{Турбина 1 · первый день прогноза · проверка на январе 2026 года.}

4. Полный февраль

Нажмите «Февраль · 28 × 24 часа». После завершения ожидаются 28 ежедневных выпусков и 672 уникальных часа за 1–28 февраля 2026 года. Скачайте месячный отчёт и повторите расчёт для второй турбины. Этот сценарий и открытие PDF показаны в видеодемонстрации.

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

cd backend
uv run ruff check app scripts tests
uv run pytest -q

cd ../frontend
npm run build

Тесты проверяют API, модельные артефакты, валидацию данных, журнал этапов, обработку ошибок, идемпотентность и полноту CSV.

Технологии

Компонент	Технологии
Frontend	React, Vite, Recharts, Lucide
Backend	Python, FastAPI, Pydantic
ML	scikit-learn, XGBoost/CUDA для обучения, NumPy inference, pandas, joblib
Данные погоды	Open-Meteo Previous Runs API
Хранение	SQLite, локальный файловый кэш
Отчёты	ReportLab, OpenPyXL
Зависимости	uv, npm
Развёртывание	PowerShell, Docker Compose
Проверки	pytest, Ruff, Vite build

Архитектура

React dashboard
      │
      ▼
FastAPI ──► очередь фоновых заданий ──► Agentic pipeline
                                                │
                    ┌───────────────────────────┼──────────────────────┐
                    ▼                           ▼                      ▼
             Open-Meteo / cache         Проверка данных        Выбор модели
                    │                           │                      │
                    └───────────────────────────┼──────────────────────┘
                                                ▼
                                      Признаки и ML-прогноз
                                                │
                                                ▼
                                  Контроль результата и SQLite
                                                │
                                                ▼
                              Графики, история и PDF / Excel / CSV

Агент последовательно выполняет семь наблюдаемых этапов:

получение архивного прогноза погоды;
проверка временной сетки и значений;
выбор модели по турбине, горизонту и дате;
подготовка признаков;
расчёт мощности;
анализ качества результата;
сохранение прогноза и метаданных.

Для каждого этапа сохраняются статус, время начала и завершения, длительность, описание и технические метаданные. При временной ошибке погодного сервиса запрос повторяется, после чего система может использовать сохранённый архив.

Модели и качество

Мощность представлена в нормализованной шкале от 0 до 1. Признаки включают архивный прогноз скорости ветра и температуры, изменения погоды внутри горизонта и календарные характеристики. Будущие фактические показания турбин при построении прогноза не используются.

Для каждой турбины используются отдельные модели первого и второго дня. Сравниваются HistGradientBoosting, ExtraTrees и ансамбли; конфигурация выбирается на временном validation-периоде.

Результаты хронологической проверки на январе 2026 года:

Турбина и горизонт	Часов	MAE	RMSE	R²	Снижение MAE к wind curve
1, часы 1–24	744	0.146	0.201	0.646	18.16%
1, часы 25–48	720	0.189	0.241	0.484	6.18%
2, часы 1–24	744	0.151	0.204	0.634	15.73%
2, часы 25–48	720	0.188	0.243	0.478	6.62%

MAE и RMSE указаны в нормализованной шкале мощности. R² характеризует качество описания изменений мощности и не является процентом точности. Исходные точки для независимого пересчёта метрик находятся в backend/models/validation_predictions.csv.

Расчёт февраля 2026

Февральский режим воспроизводит 28 ежедневных выпусков и формирует по 672 уникальных почасовых значения для каждой турбины. В репозиторий включён проверенный архив Open-Meteo для обеих точек, поэтому полный расчёт доступен offline. Перед экспортом система проверяет временную сетку, происхождение данных, SHA-256 и отсутствие дубликатов.

Подготовка архива погоды:

cd backend
uv run python -m scripts.prepare_demo

Расчёт и экспорт файлов:

uv run python -m scripts.export_submission --offline

Результаты сохраняются в artifacts/submission/: два CSV-файла, манифест и отчёт с метриками. Команда подготовки нужна только для обновления погодного архива; включённый архив уже позволяет воспроизвести расчёт без интернета.

Для каждого сохранённого прогноза доступны три формата:

PDF — оформленный отчёт с резюме, KPI, графиком и почасовой таблицей;
Excel — листы Summary, Hourly forecast, Agent log, Model metrics и Metadata;
CSV — компактные почасовые данные для статистической обработки.

Ежедневный запуск

Один выпуск прогноза для обеих турбин:

cd backend
uv run python -m scripts.run_daily --issue-date 2026-01-29 --offline

Постоянный режим планировщика:

uv run python -m scripts.run_daily --loop

В Docker планировщик запускается отдельным профилем:

docker compose --profile schedule up --build

API

Метод	Путь	Назначение
`GET`	`/api/health`	Состояние сервиса и моделей
`GET`	`/api/models/metrics`	Метрики моделей
`GET`	`/api/models/validation`	Факт, прогноз и baseline
`POST`	`/api/jobs`	Фоновый прогноз на 24/48 часов
`POST`	`/api/jobs/february`	Расчёт февраля
`GET`	`/api/jobs`	История фоновых заданий
`GET`	`/api/jobs/{job_id}`	Прогресс, этапы и результат
`GET`	`/api/forecasts`	История сохранённых прогнозов
`GET`	`/api/forecasts/{run_id}`	Полный сохранённый прогноз
`GET`	`/api/forecasts/{run_id}/report.pdf`	PDF-отчёт одного прогноза
`GET`	`/api/forecasts/{run_id}/export.xlsx`	Excel одного прогноза
`GET`	`/api/forecasts/{run_id}/export.csv`	CSV одного прогноза
`GET`	`/api/forecasts/february/report.pdf`	PDF полного месяца
`GET`	`/api/forecasts/february/export.xlsx`	Excel полного месяца
`GET`	`/api/forecasts/february/export.csv`	CSV полного месяца

Пример запуска:

{
  "turbine_id": 1,
  "issue_date": "2026-01-29",
  "horizon_hours": 48,
  "data_mode": "offline"
}

Режимы получения погоды:

auto — использовать локальный архив, при отсутствии обратиться к API;
offline — использовать только сохранённые данные;
live — загрузить данные из Open-Meteo.

Переобучение

Исходные CSV передаются скрипту явно и не хранятся в репозитории:

cd backend
uv run python -m scripts.train_models `
  --turbine-1 "C:\data\turbine 1.csv" `
  --turbine-2 "C:\data\turbine 2.csv"

Загруженная история погоды сохраняется в backend/data_cache/. Для повторного обучения с готовым отчётом выбора моделей добавьте --selection-report models/model_selection.json.

Структура репозитория

backend/
  app/                 FastAPI, агент и сервисы
  demo/                архив погоды для offline-запуска
  models/              обученные модели и отчёты
  scripts/             обучение, ежедневный запуск и экспорт
  tests/               автоматические тесты
frontend/
  src/                 React-dashboard
docs/                   технические материалы и проверка решения
Dockerfile              контейнер приложения
compose.yaml            приложение и планировщик
run.ps1                 запуск и проверка на Windows

Конфигурация и безопасность

Приложение не требует API-ключей для Open-Meteo. Настройки можно передать через MODEL_DIR, DATABASE_PATH, DEMO_DIR, WEATHER_CACHE_DIR, WEATHER_TIMEOUT_SECONDS и WEATHER_ATTEMPTS.

Файлы .env, локальная SQLite, кэши, исходные датасеты и результаты запусков исключены из Git. Для локальной настройки задайте нужные переменные окружения в оболочке; API-ключи для запуска не требуются.

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

GitHub

BAITC-Hacks/hack-e4239371-kokcit

Звёзды

⭐ 0

Форки

Язык

Python

Последний push

в прошлом месяце

Коммиты

Авторы

Файлы

Ветки

Авторы коммитов

Darkhan 10

История коммитов

2026-09-23 17:40Embed animated demo preview in READMEDarkhan
2026-09-23 17:32Add illustrated setup guide and sanitized demo videoDarkhan
2026-09-23 17:30Preserve weather archive checksums across platformsDarkhan
2026-09-23 17:09Remove internal handoff and presentation notesDarkhan
2026-09-23 16:57Add readable names for forecast downloadsDarkhan
2026-09-23 16:44Complete February reporting and submission workflowDarkhan
2026-09-23 16:22Promote v3 models and polish project documentationDarkhan
2026-09-23 15:46Harden forecasting pipeline and demo experienceDarkhan

Все коммиты (10)

2026-09-23 14:34Build agentic wind forecasting prototypeDarkhan
2026-09-23 13:37Initialize WindFlow agentic forecasting platformDarkhan

Структура репозитория (84 файлов)

.dockerignore
.gitattributes
.gitignore
Dockerfile
README.md
backend/app/__init__.py
backend/app/agent.py
backend/app/catalog.py
backend/app/config.py
backend/app/jobs.py
backend/app/main.py
backend/app/report_routes.py
backend/app/schemas.py
backend/app/services/__init__.py
backend/app/services/advanced_features.py
backend/app/services/dataset.py
backend/app/services/downloads.py
backend/app/services/evaluation.py
backend/app/services/features.py
backend/app/services/forecast.py
backend/app/services/model.py
backend/app/services/portable_boost.py
backend/app/services/reporting.py
backend/app/services/storage.py
backend/app/services/weather.py
backend/assets/fonts/DejaVuSans-Bold.ttf
backend/assets/fonts/DejaVuSans.ttf
backend/assets/fonts/LICENSE-DejaVu.txt
backend/demo/february_manifest.json
backend/demo/manifest.json
backend/demo/weather_february_turbine_1.csv
backend/demo/weather_february_turbine_2.csv
backend/demo/weather_turbine_1.csv
backend/demo/weather_turbine_2.csv
backend/models/metrics.json
backend/models/metrics_before_v3.json
backend/models/model_selection.json
backend/models/optimization_report.json
backend/models/previous_metrics.json
backend/models/turbine_1_day_1.joblib
backend/models/turbine_1_day_2.joblib
backend/models/turbine_2_day_1.joblib
backend/models/turbine_2_day_2.joblib
backend/models/validation/turbine_1_day_1.joblib
backend/models/validation/turbine_1_day_2.joblib
backend/models/validation/turbine_2_day_1.joblib
backend/models/validation/turbine_2_day_2.joblib
backend/models/validation_predictions.csv
backend/pyproject.toml
backend/scripts/benchmark_gpu.py
backend/scripts/diagnose_signal.py
backend/scripts/experiment_smooth.py
backend/scripts/experiment_xgboost.py
backend/scripts/export_submission.py
backend/scripts/prepare_demo.py
backend/scripts/promote_optimized_models.py
backend/scripts/refresh_metrics.py
backend/scripts/run_daily.py
backend/scripts/train_baseline.py
backend/scripts/train_models.py
backend/tests/conftest.py
backend/tests/test_demo_archive.py
backend/tests/test_forecast_api.py
backend/tests/test_hardening.py
backend/tests/test_optimized_models.py
backend/tests/test_reporting.py
backend/tests/test_storage.py
backend/uv.lock
compose.yaml
docs/DELIVERY.md
docs/FORECAST_PROTOCOL.md
frontend/index.html
frontend/package-lock.json
frontend/package.json
frontend/src/QualityReport.jsx
frontend/src/main.jsx
frontend/src/styles.css
frontend/vite.config.js
images/image.png
images/image1.png
images/image2.png
images/windflow-demo.gif
images/windflow-demo.mp4
run.ps1

Обсуждение 0 комментариев

Войдите, чтобы комментировать

Пока нет комментариев — будьте первым.