# AI利用システム（完成）— v1.0 / 2026-06-19

**役割**: 開発したAIモデル・システムを使う側（**推論専用**）。
入力された **濃度数値 ＋ 動画 ＋ 時間帯** に合わせて推論し、スコア／グレード／要確認 を出力する。
学習機能は持たない（学習はAI開発システム側）。

## 構成

```
AI利用システム_完成_20260619/
├─ app.py             … 画面（ブラウザUI）。動画アップロード→end-to-end推論
├─ pipeline_full.py    … end-to-end: 動画→上流(RF-DETR/濃度)→LLM評価→後段スコア
├─ scoring_engine.py   … 後段スコアリング（モデル読込・2段ゲート・スコア回帰）
├─ infer.py            … 後段のみのCLI（既にLLM評価済みの入力で推論）
├─ models/             … AI開発システムが学習・保存した *.pkl + metadata.json
└─ samples/            … 入力例（sample_record.json）
```

## 画面の入力と全体フロー

画面の入力は **濃度（任意）／時間帯／動画ファイル** の3つ＋「推論する」ボタン。
動画を入れると以下を自動実行する（学習時＝開発環境と同一の上流を再利用）。

```
動画アップロード ＋ 濃度(任意) ＋ 時間帯
  └ 上流 DensityResolver（local_batch_api/density_resolver.py）
       多フレーム抽出 → 湯気除外 → RF-DETRスープ抽出（可読性判定）
       → 最良フレーム選択 → 濃度確定（実測優先 / 無ければ濃度推定AI）
  └ ゲート①: readable=False → 要確認（LLMに送らない）
  └ LLM画像評価（batch_process.py / 学習時と同じプロンプト・同じBytePlus API）
  └ ゲート②: assessable=0（4軸が判定不可）→ 要確認
  └ 後段スコアリング（線形回帰 visual_plus_brix_slot）→ スコア/グレード
```

> **必要環境**: GPU ／ ffmpeg(PATH) ／ BytePlus APIキー（`secrets/byteplus.key` か 環境変数 `ARK_API_KEY`）。
> 初回推論時に上流モデル(RF-DETR/EfficientNet/ResNet)を読み込むため、最初の1件のみ時間がかかる。

## 入出力

### 入力（1件）
| キー | 必須 | 内容 |
|---|---|---|
| `brix_raw` | △ | **濃度数値**（実測 or 濃度推定AI。空でも可） |
| `slot` | ◯ | **時間帯**（開店前 / 17時〜19時 等） |
| `visual_density` / `water_level` / `oil_emulsification` / `boiling_heat_state` / `photo_quality` / `image_condition_score` | ◯ | **動画**→最良フレーム→LLM画像評価AI の出力 |
| `readable` | △ | 上流RF-DETRスープ可読性(bool)。Falseで「要確認」。無ければLLM側のみで判定 |

> 「動画」は上流前処理（最良フレーム抽出 → LLM画像評価。実体は `local_batch_api/`）で
> 上記のLLM評価項目に変換された状態で渡す。本システムはその後段の採点を担う。

### 出力
`status`（scored / 要確認）、`reason`、`total_score`/`total_grade`、`soup_score`/`soup_grade`。
2段ゲート（① readable可読性 ② assessable）のどちらかが不可なら **要確認**（スコアしない）。

## 使い方（画面 / 推奨）

```powershell
$env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"
cd "AI利用システム_完成_20260619"
& "C:\rmlenv\Scripts\python.exe" app.py        # ブラウザが自動で開く（http://127.0.0.1:8000）
# ポート変更: app.py --port 8001 / 自動で開かない: app.py --no-open
```
濃度（任意）・時間帯を選び、動画ファイルを選択して「推論する」を押すと、上流→LLM→採点まで
自動実行し、総合/スープのスコア・グレードを表示する。判定不能なら「要確認」を表示する。
（LLM評価・上流処理の中間結果も折りたたみで確認できる。）

### end-to-end をCLIで実行
```powershell
& "C:\rmlenv\Scripts\python.exe" pipeline_full.py --video 123.MOV --brix 12 --slot 開店前
```

## 使い方（後段のみ / LLM評価が既にある場合）

```powershell
$env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"
cd "AI利用システム_完成_20260619"

# サンプル（scored / 要確認）
& "C:\rmlenv\Scripts\python.exe" infer.py --demo

# 単件JSON
& "C:\rmlenv\Scripts\python.exe" infer.py --record samples\sample_record.json

# 直接指定（濃度・時間帯・動画由来のLLM評価）
& "C:\rmlenv\Scripts\python.exe" infer.py --brix 12 --slot "17時〜19時" `
    --density 12 --water "水位良好" --oil "乳化が進んでいる" `
    --boiling "良い" --photo "良い" --image-score 8

# バッチ（training_dataset互換CSV）
& "C:\rmlenv\Scripts\python.exe" infer.py --input batch.csv --output out.csv
```

Pythonから:
```python
import scoring_engine as E
models = E.load_models("models")
E.score_record({"brix_raw":12,"slot":"開店前","visual_density":"12",
                "water_level":"水位良好","oil_emulsification":"乳化が進んでいる",
                "boiling_heat_state":"良い","photo_quality":"良い","image_condition_score":8}, models)
```

## モデル更新
AI開発システムで再学習したら、`models_output/*.pkl` と `metadata.json` を
本フォルダ `models/` へ上書きコピーする。特徴量・ゲート定義は開発システムと一致させること。

## 参考精度（学習時 5-fold OOF / 採点対象 346件）
total: グレード一致 88.7% / ±15点以内 91.6% / MAE 8.35 ・ soup: 87.6% / 90.5% / 8.04