ALT Energy — почасовой прогноз мощности ветровых турбин

ALT Energy — веб-приложение, созданное для HackAlem AI на выданных организаторами датасетах. Оно строит прогноз нормализованной активной мощности двух ветровых турбин на 24 или 48 часов с шагом один час. Пользователь задаёт турбину, момент исторического запуска и горизонт вручную или текстом через ИИ. Система применяет обученную модель к архивному прогнозу ветра и показывает результат вместе с происхождением погоды и версией модели.

Быстрый пример: турбина 1, запуск 2026-02-01T12:00:00Z, горизонт 48 часов. Обученные модели и необходимый погодный кэш уже включены в репозиторий; для первого ручного расчёта переобучение и ключ OpenAI не нужны. Февральский replay содержит 116 сценариев: 29 ежедневных запусков в 12:00 UTC с 31 января по 28 февраля, две турбины и два горизонта.

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

• Два режима ввода: «Вручную» и «Спросить ИИ», с выбором турбины и горизонта в обоих режимах. ИИ разбирает текстовую дату и параметры, после чего интерфейс запускает обычное прогнозное ядро; неоднозначный ввод требует уточнения.
• Интерфейс на русском, казахском и английском с сохранением выбранного языка.
• Интерактивный график с выбором часа, почасовая таблица, минимум, среднее и максимум прогнозной мощности; отдельное окно со сведениями об исходных CSV и пропусках.
• Подготовка десятиминутных наблюдений в часовые ряды, обучение отдельной кривой мощности для каждой турбины и выбор версии модели без использования будущих наблюдений.
• Получение архивного погодного выпуска ECMWF IFS, проверка его расчётной доступности к моменту запуска и вывод происхождения погоды вместе с прогнозом.
• HTTP API с валидацией запроса и результата, сохранением успешных запусков в SQLite, февральский replay на 116 запусков и последовательная проверка на декабре–январе.
• Воспроизводимый эксперимент с расширенными погодными признаками. Экспериментальная модель пока не подключена к API.

Технологии и архитектура

Frontend: React 19, TypeScript 5.8, Vite 8 и Lucide; график реализован на SVG. Backend: Python, FastAPI, Pydantic и Uvicorn; прогнозное ядро также написано на Python. Для хранения запусков используется SQLite — локальный файл, которому не нужен отдельный сервер БД. Совместный локальный запуск выполняется через Docker Compose. Текстовый ввод использует OpenAI Responses API со строгой JSON-схемой. scikit-learn нужен только для отдельного эксперимента. Зависимости указаны в backend/requirements.txt, backend/requirements-test.txt, frontend/package.json и forecasting/requirements-experiment.txt.

Ручной ввод ────────────────────────────→ параметры прогноза
Текст → FastAPI → OpenAI Responses ────→ параметры прогноза
                                                 │
                                         FastAPI /forecast-runs
                                                 │
                                         forecasting.runner
                                          │             │
                                     модель JSON    архив ECMWF IFS
                                                 │
                                       проверка → SQLite
                                                 │
                                         график и таблица

Папка	Ответственность
backend/	HTTP API, валидация, проверка временных границ, сохранение успешных запусков
frontend/	Выбор параметров, график и таблица почасового прогноза, ошибки
forecasting/	Подготовка часовых рядов, погодный архив, обучение и расчёт модели
data/raw/	Два исходных CSV, выданных организаторами
data/processed/	Часовые ряды, манифест исторических запусков и отчёт проверки
data/weather/	Сохранённые ответы архива погоды
shared/API.md	Формат запросов и ответов между участниками

При текстовом вводе frontend сначала получает проверенные параметры, затем вызывает тот же endpoint прогноза, что и ручная форма. ИИ не генерирует значения мощности. В OpenAI передаются текст пользователя и выбранные параметры; CSV и прогнозные ряды не передаются. Ключ используется только на backend.

Данные и модель

Исходные CSV организаторов сохранены без изменений и содержат десятиминутные наблюдения двух турбин с 11 марта 2023 года по 31 января 2026 года: время, скорость ветра, температуру и нормализованную активную мощность. Февраль 2026 года — период исторического воспроизведения прогнозов; фактических значений мощности за февраль в репозитории нет. Целевая величина находится в диапазоне 0–1 и не является кВт·ч.

Файл	Наблюдений	Пропущенных десятиминутных интервалов
data/raw/turbine_1.csv	142 360	9 992
data/raw/turbine_2.csv	149 499	2 853

