GridAgent-Wind — почасовой прогноз выработки ВЭС на 24–48 часов

Проект для хакатона HackAlem AI, трек «Энергетика» (кейс Самрук-Казына).

Система сама берёт архивный прогноз погоды ECMWF IFS по координатам двух ветротурбин. Затем она прогоняет его через локальную ML-модель и выдаёт почасовой прогноз нормализованной мощности на 24 или 48 часов вперёд. LLM-агент в чате только вызывает эти расчёты и объясняет результат, сам он цифры не считает.

---

1. Проблема

Оператор ВЭС заранее подаёт почасовой график выработки. Если факт расходится с графиком, станция платит за небаланс. Ветер плохо предсказуем, поэтому нужен прогноз на сутки–двое, построенный только на тех данных, которые реально были доступны в момент прогноза.

Объект. ВЭС из двух ветроустановок, Алматинская область (Шелекский ветровой коридор).

Турбина	Широта	Долгота
Т1	43.643194	78.538833
Т2	43.645139	78.535611

Т2 стоит примерно в 340 м от Т1, по азимуту ~310° (на северо-запад). При ветре северо-западного или юго-восточного направления одна турбина может оказаться в аэродинамическом следе другой. Отдельно этот эффект не моделируется: в модель подаются направление ветра и номер турбины, так что она может выучить разницу неявно. Это не проверялось.

---

2. Демо

TODO: добавить скриншот или GIF HTML-консоли диспетчера (чат, график и журнал шагов агента).

---

3. SMART-цель

• S — прогнозировать нормализованную активную мощность (0…1 от номинала) двух турбин по часам на 24–48 ч.
• M — на отложенной выборке (январь 2026) модель показала MAE = 0.2468 и RMSE = 0.3004 (в долях номинала).
• A — обучение на SCADA за 11.03.2023–31.01.2026 и архивных прогнозах ECMWF IFS, модель LightGBM.
• R — прогноз нужен оператору ВЭС, чтобы подавать график выработки на следующие сутки.
• T — walk-forward прогноз на 1–28 февраля 2026 строится командой backtest_runner.py. Метрика за февраль будет посчитана после получения факта SCADA за этот период (TODO).

---

4. Архитектура: два контура

Модель и физика — детерминированный Python-код. LLM только вызывает этот код и пересказывает результат.

  SCADA (10 мин, XLSX/CSV)          Open-Meteo ECMWF IFS (1 ч)
            │                                   │
            ▼                                   ▼
┌──────────────────────────────────────────────────────────────┐
│  ДЕТЕРМИНИРОВАННЫЙ КОНТУР  (pandas / NumPy / LightGBM)       │
│  • SCADA → почасовые средние                                 │
│  • погода «на момент выпуска» — без заглядывания в будущее   │
│  • физические признаки (сдвиг ветра, u/v, v³, время суток)   │
│  • LightGBM: прогноз погоды → фактическая мощность           │
│  • ограничения: мощность в [0, 1], 0 при ветре > 25 м/с      │
│  • проверки прогноза по правилам                             │
└───────────────────────────┬──────────────────────────────────┘
                            │ ForecastResult: цифры, шаги, предупреждения
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  АГЕНТНЫЙ КОНТУР  (OpenAI gpt-4o-mini, tool calling)         │
│  run_forecast_cycle · check_weather_update · get_weather_tool│
│  не более 4 раундов вызова инструментов                      │
└───────────────────────────┬──────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  FastAPI + HTML-консоль: чат · график по турбинам · метрики  │
│  журнал шагов агента · «Проверить обновление погоды»         │
└──────────────────────────────────────────────────────────────┘

Один цикл прогноза (src/agents/pipeline.py)

Прогноз, выпущенный в день D в 12:00 UTC, покрывает часы с D+1 00:00 UTC на 24 или 48 ч.

1. context — загрузка модели models/wind_power_lgb.pkl и её метрик.
2. weather — прогноз погоды для каждой турбины, но только из прогонов ECMWF, опубликованных до момента выпуска. Учитывается задержка публикации 7 ч. Источник — Open-Meteo Previous Runs API, модель ecmwf_ifs025. Нет сети — берётся локальный кэш. Если хоть одного часа нет, цикл останавливается с ошибкой и не подставляет выдуманные значения.
3. features — 16 признаков (раздел 5).
4. model — предсказание, ограничения, сохранение в outputs/forecasts/forecast_<дата>_t12_<h>h.csv.
5. validation — проверки по правилам (раздел 6) и сравнение с прогнозом предыдущего дня.

Кнопка «Проверить обновление погоды» заново скачивает погоду и сравнивает хэш входных данных. Если погода изменилась, прогноз пересчитывается и показывается разница с прошлым расчётом.

---

5. Данные, погода и признаки

Защита от утечки будущего

• В прогнозе и бэктесте используются только архивные прогнозы ECMWF IFS, опубликованные до выпуска прогноза. Реанализ ERA5 не используется: он построен на фактических наблюдениях задним числом и в реальном времени недоступен.
• Модель обучается сопоставлять «прогноз погоды → фактическая мощность SCADA», а не «анемометр → мощность». Так она сразу учитывает систематическую ошибку глобальной модели для этой местности (идея Model Output Statistics).

