nixtla-batch-forecaster
使用TimeGPT API并行批量预测多个时间序列。通过速率限制优化吞吐量,支持投资组合聚合。适用于处理10-100+份合同或需要高效的多序列预测。通过“批量预测”、“投资组合预测”、“并行预测”触发。
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,tqdmpackages
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
Error:
NIXTLA_TIMEGPT_API_KEY not setSolution:export NIXTLA_TIMEGPT_API_KEY=your_keyError:
API Rate Limit ExceededSolution: Increase--delayor reduce--batch-sizeError:
Missing required columnsSolution: Ensure CSV hasunique_id,ds,ycolumnsError:
Batch failed, falling back to individualSolution: 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/