# 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`를 통해 다음 과정을 거쳐 결과를 도출합니다.

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

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