Шесть записей HH:00–HH:50 образуют среднее за час, обозначенный концом HH+1:00. Для действующей модели используются сопоставленные примеры ноября 2025 — января 2026, а не весь многолетний CSV. Кривая строится отдельно для каждой турбины по интервалам скорости 0,5 м/с; редкие интервалы сглаживаются к среднему обучающего ряда.

Подготовка данных формирует часовую сетку и сохраняет пропуски. Для обучения используются только полные часы с известной мощностью. Текущая базовая модель — сглаженная зависимость мощности от прогнозной скорости ветра на высоте 100 м. Прогнозы ветра взяты из отдельных архивных запусков ECMWF IFS через Open-Meteo Single Runs; код выбирает выпуск, инициализированный не позже чем за 12 часов до расчёта. Время инициализации модели погоды и расчётный порог доступности отдельно показаны в API, интерфейсе и манифесте. Фактическое время публикации в архиве неизвестно; подробности — в forecasting/README.md.

Исходные метки времени используются как в датасете, без прибавления или вычитания часового пояса. Для соединения с погодой одинаковые календарные даты и часы сопоставляются напрямую с осью API. В моделях и отчётах записано time_alignment.policy = as_provided_no_shift. Это принятое правило обработки предоставленных данных. API принимает явное смещение или Z и возвращает UTC. Первая точка прогноза соответствует часу, заканчивающемуся через час после запуска.

Качество модели

Проверка последовательная: ноябрь → декабрь, ноябрь–декабрь → январь. Целевые часы обучения строго предшествуют проверяемому периоду. MAE — средняя абсолютная ошибка нормализованной мощности; меньше лучше. Значение 0,328 означает отклонение в среднем на 32,8 процентного пункта шкалы 0–1, а не «точность 67,2%».

Модель	Декабрь 2025, MAE	Январь 2026, MAE	Использование
Сглаженная кривая мощности	0,32776	0,28852	Действующая модель API
Бустинг: расширенная погода и производные признаки	0,26998	0,24369	Эксперимент, выбран по декабрю
Бустинг: ветер и временные производные	0,27844	0,22097	Контрольное сравнение

Метрики объединяют обе турбины и горизонты 1–24 и 1–48 часов; часть целевых часов учитывается повторно. Январь уже использовался для анализа проекта и не является новым нетронутым тестом. Расширенный вариант улучшает ошибку относительно действующей модели, но польза именно новых погодных величин нестабильна: в январе контрольный вариант лучше. Эксперимент не заменяет модель приложения.

Подробности: backtest_report.json, аудит прогнозов, эксперимент с архивными признаками. Ошибку за февраль по предоставленным файлам вычислить нельзя.

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

Для локального запуска нужны Python 3.11+ и Node.js версии ^20.19.0 или >=22.12.0. Для контейнерного запуска достаточно Docker с Compose. Интернет нужен для установки зависимостей, режима ИИ и погодных выпусков, которых нет в локальном кэше. Ключ API для реализованного погодного запроса не требуется. Начните с клонирования:

git clone https://github.com/BAITC-Hacks/hack-1f9ed603-alt.git
cd hack-1f9ed603-alt

Локально

В первом терминале, из корня репозитория:

python -m venv .venv
.\.venv\Scripts\python -m pip install -r backend\requirements.txt
# Выполните один раз, если .env ещё не создан:
Copy-Item .env.example .env
# Заполните OPENAI_API_KEY в .env для режима ИИ (ручной режим работает без ключа).
.\.venv\Scripts\python -m uvicorn backend.app.main:app --reload --port 8000 --env-file .env

На macOS/Linux команды первого терминала:

python3 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements.txt
# Выполните один раз, если .env ещё не создан:
cp .env.example .env
.venv/bin/python -m uvicorn backend.app.main:app --reload --port 8000 --env-file .env

Если .env уже существует, сохраните его настройки вместо повторного копирования. Ключ хранится только на backend и не включается в frontend. Во втором терминале, из корня репозитория:

cd frontend
npm ci
npm run dev

Откройте http://localhost:5173. Документация API: http://localhost:8000/docs. Vite проксирует /api к http://localhost:8000.

Настройки окружения

Переменная	Назначение
OPENAI_API_KEY	Серверный ключ для «Спросить ИИ»; ручной режим работает без него
OPENAI_MODEL	По умолчанию gpt-4o-mini; нужен Responses API и поддержка строгой JSON-схемы
DATA_DIR	CSV для сведений о турбинах в API; по умолчанию data/raw
RUNS_DB_PATH	SQLite успешных расчётов; локально backend/runs.sqlite3
VITE_API_PROXY_TARGET	Адрес backend для Vite; локально http://localhost:8000

