# Codex 引き継ぎプロンプト：ラーメンスープAI評価パイプラインの技術検証

あなたはこのプロジェクトを引き継いで「ここから先の技術検証（学習データの折り畳み＝交差検証フォールド設計、総合スコアの作り方、データ品質検証など）」を進める担当です。
以下に、これまでにやったこと・成果物の置き場所・残課題・実行環境を全てまとめます。**まず本ドキュメントと参照先を読んでから着手してください。**

---

## 0. プロジェクトの目的（確定事項）

ラーメン豚山の寸胴鍋スープ動画を入力し、各動画について構造化された評価データを生成する。**最終目的は、その評価データを学習データとして最終AIモデルを開発すること。**

設計上の確定事項（変更しないこと）:
1. **濃度（visual_density）はLLMに当てさせない。** 濃度判定AI（RF-DETRスープ抽出＋ResNet濃度分類）または CSV人手ラベルが確定する。
2. **LLMは濃度を「参考入力」として受け取り**、総合評価（撮影品質・水位・乳化・沸騰）を行う。これはリークではなく意図された設計。
3. LLMの構造化出力（JSON）を**学習データ**にする。
4. 不可読×湯気多の動画はLLMに送らず「判定不可」レコードを生成（課金節約）。

---

## 1. 現在の到達点（2026-06-19 時点で完了済み）

### 1.1 LLMスコアリング 全520件完了
- 出力: `local_batch_api/output_full/`
  - `ramen_soup_evaluations.sqlite3`（テーブル `evaluations`）
  - `training_dataset.csv` / `training_dataset.jsonl`（**動画単位でデダプ済みの最終学習データ520行**）
  - `frames/`（送信フレーム）
- 集計:
  - 動画ユニーク **520件 / 通信エラー 0件**
  - **LLM送信（課金あり）384件 / 送信前スキップ（readability_layer・課金なし）135件**
  - assessable=true **367件** / 判定不可 153件
  - 濃度分布: 10→14, 11→47, 12→157, 13→150, 判定不可→152
  - 送信成功分のLLM確信度: 高212 / 中131 / 低24
  - 水位: 良好360 / 判定不可160 ／ 乳化: 乳化進行180 / 油感乳化良好145 / 油感強い24 / 判定不可171
- 既知の軽微な事象: `807.MOV` が初回タイムアウト→再送成功。DBに古い失敗行（id=417）が1行だけ残存するが、**学習データ出力はデダプ済みで影響なし**。気になれば `DELETE FROM evaluations WHERE id=417;` で物理削除可。

### 1.2 濃度判定AIの精度（人間ラベル基準・キャリブレーション後）
- 高信頼(high)222件: 完全一致77% / ±1以内96% / MAE 0.27
- キャリブレーション: linear `{10→11,11→12,12→12,13→13,14→13}`（`local_batch_api/calibration.json`、resolverが自動適用）

### 1.3 パイプライン構成
```
1動画 → 可読性レイヤー(density_resolver) … 多フレーム抽出→湯気除外(EfficientNet)→スープ抽出(RF-DETR)→最良フレーム選定＋濃度確定
   ├─ 不可読 かつ steam_mean≥0.8 → LLM送らず「判定不可」レコード生成
   └─ それ以外 → LLM送信（best frame画像1枚＋固定プロンプト＋濃度参考値）→ JSON評価
```

---

## 2. LLM入出力データの中身（学習データを扱う前に把握すべき）

詳細は **`LLM入出力データ仕様.md`** に実例つきでまとめてある。要点:

- **渡したデータ**＝`user`メッセージ1本。content2ブロック:
  1. `input_image`: best frame 画像1枚（`local_batch_api/prepared_best_frames/<ID>_best.jpg` をbase64 data URL化）
  2. `input_text`: 固定評価方針プロンプト（約4,400字）＋ `【別入力】スープ濃度(計測/人手ラベル): N` ＋ 撮影品質ヒント
- **返ってきたデータ**＝プロンプト指定のJSON。主キー:
  `assessable / retake_recommended / image_condition_score / visual_density{value,reason,confidence} / water_level{state,reason,confidence} / oil_emulsification{state,...} / boiling_heat_state / photo_quality / deduction_reasons[] / craftsperson_check_points[] / summary`
- 送信前スキップ行は `evaluation_source="readability_layer"` と `skip_reason` が付く（LLM評価行と見分けられる）。
- DB列対応: `request_json`（送信内容）/ `response_json`（生レスポンス, reasoning＋本文＋usage）/ `assessment_json`（パース済み最終評価）/ `frame_metrics_json`（フレーム選定メトリクス）。
- プロンプト全文: `local_batch_api/output_full/_prompt_full.txt`、原本は `APIテスト/豚山スープ画像評価プロンプト方針.md`。

---

## 3. ここから先の技術検証タスク（あなたの担当）

### 3.1 最初に決める未決定事項：最終「総合スコア」の作り方
学習ターゲットとなる総合スコアをどう作るか未決定。2案:
- **(A) LLMに総合スコア1項目を出させる** → `APIテスト/豚山スープ画像評価プロンプト方針.md` に総合点定義を追記 → `output_full` を作り直して全件再送（データ統一のため）。
- **(B) LLMは各項目だけ出し、後段モデル／ルールで合成** → 既存の520件出力をそのまま使い、`training_dataset.*` から合成スコアを算出。
> どちらでも現パイプラインは動く。(A)はデータ再生成（約10分・約330円）が必要、(B)は再送不要。

