# 検証フェイズ README

このフォルダは、別エージェントが用意する学習データを受け取った後に、後段モデルの精度を同一条件で比較するための作業場所です。

## 目的

学習データから作った特徴量を使い、以下の方法をすべて同じ train/validation/test 分割で評価します。

| 比較対象 | 使用するもの | 目的 |
|---|---|---|
| 固定配点 | Excel、Python、pandas | 機械学習なしの基準値 |
| 線形回帰 | scikit-learn | 最も単純な学習モデル |
| Ridge回帰 | scikit-learn | 少量データでの過学習抑制 |
| Random Forest | scikit-learn | 非線形パターンの確認 |
| XGBoost | xgboost | BytePlus提案方式との比較 |
| LightGBM | lightgbm | XGBoost系の代替候補 |

## 前提

- 入力画像評価の方針は `APIテスト/豚山スープ画像評価プロンプト方針.md` を固定の正とします。
- 評価対象は、厨房の寸胴・鍋・スープ釜のスープ表面のみです。
- Brix は画像から推定せず、別入力特徴として扱います。
- 人間評価コメントは運用時に得られないため、特徴量には使いません。
- test データは最終評価まで調整に使いません。

## フォルダ構成

```text
検証/
├── README.md
├── 方針.md
├── data/
│   └── README.md
├── notebooks/
│   └── README.md
├── scripts/
│   └── README.md
└── results/
    ├── README.md
    └── comparison_template.csv
```

## 実行方針

1. 学習データを `検証/data/` に配置する。
2. 既存の `common/data_loader.py` または受領データ専用の読み込み処理で、目的変数と特徴量を確定する。
3. `train/val/test = 70/10/20` を seed 固定で分割する。
4. `common/compare_models.py` の比較対象に合わせ、固定配点・線形回帰・Ridge・Random Forest・XGBoost・LightGBM を評価する。
5. 結果を `検証/results/comparison_template.csv` に追記し、最終レポート用の表にする。

## 実行コマンド

学習データを `検証/data/learning_data.csv` に置いた後、まず特徴量 CSV を作ります。

```powershell
python 検証/scripts/prepare_features.py --target total_score
```

列名が違う場合は、目的変数を明示します。

```powershell
python 検証/scripts/prepare_features.py --target 濃度込みの点数
```

次に split を作ります。

```powershell
python 検証/scripts/make_splits.py
```

最後に比較を実行します。`--dim-cols` には固定配点として足し合わせる軸を指定します。

```powershell
python 検証/scripts/run_comparison.py --dim-cols visual_density water_level oil_emulsification boiling_heat_state
```

撮影品質で絞った ablation は次の形です。

```powershell
python 検証/scripts/quality_ablation.py --quality-col image_condition_score --min-quality 3 --dim-cols visual_density water_level oil_emulsification boiling_heat_state
```

## 主な評価指標

- `rho`: スピアマン順位相関。BytePlus公表値との比較主指標。
- `mae`: 平均絶対誤差。
- `grade_match`: A/B/C/D のグレード一致率。
- `anomaly_recall`: C+D、つまり 60 点未満を拾えた割合。

## 採用判断の見方

- 固定配点と機械学習が横並びなら、まず固定配点または Ridge を優先します。
- XGBoost/LightGBM だけ高い場合は、非線形モデル採用候補ですが、過学習確認を必須にします。
- 全モデルが低い場合は、後段モデルではなく前段特徴量、画像条件、人間評価のばらつきを疑います。
- 画質の悪いデータを除くと改善する場合は、撮影品質ゲートを導入候補にします。