操作手順書

YOLOv9 (MultimediaTechLab/YOLO) をバックエンドとしたオブジェクト検出モデルの学習〜配布変換までを行うアプリケーションです。本手順書では、データセット準備から学習、ONNX / TFLite / Core ML 各形式への変換、配布用アーカイブの取得までを順を追って説明します。

前提条件
データセット要件 (ZIP の中身)
基本操作の流れ
セットアップ画面の使い方
学習中の進捗確認
変換結果と配布アーカイブ
既存プロジェクトの「変換のみ再実行」
モバイル組み込みガイド
トラブルシューティング
自動チューニングパラメータ一覧

1. 前提条件

サーバー側で GPU (CUDA 11.8 想定, 例: RTX 4090) が利用できること
ブラウザ (Chrome / Safari / Firefox) からアクセスできること
有効なログインアカウント (発行が必要な場合は管理者へ依頼)
学習用画像とアノテーション (COCO 形式) を 1 つの ZIP にまとめたもの

2. データセット要件 (ZIP の中身)

アップロードする .zip は COCO 形式を想定しています。最低限以下の構造が必要です。

your_dataset.zip
├── annotations/
│   └── instances_train.json          ← COCO アノテーション
└── images/
    ├── 0001.jpg
    ├── 0002.jpg
    └── ...

JSON 内の file_name と images/ 下のファイル名は一致させてください
クラス情報 (categories) は JSON から自動抽出されます
train / validation の分割はサーバー側で自動 (9:1) に行います

破損画像の自動除外: 展開時の CRC エラーや、JPEG デコード時の壊れたバイト列は自動でスキップされます。残骸は学習対象から外れます。

3. 基本操作の流れ

ホーム画面で「データ生成」を選択 → セットアップ画面へ
ZIP をドラッグ＆ドロップでアップロード
プロジェクト名 (任意。空欄で自動採番)
学習数 (epoch)、モデルタイプ、データ拡張の有無を選択
準備 ボタンを押下し設定確定
実行 ボタンを押下し学習開始
進捗グラフが自動更新され、AP @ .5 / .5:.95 などが可視化
学習完了後、自動で ONNX → TFLite (各サイズ) → Core ML mlpackage の変換が走る
「プロジェクトをダウンロード」ボタンで成果物 ZIP を取得

4. セットアップ画面の使い方

4-1. プロジェクト名

未入力なら YYYYMMDDHHMMSS 形式で自動採番されます。半角英数・アンダースコア・ハイフンのみ使用可。日本語不可。

4-2. データ入力

ドロップゾーンへ ZIP をドラッグ、またはクリックでファイル選択。アップロード成功で「学習数」「Type」「データ拡張」が有効化されます。

4-3. 学習数 (epoch)

20〜500 の範囲。データ枚数に応じて目安：

画像枚数	推奨 epoch
< 100	150〜300
100〜500	100〜200
500〜2000	75〜150
2000+	50〜100

短い epoch では warmup が学習を食い潰すケースがあるため、内部で warmup epoch は総 epoch の 10% を上限に自動短縮しています。

4-4. Type (モデルサイズ)

Type	モデル	FLOPs	用途目安
nano	YOLOv9-T	7.7G	iPhone / 軽量 Android, 高速プレビュー
tiny	YOLOv9-S	26.4G	汎用バランス型
middle	YOLOv9-M	76.8G	サーバー / 高精度モバイル
high	YOLOv9-C	102.1G	サーバー側オフライン解析向け

4-5. データ拡張

ON にすると Mosaic + RandomCrop が有効化されます。少枚数 (<100) では Mosaic 確率を自動で 0.3 に下げ、合成画像偏重を防いでいます。

4-6. 準備 / 実行 / キャンセル

準備 — ZIP 展開、クラス情報抽出、Hydra 設定生成 (yolo_project_config/)
実行 — 学習サブプロセスを起動。進捗バーとグラフが更新開始
キャンセル — 学習プロセスを途中停止 (中間チェックポイントは保持されます)

5. 学習中の進捗確認

5-1. 進捗グラフ (Loss)

BoxLoss / DFLLoss / BCELoss と total_loss が epoch ごとに記録され折れ線で表示されます。最初の 10 epoch で単調減少していない場合は学習が破綻している可能性があります (ログ確認推奨)。

5-2. AP / AR グラフ

AP @ .5:.95 (mAP) と AP @ .5 を validation epoch ごとに描画。急上昇後プラトーが典型的な学習曲線。ずっと 0 のままなら設定の見直しが必要。

5-3. ETA (終了予定時刻)

直近 5 epoch の平均所要時間から残り時間を逆算しています。最初の 1〜2 epoch はキャッシュ生成・cuDNN benchmark が走るため遅く見えますが、3 epoch 目以降で安定します。

6. 変換結果と配布アーカイブ

学習完了直後、サブプロセスで以下が順次生成されます。

6-1. 出力ファイル一覧 (exports/)

ファイル	用途
`{project}.onnx`	ONNX 単体 (640×640, opset 11)
`{project}_320.tflite`	TFLite FP16 320×320
`{project}_416.tflite`	TFLite FP16 416×416
`{project}_416_litert.tflite`	LiteRT 再変換版 416×416 (実験的)
`{project}_480.tflite`	TFLite FP16 480×480
`{project}_640.tflite`	TFLite FP16 640×640
`{project}_640_litert.tflite`	LiteRT 再変換版 640×640 (実験的)
`label.txt`	1 行 1 クラス名
`{project}.tflite.zip`	★ Android 配布用: 全 TFLite + label.txt
`{project}.mlpackage/`	Core ML simple モード (Swift で NMS 必要)
`{project}.metadata.json`	Core ML サイドカー (クラス名 / 入出力レイアウト)
`{project}.coreml.zip`	★ iOS 配布用: mlpackage + metadata.json

