Home Assistant光伏预测插件：用XGBoost实现家庭太阳能发电智能预测

基于XGBoost机器学习模型的Home Assistant自定义集成，结合Open-Meteo天气数据，实现家庭光伏发电功率的精准预测与自动化管理

• 原作者/维护者: wolpa29
• 来源平台: GitHub
• 原始标题: homeassistant-pv-forecast-planner
• 原始链接: https://github.com/wolpa29/homeassistant-pv-forecast-planner
• 发布时间: 2026-06-03

随着全球能源转型加速，家庭光伏系统正快速普及。然而，光伏发电受天气影响极大——云层遮挡、降雨、季节变化都会导致发电量剧烈波动。对于希望最大化自用率、优化储能策略的家庭用户而言，准确预测未来发电能力至关重要。

传统光伏预测依赖物理模型，需要复杂的太阳位置计算和大气光学参数。而机器学习模型能够从历史数据中学习天气与发电量的复杂非线性关系，提供更实用的预测结果。本项目将XGBoost预测模型无缝集成到Home Assistant智能家居平台，让普通家庭用户也能享受AI驱动的能源管理。

该项目采用模块化架构，各组件职责清晰分离：

1. 数据获取层 (pv/weather.py)

系统通过Open-Meteo免费API获取天气预报数据，支持多种气象模型（如icon_eu）。获取的数据包括太阳辐射强度、云量、温度、湿度等关键气象参数，这些都是影响光伏发电的核心变量。

2. 物理辅助计算 (pv/physical_model.py)

虽然主要依赖机器学习，但系统仍保留了物理模型计算太阳高度角、方位角等基础参数，作为特征工程的重要输入。这结合了物理模型的可解释性和数据驱动模型的灵活性。

3. 特征工程 (pv/features.py)

将原始气象数据转换为模型可用的特征矩阵，包括时间特征（小时、月份）、太阳几何特征、气象特征的组合变换等。良好的特征工程是预测准确性的关键。

4. 模型推理 (pv/model.py)

加载预训练的XGBoost模型和特征元数据，执行推理计算。XGBoost因其在处理表格数据方面的优异表现、对缺失值的鲁棒性以及可解释性而被选用。

5. 预测协调 (pv/forecast.py)

整合天气数据、特征工程和模型推理，生成最终的功率预测结果。支持配置预测天数和气象模型选择。

6. Home Assistant集成层

• sensor.py: 暴露sensor.pv_forecast_power实体，当前状态显示当前15分钟时段的预测功率（瓦特），完整预测数据存储在forecast属性中
• coordinator.py: 管理预测更新周期
• config_flow.py: 提供图形化配置界面，支持设置地理位置、面板方位角/倾斜角、模型路径等参数
• services.yaml: 定义pv_forecast_planner.update_forecast服务，允许通过自动化触发更新

用户可通过HACS（Home Assistant社区商店）一键安装，或手动复制到custom_components目录。配置时需要提供：

• 模型文件路径（支持用户自定义训练模型）
• 经纬度坐标（用于太阳位置计算）
• 时区设置
• 面板方位角（Azimuth）和倾斜角（Tilt）
• 预测天数
• 备用气象模型选择

这种设计既保证了开箱即用的便利性，又为高级用户保留了充分的自定义空间。

预测数据的价值在于驱动智能决策。以下是典型的自动化场景：

场景一：储能充放电优化

当预测显示下午发电量充足时，系统可在上午电价低谷期提前为电池充电；当预测明日阴雨时，则保留更多电量应对晚间用电高峰。

场景二：高耗能设备调度

洗衣机、洗碗机、电动汽车充电等高耗能设备可自动安排在预测发电高峰期运行，最大化使用自产清洁能源，减少对电网的依赖。

场景三：向电网售电决策

在实行净计量或动态电价的地区，系统可根据预测判断是将余电售回电网更划算，还是存储供自用更经济。

自动化示例配置

alias: 每日早晨更新光伏预测
trigger:
  - platform: time
    at: "06:00:00"
action:
  - service: pv_forecast_planner.update_forecast
mode: single

项目提供了完整的本地测试环境搭建指南，用户可以使用自己的历史发电数据训练专属模型：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 custom_components/pv_forecast_planner/tests.py

这种开放性设计意味着：

• 不同地区、不同气候带的用户可训练适应本地天气模式的模型
• 不同品牌、规格的光伏面板可建立专属预测模型
• 模型可随时间持续学习，适应设备老化带来的性能变化

1. 15分钟粒度预测

相比小时级预测，15分钟粒度能更好捕捉云层快速移动导致的功率波动，对储能系统的充放电控制尤为重要。

2. 多气象模型支持

Open-Meteo提供多种数值天气预报模型，用户可选择最适合所在地区精度的模型，或配置备用模型在主模型不可用时自动切换。

3. 属性存储完整预测

将完整预测序列存储在实体属性而非状态中，既保持了主状态的简洁性，又允许自动化脚本和仪表盘访问未来数小时的预测数据。

4. 服务化更新机制

通过服务调用触发预测更新，而非固定轮询，既节省API调用配额，又允许用户根据需求灵活控制更新时机。