Kronos: Foundation Models for Financial Candlestick Forecasting

repository·master·Indexed 12 days ago

A family of decoder-only foundation models (Kronos-mini, Kronos-small, and Kronos-base) designed for financial K-line forecasting. It utilizes a two-stage framework consisting of a specialized tokenizer to quantize OHLCV data into discrete tokens and an autoregressive Transformer for quantitative tasks. Includes tools for fine-tuning via CSV or the Microsoft Qlib pipeline, a KronosPredictor class for inference, and a dedicated Web UI for visual predictions.

Tokens: 7.1K
Snippets: 18
Records: 28
Agent score: 97%

What's inside Kronos

What is Kronos?
master
Kronos is a family of decoder-only foundation models specifically pre-trained for financial market K-line (candlestick) sequences. It is designed to handle the high-noise characteristics of financial data using a two-stage framework:
1. Specialized Tokenizer: Quantizes continuous, multi-dimensional K-line data (OHLCV) into hierarchical discrete tokens.
2. Autoregressive Transformer: A large model pre-trained on these tokens to perform various quantitative tasks.
Available models in the Model Zoo include Kronos-mini, Kronos-small, and Kronos-base, which vary in parameter count and context length.
https://github.com/shiyu-coder/kronos/blob/master/README.md

How to make forecasts with KronosPredictor

master

Forecasting is performed using the KronosPredictor class, which manages data preprocessing, normalization, prediction, and inverse normalization.

Workflow

Load Model and Tokenizer: Use .from_pretrained() from the Hugging Face Hub for both Kronos and KronosTokenizer.
Initialize Predictor: Instantiate KronosPredictor with the model, tokenizer, and max_context.
Prepare Data: Provide a pandas DataFrame with ['open', 'high', 'low', 'close'] columns, historical timestamps (x_timestamp), and target future timestamps (y_timestamp).
Generate Forecast: Call .predict() with desired sampling parameters.

Note on Context Length: For Kronos-small and Kronos-base, the max_context is 512. It is recommended that your lookback (input data length) does not exceed this limit. The predictor will automatically truncate longer contexts.

from model import Kronos, KronosTokenizer, KronosPredictor
import pandas as pd

# 1. Load from Hugging Face Hub
tokenizer = KronosTokenizer.from_pretrained("NeoQuasar/Kronos-Tokenizer-base")
model = Kronos.from_pretrained("NeoQuasar/Kronos-small")

# 2. Initialize the predictor
predictor = KronosPredictor(model, tokenizer, max_context=512)

# 3. Prepare Input Data
df = pd.read_csv("./data/XSHG_5min_600977.csv")
df['timestamps'] = pd.to_datetime(df['timestamps'])

lookback = 400
pred_len = 120

x_df = df.loc[:lookback-1, ['open', 'high', 'low', 'close', 'volume', 'amount']]
x_timestamp = df.loc[:lookback-1, 'timestamps']
y_timestamp = df.loc[lookback:lookback+pred_len-1, 'timestamps']

# 4. Generate Forecasts
pred_df = predictor.predict(
    df=x_df,
    x_timestamp=x_timestamp,
    y_timestamp=y_timestamp,
    pred_len=pred_len,
    T=1.0,          # Temperature for sampling
    top_p=0.9,      # Nucleus sampling probability
    sample_count=1  # Number of forecast paths to generate and average
)

print(pred_df.head())

Perform Distributed Data Parallel (DDP) training
master
To accelerate training using multiple GPUs, use torchrun with the DIST_BACKEND environment variable.
- Use nccl for NVIDIA GPUs.
- Use gloo for CPU or mixed environments.
Example for 8 GPUs:
```
DIST_BACKEND=nccl \
torchrun --standalone --nproc_per_node=8 train_sequential.py --config configs/config_ali09988_candle-5min.yaml
```
https://github.com/shiyu-coder/kronos/blob/master/finetune_csv/README.md
Enable Distributed Data Parallel (DDP) training
master
To accelerate training using multiple GPUs, use torchrun with the DIST_BACKEND environment variable.
- For NVIDIA GPUs, use nccl.
- For CPU or mixed environments, use gloo.
```
# Set communication backend (nccl for NVIDIA GPU)
DIST_BACKEND=nccl \
torchrun --standalone --nproc_per_node=8 train_sequential.py --config configs/config_ali09988_candle-5min.yaml
```
https://github.com/shiyu-coder/kronos/blob/master/finetune_csv/README_CN.md
Finetune Kronos on custom data using the Qlib pipeline
master
Kronos provides a complete pipeline for finetuning the model on custom datasets, demonstrated using the Microsoft Qlib framework for A-share market data. The process follows four stages: Configuration, Data Preparation, Model Finetuning (Tokenizer then Predictor), and Backtesting.
Prerequisites
1. Install dependencies from requirements.txt.
2. Install pyqlib:
  pip install pyqlib
