本番デプロイ運用ガイド

0. 3 デプロイ先の役割分担

Mahjong Vision は以下の 3 つのデプロイ先を用途別に使い分け る前提で本番運用する。 1 つに集約せず併用することで、レイテンシ・コスト・オフライン性のトレードオフを最適化する。

0.1 推論パスの選択基準

A. Cloudflare Workers AI (クラウド推論)

A-1. 必要ハード / アカウント

A-2. Roboflow → ONNX export

Roboflow Workspace から学習済みモデルを ONNX で取得し、Cloudflare 互換に整形する。

# PowerShell (Windows / Python 3.14)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install roboflow ultralytics onnx onnxruntime onnxsim

# API キーは .env.local から読み込み (会話/ログに直接貼らない)
# Get-Content .env.local | Where-Object { $_ -match '^ROBOFLOW_API_KEY=' } 等で参照

python scripts/build/roboflow-export.py `
    --workspace mahjong-vision `
    --project mleague-tiles-v2 `
    --version 7 `
    --format onnx `
    --imgsz 640 `
    --opset 17 `
    --simplify `
    --output models/mleague-tiles-v2-7.onnx

# bash (Linux / macOS dev box)
python3 -m venv .venv && source .venv/bin/activate
pip install roboflow ultralytics onnx onnxruntime onnxsim

python scripts/build/roboflow-export.py \
    --workspace mahjong-vision \
    --project mleague-tiles-v2 \
    --version 7 \
    --format onnx \
    --imgsz 640 \
    --opset 17 \
    --simplify \
    --output models/mleague-tiles-v2-7.onnx

A-3. Workers AI BYOM デプロイ

npx wrangler login                       # 初回のみ
# モデルアップロード (BYOM)
npx wrangler ai models put mleague-tiles-v2-7 `
    --file models/mleague-tiles-v2-7.onnx `
    --task object-detection

# Workers にバインド (wrangler.toml)
# [ai]
# binding = "AI"
# [[ai.models]]
# binding = "TILES_MODEL"
# name    = "mleague-tiles-v2-7"

npm run build
npx wrangler deploy

A-4. 推論料金見積

2026-05 時点の Workers AI 料金 (ニューロン課金) を元にした参考見積:

A-5. レイテンシ実測の指針

• P50: 100〜150 ms (東京リージョン edge から JP ユーザ)
• P95: 200〜300 ms
• P99: 400〜600 ms (cold start を含む)
• cold start 後 60 秒は再利用可。連続アクセス時は P50 が 80 ms まで下がる

A-6. ロールバック手順

# 1. 旧バージョンに即時切替 (モデルバインディングを過去 ID に戻す)
npx wrangler ai models list                         # 既存モデル一覧
# wrangler.toml の TILES_MODEL を v6 に戻し再 deploy
git checkout HEAD~1 -- wrangler.toml
npx wrangler deploy

# 2. それでも問題ある場合は Worker 自体を 1 世代前にロールバック
npx wrangler rollback                               # 直前 deploy にリバート

B. Jetson Orin Nano (エッジ推論)

B-1. 必要ハード仕様

B-2. JetPack 6 セットアップ

# Jetson 側 (Ubuntu 22.04 / JetPack 6)
sudo apt update && sudo apt install -y python3.10-venv git docker.io
sudo usermod -aG docker $USER
newgrp docker

# NVIDIA Container Toolkit (Docker GPU access)
distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
    | sudo gpg --dearmor -o /etc/apt/keyrings/nvidia-container-toolkit.gpg
curl -fsSL https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list \
    | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update && sudo apt install -y nvidia-container-toolkit
sudo systemctl restart docker

# 動作確認
docker run --rm --runtime nvidia nvcr.io/nvidia/l4t-base:r36.2.0 nvidia-smi

B-3. TensorRT INT8 量子化

RTX4090 で学習・ONNX export した .onnx を Jetson 側で TensorRT エンジン化する (クロスコンパイル不可なので必ず実機上)。

# Jetson 上で実行
git clone https://github.com/<org>/mahjong-scorekeeping.git
cd mahjong-scorekeeping
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-jetson.txt

# INT8 キャリブ用に学習データから 1000 枚抽出 (Roboflow から落として配置)
ls calib-data/ | wc -l   # 1000 枚あるか確認

# ONNX → TensorRT INT8
python scripts/build/build-trt-engine.py \
    --onnx models/mleague-tiles-v2-7.onnx \
    --output models/mleague-tiles-v2-7.int8.engine \
    --precision int8 \
    --calib-dir calib-data/ \
    --workspace 4096 \
    --imgsz 640

B-4. 推論速度 (実測ベース見積)

B-5. systemd 常駐化

# /etc/systemd/system/mahjong-edge.service
[Unit]
Description=Mahjong Vision edge inference
After=network.target

[Service]
Type=simple
User=mjvision
WorkingDirectory=/home/mjvision/mahjong-scorekeeping
ExecStart=/home/mjvision/mahjong-scorekeeping/.venv/bin/python \
    -m src.orchestrator.edge \
    --engine models/mleague-tiles-v2-7.int8.engine \
    --camera 0 --imgsz 1280
Restart=on-failure
RestartSec=5
StandardOutput=append:/var/log/mahjong-edge.log
StandardError=append:/var/log/mahjong-edge.err.log

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now mahjong-edge.service
sudo systemctl status mahjong-edge.service

B-6. ロールバック手順

# models/ 配下に v6 (前バージョン) を常に残しておく運用
ls -lh models/
# mleague-tiles-v2-6.int8.engine
# mleague-tiles-v2-7.int8.engine   ← 不調

