# Claude Code 引き継ぎ: 精度改善方針と後段モデル比較結果

作成日: 2026-06-19

## 1. 前提

このプロジェクトは、ラーメン豚山のスープ動画からスープ状態を評価し、最終的に人間評価に近いスコアを出すことを目的としている。

最終的に人間から渡される入力は、原則として以下。

- 動画データ
- 濃度の数値

ただし、濃度の数値は将来的に渡されなくなる可能性がある。その場合は、以前開発した濃度推定AIモデルを使って代替する。

評価対象は完成したラーメン丼ではなく、厨房内の寸胴・大鍋・スープ釜の中にあるスープ表面である。評価方針の固定ソースは以下。

- `APIテスト/豚山スープ画像評価プロンプト方針.md`

プロンプトや評価ロジックを変更する場合は、以下を同期すること。

- `APIテスト/index.html`
- `APIテスト/豚山スープ画像評価プロンプト方針.md`

## 2. 想定パイプライン

LLMを使う場所には `（LLM）` を付ける。

```text
動画
  ↓
代表フレーム抽出
  ↓
画像評価AI（LLM）
  ↓
濃度入力の確認
  ├─ 実測濃度あり
  │    ↓
  │  実測濃度を使用
  │
  └─ 実測濃度なし
       ↓
     スープ部分抽出モデル
       ↓
     濃度推定AI
       ↓
     推定濃度を使用
  ↓
後段モデル
  ├─ 要注意判定
  └─ スコア回帰
  ↓
最終出力生成（LLM）
```

スープ部分抽出モデルは、画像評価AIの代替ではない。濃度数値がない場合に、濃度推定AIへ渡すスープ領域を切り出すために使う。

## 3. 採用方針

### 3.1 代表フレーム抽出

採用するもの:

- OpenCVベースのルール処理
- 1動画から3〜5枚の代表フレームを抽出
- 白飛び、ブレ、湯気過多、鍋外が多いフレームを除外
- スープ表面が広く見えるフレームを優先

ここはLLMではなく通常の画像処理で行う。

### 3.2 画像評価AI（LLM）

採用するもの:

- 画像対応LLM
- 固定JSON出力
- 評価対象はスープ表面のみ
- 評価方針は `APIテスト/豚山スープ画像評価プロンプト方針.md` に従う

主な出力項目:

- `assessable`
- `retake_recommended`
- `image_condition_score`
- `visual_density`
- `water_level`
- `oil_emulsification`
- `boiling_heat_state`
- `photo_quality`
- `deduction_reasons`
- `craftsperson_check_points`
- `summary`

特に `visual_density` の 11/12 境界は重要。白泡、湯気、脂膜、白い膜、具材表面の白さだけで濃度を上げないこと。

### 3.3 濃度入力確認

採用するもの:

- ルール処理
- 実測濃度がある場合は実測値を優先
- 実測濃度がない場合のみ、スープ部分抽出モデルと濃度推定AIに回す

後段モデルには以下を渡す。

- `density_value`
- `density_source`: `measured / estimated / missing`
- `density_confidence`
- `density_available`
- `visual_density` と濃度値の差分

実測濃度と推定濃度は同じものとして扱わない。必ず `density_source` を特徴量に含める。

### 3.4 スープ部分抽出モデル

採用するもの:

- 以前開発したスープ領域抽出モデル
- 使用タイミングは「実測濃度なし」の場合
- 目的は濃度推定AIに渡すスープ領域を抽出すること

### 3.5 濃度推定AI

採用するもの:

- 以前開発した濃度推定AIモデル
- 入力はスープ部分抽出済み画像
- 出力は推定濃度値と信頼度

実測濃度がある期間も、裏側では推定濃度を出しておくとよい。将来、実測濃度がなくなった場合の性能劣化を事前に測れる。

### 3.6 後段モデル

後段モデルについては、以下の比較レポートを根拠にする。

- `reports/後段モデル比較レポート_20260619.md`

現時点の採用方針:

| 用途 | 候補 | 理由 |
|---|---|---|
| 本番初期の基準 | 線形回帰 または Ridge回帰 | 精度が上位帯で、説明しやすく、運用が安定しやすい |
| 精度比較用 | Random Forest | `human_total_score` で今回のMAE最良 |
| 精度比較用 | LightGBM | 相関が最良 |
| 外部提案比較用 | XGBoost | BytePlus提案方式との比較軸として残す |
| 不採用 | 固定配点 | 学習モデルより大きく劣る |

構成は以下を推奨する。

