fiftyone-model-evaluation

FiftyOne でモデルの予測を評価する

重要な指示

必ず以下のルールに従ってください：

1. データセットが存在し、必須フィールドを備えていることを確認する

list_datasets()
set_context(dataset_name="my-dataset")
dataset_summary(name="my-dataset")

データセットに、互換性のある型の予測フィールドと正解データフィールドが両方あることを確認します。

2. 利用できない場合は評価プラグインをインストールする

list_plugins()
# If @voxel51/evaluation not listed:
download_plugin(url_or_repo="voxel51/fiftyone-plugins", plugin_names=["@voxel51/evaluation"])
enable_plugin(plugin_name="@voxel51/evaluation")

3. 評価パラメーターをユーザーに確認する

必ず以下の項目をユーザーに確認します：

• 予測フィールド名
• 正解データフィールド名
• 評価キー（この評価を識別する一意の識別子）
• 評価方法（coco、open-images、simple、top-k、binary）
• mAP を計算するかどうか（検出タスクの場合）

4. 評価オペレーターを使うためにアプリを起動する

launch_app(dataset_name="my-dataset")

5. 完了したらアプリを閉じる

close_app()

ワークフロー

ステップ 1：データセットとフィールドを確認する

list_datasets()
set_context(dataset_name="my-dataset")
dataset_summary(name="my-dataset")

以下を確認します：

• サンプル数
• 利用可能なラベルフィールドとその型
• 予測フィールド（モデルの出力）を特定する
• 正解データフィールド（アノテーション）を特定する

ラベルの型と互換性のある評価：

ラベルの型	評価方法	対応する方法
Detections	evaluate_detections()	coco、open-images
Polylines	evaluate_detections()	coco、open-images
Keypoints	evaluate_detections()	coco、open-images
TemporalDetections	evaluate_detections()	activitynet
Classification	evaluate_classifications()	simple、top-k、binary
Segmentation	evaluate_segmentations()	simple
Regression	evaluate_regressions()	simple

ステップ 2：評価プラグインがインストールされていることを確認する

list_plugins()

リストに @voxel51/evaluation がない場合：

download_plugin(
    url_or_repo="voxel51/fiftyone-plugins",
    plugin_names=["@voxel51/evaluation"]
)
enable_plugin(plugin_name="@voxel51/evaluation")

ステップ 3：アプリを起動する

launch_app(dataset_name="my-dataset")

ステップ 4：評価を実行する

ユーザーに以下を確認します：

• 予測フィールド（pred_field）
• 正解データフィールド（gt_field）
• 評価キー（eval_key） - 一意の識別子である必要があります
• 評価方法

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval",
        "method": "coco",
        "iou": 0.5,
        "compute_mAP": true
    }
)

ステップ 5：結果を確認する

評価後、データセットに新しいフィールドが追加されます：

• {eval_key}_tp - サンプルごとの真陽性数
• {eval_key}_fp - サンプルごとの偽陽性数
• {eval_key}_fn - サンプルごとの偽陰性数

偽陽性があるサンプルだけを表示する：

set_view(filters={"eval_fp": {"$gt": 0}})

アプリのモデル評価パネルを使って、以下を対話的に確認します：

• サマリーメトリクス（mAP、適合率、再現率）
• 混同行列
• クラスごとのパフォーマンス
• シナリオ分析

ステップ 6：評価パッチ（TP/FP/FN）を確認する

個々の真陽性、偽陽性、偽陰性を調べるには、Python SDK を使うようユーザーに案内します：

import fiftyone as fo

dataset = fo.load_dataset("my-dataset")

# Convert to evaluation patches view
eval_patches = dataset.to_evaluation_patches("eval")

# Count by type
print(eval_patches.count_values("type"))
# Output: {'fn': 246, 'fp': 4131, 'tp': 986}

# View only false positives
fp_view = eval_patches.match(F("type") == "fp")
session = fo.launch_app(view=fp_view)

ステップ 7：クリーンアップする

close_app()

評価の種類

検出評価

Detections、Polylines、Keypoints ラベルの場合。

COCO 形式（デフォルト）：

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_coco",
        "method": "coco",
        "iou": 0.5,
        "classwise": true,
        "compute_mAP": true
    }
)

パラメーター	型	デフォルト	説明
iou	float	0.5	マッチングに使用する IoU のしきい値
classwise	bool	true	同じクラスのオブジェクトのみをマッチングする
compute_mAP	bool	false	mAP、mAR、PR 曲線を計算する
use_masks	bool	false	IoU にインスタンスマスクを使用する（利用可能な場合）
iscrowd	string	null	群衆アノテーションの属性名
iou_threshs	string	null	mAP 用のカンマ区切り IoU しきい値
max_preds	int	null	mAP 用のサンプルごとの予測数の上限

