# ラーメンスープ評価AI 導入マニュアル

zipを受け取ってから本番稼働まで、このページの順番どおりに進めれば完了します。
各ステップに「成功するとこう表示される」を載せているので、表示が違う場合はその場で止まって §7 を見てください。

- 対象: サーバーに設置するエンジニア
- 所要時間: 約30分（うち待ち時間15分程度）
- 対象OS: Ubuntu 22.04 LTS（メモリ8GB以上・ディスク空き30GB以上・GPU不要）

---

## 0. 事前に手元に用意するもの

| 用意するもの | 入手先 |
|---|---|
| `ramen-grade_dist_20260721.zip`（181MB） | 発注元から受領（GitHubには無い） |
| BytePlus(ARK) APIキー | 発注元から**別経路**で受領（zipには入っていない） |
| VPSへのSSHログイン情報とsudo権限 | — |

---

## 1. 転送と展開（2分)

手元のPCから:

```bash
scp ramen-grade_dist_20260721.zip ユーザー名@サーバーIP:~/
ssh ユーザー名@サーバーIP
unzip ramen-grade_dist_20260721.zip   # → ramen-grade/ フォルダができる
cd ramen-grade
```

- 設置場所はどこでも構いません（`/var/www` 配下でも可）。コードは自分の位置を基準に動くため、階層の指定はありません。
- **展開後にフォルダ構成やファイル名を変更しないでください**（過去にリネームが原因のエラーが発生しています）。

## 2. 自動セットアップ（15分・待ちが大半）

```bash
bash setup.sh
```

ffmpeg導入 → Python仮想環境(.venv)作成 → PyTorch(CPU版)・全ライブラリ導入 → 環境診断、まで全自動です。

成功するとこう表示される:
```
==> 6/6 環境診断（check_env.py）
 ...
 判定: ⚠ 実行可能（警告 1 件。...）   ← この時点ではAPIキー未設定の警告1件が正常
```

## 3. APIキー設置（1分）
```bash
nano secrets/byteplus.key    # 受領したキーを1行だけ貼り付けて保存
chmod 600 secrets/byteplus.key
```

詳細・注意事項: [README_api_key_setup.md](README_api_key_setup.md)

## 4. 環境診断（30秒）

```bash
python3 check_env.py
```

成功するとこう表示される（この表示になるまで先へ進まない）:
```
 判定: ✓ すべてOK — このまま実行できます
```

✗が出た場合は、各行の「→」に対処コマンドが書いてあります。実行して再診断してください。

## 5. 動作テスト（動画1本・約2分）

テスト動画（スープ鍋を撮った .MOV/.mp4）を1本、`test_videos/` に置いて:

```bash
source .venv/bin/activate
python app/batch_test.py --input test_videos --slot 開店前
```

成功するとこう表示される:
```
事前チェック: すべてOK（ffmpeg・モデル・プロンプト・キー）
モデル読込中（初回のみ1〜2分）...
[1/1] test.MOV ... scored (total=83.8/A, soup=87.2/A) 31s
===== 完了 =====
採点: 1 / 要確認: 0 / エラー: 0  （計 1 本）
```

- `scored` = 採点成功。結果はパッケージ直下の `results/`（CSV・JSONL・詳細JSON）
- `要確認` = 湯気が多い等でAIが判定不能。**エラーではなく正常なゲート動作**です（別の動画で再確認を）
- `error` = §7へ

ここまでで「フォルダに動画を置いて一括採点」は使える状態です。バッチ利用だけならこれで導入完了。
CSVで動画ごとに濃度・時間帯を指定する方法などの詳細: [README_batch_test.md](README_batch_test.md)

## 6. 本番稼働（APIサーバー常駐・10分）

Webブラウザ/APIから動画を受け付ける常駐サーバーを立てます。

### 6.1 認証トークンを決めて常駐化

```bash
# トークン生成（値を控える。利用者がX-API-Keyヘッダで送る値）
openssl rand -hex 24

nano ramen-grade.service
#   <DEPLOY_DIR> → 設置パス（例 /home/ubuntu/ramen-grade）に置換（3箇所）
#   <USER>       → 実行ユーザー名に置換
#   RAMEN_API_TOKEN= の行に上で生成したトークンを設定

sudo cp ramen-grade.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ramen-grade
```

### 6.2 稼働確認

```bash
sudo systemctl status ramen-grade    # → active (running)
curl http://127.0.0.1:8000/api/health
```

成功するとこう表示される:
```json
{"status": "ok", "queued": 0, "processing": 0, "model_loaded": false, "auth_required": true}
```

起動ログに環境チェック結果も出ます: `journalctl -u ramen-grade | head`

### 6.3 swap設定（メモリ8GBのサーバーは必須）

```bash
sudo fallocate -l 8G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h    # Swap行に8Gが出ればOK
```

### 6.4 外部公開（利用形態に合わせて1つ選択）

| 方式 | 用途 | 手順 |
|---|---|---|
| nginxリバースプロキシ＋Basic認証（推奨） | 複数人で常用 | [README_deploy.md](README_deploy.md) §6 方式A |
| SSHトンネル | 社内少人数・非公開 | 同 §6 方式B |

## 7. トラブル時

1. **まず診断**: `python3 check_env.py` — 環境系の原因はここで特定できます
2. **エラー詳細**: バッチは `results/details/<動画名>.json`（トレースバック入り）、常駐は `journalctl -u ramen-grade -n 50`
3. 代表的な症状と対処の一覧: [README_deploy.md](README_deploy.md) §9
4. 解決しない場合、次の3点を発注元へ送付:
   - `python3 check_env.py` の出力全文
   - エラーが出た `results/details/*.json` または journalctl の該当部分
   - 実行したコマンド

## 8. 資料一覧

| ファイル | 内容 |
|---|---|
| **INSTALL.md** | 本書（導入の全手順） |
| [README_requirements.md](README_requirements.md) | 環境に必要なものリスト（全網羅） |
| [README_deploy.md](README_deploy.md) | 詳細版デプロイ手順（API仕様・nginx・GPU・トラブル一覧） |
| [README_operations.md](README_operations.md) | 日常運用（起動停止・使い方・結果の読み方） |
| [README_batch_test.md](README_batch_test.md) | フォルダ一括テストの詳細 |
| [README_api_key_setup.md](README_api_key_setup.md) | APIキー設置の詳細 |
| [README_paths.md](README_paths.md) | 動画・ログ・結果の格納場所 |