nixtla-batch-forecaster

使用TimeGPT API并行批量预测多个时间序列。通过速率限制优化吞吐量,支持投资组合聚合。适用于处理10-100+份合同或需要高效的多序列预测。通过“批量预测”、“投资组合预测”、“并行预测”触发。

📖 中文导读:使用TimeGPT API并行批量预测多个时间序列。通过速率限制优化吞吐量,支持投资组合聚合。适用于处理10-100+份合同或需要高效的多序列预测。通过“批量预测”、“投资组合预测”、“并行预测”触发。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: nixtla-batch-forecaster description: | Forecasts multiple time series in parallel batches using TimeGPT API. Optimizes throughput with rate limiting and supports portfolio aggregation. Use when processing 10-100+ contracts or needing efficient multi-series forecasting. Trigger with "batch forecast", "portfolio forecast", "parallel forecasting". allowed-tools: "Read,Write,Bash,Glob,Grep" version: "1.0.0"

Nixtla Batch Forecaster

Process multiple time series forecasts in parallel with optimized throughput.

Overview

Leverages TimeGPT API to generate forecasts for many time series concurrently. Features parallel batch processing with rate limiting, automatic fallback for failed batches, and optional portfolio-level aggregation. Produces individual forecasts per series plus combined outputs.

Prerequisites

Required:

  • Python 3.8+
  • nixtla, pandas, tqdm packages

Environment Variables:

  • NIXTLA_TIMEGPT_API_KEY: Your TimeGPT API key

Installation:

pip install nixtla pandas tqdm

Instructions

Step 1: Prepare Input Data

Your CSV must have the Nixtla schema columns:

Column Type Description
unique_id string Series identifier (contract ID)
ds datetime Timestamp
y numeric Value to forecast

Analyze your data:

python {baseDir}/scripts/prepare_data.py your_data.csv

Step 2: Set API Key

export NIXTLA_TIMEGPT_API_KEY=your_api_key_here

Step 3: Run Batch Forecast

Execute the batch forecasting engine:

python {baseDir}/scripts/batch_forecast.py your_data.csv --horizon 14 --freq D

Available options:

  • --horizon: Forecast horizon (default: 14)
  • --freq: Frequency D/H/W/M (default: D)
  • --batch-size: Series per batch (default: 20)
  • --output-dir: Output directory (default: forecasts)
  • --aggregate: Create portfolio aggregation
  • --delay: Rate limit delay in seconds (default: 1.0)

Step 4: Generate Report

Create a summary report:

python {baseDir}/scripts/generate_report.py forecasts/

Output

  • forecasts/all_forecasts.csv: Combined forecasts for all series
  • forecasts/{series}_forecast.csv: Individual series forecasts
  • forecasts/summary.json: Processing metadata
  • forecasts/aggregated_forecast.csv: Portfolio aggregation (if --aggregate)
  • forecasts/batch_report.md: Human-readable summary

Error Handling

  1. Error: NIXTLA_TIMEGPT_API_KEY not set Solution: export NIXTLA_TIMEGPT_API_KEY=your_key

  2. Error: API Rate Limit Exceeded Solution: Increase --delay or reduce --batch-size

  3. Error: Missing required columns Solution: Ensure CSV has unique_id, ds, y columns

  4. Error: Batch failed, falling back to individual Solution: Normal behavior - some series may have issues

Examples

Example 1: Forecast 50 Daily Contracts

python {baseDir}/scripts/batch_forecast.py contracts.csv \
    --horizon 14 \
    --freq D \
    --batch-size 10 \
    --output-dir forecasts/

Output:

Batch Forecast Complete
Series forecasted: 50/50
Success rate: 100.0%

Example 2: Hourly Portfolio with Aggregation

python {baseDir}/scripts/batch_forecast.py portfolio.csv \
    --horizon 24 \
    --freq H \
    --aggregate \
    --output-dir portfolio_forecasts/

Resources

  • Scripts:
    • {baseDir}/scripts/prepare_data.py - Data validation and analysis
    • {baseDir}/scripts/batch_forecast.py - Main forecasting engine
    • {baseDir}/scripts/generate_report.py - Report generation
  • Nixtla Docs: https://nixtla.github.io/