Backend читает .env через --env-file; Compose передаёт ключ и модель из корневого .env или окружения. Для изменения локального прокси задайте VITE_API_PROXY_TARGET в окружении терминала frontend перед npm run dev: например, $env:VITE_API_PROXY_TARGET="http://localhost:8001" в PowerShell. Корневой .env автоматически процессом Vite не загружается. DATA_DIR не меняет пути обучения и артефактов прогнозного ядра; сохраняйте стандартную структуру проекта. .env исключён из Git и Docker-образов; не используйте префикс VITE_ для секретов.

Docker

Если установлен Docker с Compose, вместо двух локальных серверов выполните из корня репозитория. Для ручного режима .env не обязателен; для ИИ предварительно создайте его из .env.example и заполните ключ:

docker compose up --build

Интерфейс откроется на http://localhost:5173, документация API — на http://localhost:8000/docs. Исходные CSV монтируются в контейнер backend без записи. Сохранённые погодные выпуски монтируются из data/weather/ecmwf_ifs/; новые выпуски backend может добавить в эту папку через внешний API, поэтому для дат вне кэша нужна сеть. Успешные расчёты хранятся в именованном томе runs_data и сохраняются при пересоздании контейнера и обычном docker compose down. Команда docker compose down -v удаляет этот том.

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

Команды Python выполняются из корня в созданном окружении. Если оно не активировано, вместо python используйте .\.venv\Scripts\python.exe на Windows или .venv/bin/python на macOS/Linux.

python -m pip install -r backend/requirements-test.txt
python -m unittest discover -s forecasting/tests -v
python -m unittest discover -s backend/tests -v

Frontend:

cd frontend
npm ci
npm test
npm run build

Для пересоздания моделей и отчётов, из корня:

python -m forecasting.train_baseline
python -m forecasting.replay_february
python -m forecasting.audit

Эти команды перезаписывают генерируемые артефакты и отчёты. Используется локальный погодный кэш; отсутствующие выпуски запрашиваются у Open-Meteo. Для обычного запуска приложения повторное обучение не требуется. Подробности — в forecasting/README.md.

Отдельный эксперимент с расширенной погодой:

python -m pip install -r forecasting/requirements-experiment.txt
python -m forecasting.experiment_features

Эксперимент работает офлайн на выданных CSV и 92 сохранённых погодных запусках, записывает data/processed/feature_experiment.json и не заменяет действующую модель.

Проверить основной сценарий

1. Откройте интерфейс и убедитесь, что отображаются обе турбины и количество наблюдений.
2. Выберите турбину 1, горизонт 48 часов и введите 2026-02-01T12:00:00Z.
3. Нажмите «Построить прогноз». Ожидаемый результат — график и таблица из 48 значений: от 2026-02-01T13:00:00Z до 2026-02-03T12:00:00Z.
4. В блоке «Источник и параметры запуска» проверьте время инициализации погодной модели, расчётный порог её доступности, идентификатор погодного запуска и версию модели.

Для текстового ввода при настроенном ключе откройте «Спросить ИИ», выберите турбину и горизонт и введите «22 февраля 17:00 2026 года». Форма получит 2026-02-22T17:00:00Z, а график и таблица будут построены обычной моделью. Первая точка — 18:00. Если турбина или горизонт указаны в тексте, они заменяют выбранные значения; иначе используются параметры формы. Время без явно указанного пояса не сдвигается. Неполная дата, отсутствующий год или неподдерживаемый горизонт требуют уточнения.

Ручной запрос через API на macOS/Linux:

curl -X POST http://localhost:8000/api/forecast-runs \
  -H "Content-Type: application/json" \
  -d '{"turbine_id":"turbine_1","issued_at":"2026-02-01T12:00:00Z","horizon_hours":48}'

PowerShell:

Invoke-RestMethod http://localhost:8000/api/health
$body = '{"turbine_id":"turbine_1","issued_at":"2026-02-01T12:00:00Z","horizon_hours":48}'
$result = Invoke-RestMethod -Method Post -Uri http://localhost:8000/api/forecast-runs -ContentType 'application/json' -Body $body
$result.points.Count  # 48
$result.points[0]
$result.points[-1]

