# 引き継ぎ資料：AIラーメンスープ評価パイプライン

最終更新: 2026-06-18 / 対象: 本パイプラインを引き継ぐ開発者

このドキュメントだけで、環境構築から学習データ生成まで同じ作業を再現できることを目的とする。

---

## 0. 全体像（何をするシステムか）

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

処理は2系統に分かれる：
- **濃度（スープ濃度）**: LLMではなく、専用の画像AI（湯気除外→スープ抽出→濃度分類）または CSV記入値で確定する。
- **総合評価**: LLM（BytePlus ModelArk / seed-2-0-pro）が、濃度を参考入力として受け取り、撮影品質・水位・乳化・沸騰状態などを評価する。

```
動画 + (任意)CSV
  └─[可読性レイヤー: density_resolver.py]  ※濃度の有無と独立に常時実行
       多フレーム抽出 → 湯気除外(EfficientNet) → スープ抽出(RF-DETR)
        ├─ 濃度確定: CSVにスープ濃度あれば採用 / 無ければ濃度分類(ResNet)で推定+キャリブレーション
        ├─ 可読性判定: スープ表面が読めるか(RF-DETR抽出信頼度)
        └─ LLMに送る最良フレーム(best_frame)を選択
  └─[条件分岐: batch_process.py]
        ├─ 不可読 かつ 湯気多(steam_mean>=0.8) → LLMに送らず「判定不可」レコードを生成（節約）
        └─ それ以外 → LLM送信（最良フレーム + 濃度を参考入力）
  └─ 結果: SQLite + training_dataset.csv / .jsonl
```

---

## 1. 環境構築

### 1.1 ハードウェア前提
- GPU: NVIDIA RTX 5060（CUDA。Blackwell世代 = compute capability sm_120）
- NPUあり(Intel AI Boost)だがPyTorch非対応のため未使用。GPU(CUDA)を使う。

### 1.2 Python仮想環境（短いパス必須）
Microsoft Store版Python直下に torch を入れると **Windowsロングパス未対応で展開失敗**する。必ず短いパスに venv を作る。

```powershell
python -m venv C:\rmlenv
```
以降すべて `C:\rmlenv\Scripts\python.exe` を使う。

### 1.3 依存パッケージ
```powershell
# GPU版 torch（RTX 50系はcu128が必須）
& "C:\rmlenv\Scripts\python.exe" -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
# その他
& "C:\rmlenv\Scripts\python.exe" -m pip install timm albumentations rfdetr opencv-python numpy pandas scikit-learn requests pyyaml
# matplotlib は 3.9.4 を固定（重要・下記ハマりどころ参照）
& "C:\rmlenv\Scripts\python.exe" -m pip install "matplotlib==3.9.4"
```
動作確認：
```powershell
& "C:\rmlenv\Scripts\python.exe" -c "import torch,timm,albumentations,rfdetr,cv2; print('cuda',torch.cuda.is_available())"
```
`cuda True` が出ればOK。

### 1.4 ffmpeg
`ffmpeg` / `ffprobe` が必要（フレーム抽出用）。WinGetで導入し、パスを config に記載済み（`config.test10.yaml` の processing.ffmpeg_path / ffprobe_path）。

---

## 2. ハマりどころ（必読）

| 症状 | 原因 | 対処 |
|---|---|---|
| `torch._C` ImportError / lib欠落 | Store Python＋長いパスでwheel展開失敗 | 短いパス`C:\rmlenv`にvenv |
| `ft2font` ImportError「アクセスが拒否されました」 | matplotlib最新(3.11)のpydがDefenderにブロックされRF-DETRのsupervision経由でコケる | `matplotlib==3.9.4` を入れる |
| 文字化け（cp932） | Windowsコンソール既定エンコーディング | 実行前に `$env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"` |
| `loaded only partially`等のRF-DETR警告 | チェックポイントと構成の差分警告 | 動作に支障なし（無視可） |

---

## 3. 参照モデル（学習済みAIの所在）

別プロジェクト `~/Documents/開発しているもの/制作中/AIラーメン開発/ramen-soup-ai-suite` に学習済みモデルがある。本プロジェクトはそれを参照する（再学習しない）。

