# ラーメンスープ評価AI — 動かし方（運用者向け・これだけ読めばOK）

VPSに設置済みの前提で「起動・使い方・困ったとき」だけをまとめた早見表です。
詳しい設置手順は [README_deploy.md](README_deploy.md) を参照。

---

## これは何をするもの？

**ラーメンの動画を送ると、AIがスープの状態を採点してスコアとグレードを返す**システムです。

```
動画をアップロード → ①フレーム抽出 → ②画像AIで濃度・湯気を解析
 → ③LLMが画像評価 → ④スコア／グレード算出（総合・スープ）
```

- 途中でAIが判定できないとき（湯気が多すぎ・スープ面が見えない等）は点を付けず「要確認」で止まります。
- 1動画あたり **数十秒〜2分**（CPU運用時）。1件ずつ順番に処理します。

---

## 1. 起動する（3パターン）

サーバーにSSHでログインし、設置フォルダ（例 `~/ramen-grade`）へ移動してから。

### ふだんの運用 → systemd常駐（推奨・自動起動）
一度設定すれば、サーバー再起動後も勝手に立ち上がります。

```bash
sudo systemctl start ramen-grade     # 起動
sudo systemctl stop ramen-grade      # 停止
sudo systemctl restart ramen-grade   # 再起動（設定変更やモデル更新後）
sudo systemctl status ramen-grade    # 動いているか確認（active(running)ならOK）
journalctl -u ramen-grade -f         # ログをリアルタイム監視（Ctrl+Cで抜ける）
```

### 手動で試しに起動したいとき
```bash
cd ~/ramen-grade
bash run.sh        # 127.0.0.1:8000 で起動（Ctrl+Cで停止）
```

### 動いているかの一番簡単な確認
```bash
curl http://127.0.0.1:8000/api/health
# => 稼働状況・キュー滞留数・モデル読込状態が返れば正常
```

---

## 2. 使う（2通り）

### A) ブラウザで使う（人が使う場合・かんたん）
ブラウザで `http://サーバー/`（または後述のSSHトンネルで `http://127.0.0.1:8000`）を開くと、
**動画アップロード → 順番待ち表示 → 結果表示** のUIが出ます。動画を選んで送るだけ。

サーバーを外に公開していない場合、手元のPCから次でトンネルを張ってからブラウザで開きます:
```bash
ssh -L 8000:127.0.0.1:8000 ユーザー名@サーバーIP
# → ブラウザで http://127.0.0.1:8000
```

### B) APIで使う（プログラムから叩く場合）
動画を投げると即 `job_id` が返り、あとから結果を取りにいく方式です。

```bash
TOKEN=xxxxxxxx   # 認証トークン(RAMEN_API_TOKEN)を設定している場合のみ。無ければ -H 行は不要

# 1) 動画を送る（slot=時間帯, brix=濃度は省略可）→ job_id が即返る
curl -X POST "http://127.0.0.1:8000/api/jobs?name=123.MOV&slot=開店前&brix=12" \
     -H "X-API-Key: $TOKEN" --data-binary @123.MOV
# => {"job_id":"j0001_...","status":"queued", ...}

# 2) 結果を確認（done になるまで数秒おきに叩く）
curl -H "X-API-Key: $TOKEN" http://127.0.0.1:8000/api/jobs/j0001_...
# => {"status":"done","result":{"status":"scored","total_score":88.3,"total_grade":"A", ...}}
```

**エンドポイント一覧**

| メソッド | パス | 用途 |
|---|---|---|
| POST | `/api/jobs?name=&slot=&brix=` | 動画を送信（本文にバイナリ）。即 `job_id` を返す |
| GET | `/api/jobs/<job_id>` | ジョブの状態・結果を取得 |
| GET | `/api/jobs` | 直近ジョブ一覧 |
| GET | `/api/health` | 稼働確認（認証不要） |
| GET | `/` | ブラウザ用UI |

---

## 3. 結果の読み方

`result` フィールドを見ます。

- **`status: "scored"`** … 採点成功
  - `total_score` / `total_grade` … 総合スコア・グレード
  - `soup_score` / `soup_grade` … スープのスコア・グレード
- **`status: "要確認"`** … AIが判定不能。点は付かず、`reason` に理由が入る
  （湯気が多すぎる／スープ面が見えない／LLMが判定できない 等）
- 動画は処理後に**自動削除**。履歴は `app/_jobs/history.jsonl` に1行ずつ残る

---

## 4. 動かす前に必要なもの（設置担当が済ませているはず）

- **BytePlus(ARK) APIキー** … ③のLLM評価に必須。`secrets/byteplus.key` に保存 or 環境変数 `ARK_API_KEY`
- 外部公開している場合の**認証トークン** `RAMEN_API_TOKEN`（クライアントは `X-API-Key` ヘッダで送る）
- メモリ8GBサーバーなら**swap 4〜8GB**（未設定だと処理中に落ちることあり）

---

## 5. 困ったとき（早見表）

| 症状 | 対処 |
|---|---|
| サーバーに繋がらない | `sudo systemctl status ramen-grade` で稼働確認。落ちてたら `restart` |
| 処理中にプロセスが落ちる(Killed) | メモリ不足。swapを設定（README手順4.5）。1件ずつ処理する |
| `API key not found` | `secrets/byteplus.key` が無い/空。キーを設定して再起動 |
| `ffmpeg failed` | `sudo apt-get install -y ffmpeg` |
| `rfdetr is not installed` | `bash setup.sh` を再実行 |
| `libGL.so.1` エラー | `sudo apt-get install -y libgl1 libglib2.0-0` |
| アップロードが途中で切れる | nginx使用時は `client_max_body_size` と `proxy_read_timeout` を上げる |
| 動画の上限 | 1本 **500MB** まで |

より詳しい表・公開方法(nginx/HTTPS)・モデル更新は [README_deploy.md](README_deploy.md) を参照。

---

## 6. モデルを更新したとき

再学習した `.pkl` / `metadata.json`（グレード算出）や上流の `.pth`/`.pt`（画像AI）を差し替えたら、
**必ずサービスを再起動**してメモリ上のモデルを読み直させます。

```bash
sudo systemctl restart ramen-grade
```