Успех — HTTP 201, status: completed, уникальный run_id, 48 почасовых точек в диапазоне 0–1 и сохранённый расчёт в SQLite. Полная структура — в shared/API.md.

Endpoint	Назначение
GET /api/health	Проверка доступности процесса API; не полная диагностика зависимостей
GET /api/turbines	Координаты и сводка исходных CSV
POST /api/forecast-runs	Расчёт и сохранение прогноза
POST /api/assistant/forecast-parameters	Разбор текста: ready с параметрами либо clarification с уточнением

Ошибки имеют формат {"error":"сообщение"}. Неверный запрос возвращает 422; отсутствие модуля прогнозного ядра — 501; некорректный ответ ядра/ИИ — 502; недоступные данные, погода, хранилище или сервис ИИ — 503; внутренняя ошибка — 500. Ручной режим не зависит от OpenAI. При ошибке прогноз не подменяется вымышленными значениями.

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

• Прогнозируемая величина — доля нормализованной активной мощности от 0 до 1. Без номинальной мощности турбин её нельзя корректно перевести в кВт или кВт·ч.
• Основной проверенный сценарий — исторические запуски. Для 2026-01-31T12:00:00Z используется отдельная модель, обученная до запуска; с 1 февраля доступна финальная модель. Более ранние даты требуют отдельно обученного артефакта. Постоянного переобучения на текущих наблюдениях нет.
• Февральский replay сохраняет результаты и происхождение погоды в data/processed/february_replay.json. Фактической мощности за февраль в предоставленных файлах нет, поэтому ошибку этих прогнозов здесь оценить нельзя.
• Фактическое историческое время публикации погодного выпуска архив не предоставляет; используется консервативное правило доступности через 12 часов после инициализации.
• Исходные метки CSV используются без сдвига; группировка десятиминутных записей по часам — принятое правило обработки, сохранённое в артефактах.
• Прогноз погоды использует ветер на высоте 100 м. Обе турбины попадают в одну погодную ячейку архива, поэтому локальные различия ветра моделью погоды не разрешаются.
• Модель основана на статистической кривой «скорость ветра → мощность»; редкие экстремальные скорости, остановки и ограничения работы турбины она не воспроизводит надёжно. Результаты аудита — в data/processed/validation_report.json.
• На Windows обнаружен отказ доступа при конкурентном чтении/обновлении погодного кэша: соответствующий тест завершается PermissionError. Ошибка воспроизведена и вне песочницы; общий набор тестов прогнозирования сейчас не полностью проходит.
• Режиму ИИ нужны сеть, действующий серверный ключ и доступный лимит OpenAI. Распознанные параметры показываются пользователю; неполные и неоднозначные запросы требуют уточнения. Это помощник для ввода параметров, а не универсальный чат или управление турбинами.
• В SQLite сохраняются успешные расчёты, но интерфейс истории не реализован. Нет авторизации и ограничения частоты запросов. Compose предназначен для локального запуска и использует Vite dev server.

Развёрнутая версия

Публичный URL приложения в репозитории не указан. Проект запускается локально по инструкции выше.

Отчёт проверки — 23 сентября 2026

При подготовке этой редакции README проверена текущая реализация на Windows с Python 3.13 и Node.js 24.12:

Проверка	Результат
Backend unittest	29 тестов пройдено, включая все 116 сценариев replay через API
Forecasting unittest	27 из 28 пройдено; конкурентный доступ к погодному кэшу завершился PermissionError
npm ci	Зависимости установлены по lock-файлу
npm test	8 тестов пройдено
npm run build	Проверка TypeScript и сборка Vite успешны

Backend-тесты используют настоящее прогнозное ядро, архивную погоду и временную SQLite. Ответ OpenAI подменяется только в автоматических тестах. Docker, браузер и реальный сетевой вызов OpenAI в этой проверке повторно не запускались. Предыдущие проверки команды с реальным OpenAI и браузером описаны в backend/AI_QA.md; более ранняя проверка интеграции — в backend/QA.md.

Использованные материалы

• Условие задачи и исходные CSV предоставлены организаторами HackAlem AI.
• Погодные данные: ECMWF IFS через Open-Meteo Single Runs, условия использования и атрибуции — Open-Meteo Terms.
• OpenAI Responses API используется только для текстового ввода; настройка и поведение описаны в backend/README.md. Реализация задаёт store: false, таймаут 30 секунд и повторно проверяет структурированный ответ.
• Библиотеки перечислены в backend/requirements.txt и frontend/package.json.
• При разработке использовался OpenAI Codex.