# サーバーエンジニア向け共有事項 — ラーメンスープ評価AI 設置依頼

作成日: 2026-07-14 / 依頼元: 嘉手川

## 1. お願いしたいこと

この「VPSデプロイパッケージ」一式をVPSに設置し、APIサーバーとして常駐起動してください。
手順はすべて同梱の **[README_deploy.md](README_deploy.md)** にあります（このパッケージだけで完結します）。

- 設置: README手順4（転送 → `setup.sh` → キー設定 → 動作テスト → swap → 起動）
- 常駐化: README手順7（`ramen-grade.service` を systemd に登録）
- 公開方法: README手順6（**nginxリバースプロキシ＋Basic認証を推奨**。用途に応じて選択してください）

## 2. システム概要（1分で把握）

- 動画をアップロードすると AI がスープ状態を評価し、スコア／グレード（A〜D）を返すシステム
- 処理の流れ: ffmpegフレーム抽出 → 画像AI(PyTorch/RF-DETR) → **外部LLM API(BytePlus)呼び出し** → グレード算出
- `app/api_server.py` が本体。**受付キュー方式**で、複数人から同時に動画が来ても1件ずつ順番に処理します
  （受付は即時応答、推論は逐次。詳細APIはREADME手順5）
- Python標準ライブラリのみのHTTPサーバー（フレームワーク依存なし）。ポートは8000（変更可）

## 3. サーバー要件（確認済み）

| 項目 | 要件 | 備考 |
|---|---|---|
| OS | Ubuntu 22.04 LTS 推奨 | 他のLinuxでも可（ffmpeg/python3.10+が入れば） |
| CPU/メモリ | 6vCore/8GB で動作可 | **swap 4〜8GBを必ず設定**（README手順4.5。OOM対策） |
| ディスク | 30GB以上あれば十分 | パッケージ約190MB＋Python環境約5GB |
| GPU | 不要 | CPUで1動画あたり数十秒〜2分。GPUがあれば自動使用 |
| 外向き通信 | **HTTPS(443)を許可** | `ark.ap-southeast.bytepluses.com`（BytePlus LLM API）への接続が必須 |
| 内向き通信 | 公開方式による | nginx経由なら80/443のみ。アプリ自体は127.0.0.1:8000で待受 |

## 4. 【重要】キー・認証情報の取り扱い

### 4.1 BytePlus APIキー（こちらから別途お渡しします）
- **このパッケージにはAPIキーを含めていません。** キー文字列は別の安全な経路（社内チャットのDM等）で送ります
- 受け取ったら `secrets/byteplus.key` に1行で保存してください（または環境変数 `ARK_API_KEY`）
- **キーをgitにコミットしない／メール平文で転送しないでください**（`.gitignore` 設定済み）

### 4.2 API認証トークン（そちらで生成をお願いします）
- 本システムのAPIを叩くための共有トークンです。任意の長いランダム文字列を生成し、
  `ramen-grade.service` 内の `RAMEN_API_TOKEN=` に設定してください（例: `openssl rand -hex 32`）
- クライアント（動画を送る側のシステム/担当者）には `X-API-Key` ヘッダとしてこの値を配ります
- 生成した値をこちらにも共有してください（クライアント側設定に必要です）

### 4.3 nginx Basic認証（公開する場合）
- ブラウザUIも使うため、公開時はBasic認証の併用を推奨します（README手順6の方式A）
- ID/パスワードを決めたらこちらへ共有してください

## 5. 設置後の確認方法（受け入れテスト）

```bash
# 1) 稼働確認（認証不要）
curl http://127.0.0.1:8000/api/health
# => {"status":"ok","queued":0,...} が返ればOK

# 2) 後段モデル単体（AIやLLMを通さない軽い確認）
cd <設置先> && source .venv/bin/activate && cd app && python infer.py --demo

# 3) 実動画1本のend-to-end（テスト動画はこちらから提供可能です）
curl -X POST "http://127.0.0.1:8000/api/jobs?name=test.MOV&slot=開店前" \
     -H "X-API-Key: <トークン>" --data-binary @test.MOV
# job_id が返る → GET /api/jobs/<job_id> で status:"done" と result にスコアが出れば完了
```

こちらの開発環境（Windows/GPU）では上記3点すべて動作確認済みです
（2本同時投入→順番処理→両方採点完了、認証401/アップロード検証400も確認済み）。

## 6. 運用について

- **ログ**: `journalctl -u ramen-grade -f`（systemd登録後）
- **処理履歴**: `app/_jobs/history.jsonl` に1行1件で自動記録（動画本体は処理後に自動削除）
- **再起動**: `sudo systemctl restart ramen-grade`
- **モデル更新**: こちらから新しい `.pkl`／`.pt`／`.pth` を渡した際は README手順10 の場所に上書き→再起動
- **費用が発生する箇所**: BytePlus LLM APIの従量課金（動画1本＝画像1枚の評価リクエスト1回）。
  サーバー側で回数制限が必要な場合は `requests_per_minute`（`local_batch_api/config.test10.yaml`）で調整可能

## 7. 不明点・詰まった場合

- まず README手順9「トラブルシューティング」を確認してください（rfdetr導入失敗・ffmpeg・OOM等の既知の対処を記載）
- 解決しない場合は、エラーメッセージ・`journalctl` のログを添えて嘉手川までご連絡ください

## 8. こちらから送るもの一覧（チェックリスト）

- [x] 本パッケージ一式（このフォルダ。zip圧縮推奨・約190MB）
- [ ] BytePlus APIキー（**別送**・安全な経路で）
- [ ] テスト用動画1〜2本（受け入れテスト用・必要なら）

以上、よろしくお願いします。