Kronos는 최초의 오픈소스 파운데이션 모델로, 전 세계 45개 이상의 거래소 데이터로 학습된 금융 캔들스틱(K-line) 모델입니다.

📰 소식

• 🚩 [2025.08.17] 파인튜닝 스크립트를 공개했습니다! Kronos를 여러분의 작업에 맞게 적용해 보세요.
• 🚩 [2025.08.02] 논문이 arXiv에 게재되었습니다!

📜 소개

Kronos는 디코더 전용 파운데이션 모델 패밀리로, 금융 시장의 "언어"인 K-line 시퀀스에 특화되어 사전 학습되었습니다. 범용 TSFM과 달리 Kronos는 금융 데이터의 고유한 고잡음 특성을 처리하도록 설계되었습니다. 새로운 2단계 프레임워크를 활용합니다:

1. 특화된 토크나이저가 연속적이고 다차원적인 K-line 데이터(OHLCV)를 계층적 이산 토큰으로 양자화합니다.
2. 대규모 자기회귀 Transformer가 이러한 토큰으로 사전 학습되어 다양한 양적 작업을 위한 통합 모델로 기능할 수 있습니다.

✨ 라이브 데모

Kronos의 예측 결과를 시각화하는 라이브 데모를 설정했습니다. 웹페이지는 향후 24시간 동안의 BTC/USDT 거래 쌍에 대한 예측을 보여줍니다.

👉 라이브 데모 바로가기

📦 모델 목록

다양한 컴퓨팅 및 애플리케이션 요구에 맞춰 다양한 용량의 사전 훈련된 모델 패밀리를 공개합니다. 모든 모델은 Hugging Face Hub에서 바로 이용할 수 있습니다.

모델	토크나이저	컨텍스트 길이	매개변수	오픈소스
Kronos-mini	Kronos-Tokenizer-2k	2048	4.1M	✅ NeoQuasar/Kronos-mini
Kronos-small	Kronos-Tokenizer-base	512	24.7M	✅ NeoQuasar/Kronos-small
Kronos-base	Kronos-Tokenizer-base	512	102.3M	✅ NeoQuasar/Kronos-base
Kronos-large	Kronos-Tokenizer-base	512	499.2M	❌

🚀 시작하기

설치

1. Python 3.10+를 설치한 후 종속성을 설치하세요:

pip install -r requirements.txt

📈 예측 생성하기

Kronos로 예측하는 것은 KronosPredictor 클래스를 사용하여 간단합니다. 데이터 전처리, 정규화, 예측 및 역정규화를 처리하므로 원시 데이터에서 예측까지 몇 줄의 코드로 이동할 수 있습니다.

중요 참고: Kronos-small 및 Kronos-base의 max_context는 512입니다. 이는 모델이 처리할 수 있는 최대 시퀀스 길이입니다. 최적의 성능을 위해 입력 데이터 길이(즉, lookback)가 이 제한을 초과하지 않는 것이 좋습니다. KronosPredictor는 더 긴 컨텍스트에 대해 자동으로 잘림을 처리합니다.

첫 번째 예측을 생성하는 단계별 가이드입니다.

1. 토크나이저와 모델 로드하기

먼저, Hugging Face Hub에서 사전 훈련된 Kronos 모델과 해당 토크나이저를 로드합니다.

from model import Kronos, KronosTokenizer, KronosPredictor

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

2. 예측기 인스턴스화하기

모델, 토크나이저 및 원하는 장치를 전달하여 KronosPredictor의 인스턴스를 생성합니다.

# Initialize the predictor
predictor = KronosPredictor(model, tokenizer, device="cuda:0", max_context=512)

3. 입력 데이터 준비하기

predict 메서드에는 세 가지 주요 입력이 필요합니다:

• df: 과거 K-line 데이터를 포함하는 pandas DataFrame. ['open', 'high', 'low', 'close'] 열을 포함해야 합니다. volume과 amount는 선택 사항입니다.
• x_timestamp: df의 과거 데이터에 해당하는 타임스탬프의 pandas Series.
• y_timestamp: 예측하려는 미래 기간의 타임스탬프 pandas Series.

import pandas as pd

# Load your data
df = pd.read_csv("./data/XSHG_5min_600977.csv")
df['timestamps'] = pd.to_datetime(df['timestamps'])

# Define context window and prediction length
lookback = 400
pred_len = 120

# Prepare inputs for the predictor
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. 예측 생성하기

predict 메서드를 호출하여 예측을 생성합니다. 확률적 예측을 위해 T, top_p, sample_count와 같은 매개변수로 샘플링 과정을 제어할 수 있습니다.

# Generate predictions
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("Forecasted Data Head:")
print(pred_df.head())

predict 메서드는 제공한 y_timestamp를 인덱스로 하여 open, high, low, close, volume, amount에 대한 예측값을 포함하는 pandas DataFrame을 반환합니다.