| 役割 | モデル | パス |
|---|---|---|
| 湯気分類 | EfficientNet-B0 | `04_steam-classification/steam_detection_project/models/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の5クラス) | `03_soup-density-ai/models/density/density_classifier_extracted_v1/model.pt` |

パスは `local_batch_api/density_resolver.py` の冒頭定数に定義。

---

## 4. ファイル構成（local_batch_api/）

| ファイル | 役割 |
|---|---|
| `density_resolver.py` | 中核。可読性判定＋最良フレーム選択＋濃度解決＋キャリブレーション適用 |
| `prepare_densities.py` | (1)前処理キャッシュ生成（全動画を事前処理して結果と最良フレームを保存。--resume対応） |
| `batch_process.py` | (2)LLM送信。キャッシュ読込・条件分岐(skip_if_steamy)・最良フレーム送信・DB保存・学習データ出力 |
| `full_density_eval.py` | 全件の濃度精度を人間ラベルと突合（検証用） |
| `fit_calibration.py` | 濃度モデルのキャリブレーション学習（CV比較→calibration.json生成） |
| `calibration.json` | 採用された補正マップ（resolverが自動読込） |
| `inspect_results.py` | DB内のLLM評価結果を確認 |
| `verify_cache.py` | (1)キャッシュの件数・送信/スキップ内訳を確認 |
| `config.test10.yaml` | 設定（api / processing / concurrency / density / paths） |
| `density_cache.jsonl` | (1)前処理の結果キャッシュ（(2)で再計算回避） |
| `prepared_best_frames/` | (2)でLLMに送る最良フレーム画像 |
| `output_full/` | (2)の出力（SQLite + training_dataset.csv/jsonl） |

学習データ動画とラベルCSV: `学習データ/`（動画 `<ID>.MOV/.mp4`、ラベルCSV `*グリッド 10.csv` に ID と スープ濃度）。

---

## 5. 実行手順（再現方法）

すべてPowerShellで、先頭に環境変数を設定する：
```powershell
cd "C:\Users\NX023286.NEXYZ\Documents\開発しているもの\制作中\AIラーメン評価アルゴリズム分析"
$env:PYTHONIOENCODING = "utf-8"; $env:PYTHONUTF8 = "1"
```

### 手順1：濃度モデルの精度検証（任意・初回のみ）
全動画を濃度AIで判定し人間ラベルと突合。
```powershell
& "C:\rmlenv\Scripts\python.exe" -u "local_batch_api\full_density_eval.py" --resume
```
→ `full_density_eval.csv` と末尾に精度サマリ・混同行列。

### 手順2：キャリブレーション学習（任意・初回のみ）
```powershell
& "C:\rmlenv\Scripts\python.exe" -u "local_batch_api\fit_calibration.py"
```
→ CVで補正を比較し、改善があれば `calibration.json`(enabled) を保存。無ければenabled:false（過剰補正防止）。

### 手順3：(1)前処理キャッシュ生成（必須・約30分/GPU）
```powershell
& "C:\rmlenv\Scripts\python.exe" -u "local_batch_api\prepare_densities.py" --resume
```
→ `density_cache.jsonl` ＋ `prepared_best_frames/`。`--resume`で中断再開可。
確認：
```powershell
& "C:\rmlenv\Scripts\python.exe" "local_batch_api\verify_cache.py"
```

### 手順4：APIキー設定（(2)の前に）
`secrets/byteplus.key` にBytePlus APIキーを記入（または環境変数 `ARK_API_KEY`）。

### 手順5：(2)LLM送信（10件テスト → 全件）
```powershell
# 10件テスト（実レート・エラー確認）
& "C:\rmlenv\Scripts\python.exe" -u "local_batch_api\batch_process.py" --input "学習データ" --config "local_batch_api\config.test10.yaml" --limit 10
# 問題なければ全件
& "C:\rmlenv\Scripts\python.exe" -u "local_batch_api\batch_process.py" --input "学習データ" --config "local_batch_api\config.test10.yaml"
```
- 起動時 `density cache: 520 件読み込み` が出れば前処理を再計算していない証拠。
- 処理済みは `already_done` でスキップ（二重課金なし・中断再開可）。
- 結果は `output_full/`：SQLite（1件ずつ即コミット）＋ 末尾で training_dataset.csv/jsonl 生成。

### 手順6：結果確認
```powershell
& "C:\rmlenv\Scripts\python.exe" "local_batch_api\inspect_results.py"
```

---

## 6. 設定リファレンス（config.test10.yaml の density セクション）

| キー | 意味 | 既定 |
|---|---|---|
| `enabled` | 濃度レイヤーを使うか | true |
| `frames` | 1動画の抽出フレーム数 | 16 |
| `conf_keep` | スープ抽出信頼度の採用閾値 | 0.50 |
| `multi_min` / `vote_min` / `high_mean_conf` | high(高信頼)判定の条件 | 4 / 0.70 / 0.72 |
| `unreadable_action` | 不可読時の挙動 | skip_if_steamy |
| `steam_skip_threshold` | 不可読時にスキップする湯気平均 | 0.80 |
| `use_best_frame_for_llm` | LLMに最良フレームを送る | true |
| `cache_path` | (1)キャッシュの場所 | local_batch_api/density_cache.jsonl |

concurrency: `api_workers`(同時送信数) / `requests_per_minute`(全体上限)。速度は `min(rpm, workers*60/1件秒数)`。429が出たら下げる（自動リトライ実装済み）。

---

## 7. 運用上の注意
- **Bash/自動実行が不安定な環境のため、重い処理はPowerShellで手動実行**する運用。
- 中断しても **SQLiteは1件ずつ保存・再実行で続きから・二重課金なし**。
- training_dataset.csv/jsonl は実行完了時に生成。途中で止めたらDBは残るので再実行で再生成される。
- プロンプト方針を変えたら、データの統一性のため **output_full を作り直して全件再送**するのが安全。