```text
後段モデル
  ├─ 要注意判定
  │    └─ まずはルール、低評価サンプルが増えたら軽量分類モデル
  │
  └─ スコア回帰
       ├─ 第1候補: 線形回帰 / Ridge回帰
       ├─ 第2候補: Random Forest
       ├─ 第3候補: LightGBM
       └─ 比較継続: XGBoost
```

最終スコアは `human_total_score` を主対象にする。`human_soup_score` は画像評価AIの品質確認用に残す。

### 3.7 最終出力生成（LLM）

採用するもの:

- LLM
- 後段モデルのスコア、要注意判定、画像評価JSON、濃度情報をもとに、人間向けの説明文を生成する
- LLMにスコアを自由に決めさせない

LLMの役割:

- 判定理由の文章化
- 職人確認ポイントの整理
- 撮り直し推奨理由の説明
- 濃度値が実測か推定かの明示

## 4. 精度を高めるために今すぐ優先すること

最優先は、後段モデルの変更ではなく、大外しサンプルの原因分類である。

### 4.1 大外し上位20〜50件を確認する

やること:

1. `predictions.csv` から誤差が大きい動画を抽出する。
2. 元動画、代表フレーム、LLM出力、人間点数、濃度値を並べて確認する。
3. 外れた理由を分類する。

分類は以下で開始する。

| 分類 | 意味 |
|---|---|
| フレーム抽出ミス | 湯気、ブレ、白飛び、鍋外など、悪いフレームを見ている |
| LLM評価ミス | `visual_density`、油感、水位などの判定が人間目線とズレている |
| 濃度ズレ | 見た目とBrix/濃度数値が矛盾している |
| 教師点数ブレ | 人間点数側が画像から見える状態と合わない |
| 画像では判断不能 | 味、香り、塩分、工程状態など、画像外要因で点数が付いている |

この分類により、次に直すべき場所を決める。

### 4.2 代表フレーム抽出を改善する

今すぐ効果が出やすい改善。

- 1動画1枚ではなく、3〜5枚を見る
- 湯気が多いフレームを避ける
- 白飛び、暗い、ブレを除外する
- スープ面が広いフレームを優先する
- 複数フレームのLLM結果を中央値、多数決、信頼度加重で統合する
- フレーム間で判定が大きく割れる動画は `要確認` に回す

### 4.3 `visual_density` 11/12境界を重点確認する

後段モデルで効いている特徴量なので、ここを安定させる価値が高い。

やること:

- 大外しサンプルの中で `visual_density=11/12` を抽出
- 実画像を見て、11と12の判定が妥当か確認
- 誤りが多ければプロンプトの境界説明を補強
- 修正時は `APIテスト/index.html` と `APIテスト/豚山スープ画像評価プロンプト方針.md` を同期更新

### 4.4 低評価サンプルを増やす

現状は `anomaly_recall` がほぼ0であり、60点未満の要確認対象を拾う力が弱い。低評価データが少ない可能性が高い。

やること:

- 既存データから60点未満を一覧化
- 低評価動画を追加収集
- `通常 / 要注意 / 撮り直し推奨` の分類ラベルを付ける
- スコア回帰とは別に要注意判定を作る

### 4.5 後段モデルの交差検証を追加する

今回の比較ではモデル間の差が小さいため、1回の固定testだけで決めない。

やること:

- 5-fold交差検証を追加
- 店舗別、時間帯別、期間別の誤差を見る
- `実測濃度あり / 推定濃度あり / 濃度なし` の3条件で比較する
- 線形回帰、Ridge、Random Forest、LightGBM、XGBoostの安定性を比較する

## 5. 今回の後段モデル比較結果

比較結果の詳細レポート:

- `reports/後段モデル比較レポート_20260619.md`

### 5.1 使用データ

入力データ:

- `local_batch_api/output_full/training_dataset.csv`

元データは520件。`human_total_score=880` の1件が100点満点スケール外だったため除外し、比較には519件を使用した。

| 項目 | 件数 |
|---|---:|
| 元データ | 520 |
| 100点スケール外で除外 | 1 |
| 比較に使用 | 519 |
| assessable=true | 346 |
| 判定不可を含む行 | 173 |

固定分割:

| split | 件数 |
|---|---:|
| train | 363 |
| validation | 52 |
| test | 104 |

### 5.2 比較対象モデル

- 固定配点
- 線形回帰
- Ridge回帰
- Random Forest
- XGBoost
- LightGBM

### 5.3 特徴量セット

| feature_set | 内容 |
|---|---|
| `visual_only` | LLM視覚評価のみ |
| `visual_plus_brix` | LLM視覚評価 + Brix |
| `visual_plus_brix_slot` | LLM視覚評価 + Brix + 時間帯 |
| `brix_only` | Brixのみ |

人間コメントは、運用時に得られない情報のため特徴量には入れていない。