### 3.2 学習データの折り畳み（交差検証フォールド設計）
- `training_dataset.csv/jsonl` 520行を学習用にどう分割するか（K-fold等）。
- 注意点:
  - **判定不可153件の扱い**（学習から除外するか、別クラスにするか）を明示的に決める。
  - クラス不均衡: 濃度は12/13に集中、10/14が少数（10→14件）。**層化（stratified）分割**を推奨。
  - リーク防止: 同一店舗・同一撮影バッチが train/val に跨らないようグループ分割を検討（メタの撮影日時 `metadata_json` を参照）。
- 検証用の素材は既に揃っている（`full_density_eval.csv` 等）ので、濃度AIの精度フォールドと混同しないこと（あちらは濃度モデルのCV、こちらは学習データの分割）。

### 3.3 データ品質検証
- assessable=false / confidence=低 の行を学習にどう含めるか。
- LLM出力の項目別分布の偏り、矛盾（例: water_level良好だがretake推奨）チェック。
- 重複・欠損・スキーマ逸脱の検査（`assessment_json` をスキーマ照合）。

---

## 4. 実行環境（重要・必読のハマりどころ）

- **OS**: Windows 11 / シェルは PowerShell（Bashは不安定なので重い処理はPowerShell手動実行運用）。
- **Python**: `C:\rmlenv\Scripts\python.exe`（短いパスのvenv必須。Store Python直下だとtorchがロングパス未対応で展開失敗）。
- **GPU**: RTX 5060（Blackwell sm_120）。torch cu128。CPU比6〜8倍速。
- **matplotlib==3.9.4 固定**（最新3.11系は `ft2font.pyd` がDefenderにブロックされRF-DETR経由でImportError）。
- 文字化け対策: 実行前に `$env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"`。
- 詳細な環境構築・依存パッケージ・ハマりどころ一覧は **`引き継ぎ資料.md`** を参照（このプロジェクト直下、再現手順が全部ある）。

### よく使うコマンド
```powershell
cd "C:\Users\NX023286.NEXYZ\Documents\開発しているもの\制作中\AIラーメン評価アルゴリズム分析"
$env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"

# 結果確認
& "C:\rmlenv\Scripts\python.exe" "local_batch_api\inspect_results.py"
# キャッシュ確認
& "C:\rmlenv\Scripts\python.exe" "local_batch_api\verify_cache.py"
# （A案で再送する場合）全件LLM送信。already_doneでスキップ・二重課金なし
& "C:\rmlenv\Scripts\python.exe" -u "local_batch_api\batch_process.py" --input "学習データ" --config "local_batch_api\config.test10.yaml"
```

---

## 5. ファイル/ディレクトリ早見表（プロジェクト直下）

| パス | 内容 |
|---|---|
| `Codex引き継ぎプロンプト.md` | **本ドキュメント** |
| `LLM入出力データ仕様.md` | LLMに渡した/返ってきたデータの実例仕様 |
| `引き継ぎ資料.md` | 環境構築〜学習データ生成の完全再現手順 |
| `明日の作業方針.md` | 未決定事項（総合スコアA/B）と実行手順の元メモ |
| `業務報告資料.md` | 進捗報告 |
| `学習データ/` | 入力動画 `<ID>.MOV/.mp4` ＋ ラベルCSV（`*グリッド 10.csv` にIDとスープ濃度） |
| `APIテスト/豚山スープ画像評価プロンプト方針.md` | LLMプロンプトの原本（A案で編集する対象） |
| `local_batch_api/` | パイプライン本体（下記） |

### local_batch_api/ の主要ファイル
| ファイル | 役割 |
|---|---|
| `density_resolver.py` | 中核。可読性判定＋最良フレーム選択＋濃度解決＋キャリブレーション適用。先頭定数に3モデルのパス定義 |
| `prepare_densities.py` | ①前処理キャッシュ生成（--resume対応） |
| `batch_process.py` | ②LLM送信。cache読込・skip_if_steamy・最良フレーム送信・DB保存・学習データ出力 |
| `full_density_eval.py` / `fit_calibration.py` | 濃度AI精度検証 / キャリブレーション学習 |
| `inspect_results.py` / `verify_cache.py` | 結果確認 / キャッシュ確認 |
| `config.test10.yaml` | 設定（api / processing / concurrency / density / paths） |
| `calibration.json` | 濃度補正マップ（resolver自動読込） |
| `density_cache.jsonl` | ①前処理結果キャッシュ（全520件） |
| `prepared_best_frames/` | LLMに送る最良フレーム画像 `<ID>_best.jpg` |
| `output_full/` | **最終出力**（sqlite + training_dataset.csv/jsonl + _prompt_full.txt） |

### 参照モデル（別プロジェクト・再学習しない）
`~/Documents/開発しているもの/制作中/AIラーメン開発/ramen-soup-ai-suite` に学習済みモデル:
- 湯気分類 EfficientNet-B0: `04_steam-classification/.../steam_classifier_best.pt`
- スープ抽出 RF-DETR seg: `03_soup-density-ai/models/crop/soup_valid_area_rfdetr_seg_v2/checkpoint_best_ema.pth`
- 濃度分類 ResNet18(10〜14): `03_soup-density-ai/models/density/density_classifier_extracted_v1/model.pt`

---

## 6. 着手時の推奨手順
1. 本ドキュメント → `LLM入出力データ仕様.md` → `引き継ぎ資料.md` の順で読む。
2. `inspect_results.py` で現状の出力を目視確認。
3. §3.1（総合スコアA/B）をユーザに確認して確定 → 確定後にフォールド設計（§3.2）とデータ品質検証（§3.3）に進む。
4. 重い処理・GPU処理はPowerShellコマンドをユーザに渡して実行してもらう運用（Bash自動実行は不安定）。
</content>