# systemd の引数を v6 に戻して再起動
sudo sed -i 's/v2-7\.int8\.engine/v2-6.int8.engine/' /etc/systemd/system/mahjong-edge.service
sudo systemctl daemon-reload
sudo systemctl restart mahjong-edge.service

C. RTX4090 (ローカル GPU / 開発環境)

C-1. 必要ハード仕様

C-2. CUDA + PyTorch セットアップ (Windows)

# Windows 11 PowerShell
# 1. NVIDIA Driver 最新版を Windows 側にインストール (CUDA は WSL 経由で十分)
# https://www.nvidia.com/Download/index.aspx → RTX 4090

# 2. WSL2 + Ubuntu 22.04
wsl --install -d Ubuntu-22.04

# 3. WSL 内に入る
wsl

# WSL Ubuntu 内
sudo apt update && sudo apt install -y python3.14 python3.14-venv git
python3.14 -m venv .venv && source .venv/bin/activate

# PyTorch (CUDA 12.4 対応版)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
pip install ultralytics onnx onnxruntime-gpu

# GPU 認識確認
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
# True NVIDIA GeForce RTX 4090

C-3. CUDA セットアップ (Linux 直)

wget https://developer.download.nvidia.com/compute/cuda/12.4.1/local_installers/cuda_12.4.1_550.54.15_linux.run
sudo sh cuda_12.4.1_550.54.15_linux.run
# /etc/profile.d/cuda.sh に PATH 追加
echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' | sudo tee /etc/profile.d/cuda.sh
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' | sudo tee -a /etc/profile.d/cuda.sh

C-4. 推論速度 (実測ベース見積)

C-5. バッチ評価用途

# M-League 60 分動画 1 本 ≈ 108,000 frame
# YOLOv8m FP16 bs=8 で 108,000 / 360 ≈ 5 分で完走

python scripts/evaluate-agari-transition-detector.py \
    --video mleague/input/sample01.mp4 \
    --model models/mleague-tiles-v2-7.pt \
    --device cuda:0 \
    --imgsz 1280 --half --batch 8 \
    --output mleague/eval/sample01-v2-7.json

C-6. ロールバック手順

RTX4090 環境は 開発 / 評価専用 のため、本番ロールバックの概念は不要。 ただし「v2-7 のチェックポイントで mAP が落ちた」を発見した場合は git checkout + models/v2-6.pt 復元で対応:

git checkout models/mleague-tiles-v2-6.pt   # LFS 経由の場合
python scripts/evaluate-agari-transition-detector.py \
    --video mleague/input/sample01.mp4 \
    --model models/mleague-tiles-v2-6.pt \
    --device cuda:0 --half

4. 3 環境共通: モデル切替 / ロールバック

4.1 推論スクリプトの統一 CLI フラグ

全スクリプトで --roboflow-model, --engine, --device を共通に揃える。これにより 1 コマンドで A/B/C を切替可能。

4.2 モデル切替の典型コマンド

# A. Cloudflare Workers AI 経由
python scripts/render-3d-overlay-cf.py `
    --backend workers-ai --device cloudflare `
    --roboflow-model mahjong-vision/mleague-tiles-v2/7 `
    --input mleague/input/sample01.mp4

# B. Jetson Orin Nano (TensorRT INT8)
python scripts/render-3d-overlay-cf.py `
    --backend tensorrt --device jetson `
    --engine models/mleague-tiles-v2-7.int8.engine `
    --input /dev/video0

# C. RTX4090 (PyTorch FP16)
python scripts/render-3d-overlay-cf.py `
    --backend ultralytics --device cuda:0 `
    --pt models/mleague-tiles-v2-7.pt --half `
    --input mleague/input/sample01.mp4

4.3 共通ロールバック原則

• モデルは 2 世代並走: v(N) と v(N-1) を常に同じディレクトリ/バケットに残す
• 切替は設定ファイル 1 行: 環境変数 MJ_MODEL_VERSION で v6 / v7 を切替可能にする
• 30 分監視ルール: 新モデル投入後 30 分の P95 レイテンシ・false positive 率を比較し、5% 以上悪化したら自動ロールバック
• 共通契約テスト: scripts/contract-test-model.py を A/B/C 各環境で実行し、同じテスト画像で bbox 数 / クラス分布が一致することを確認

5. 運用チェックリスト

5.1 新モデル本番投入チェックリスト

• [ ] Roboflow で val set 500 枚に対し mAP@50 ≥ 0.80 を確認
• [ ] RTX4090 (C 環境) でフルバッチ評価し前バージョンと差分レポート (mleague/eval/diff-v6-v7.md)
• [ ] ONNX export & onnxsim で簡約化 (sanity: onnxruntime.InferenceSession 起動できること)
• [ ] Jetson 実機で TensorRT engine ビルド成功 (約 8〜15 分)
• [ ] Workers AI に BYOM 登録、wrangler ai run で smoke test
• [ ] 3 環境とも contract-test-model.py PASS
• [ ] 旧バージョン (v-1) を全環境で 削除せず 残置
• [ ] Monitoring ダッシュボード (監視・スケーリング) の閾値を新バージョン基準に更新

5.2 障害時の優先順位

1. 影響範囲確認: A/B/C のどこで発生したか
2. 5 分以内: ロールバック実行 (B は systemd 再起動、A は wrangler rollback)
3. 30 分以内: 影響顧客への通知 (該当環境のクラファンバッカー / 店舗オペレータ)
4. 4 時間以内: 一次原因仮説と再発防止策ドラフト
5. 翌営業日: runbook-incident-response.md のテンプレで事後検証