여러 시계열을 효율적으로 처리하기 위해 Kronos는 predict_batch 메서드를 제공하며, 이를 통해 여러 데이터셋에 대해 동시에 병렬 예측을 수행할 수 있습니다. 이는 여러 자산이나 기간을 한 번에 예측해야 할 때 특히 유용합니다.

# Prepare multiple datasets for batch prediction
df_list = [df1, df2, df3]  # List of DataFrames
x_timestamp_list = [x_ts1, x_ts2, x_ts3]  # List of historical timestamps
y_timestamp_list = [y_ts1, y_ts2, y_ts3]  # List of future timestamps

# Generate batch predictions
pred_df_list = predictor.predict_batch(
    df_list=df_list,
    x_timestamp_list=x_timestamp_list,
    y_timestamp_list=y_timestamp_list,
    pred_len=pred_len,
    T=1.0,
    top_p=0.9,
    sample_count=1,
    verbose=True
)

# pred_df_list contains prediction results in the same order as input
for i, pred_df in enumerate(pred_df_list):
    print(f"Predictions for series {i}:")
    print(pred_df.head())

배치 예측을 위한 주요 요구사항:

• 모든 시계열은 동일한 과거 길이(룩백 윈도우)를 가져야 합니다.
• 모든 시계열은 동일한 예측 길이(pred_len)를 가져야 합니다.
• 각 DataFrame은 필수 열인 ['open', 'high', 'low', 'close']를 포함해야 합니다.
• volume 및 amount 열은 선택 사항이며, 누락된 경우 0으로 채워집니다.

predict_batch 메서드는 효율적인 처리를 위해 GPU 병렬 처리를 활용하며, 각 시계열에 대해 독립적으로 정규화 및 역정규화를 자동으로 처리합니다.

5. 예제 및 시각화

데이터 로딩, 예측, 플로팅을 포함하는 완전한 실행 가능한 스크립트는 examples/prediction_example.py를 참조하세요.

이 스크립트를 실행하면 아래와 유사한 그래프가 생성되어 실제 데이터와 모델 예측치를 비교할 수 있습니다:

또한 Volume 및 Amount 데이터 없이 예측을 수행하는 스크립트도 제공하며, 이는 examples/prediction_wo_vol_example.py에서 확인할 수 있습니다.

🔧 사용자 데이터로 파인튜닝 (A-Share 시장 예시)

Kronos를 사용자 데이터셋으로 파인튜닝하기 위한 완전한 파이프라인을 제공합니다. 예시로 중국 A-Share 시장 데이터를 Qlib으로 준비하고 간단한 백테스트를 수행하는 방법을 보여줍니다.

면책 조항: 이 파이프라인은 파인튜닝 프로세스를 설명하기 위한 데모용입니다. 단순화된 예시이며 프로덕션 준비된 양적 트레이딩 시스템이 아닙니다. 안정적인 알파를 달성하기 위해서는 포트폴리오 최적화 및 리스크 팩터 중성화와 같은 더 정교한 기법이 필요합니다.

파인튜닝 프로세스는 네 가지 주요 단계로 구성됩니다:

1. 구성: 경로 및 하이퍼파라미터 설정
2. 데이터 준비: Qlib을 사용하여 데이터 처리 및 분할
3. 모델 파인튜닝: Tokenizer 및 Predictor 모델 파인튜닝
4. 백테스팅: 파인튜닝된 모델의 성능 평가

필수 조건

1. 먼저 requirements.txt에 명시된 모든 의존성을 설치하세요.
2. 이 파이프라인은 qlib에 의존합니다. 다음 명령어로 설치하세요:

     pip install pyqlib
   

3. Qlib 데이터를 준비해야 합니다. 공식 Qlib 가이드를 따라 데이터를 다운로드하고 로컬에 설정하세요. 예제 스크립트는 일별(daily) 주기 데이터를 사용한다고 가정합니다.

1단계: 실험 구성하기

데이터, 학습, 모델 경로에 대한 모든 설정은 finetune/config.py에서 중앙 집중화되어 있습니다. 어떤 스크립트를 실행하기 전에, 사용자 환경에 맞게 다음 경로들을 수정하세요:

• qlib_data_path: 로컬 Qlib 데이터 디렉토리 경로입니다.
• dataset_path: 처리된 훈련/검증/테스트 피클(pickle) 파일이 저장될 디렉토리입니다.
• save_path: 모델 체크포인트를 저장할 기본 디렉토리입니다.
• backtest_result_path: 백테스팅 결과를 저장할 디렉토리입니다.
• pretrained_tokenizer_path 및 pretrained_predictor_path: 사전 훈련된 모델의 경로입니다 (로컬 경로 또는 Hugging Face 모델 이름 사용 가능).

특정 작업에 맞게 instrument, train_time_range, epochs, batch_size와 같은 다른 매개변수들도 조정할 수 있습니다. Comet.ml을 사용하지 않는다면 use_comet = False로 설정하세요.