Open Images 形式：

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_oi",
        "method": "open-images",
        "iou": 0.5
    }
)

追加パラメーターに対応しています：

• pos_label_field：評価対象にするクラスを指定する分類
• neg_label_field：評価対象にしないクラスを指定する分類

ActivityNet 形式（時間的）：

動画データセットの TemporalDetections の場合：

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_temporal",
        "method": "activitynet",
        "compute_mAP": true
    }
)

分類評価

Classification ラベルの場合。

シンプル（デフォルト）：

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_cls",
        "method": "simple"
    }
)

サンプルごとのフィールド {eval_key} には、予測が正しかったかどうかを示すブール値が保存されます。

Top-k：

logits フィールドを持つ予測が必要です：

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_topk",
        "method": "top-k",
        "k": 5
    }
)

バイナリー：

バイナリー分類器の場合：

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_binary",
        "method": "binary"
    }
)

サンプルごとのフィールド {eval_key} には、"tp"、"fp"、"tn"、または "fn" が保存されます。

セグメンテーションの評価

Segmentation ラベル用です。

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_seg",
        "method": "simple",
        "bandwidth": 5  # Optional: evaluate only boundary pixels
    }
)

パラメーター	型	デフォルト	説明
bandwidth	int	null	評価する輪郭に沿ったピクセル数（null = マスク全体）
average	string	"micro"	平均化方法：micro、macro、weighted、samples

サンプルごとのフィールド：

• {eval_key}_accuracy
• {eval_key}_precision
• {eval_key}_recall

回帰の評価

Regression ラベル用です。

execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_reg",
        "method": "simple",
        "metric": "squared_error"  # or "absolute_error"
    }
)

サンプルごとのフィールド {eval_key} には、誤差値が格納されます。

利用可能なメトリクス：

• 平均二乗誤差（MSE）
• 平均二乗誤差平方根（RMSE）
• 平均絶対誤差（MAE）
• 中央絶対誤差
• R² スコア
• 説明分散スコア
• 最大誤差

評価の管理

既存の評価を一覧表示する

execute_operator(
    operator_uri="@voxel51/evaluation/get_evaluation_info",
    params={
        "eval_key": "eval"
    }
)

評価ビューを読み込む

評価の実行時に使用したビューを正確に読み込みます：

execute_operator(
    operator_uri="@voxel51/evaluation/load_evaluation_view",
    params={
        "eval_key": "eval",
        "select_fields": false
    }
)

評価の名前を変更する

execute_operator(
    operator_uri="@voxel51/evaluation/rename_evaluation",
    params={
        "eval_key": "eval",
        "new_eval_key": "eval_v2"
    }
)

評価を削除する

execute_operator(
    operator_uri="@voxel51/evaluation/delete_evaluation",
    params={
        "eval_key": "eval"
    }
)

一般的なユースケース

ユースケース 1：物体検出モデルを評価する

# Verify dataset has detection fields
set_context(dataset_name="my-dataset")
dataset_summary(name="my-dataset")

# Launch app
launch_app(dataset_name="my-dataset")

# Run COCO-style evaluation with mAP
execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval",
        "method": "coco",
        "iou": 0.5,
        "compute_mAP": true
    }
)

# View samples with most false positives
set_view(filters={"eval_fp": {"$gt": 5}})

ユースケース 2：2 つの物体検出モデルを比較する

set_context(dataset_name="my-dataset")
launch_app(dataset_name="my-dataset")

# Evaluate first model
execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "model_a_predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_model_a",
        "method": "coco",
        "compute_mAP": true
    }
)

# Evaluate second model
execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "model_b_predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_model_b",
        "method": "coco",
        "compute_mAP": true
    }
)

# Use the Model Evaluation Panel to compare results

ユースケース 3：分類モデルを評価する

set_context(dataset_name="my-classification-dataset")
launch_app(dataset_name="my-classification-dataset")

# Simple classification evaluation
execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_cls",
        "method": "simple"
    }
)

# View misclassified samples
set_view(filters={"eval_cls": false})

ユースケース 4：異なる IoU しきい値で評価する

set_context(dataset_name="my-dataset")
launch_app(dataset_name="my-dataset")

# Strict evaluation (IoU 0.75)
execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_strict",
        "method": "coco",
        "iou": 0.75,
        "compute_mAP": true
    }
)

