XGBoost 기반 난이도 상수 예측 모델

이 문서는 프로젝트의 핵심 학습 엔진인 XGBoost 모델의 구조, 하이퍼파라미터 및 파이프라인 과정을 설명합니다.

1. 모델 개요

본 프로젝트는 태고의 달인 채보의 미세한 난이도 차이(상수)를 예측하기 위해 XGBoost (Extreme Gradient Boosting) 회귀 모델을 사용합니다. 8가지 주요 피처를 입력으로 받아 0.1 단위의 정밀한 난이도 상수를 출력하는 것을 목표로 합니다.

2. 하이퍼파라미터 설정

train/train_xgboost.py에 정의된 주요 설정값은 다음과 같습니다.

파라미터	설정값	설명
`N_ESTIMATORS`	500	결정 트리의 개수
`MAX_DEPTH`	6	각 트리의 최대 깊이
`LEARNING_RATE`	0.05	학습률 (경사 하강 단계의 크기)
`SUBSAMPLE`	0.8	각 트리 학습 시 사용할 데이터 샘플 비율 (과적합 방지)
`COLSAMPLE_BYTREE`	0.8	각 트리 학습 시 사용할 피처 비율
`RANDOM_STATE`	42	결과 재현성을 위한 난수 시드
`Objective`	`reg:squarederror`	평균 제곱 오차 최소화를 목표로 함

3. 학습 프로세스 (Training Pipeline)

A. 데이터 로드 및 매칭

features.json: 전처리 단계에서 추출된 채보별 피처 데이터.
measure.csv: 각 곡의 songno, diff에 대응하는 실제 난이도 상수(Label).
두 데이터를 (songno, difficulty) 키를 기준으로 매칭하여 학습 데이터셋을 구성합니다.

B. 전처리 및 정규화

Feature Selection: songno, difficulty를 제외한 모든 수치형 데이터를 피처로 사용합니다.
Scaling: sklearn.preprocessing.StandardScaler를 사용하여 피처의 평균을 0, 분산을 1로 정규화합니다. 이는 color_complexity와 같이 수치 범위가 큰 피처가 모델에 과도한 영향을 주는 것을 방지합니다.

C. 모델 학습 및 지속 학습 (Warm Start)

CONTINUE_TRAINING 옵션이 활성화된 경우, 기존에 저장된 model.pkl과 scaler.pkl을 로드하여 이전 상태를 유지하며 추가 학습을 진행합니다.

4. 평가 지표

MAE (Mean Absolute Error): 실제 상수와 예측값 간의 절대 오차 평균.
Accuracy (±0.1): 예측값이 실제 값과 0.1 이내로 일치하는 비율을 측정하여 실질적인 예측 성능을 평가합니다.
Feature Importance: 학습 완료 후 각 피처가 예측에 기여한 중요도를 출력하여 모델의 판단 근거를 확인합니다.

5. 예측 프로세스 (Inference)

predict/predict_xgboost.py를 통해 다음 과정을 거쳐 결과를 도출합니다.

학습 시 저장된 model.pkl, scaler.pkl, features.txt 로드.
입력받은 songno에 해당하는 피처를 features.json에서 탐색.
학습 시와 동일한 순서로 피처 벡터를 구성하고 Scaler를 적용.
모델을 통해 예측을 수행하고 결과를 JSON 배열 형태로 출력.

[
  {
    "songno": "1000",
    "diff": "oni",
    "predicted": 11.2345
  }
]

3.1 KiB Raw Permalink Blame History