general-predictor 0.1.0

General Time Series Forecasting Framework based on Darts

General Predictor

通用时序预测框架，基于Darts库，支持任意时间序列预测任务。

特性

• 通用预测能力：支持销售预测、需求预测、交通流量、电力市场预测等任意时序任务
• 多种模型支持：LightGBM、XGBoost、CatBoost、LinearRegression
• 特征工程：时间特征、滞后特征、滚动统计（内置数据泄露防范）
• 预测模式：支持滚动预测、日前预测、单步预测
• 多时间粒度：15分钟(96点)、30分钟(48点)、1小时(24点)、日度等
• MCP协议支持：可作为MCP Server与Claude等AI助手集成

安装

pip install general-predictor

快速开始

命令行使用

# 启动MCP Server
general-predictor

Python API使用

from general_predictor import TimeSeriesForecaster, ForecastConfig

# 创建配置
config = ForecastConfig(
    data_path='data/power_load.csv',
    target_col='load',
    datetime_col='datetime',
    freq='15min',
    model_type='lightgbm'
)

# 初始化预测器
forecaster = TimeSeriesForecaster(config)

# 加载数据
forecaster.load_data()
df = forecaster.preprocess_data()

# 准备特征
forecaster.prepare_features(df)

# 创建模型
forecaster.create_model()

# 滚动预测（D日预测D+1日）
predictions = forecaster.rolling_forecast(
    test_start_date='2025-12-01',
    test_end_date='2025-12-31'
)

# 评估
metrics = forecaster.evaluate()

# 保存结果
forecaster.save_results('forecast_results.csv')

MCP工具

forecast_rolling - 滚动预测

执行滚动时序预测（日前预测模式：D日预测D+1日）

{
  "tool": "forecast_rolling",
  "arguments": {
    "data_path": "data/power_load.csv",
    "target_col": "load",
    "datetime_col": "datetime",
    "freq": "15min",
    "test_start_date": "2025-12-01",
    "test_end_date": "2025-12-31",
    "model_type": "lightgbm",
    "prediction_mode": "direct",
    "lag_preset": "preset1"
  }
}

forecast_single - 单次预测

训练并预测未来N个时间点

{
  "tool": "forecast_single",
  "arguments": {
    "data_path": "data/sales.csv",
    "target_col": "sales",
    "forecast_horizon": 30,
    "train_ratio": 0.8,
    "model_type": "lightgbm"
  }
}

get_lag_presets_info - 获取滞后预设

获取滞后特征预设配置信息

{
  "tool": "get_lag_presets_info",
  "arguments": {
    "freq": "15min"
  }
}

evaluate_forecast - 评估预测

评估预测结果

{
  "tool": "evaluate_forecast",
  "arguments": {
    "predictions_path": "forecast_results.csv"
  }
}

create_feature_config - 特征配置建议

创建特征工程配置建议

{
  "tool": "create_feature_config",
  "arguments": {
    "scenario": "power_load",
    "freq": "15min"
  }
}

应用场景

电力市场预测

• 光伏功率预测：考虑太阳辐射、云层覆盖
• 风电功率预测：考虑风速、风向
• 系统负荷预测：考虑温度、节假日
• 日前/实时电价预测：考虑供需关系

商业预测

• 销售预测：考虑促销、季节性
• 需求预测：考虑趋势、周期
• 库存预测：考虑补货周期

交通预测

• 道路流量预测：考虑早晚高峰
• 网络流量预测：考虑用户行为

数据泄露防范

本框架内置数据泄露防范机制：

1. 滞后特征：基于实际值的特征至少滞后2天
2. 滚动统计：先shift至少2天，再计算滚动统计
3. 训练集划分：使用时序分割，不使用未来数据训练

滞后特征预设

preset1 - 推荐配置（平衡型）

• lags: [-7d, -3d, -2d, -1d, -4h]
• 适用于：电力负荷、电价、销售预测

preset2 - 短期依赖

• lags: [-1d, -4h, -1]
• 适用于：光伏、风电、交通流量

preset3 - 长期依赖

• lags: [-7d, -14d, -30d]
• 适用于：长期趋势预测

项目结构

general_predictor/
├── __init__.py
├── _version.py
├── server.py          # MCP Server
└── forecaster.py      # 核心预测功能

依赖

• Python >= 3.11, < 3.12
• u8darts[notorch] >= 0.30.0
• lightgbm
• xgboost
• catboost
• scikit-learn
• pandas
• numpy

许可证

MIT