# Lenient evaluation (IoU 0.25)
execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_lenient",
        "method": "coco",
        "iou": 0.25,
        "compute_mAP": true
    }
)

ユースケース 5：セグメンテーションモデルを評価する

set_context(dataset_name="my-segmentation-dataset")
launch_app(dataset_name="my-segmentation-dataset")

# Full mask evaluation
execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_seg",
        "method": "simple"
    }
)

# Boundary-only evaluation (5 pixel bandwidth)
execute_operator(
    operator_uri="@voxel51/evaluation/evaluate_model",
    params={
        "pred_field": "predictions",
        "gt_field": "ground_truth",
        "eval_key": "eval_seg_boundary",
        "method": "simple",
        "bandwidth": 5
    }
)

Python SDK の代替方法

評価をより細かく制御し、結果全体にアクセスするには、Python SDK をユーザーに案内してください：

import fiftyone as fo
import fiftyone.zoo as foz

# Load dataset
dataset = fo.load_dataset("my-dataset")

# Evaluate detections
results = dataset.evaluate_detections(
    "predictions",
    gt_field="ground_truth",
    eval_key="eval",
    method="coco",
    iou=0.5,
    compute_mAP=True,
)

# Print classification report
results.print_report()

# Get mAP value
print(f"mAP: {results.mAP():.3f}")

# Plot confusion matrix (interactive)
plot = results.plot_confusion_matrix()
plot.show()

# Plot precision-recall curves
plot = results.plot_pr_curves(classes=["person", "car", "dog"])
plot.show()

# Convert to evaluation patches to view TP/FP/FN
eval_patches = dataset.to_evaluation_patches("eval")
print(eval_patches.count_values("type"))

# View false positives in the App
from fiftyone import ViewField as F
fp_view = eval_patches.match(F("type") == "fp")
session = fo.launch_app(view=fp_view)

Python SDK の評価メソッド：

• dataset.evaluate_detections() - 物体検出
• dataset.evaluate_classifications() - 分類
• dataset.evaluate_segmentations() - セマンティックセグメンテーション
• dataset.evaluate_regressions() - 回帰

結果オブジェクトのメソッド：

• results.print_report() - 分類レポートを出力
• results.print_metrics() - 集計メトリクスを出力
• results.mAP() - mAP 値を取得（物体検出のみ）
• results.mAR() - mAR 値を取得（物体検出のみ）
• results.plot_confusion_matrix() - インタラクティブな混同行列
• results.plot_pr_curves() - 適合率・再現率曲線
• results.plot_results() - 散布図（回帰のみ）

トラブルシューティング

エラー：「No suitable label fields」

• データセットには、互換性のある型のラベルフィールドが必要です
• dataset_summary() を使用して、利用可能なフィールドと型を確認してください

エラー：「No suitable ground truth fields」

• グラウンドトゥルースフィールドは予測フィールドと同じ型である必要があります
• Detections の予測と Classification のグラウンドトゥルースは比較できません

エラー：「Evaluation key already exists」

• 各評価には一意のキーが必要です
• 既存の評価を削除するか、別のキー名を使用してください

エラー：「Plugin not found」

• 評価プラグインをインストールします：

  download_plugin(url_or_repo="voxel51/fiftyone-plugins", plugin_names=["@voxel51/evaluation"])
  enable_plugin(plugin_name="@voxel51/evaluation")
  

mAP が計算されない

• params に compute_mAP: true を設定してください
• mAP を有意義な値にするには、画像ごとに複数の予測が必要です

評価に時間がかかる

• 大規模なデータセットの評価には時間がかかります
• まずフィルター済みビューを評価することを検討してください
• バックグラウンド処理には委任実行を使用してください

ベストプラクティス

1. 説明的な eval_keys を使用する - eval_yolov8_coco、eval_resnet_topk5
2. 評価を上書きしない - 評価の実行ごとに一意のキーを使用する
3. 同じ IoU で比較する - モデルを比較する際は、一貫した IoU しきい値を使用する
4. 最初にフィールドの型を確認する - 予測フィールドとグラウンドトゥルースフィールドに互換性があることを確認する
5. Model Evaluation Panel を使用する - インタラクティブな探索はスクリプトより簡単です
6. パッチを調べる - to_evaluation_patches() を使用してエラーを把握する

Resources

• FiftyOne Evaluation Guide
• Detection Evaluation
• Classification Evaluation
• Segmentation Evaluation
• Model Evaluation Panel
• Evaluation Plugin