3. Prepare local Qlib data following the official Qlib guide.
Step 1: Configure the Experiment
Modify finetune/config.py to set the following essential paths and parameters:
- qlib_data_path: Path to your local Qlib data.
- dataset_path: Where processed pickle files will be saved.
- save_path: Base directory for model checkpoints.
- backtest_result_path: Directory for backtesting results.
- pretrained_tokenizer_path & pretrained_predictor_path: Paths to pre-trained models (local or Hugging Face names).
- use_comet: Set to False if not using Comet.ml.
Step 2: Prepare the Dataset
Run the preprocessing script to load raw Qlib data and split it into train_data.pkl, val_data.pkl, and test_data.pkl:
```
python finetune/qlib_data_preprocess.py
```
Step 3: Run Finetuning
Finetuning is done in two stages using torchrun for multi-GPU support.
3.1 Finetune the Tokenizer (adjusts tokenizer to your domain distribution):
```
# Replace NUM_GPUS with your GPU count
torchrun --standalone --nproc_per_node=NUM_GPUS finetune/train_tokenizer.py
```
3.2 Finetune the Predictor (finetunes the main forecasting model):
```
# Replace NUM_GPUS with your GPU count
torchrun --standalone --nproc_per_node=NUM_GPUS finetune/train_predictor.py
```
Step 4: Evaluate with Backtesting
Run the backtesting script to perform inference on the test set and evaluate a top-K strategy:
```
python finetune/qlib_test.py --device cuda:0
```
```
# Example workflow sequence
pip install pyqlib
python finetune/qlib_data_preprocess.py
torchrun --standalone --nproc_per_node=2 finetune/train_tokenizer.py
torchrun --standalone --nproc_per_node=2 finetune/train_predictor.py
python finetune/qlib_test.py --device cuda:0
```
https://github.com/shiyu-coder/kronos/blob/master/README.md
Train individual components manually
master
For granular control, you can train the tokenizer and the predictor as separate steps using dedicated scripts:
1. Train Tokenizer: Run finetune_tokenizer.py.
2. Train Predictor: Run finetune_base_model.py (this requires the fine-tuned tokenizer from step 1).
```
# Step 1: Train tokenizer
python finetune_tokenizer.py --config configs/config_ali09988_candle-5min.yaml

# Step 2: Train predictor (requires fine-tuned tokenizer)
python finetune_base_model.py --config configs/config_ali09988_candle-5min.yaml
```
https://github.com/shiyu-coder/kronos/blob/master/finetune_csv/README.md
Use the Kronos Web UI for financial prediction
master
Follow these steps to generate financial forecasts using the interface:
1. Load data: Select a financial data file (CSV, Feather, etc.) from the data directory.
2. Load model: Select a Kronos model size and your preferred computing device (CPU, CUDA, or MPS).
3. Set parameters: Adjust prediction quality parameters like Temperature, Nucleus Sampling, and Sample Count.
4. Select time window: Use the slider to select a time range within the fixed 400+120 data point window.
5. Start prediction: Click the prediction button to generate results.
6. View results: Analyze the output via K-line charts, tables, and comparison analysis (price difference statistics and error analysis).
https://github.com/shiyu-coder/kronos/blob/master/webui/README.md
Prepare CSV data for Kronos fine-tuning
master
To fine-tune Kronos on custom financial data, prepare a CSV file containing OHLCV (Open, High, Low, Close, Volume) data. The file must include the following columns:
- timestamps: DateTime stamps for each data point
- open: Opening price
- high: Highest price
- low: Lowest price
- close: Closing price
- volume: Trading volume (can be 0 if unavailable)
- amount: Trading amount (can be 0 if unavailable)
Example format:
timestamps open close high low volume amount
2019/11/26 9:35 182.45215 184.45215 184.95215 182.45215 15136000 0
```
| timestamps | open | close | high | low | volume | amount |
|------------|------|-------|------|-----|--------|--------|
| 2019/11/26 9:35 | 182.45215 | 184.45215 | 184.95215 | 182.45215 | 15136000 | 0 |
```
https://github.com/shiyu-coder/kronos/blob/master/finetune_csv/README.md
Install and start the Kronos Web UI
master
The Kronos Web UI provides a graphical interface for financial predictions. You can start the application using one of three methods. Once started, the interface is accessible at http://localhost:7070.
Prerequisites
Ensure you have installed the necessary dependencies:
```
pip install -r requirements.txt
```
Startup Methods
Method 1: Python script
```
cd webui
python run.py
```
Method 2: Shell script
```
cd webui
chmod +x start.sh
./start.sh
```
Method 3: Flask application directly
```
cd webui
python app.py
```
```
cd webui
python run.py
```
https://github.com/shiyu-coder/kronos/blob/master/webui/README.md
Install Kronos
master
To use Kronos, ensure you have Python 3.10+ installed, then install the required dependencies using pip:
```
pip install -r requirements.txt
```
```
pip install -r requirements.txt
```
https://github.com/shiyu-coder/kronos/blob/master/README.md
Configure the fine-tuning data settings
master
In your YAML configuration file, define the data block to specify the source data and window parameters. You must update data_path and the pre-trained model paths.
Key configuration keys:
- data_path: Path to your custom CSV file.
- lookback_window: Number of historical data points to use.
- predict_window: Number of future points to predict.
- max_context: Maximum context length.
```
# 数据配置
data:
  data_path: "/path/to/your/data.csv"
  lookback_window: 512        # 要使用的历史数据点
  predict_window: 48           # 要预测的未来点数
  max_context: 512            # 最大上下文长度
...
```
https://github.com/shiyu-coder/kronos/blob/master/finetune_csv/README_CN.md
Configure data parameters in YAML
master
Edit your training configuration file (YAML) to specify the data path and window parameters. Key settings include:
- data.data_path: Path to your prepared CSV file.
- data.lookback_window: Number of historical data points to use.
- data.predict_window: Number of future points to predict.
- data.max_context: Maximum context length.
Refer to configs/config_ali09988_candle-5min.yaml for a complete list of available settings.
```
data:
  data_path: "/path/to/your/data.csv"
  lookback_window: 512        # Historical data points to use
  predict_window: 48           # Future points to predict
  max_context: 512            # Maximum context length
```
https://github.com/shiyu-coder/kronos/blob/master/finetune_csv/README.md

Kronos: Foundation Models for Financial Candlestick Forecasting

What's inside Kronos

Workflow

Prerequisites

Step 1: Configure the Experiment

Step 2: Prepare the Dataset

Step 3: Run Finetuning

Step 4: Evaluate with Backtesting

Prerequisites

Startup Methods