fumen-measure-analyze/docs/4. train script.md

4. 학습 스크립트 (Training Script) 가이드

이 문서는 train/ 폴더 내의 학습 스크립트(train_xgboost.py, train_lightgbm.py)의 구조와 실행 과정을 설명합니다.

1. 실행 구조 및 파라미터

학습 스크립트는 명령행 인자(CLI Arguments)를 통해 제어됩니다.

실행 예시

python3 train/train_xgboost.py \
  --workingDir ./output/xgboost \
  --dataDir ./datas \
  --trainSize 1000 \
  --validSize 200

파라미터 상세

• --workingDir: 학습 결과물(model.pkl, validate.json 등)이 저장될 경로입니다.
• --dataDir: 정답 데이터(measure.csv)가 위치한 경로입니다.
• --trainSize: 전체 데이터셋 중 학습에 사용할 샘플 수입니다.
• --validSize: 학습에 참여하지 않고 모델 평가(검증)에만 사용할 샘플 수입니다.

2. 데이터 처리 및 학습 파이프라인

스크립트 내부의 train_model 함수는 다음 순서로 동작합니다.

A. 데이터 로드 및 매칭

1. workingDir에서 features.json(전처리된 피처)을 읽어옵니다.
2. dataDir에서 measure.csv(정답 난이도)를 읽어옵니다.
3. (songno, difficulty)를 키로 사용하여 두 데이터를 매칭하고 하나의 데이터셋으로 결합합니다.

B. 데이터셋 분리 (Train/Valid Split)

1. 결합된 데이터셋을 RANDOM_STATE(42)를 기반으로 무작위로 섞습니다(Shuffle).
2. 앞에서부터 TRAIN_SIZE 만큼을 학습 데이터로, 그 뒤의 VALID_SIZE 만큼을 검증 데이터로 엄격히 분리하여 모델의 일반화 성능을 보장합니다.

C. 정규화 (Scaling)

1. StandardScaler를 사용하여 피처의 평균을 0, 분산을 1로 조정합니다.
2. CONTINUE_TRAINING 옵션이 켜져 있고 기존 scaler.pkl이 있다면 이를 로드하여 일관성을 유지합니다.

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

1. 모델 객체를 생성하거나, 기존 model.pkl이 있다면 이를 로드합니다.
2. 기존 모델이 있는 경우 이전 학습 상태를 유지한 채 새로운 데이터로 가중치를 미세 조정(Fine-tuning)합니다.

3. 검증 및 결과 시각화

학습 완료 직후, 모델이 학습 중에 보지 못한 검증 데이터셋(X_valid)을 사용하여 성능을 평가합니다.

1. 지표 계산: MAE(Mean Absolute Error)와 오차 범위 ±0.1 이내의 정확도를 산출합니다.
2. validate.json 저장: 검증된 각 곡의 실제값, 예측값, 오차를 에러 절댓값 내림차순으로 저장합니다.
3. validate.png 생성: 에러의 분포를 한눈에 볼 수 있도록 산점도 그래프를 생성합니다. (X축: 에러 크기 순, Y축: 에러 절댓값)

4. 주요 산출물 (Outputs)

학습이 성공하면 workingDir 폴더에 다음 파일들이 생성/업데이트됩니다.

파일명	내용
model.pkl	학습된 모델 바이너리
scaler.pkl	피처 정규화를 위한 Scaler 객체
features.txt	학습에 사용된 피처 이름 목록 및 순서
validate.json	검증 데이터셋에 대한 상세 예측 결과 (JSON)
validate.png	검증 에러 분포 시각화 그래프 (PNG)

5. 주의사항

• features.json이 먼저 생성되어 있어야 학습이 가능합니다 (preprocess.ts 선행 필요).
• TRAIN_SIZE + VALID_SIZE가 전체 가용 데이터 수보다 크면 오류가 발생합니다.