fiftyone-find-duplicates

用途

该技能用于在 FiftyOne 数据集中查找重复或近似重复的图像，基于 brain 相似度计算实现。适用于数据集去重、查找相似图像等场景。

主要能力

• 查找完全重复的媒体文件（find_exact_duplicates）
• 查找视觉上相似但不完全相同的近似重复图像（find_near_duplicates）
• 计算图像嵌入与相似度索引（compute_similarity）
• 删除重复项并保留每组代表样本（deduplicate_near_duplicates、deduplicate_exact_duplicates）
• 计算唯一性分数（compute_uniqueness）
• 按相似度排序（sort_by_similarity）

使用方式

前置要求

Brain 算子需要 FiftyOne App 执行器，因此必须先启动 App。

基本流程

1. 设置上下文：set_context(dataset_name="my-dataset")
2. 启动 App：launch_app()，等待 5-10 秒初始化
3. 动态发现算子：使用 list_operators(builtin_only=False) 列出所有 brain 算子，使用 get_operator_schema(operator_uri="...") 查看具体算子参数
4. 计算嵌入：

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

1. 查找近似重复：

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

1. 在 App 中查看重复项：可使用 set_view(exists=["near_dup_id"]) 显示所有重复样本，或 set_view(filters={"near_dup_id": 1}) 显示特定重复组，或 set_view(view_name="near duplicates") 加载自动保存的视图
2. 删除重复：使用 deduplicate_near_duplicates 算子保留每组代表样本，或在 App UI 中手动选择删除
3. 清理：close_app()

阈值指南（基于距离，越低越相似）

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

可用工具

会话视图工具：

• set_view(exists=[...])：筛选字段值非 None 的样本
• set_view(filters={...})：按字段精确值筛选样本
• set_view(tags=[...])：按标签筛选样本
• set_view(sample_ids=[...])：选择特定样本 ID
• set_view(view_name="...")：按名称加载已保存视图
• clear_view()：清除筛选，显示所有样本

Brain 算子：

• @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：计算唯一性分数

适用场景

• 移除意外重复的文件（字节完全相同）
• 查找并审查视觉相似但不完全相同的图像
• 按相似度排序，查找与特定样本相似的图像

限制与注意事项

• Brain 算子需要 FiftyOne App 执行器，必须启动 App
• 使用前需先计算嵌入（compute_similarity），否则会报 "Brain key not found"
• 若 brain 插件未安装，需通过 download_plugin(url_or_repo="voxel51/fiftyone-plugins", plugin_names=["@voxel51/brain"]) 和 enable_plugin(plugin_name="@voxel51/brain") 安装启用
• 缺少依赖（如 torch、tensorflow）时，MCP 服务器会自动检测并返回缺失包名和安装命令，安装后需重启 MCP 服务器并重试
• 相似度计算较慢，可使用更快的模型（mobilenet-v2-imagenet-torch）、GPU 或分批处理大数据集
• 性能参考：1,000 张图像约 1-2 分钟，10,000 张约 10-15 分钟，100,000 张约 1-2 小时；嵌入约每张 2KB，相似度索引约每张 4-8KB
• 删除前建议在 App 中审查重复项
• 遇到 "No executor available" 错误时，需引导用户在 App UI 中查看结果并手动完成删除

最佳实践

• 动态发现算子：使用 list_operators() 和 get_operator_schema() 获取当前算子名称和参数
• 从默认阈值 0.3 开始，按需调整
• 删除前审查：引导用户在 App 中检查重复项
• 存储嵌入：通过 brain_key 复用嵌入进行多次操作
• 优雅处理执行器错误：需要时引导用户使用 App UI