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. 启动 App 以使用评估操作

launch_app(dataset_name="my-dataset")

5. 完成后关闭 App

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：启动 App

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}})

使用 App 中的模型评估面板交互式探索：

• 汇总指标（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：比较两个检测模型

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