mlp_player_classifier

以 Multi-Layer Perceptron (MLP) 為核心的玩家行為分類器。此專案承接你先前的 K-Means 分群與特徵工程成果，將玩家的時窗特徵（每 30–60 分鐘或每小時）輸入監督式分類模型，輸出 玩家類型標籤（如：建築、探險、生存、紅石、競技、破壞者、社交、掛機），並提供可重現的訓練/推論流程，方便後續銜接 伺服器負載預測 與 動態節能調節。

可同時與 2026TISF_Kmeans 共同使用：以分群/規則產生的弱標註作為初始標籤，再用 MLP 微調與強化。

---

功能亮點

• 端到端監督式訓練流程：資料載入 → 前處理/特徵縮放 → MLP 訓練 → 評估 → 匯出模型。
• 可配置化：以 config/*.yaml 管理特徵欄位、標籤對映、模型超參數（層數、寬度、Dropout、L2、學習率、批次大小、Epochs 等）。
• 多種評估指標：accuracy、precision/recall/f1 (macro/weighted)、混淆矩陣、ROC-AUC（多類 One-vs-Rest）。
• 產物可追溯：自動保存 runs/（權重、最佳檢查點、學習曲線、指標報表、confusion matrix PNG、分類報告）。

---

安裝與環境

• Python 3.10+

pip install -U pandas numpy scikit-learn torch torchvision torchaudio matplotlib pyyaml joblib

或

```bash
pip install -U pandas numpy scikit-learn matplotlib pyyaml joblib

若需匯出/讀取 Excel：openpyxl；若啟用 API：fastapi uvicorn。

---

標籤範例

0: "Builder"      # 建築玩家
1: "Explorer"     # 探險玩家
2: "Survivor"     # 生存玩家
3: "Redstone"     # 紅石玩家
4: "PvP"          # 競技型玩家
5: "Griefer"      # 破壞者
6: "Social"       # 社交玩家
7: "AFK"          # 掛機玩家

---

快速開始

1) 準備資料與設定

# 建立資料夾
mkdir -p data/train data/valid data/test runs config

cat > config/experiment_default.yaml << 'YAML'
seed: 42
task: "multiclass"
label_column: "label"
id_columns: ["player_id", "ts_window_start"]

features:
  - blocks_placed
  - blocks_broken
  - chunk_loads
  - tnt_exploded
  - entity_kills
  - items_picked
  - items_dropped
  - container_interactions
  - chat_count
  - afk_minutes
  - active_minutes

preprocess:
  winsor_p: 0.99
  log1p:    ["blocks_placed", "blocks_broken", "chunk_loads"]
  scaler:   "standard"   # standard / robust / minmax

model:
  type: "pytorch"        # pytorch / sklearn
  hidden_sizes: [128, 64]
  dropout: 0.2
  l2: 1.0e-4

train:
  batch_size: 512
  lr: 1.0e-3
  epochs: 50
  early_stopping_patience: 8

eval:
  save_confusion_matrix: true
  save_classification_report: true
YAML

2) 訓練

python train.py --config config/experiment_default.yaml   --train_dir data/train --valid_dir data/valid --out_dir runs/exp1

3) 測試

python train.py --config config/experiment_default.yaml   --test_dir data/test --resume runs/exp1/best.ckpt --only_test

4) 推論

python inference.py   --model runs/exp1/best.ckpt   --input data/new_unlabeled.parquet   --output runs/exp1/predictions.parquet

---