Шаг по времени

SCADA приходит с шагом 10 минут. Данные усредняются до 1 часа (resample("1h").mean() в src/train/build_train_set.py), потому что у ECMWF шаг 1 час.

Признаки (src/tools/feature_tool.py)

Группа	Признаки
Ветер по высотам	wind_speed_10m, wind_speed_80m, wind_speed_100m
Направление	wind_direction_10m, wind_direction_100m, sin/cos направления на 100 м
Сдвиг ветра	delta_v = v100 − v10
Перенос масс	wind_u = −v·sin(θ), wind_v = −v·cos(θ)
Энергия потока	v3 = v100³
Температура	temperature_2m (связана с плотностью воздуха)
Календарь	hour_sin, hour_cos, day_of_year
Турбина	turbine_id (категориальный)

Previous Runs API не отдаёт ветер на 80 м. В прогнозе он восстанавливается из 10 м и 100 м по логарифмическому профилю.

Модель (src/train/train_model.py)

• LightGBM, функция потерь Huber, 700 деревьев, learning rate 0.03, фиксированный seed.
• Обучение: 11.03.2023–31.12.2025, кросс-валидация по времени (TimeSeriesSplit).
• Отложенная выборка: январь 2026 → MAE 0.2468, RMSE 0.3004.
• Сравнения с базовой моделью (например, «сырой» прогноз ветра через кривую мощности) пока нет — TODO.

---

6. Проверки прогноза и ограничения

Все проверки считаются в Python. LLM их только пересказывает.

Проверка	Правило
Ограничение мощности	прогноз обрезается до [0, 1]
shutdown_wind	ветер на 100 м > 25 м/с → мощность = 0 (отключение турбины)
low_wind_high_power	ветер < 3 м/с при мощности > 0.2 — подозрительно
flat_forecast	стандартное отклонение прогноза турбины < 0.01
icing_risk	температура ≤ 0 °C (влажность пока не запрашивается, поэтому это только информация)
divergence_from_previous_issue	средняя разница с прогнозом прошлого дня > 0.15

Пороги подобраны вручную: паспорта турбин у команды нет.

---

7. Быстрый запуск (Windows PowerShell, Python 3.11+)

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m src.train.train_model      # обучение → models/wind_power_lgb.pkl
python -m src.app                     # UI на http://127.0.0.1:7860

• Первое обучение скачивает погоду в data/weather_cache/. Дальше можно обучать без сети: python -m src.train.train_model --offline.
• Прогноз из UI в первый раз тоже требует интернета (Open-Meteo Previous Runs API). После этого погода кэшируется в data/weather_cache/*_previous_runs.parquet.
• Walk-forward бэктест на февраль 2026: python backtest_runner.py → submissions/forecast_february_2026.csv и backtest_report.json.
• LLM-чат: скопируйте .env.example в .env, укажите OPENAI_API_KEY, поставьте MOCK_MODE=false. Без ключа или при MOCK_MODE=true чат отвечает заглушкой, а прогноз по кнопке работает как обычно.

---

8. Тесты

pytest -v

• tests/test_agent_tools.py — инструменты агента, ограничения мощности, порядок «погода → модель».
• tests/test_orchestrator_mock.py — чат в демо-режиме без LLM.
• tests/test_agent_cycle.py — полный цикл прогноза: проверки, обновление погоды, неполная погода.

Сейчас проходят 23 из 24 тестов. test_incomplete_weather_fails_loud ждёт другой текст ошибки (TODO).

---

9. Почему просто

Мы сознательно не даём LLM считать мощность или погоду: языковая модель может выдумать цифру, а оператору нужны воспроизводимые числа. Поэтому весь расчёт — это обычный Python-конвейер из пяти шагов, который работает и без LLM, и его можно проверить тестами. Агент только выбирает один из трёх инструментов и объясняет результат. Модель — один LightGBM на обе турбины, без ансамблей и нейросетей: её легко переобучить за минуты и объяснить судье.

---

10. Известные ограничения

• Обучение использует Open-Meteo Historical Forecast API (ecmwf_ifs), а прогноз — Previous Runs API (ecmwf_ifs025). Источники близкие, но не одинаковые, поэтому ошибка на реальных данных может отличаться от holdout.
• Без интернета и без кэша *_previous_runs.parquet прогноз останавливается на шаге погоды.
• Экономический эффект (сколько экономится на штрафах за небаланс) не считался.

11. Дальше (не реализовано)

• Расчёт стоимости небаланса по тарифам балансирующего рынка РК и рекомендации диспетчеру.
• Явный учёт аэродинамического следа между Т1 и Т2.
• Сценарии для демонстрации (резкий спад ветра, сильный сдвиг ветра).
• Метрика walk-forward за февраль 2026 по факту SCADA.

---

12. Команда

• Alisher — оркестратор и инструменты агента (src/agents/).
• TODO — обучение модели и обработка данных (src/train/).
• TODO — архивная погода и проверка координат (src/tools/weather_tool.py).