Kronos 快速入门

What is Kronos?

Kronos is the first open-source K-line (candlestick) foundation model for financial markets, pre-trained specifically on the “language” of financial markets — K-line sequences. Trained on data from over 45 global exchanges, Kronos is designed specifically for the high-noise characteristics of financial data.

Kronos uses an innovative two-stage framework:

1. Specialized Tokenizer (KronosTokenizer): Quantizes continuous, multi-dimensional K-line data (OHLCV) into hierarchical discrete tokens
2. Large autoregressive Transformer: Pre-trained on these tokens to handle multiple quantitative tasks with one model

In short: Kronos treats K-lines as “language” and solves financial time-series prediction with LLM-style thinking.

Core Features

• 💾 Innovative Quantization: Binary Spherical Quantization (BSQuantizer), dual-level codebook structure
• 🔗 Hierarchical Token Structure: s1 token (coarse-grained) + s2 token (fine-grained)
• 🧠 Dependency-Aware Layer: Enhances conditional dependency modeling between s1 and s2
• 📊 Complete Prediction Pipeline: Auto normalization/denormalization, supports Nucleus Sampling and Temperature Sampling
• 🔧 Complete Fine-tuning Pipeline: Qlib-based A-share data fine-tuning with backtesting framework

Model Family

Model	Tokenizer	Context	Params	Open Source
Kronos-mini	Kronos-Tokenizer-2k	2048	4.1M	✅
Kronos-small	Kronos-Tokenizer-base	512	24.7M	✅
Kronos-base	Kronos-Tokenizer-base	512	102.3M	✅
Kronos-large	Kronos-Tokenizer-base	512	499.2M	❌

Getting Started

Installation

git clone https://github.com/shiyu-coder/Kronos.git
cd Kronos
pip install -r requirements.txt

Core dependencies:

torch >= 2.0.0
numpy, pandas
einops == 0.8.1
huggingface_hub == 0.33.1
matplotlib == 3.9.3
safetensors == 0.6.2
tqdm == 4.67.1

First Example: K-line Price Prediction

import sys
sys.path.append("./model")
from model import Kronos, KronosTokenizer, KronosPredictor
import pandas as pd

# 1. Load model and Tokenizer
tokenizer = KronosTokenizer.from_pretrained("NeoQuasar/Kronos-Tokenizer-base")
model = Kronos.from_pretrained("NeoQuasar/Kronos-small")

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

# 3. Prepare data (needs open/high/low/close columns)
df = pd.read_csv("./examples/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 prediction
pred_df = predictor.predict(
    df=x_df,
    x_timestamp=x_timestamp,
    y_timestamp=y_timestamp,
    pred_len=pred_len,
    T=1.0,
    top_p=0.9,
    sample_count=1
)
print(pred_df.head())

Common Usage

Batch Prediction (Multi-asset Parallel)

pred_df_list = predictor.predict_batch(
    df_list=[df1, df2, df3],
    x_timestamp_list=[x_ts1, x_ts2, x_ts3],
    y_timestamp_list=[y_ts1, y_ts2, y_ts3],
    pred_len=120,
    T=1.0,
    top_p=0.9,
    sample_count=1
)

Note: Batch prediction requires all sequences to have identical historical and prediction lengths.

Without Volume/Amount Data

# OHLC data only is fine (volume/amount filled with 0 automatically)
x_df = df.loc[:lookback-1, ['open', 'high', 'low', 'close']]

Sampling Parameters

Parameter	Description	Recommended
T	Temperature, higher = more random	0.6~1.0
top_p	Nucleus sampling probability threshold	0.9
sample_count	Sampling paths, more = more stable	3~5

Advanced Topics

Tokenizer Architecture

KronosTokenizer has three core modules:

• Encoder Transformer Blocks: Maps input features to latent space
• BSQuantizer: Performs binary spherical quantization, generates hierarchical token indices
• Decoder Transformer Blocks: Reconstructs original data from quantized representation

Key parameters:

• s1_bits: First-level codebook bits (determines s1 vocabulary size = 2^s1_bits)
• s2_bits: Second-level codebook bits
• group_size: BSQuantizer grouping parameter

Model Architecture

Kronos (Predictor) is a standard decoder-only Transformer:

• TemporalEmbedding: Time feature embedding (minute/hour/weekday/day/month)
• Multiple TransformerBlock layers (Multi-Head Attention + FFN + RMSNorm)
• DependencyAwareLayer: Injects s1 information during conditional s2 decoding
• DualHead: Dual output (s1 logits + conditional s2 logits)

Autoregressive Inference

Input normalization → Tokenize → Autoregressive s1/s2 token generation → Decode → Denormalize → Output

Key points:

• max_context=512: Max context length (Kronos-small/base)
• Kronos-mini supports longer max_context=2048
• Output variance reduced by averaging multiple sampling paths

Fine-tuning with Qlib

# Step 1: Configure finetune/config.py (data path, model path)
# Step 2: Data preprocessing
python finetune/qlib_data_preprocess.py

# Step 3: Fine-tune Tokenizer (multi-GPU)
torchrun --standalone --nproc_per_node=NUM_GPUS finetune/train_tokenizer.py

# Step 4: Fine-tune Predictor (multi-GPU)
torchrun --standalone --nproc_per_node=NUM_GPUS finetune/train_predictor.py

# Step 5: Backtest evaluation
python finetune/qlib_test.py --device cuda:0

Best Practices

1. Data Processing

• Time frequency: Supports 5min, 1h, 1d, any frequency — key is continuous timestamps
• Missing values: Must be filled or removed, NaN not supported
• Data volume: Longer historical data (within max_context) generally means better predictions
• Normalization: KronosPredictor handles this automatically

2. Inference Tuning

• Short predictions (pred_len < 50): Use sample_count=1
• Long predictions (pred_len > 100): Recommend sample_count=3~5 to reduce error accumulation
• Conservative prediction: T=0.6 more stable than T=1.0
• Real-time scenarios: Watch max_context limits, auto-truncates when exceeded

3. Model Selection

Scenario	Recommended
Limited resources	Kronos-mini (4.1M, longer context)
Maximum accuracy	Kronos-base (102.3M)
Balanced	Kronos-small (24.7M)

4. Production Considerations

1. Raw signal ≠ pure Alpha: Real quantitative flows need portfolio optimization models for risk factor neutralization
2. Backtest realism: Real production needs to consider trading costs, slippage, market impact
3. Data adaptation: Different markets (A-shares, crypto, US stocks) may have different data distribution effects

FAQ

Q: Getting ModuleNotFoundError: No module named 'model'?

A: Add sys.path.append("./model") at the top of your script, or run from the project root.

Q: How to choose model size?

A: Kronos-mini for resource-constrained environments (4.1M, longer context). Kronos-base for maximum accuracy (102.3M).

Q: Does it support crypto or US stock data?

A:理论上支持任意 OHLCV 格式的 K 线数据，但需要数据本身连续无断档。The demo shows BTC/USDT prediction.

Q: Prediction results are all NaN?

A: Check if DataFrame contains NaN values; confirm column names are lowercase ['open', 'high', 'low', 'close'].

Next Steps

• GitHub Repository — Source code and examples
• arXiv Paper — Technical details
• Live Demo — Online demonstration
• HuggingFace Models — Pre-trained weights