### 5.4 主結果: `human_total_score`

濃度込みの最終評価に近い `human_total_score` では以下。

| モデル | 特徴量 | test MAE | test 相関 | グレード一致率 |
|---|---|---:|---:|---:|
| Random Forest | visual + Brix + 時間帯 | 8.72 | 0.620 | 80.8% |
| LightGBM | visual + Brix + 時間帯 | 8.72 | 0.634 | 78.9% |
| 線形回帰 | visual + Brix | 8.75 | 0.622 | 80.8% |
| 線形回帰 | visual + Brix + 時間帯 | 8.75 | 0.615 | 80.8% |
| Ridge回帰 | visual + Brix + 時間帯 | 8.82 | 0.633 | 80.8% |
| XGBoost | visual + Brix + 時間帯 | 8.88 | 0.632 | 80.8% |
| 固定配点 | 固定式 | 26.67 | 0.462 | 64.4% |

固定配点より学習モデルが明確に良い。学習モデル間の差は小さく、XGBoostだけが突出している結果ではない。

### 5.5 スープのみ点数: `human_soup_score`

画像評価そのものに近い `human_soup_score` では以下。

| モデル | 特徴量 | test MAE | test 相関 | グレード一致率 |
|---|---|---:|---:|---:|
| 線形回帰 | visual_only | 8.81 | 0.519 | 73.1% |
| 線形回帰 | visual + Brix + 時間帯 | 8.83 | 0.527 | 76.0% |
| 線形回帰 | visual + Brix | 8.83 | 0.525 | 76.0% |
| Ridge回帰 | visual_only | 8.93 | 0.511 | 73.1% |
| XGBoost | visual + Brix + 時間帯 | 8.96 | 0.530 | 76.9% |
| LightGBM | visual + Brix + 時間帯 | 8.97 | 0.544 | 76.9% |

スープのみ点数では、単純な線形回帰が最も良い。Brixや時間帯を追加しても大きな改善はない。

### 5.6 BytePlus提案値との比較

| 指標 | BytePlus提案値 | 今回最良 |
|---|---:|---:|
| MAE | 11.7 | 8.72 |
| 相関 | 0.53 | 0.634 |
| グレード一致率 | 74% | 80.8% |

同一データ上の後段比較では、BytePlus提案値を上回る水準が出ている。

## 6. 比較に利用したフォルダとファイル

### 6.1 主レポート

- `reports/後段モデル比較レポート_20260619.md`
- `reports/ClaudeCode引き継ぎ_精度改善方針_20260619.md`

### 6.2 入力データ

- `local_batch_api/output_full/training_dataset.csv`

### 6.3 比較スクリプト

- `検証/scripts/run_downstream_model_comparison.py`

### 6.4 比較結果フォルダ

- `検証/results/downstream_model_comparison/`

主な成果物:

| ファイル | 内容 |
|---|---|
| `features.csv` | モデル投入用特徴量 |
| `splits.csv` | train/val/test固定分割 |
| `model_comparison.csv` | 6モデル比較結果 |
| `model_comparison_long.csv` | 比較結果のロング形式 |
| `predictions.csv` | 各動画ごとの予測値、誤差 |
| `feature_importance.csv` | 重要特徴量 |
| `summary.md` | 自動生成サマリ |
| `excluded_target_outliers.csv` | 除外した異常値 |

### 6.5 評価方針・APIテスト関連

- `APIテスト/index.html`
- `APIテスト/豚山スープ画像評価プロンプト方針.md`
- `APIテスト/server.mjs`
- `APIテスト/test-byteplus-image.mjs`

## 7. Claude Codeへの次作業依頼案

次にClaude Codeへ依頼するなら、以下の順番がよい。

1. `predictions.csv` から大外し上位20〜50件を抽出するスクリプトを作る。
2. 大外し確認用のCSVを出す。列は、動画ID、元動画パス、代表フレームパス、人間点数、予測点、誤差、LLM評価項目、濃度値を含める。
3. 人手分類用の列を追加する。分類候補は `フレーム抽出ミス / LLM評価ミス / 濃度ズレ / 教師点数ブレ / 画像では判断不能 / その他`。
4. `visual_density=11/12` の境界サンプルだけを抽出するCSVも作る。
5. 低評価、特に60点未満のサンプル一覧を作る。
6. 5-fold交差検証を `検証/scripts/run_downstream_model_comparison.py` に追加する。
7. 実測濃度、推定濃度、濃度なしの3条件で後段モデルを比較できるようにする。

まず着手すべきは 1〜3。ここで外れ原因を分類しないと、プロンプト、フレーム抽出、後段モデルのどこを直すべきか判断できない。