2단계: 데이터셋 준비하기

데이터 전처리 스크립트를 실행하세요. 이 스크립트는 Qlib 디렉토리에서 원시 시장 데이터를 로드하고, 처리한 뒤 훈련, 검증, 테스트 세트로 분할하여 pickle 파일로 저장합니다.

python finetune/qlib_data_preprocess.py

실행 후에는 설정 파일의 dataset_path에 지정된 디렉토리에서 train_data.pkl, val_data.pkl, test_data.pkl 파일을 찾을 수 있습니다.

Step 3: 파인튜닝 실행

파인튜닝 과정은 두 단계로 구성됩니다: 토크나이저를 먼저 파인튜닝하고, 그 다음 예측 모델을 파인튜닝합니다. 두 훈련 스크립트 모두 torchrun을 사용한 다중 GPU 훈련을 위해 설계되었습니다.

3.1 토크나이저 파인튜닝

이 단계는 토크나이저를 특정 도메인의 데이터 분포에 맞게 조정합니다.

# Replace NUM_GPUS with the number of GPUs you want to use (e.g., 2)
torchrun --standalone --nproc_per_node=NUM_GPUS finetune/train_tokenizer.py

가장 성능이 좋은 토크나이저 체크포인트는 config.py에서 구성된 경로(save_path와 tokenizer_save_folder_name에서 파생됨)에 저장됩니다.

3.2 예측 모델 파인튜닝

이 단계는 예측 작업을 위해 주요 Kronos 모델을 파인튜닝합니다.

# Replace NUM_GPUS with the number of GPUs you want to use (e.g., 2)
torchrun --standalone --nproc_per_node=NUM_GPUS finetune/train_predictor.py

가장 성능이 좋은 예측 모델 체크포인트는 config.py에서 구성된 경로에 저장됩니다.

Step 4: 백테스팅으로 평가

마지막으로, 파인튜닝된 모델을 평가하기 위해 백테스팅 스크립트를 실행하세요. 이 스크립트는 모델을 로드하고, 테스트 세트에 대해 추론을 수행하며, 예측 신호(예: 예측된 가격 변동)를 생성하고, 간단한 상위 K개 전략 백테스트를 실행합니다.

# Specify the GPU for inference
python finetune/qlib_test.py --device cuda:0

이 스크립트는 콘솔에 상세한 성능 분석을 출력하고, 아래와 유사한 벤치마크 대비 전략의 누적 수익률 곡선을 보여주는 플롯을 생성합니다:

💡 데모에서 프로덕션으로: 중요한 고려사항

• 원시 신호 vs 순수 알파: 이 데모에서 모델이 생성하는 신호는 원시 예측값입니다. 실제 양적 투자 워크플로에서는 일반적으로 이러한 신호를 포트폴리오 최적화 모델에 입력합니다. 이 모델은 일반적인 위험 요인(예: 시장 베타, 규모 및 가치와 같은 스타일 팩터)에 대한 노출을 중성화하기 위한 제약 조건을 적용하여 **"순수 알파"**를 분리하고 전략의 견고성을 향상시킵니다.
• 데이터 처리: 제공된 QlibDataset은 예시입니다. 다른 데이터 소스나 형식의 경우 데이터 로딩 및 전처리 로직을 수정해야 합니다.
• 전략 및 백테스트 복잡성: 여기서 사용된 단순 Top-K 전략은 기본적인 시작점입니다. 프로덕션 수준의 전략은 일반적으로 포트폴리오 구성, 동적 포지션 사이징, 위험 관리(예: 손절매/익절 규칙)를 위한 더 복잡한 로직을 포함합니다. 또한, 높은 정확도의 백테스트는 거래 비용, 슬리피지, 시장 영향을 세심하게 모델링하여 실제 성능을 더 정확하게 추정해야 합니다.

📝 AI 생성 주석: finetune/ 디렉토리 내의 많은 코드 주석은 설명 목적으로 AI 어시스턴트(Gemini 2.5 Pro)에 의해 생성되었습니다. 도움이 되도록 작성되었지만 부정확한 내용이 포함될 수 있습니다. 코드 자체를 논리의 확정적인 출처로 간주할 것을 권장합니다.

📖 인용

연구에 Kronos를 사용하시는 경우, 저희 논문을 인용해 주시면 감사하겠습니다:

@misc{shi2025kronos,
      title={Kronos: A Foundation Model for the Language of Financial Markets}, 
      author={Yu Shi and Zongliang Fu and Shuo Chen and Bohan Zhao and Wei Xu and Changshui Zhang and Jian Li},
      year={2025},
      eprint={2508.02739},
      archivePrefix={arXiv},
      primaryClass={q-fin.ST},
      url={https://arxiv.org/abs/2508.02739}, 
}

📜 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.