fiftyone-find-duplicates

FiftyOne データセット内の重複を検出する

主要な指示

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

1. 最初にコンテキストを設定する

set_context(dataset_name="my-dataset")

2. FiftyOne App を起動する

Brain オペレーターは委譲されており、アプリが必要です。

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. 完了したらアプリを閉じる

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 = ある程度類似

このオペレーターは、次の 2 つの保存済みビューを自動的に作成します。

• near duplicates：近似重複であるすべてのサンプル
• representatives of near duplicates：各グループから 1 つの代表サンプル

ステップ 6：アプリで重複を表示する

重複を検出したら、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 オペレーターを使う（グループごとに代表サンプルを 1 つ残します）

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

オプション B：アプリの UI から手動で削除する

1. set_view(exists=["near_dup_id"]) を使って重複を表示します
2. http://localhost:5151/ のアプリでサンプルを確認します
3. 削除するサンプルを選択します
4. アプリの削除アクションを使います

ステップ 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」

• 原因：委譲されたオペレーターで UI トリガーを使用するには、App executor が必要です
• 解決策：結果の確認と削除の手動完了のため、ユーザーを 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 を使用します
• 大規模なデータセットはバッチ処理します

ベストプラクティス

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 時間

メモリ要件：

• 埋め込みは画像 1 枚あたり約 2KB
• 類似度インデックスは画像 1 枚あたり約 4～8KB

リソース

• FiftyOne Brain のドキュメント
• Brain プラグインのソース