6-2. プロジェクトダウンロード

「プロジェクトをダウンロード」ボタンを押すと、学習成果物 + exports/ 全体を含む ZIP がダウンロードされます。モバイルへ組み込む場合は ZIP 内の {project}.tflite.zip または {project}.coreml.zip を取り出してください。

7. 既存プロジェクトの「変換のみ再実行」

変換設定 (出力サイズ・LiteRT 有効化など) を変更した後、再学習せずに変換だけやり直したい場合に使用します。

7-1. 操作手順

「プロジェクト一覧」から該当プロジェクトの選択ボタン押下
セットアップ画面が学習完了状態 (グラフ表示) で開く
「変換のみ再実行」ボタン押下
確認ダイアログで OK
「変換実行中…」と表示され、バックグラウンドで exports/ が再生成される
完了後 (約 3〜10 分) に「プロジェクトをダウンロード」を再押下

7-2. 必要なデータ (プロジェクト内に存在していること)

ファイル / ディレクトリ	用途
`setup_config.json`	backend / type_selected / type_folder / model_name の解決
`yolo_project_config/`	Hydra 設定 (class_num / class_list / image_size 含む)
`runs/train/{project}/checkpoints/*.ckpt`	Lightning 学習済みチェックポイント

上記いずれかが欠けていると 400 エラーが返ります。プロジェクト削除後は再生成不可なので削除前に必ずダウンロードしてください。

8. モバイル組み込みガイド

8-1. Android (TFLite)

{project}.tflite.zip を展開し、用途に合うサイズの .tflite と label.txt を app/src/main/assets/ に配置。

サイズ	速度 (Snapdragon 8 Gen 1 NNAPI)	用途
320	~10〜15 ms	近距離検出 / プレビュー
416	~15〜25 ms	汎用
480	~25〜35 ms	中距離
640	~40〜70 ms	遠距離 / 小物体

LiteRT 版 (_litert サフィックス) は tf.lite.TFLiteConverter 経由で再変換した最適化版。新しい LiteRT ランタイム (ai_edge_litert.interpreter) で動作確認用。

8-2. iOS (Core ML)

{project}.coreml.zip を展開し .mlpackage と .metadata.json を Xcode プロジェクトに追加。

モデル出力 predictions の形状:

[num_anchors, 4 + num_classes]
  列 0..3: cx, cy, w, h (画像サイズで正規化済み 0..1)
  列 4..C: 各クラスの sigmoid 確率

Swift 側で 閾値フィルタ + NMS + 描画 を実装してください。metadata.json には classes / suggested_thresholds が入っているので参照可能。

9. トラブルシューティング

9-1. AP がずっと 0 / loss が動かない

画像枚数 < 50 → 学習自体が困難。データ追加 or epoch を 200+ に
クラスラベルと画像内容のミスマッチを確認 (アノテーション崩れ)
data_augmentation を OFF にして再学習 (合成過多が悪化要因のことあり)

9-2. GPU OOM

選択した Type を 1 段階下げる、または管理者にバッチサイズ閾値の調整を依頼。Mosaic 増強は VRAM を約 1.5 倍消費します。

9-3. 学習中に「予測不可」が出続ける

1 epoch も完了していない状態 (warmup や初回キャッシュ生成中)。 3〜5 分待って 1 epoch 完了すれば ETA 計算が始まります。

9-4. Xcode で .mlpackage を開いた瞬間にクラッシュ

simple モード mlpackage は対応済み。pipeline 版 (_pipeline.mlpackage) は Xcode 26 でクラッシュ報告あり。simple 版を使用してください。

9-5. 「変換のみ再実行」が 400 エラー

プロジェクトディレクトリ内に必要ファイル (上記 7-2) が揃っているか確認。手動削除や ZIP 抽出ミスで欠落することがあります。

10. 自動チューニングパラメータ一覧

システムが画像枚数 / 総 epoch / VRAM から内部で自動決定するパラメータ。学習時 app.log に出力されます。

パラメータ	決定ルール	例 (39 枚, 20 epoch, RTX 4090)
batch_size	Type と VRAM から表引き	v9-t: 32
num_workers	CPU コア数 / 2, 上限 16	16
equivalent_batch_size	min(64, batch × (batches/epoch ÷ 10))	32 (累積 1 = 毎バッチ step)
warmup.epochs	min(3.0, total_epoch × 0.1)	2.0
optimizer.lr	<100=0.001 / <500=0.005 / その他=0.01	0.001
data_augment.Mosaic	<100=0.3 / <500=0.5 / その他=1.0 (augOn 時)	0.3 (augOff なら無効化)
fp16 / pin_memory / cache	VRAM 8GB以上で fp16 on, RAM 32GB 以上で cache on	fp16=on, cache=on

手動で上書きしたい場合は管理者にお問い合わせください。設定は app.py 内のヘルパー関数 (resolve_learning_rate / resolve_mosaic_prob / resolve_equivalent_batch_size / resolve_warmup_epochs / choose_batch_size) で集中管理されています。

最終更新: アプリケーション内蔵