fiftyone-find-duplicates

在 FiftyOne 数据集中查找重复项

关键指令

始终遵循以下规则：

1. 先设置上下文

set_context(dataset_name="my-dataset")

2. 启动 FiftyOne App

Brain 操作符由委派执行，且需要 App：

launch_app()

等待 5-10 秒进行初始化。

3. 动态发现操作符

# List all brain operators
list_operators(builtin_only=False)

# Get schema for specific operator
get_operator_schema(operator_uri="@voxel51/brain/compute_similarity")

4. 查找重复项之前先计算嵌入

execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={"brain_key": "img_sim", "model": "mobilenet-v2-imagenet-torch"}
)

5. 完成后关闭 App

close_app()

完整工作流

步骤 1：设置

# Set context
set_context(dataset_name="my-dataset")

# Launch app (required for brain operators)
launch_app()

步骤 2：验证 Brain 插件

# Check if brain plugin is available
list_plugins(enabled=True)

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

步骤 3：发现 Brain 操作符

# List all available operators
list_operators(builtin_only=False)

# Get schema for compute_similarity
get_operator_schema(operator_uri="@voxel51/brain/compute_similarity")

# Get schema for find_duplicates
get_operator_schema(operator_uri="@voxel51/brain/find_duplicates")

步骤 4：计算相似度

# Execute operator to compute embeddings
execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={
        "brain_key": "img_duplicates",
        "model": "mobilenet-v2-imagenet-torch"
    }
)

步骤 5：查找近似重复项

execute_operator(
    operator_uri="@voxel51/brain/find_near_duplicates",
    params={
        "similarity_index": "img_duplicates",
        "threshold": 0.3
    }
)

阈值指南（基于距离，数值越低表示越相似）：

• 0.1 = 非常相似（近乎完全重复）
• 0.3 = 近似重复（推荐默认值）
• 0.5 = 相似图像
• 0.7 = 相似度较低

此操作符会自动创建两个已保存视图：

• near duplicates：所有近似重复的样本
• representatives of near duplicates：每组近似重复项中的一个代表样本

步骤 6：在 App 中查看重复项

查找重复项后，使用 set_view 在 FiftyOne App 中显示这些样本：

选项 A：按 near_dup_id 字段筛选

# Show all samples that have a near_dup_id (all duplicates)
set_view(exists=["near_dup_id"])

选项 B：显示特定的重复项组

# Show samples with a specific duplicate group ID
set_view(filters={"near_dup_id": 1})

选项 C：加载已保存的视图（如果有）

# Load the automatically created saved view
set_view(view_name="near duplicates")

选项 D：清除筛选条件以显示所有样本

clear_view()

find_near_duplicates 操作符会向样本添加 near_dup_id 字段。ID 相同的样本互为重复项。

步骤 7：删除重复项

选项 A：使用 deduplicate 操作符（每组保留一个代表样本）

execute_operator(
    operator_uri="@voxel51/brain/deduplicate_near_duplicates",
    params={}
)

选项 B：在 App UI 中手动删除

1. 使用 set_view(exists=["near_dup_id"]) 显示重复项
2. 在 http://localhost:5151/ 的 App 中检查样本
3. 选择要删除的样本
4. 使用 App 中的删除操作

步骤 8：清理

close_app()

可用工具

会话视图工具

工具	说明
set_view(exists=[...])	筛选字段值不为 None 的样本
set_view(filters={...})	按确切字段值筛选样本
set_view(tags=[...])	按标签筛选样本
set_view(sample_ids=[...])	选择指定的样本 ID
set_view(view_name="...")	按名称加载已保存的视图
clear_view()	清除筛选条件，显示所有样本

用于查找重复项的 Brain 操作符

使用 list_operators() 发现操作符，并使用 get_operator_schema() 查看参数：

操作符	说明
@voxel51/brain/compute_similarity	计算嵌入并建立相似度索引
@voxel51/brain/find_near_duplicates	查找近似重复样本
@voxel51/brain/deduplicate_near_duplicates	删除重复项，保留代表样本
@voxel51/brain/find_exact_duplicates	查找完全重复的媒体文件
@voxel51/brain/deduplicate_exact_duplicates	删除完全重复项
@voxel51/brain/compute_uniqueness	计算唯一性分数

常见用例

用例 1：删除完全重复项

用于意外重复的文件（字节完全相同）：

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

execute_operator(
    operator_uri="@voxel51/brain/find_exact_duplicates",
    params={}
)

execute_operator(
    operator_uri="@voxel51/brain/deduplicate_exact_duplicates",
    params={}
)

close_app()

用例 2：查找并检查近似重复项

用于视觉上相似但并不完全相同的图像：

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

# Compute embeddings
execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={"brain_key": "near_dups", "model": "mobilenet-v2-imagenet-torch"}
)

# Find duplicates
execute_operator(
    operator_uri="@voxel51/brain/find_near_duplicates",
    params={"similarity_index": "near_dups", "threshold": 0.3}
)

# View duplicates in the App
set_view(exists=["near_dup_id"])

# After review, deduplicate
execute_operator(
    operator_uri="@voxel51/brain/deduplicate_near_duplicates",
    params={}
)

# Clear view and close
clear_view()
close_app()

用例 3：按相似度排序

查找与特定样本相似的图像：

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

execute_operator(
    operator_uri="@voxel51/brain/compute_similarity",
    params={"brain_key": "search"}
)

execute_operator(
    operator_uri="@voxel51/brain/sort_by_similarity",
    params={
        "brain_key": "search",
        "query_id": "sample_id_here",
        "k": 20
    }
)

close_app()

故障排除

错误：“No executor available”

• 原因：委托操作需要 App 执行器来触发 UI
• 解决方案：引导用户前往 App UI 查看结果并手动完成删除
• 受影响的操作：find_near_duplicates、deduplicate_near_duplicates

错误：“Brain key not found”

• 原因：尚未计算嵌入
• 解决方案：先使用 brain_key 运行 compute_similarity

错误：“Operator not found”

• 原因：未安装 Brain 插件
• 解决方案：使用 download_plugin() 和 enable_plugin() 安装

错误：“Missing dependency”（例如 torch、tensorflow）

• MCP 服务会自动检测缺失的依赖
• 响应中包含 missing_package 和 install_command
• 响应示例：

  {
    "error_type": "missing_dependency",
    "missing_package": "torch",
    "install_command": "pip install torch"
  }
  

• 提议为用户运行安装命令
• 安装后，重启 MCP 服务并重试

相似度计算速度较慢

• 使用更快的模型：mobilenet-v2-imagenet-torch
• 如果有 GPU，则使用 GPU
• 分批处理大型数据集

最佳实践

1. 动态发现——使用 list_operators() 和 get_operator_schema() 获取当前的操作名称和参数
2. 从默认阈值（0.3）开始，并根据需要调整
3. 删除前先检查——引导用户前往 App 检查重复项
4. 存储嵌入——通过 brain_key 为多个操作重复使用
5. 妥善处理执行器错误——必要时引导用户前往 App UI

性能说明

嵌入计算时间：

• 1,000 张图像：约 1-2 分钟
• 10,000 张图像：约 10-15 分钟
• 100,000 张图像：约 1-2 小时

内存需求：

• 每张图像的嵌入约需 2KB
• 每张图像的相似度索引约需 4-8KB

资源

• FiftyOne Brain 文档
• Brain 插件源代码