はじめる

Ultralytics Explorer API

コミュニティ向けのお知らせ ⚠️

ultralytics>=8.3.12以降、Ultralytics Explorerは削除されています。Explorerを使用するには、pip install ultralytics==8.3.11をインストールしてください。同様の(拡張された)データセット探索機能はUltralytics Platformで利用できます。

はじめに#

Explorer APIは、データセットを探索するためのPython APIです。SQLクエリ、ベクトル類似度検索、セマンティック検索を使用したデータセットのフィルタリングと検索に対応しています。



視聴: Ultralytics Explorer API の概要

インストール#

Explorerの一部の機能は外部ライブラリに依存しています。Explorerを使用すると、これらのライブラリは自動的にインストールされます。依存関係を手動でインストールするには、次のコマンドを使用してください。

pip install "ultralytics[explorer]==8.3.11"

使用方法#

from ultralytics import Explorer

# Explorerオブジェクトを作成
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# データセットの埋め込みを作成
explorer.create_embeddings_table()

# 指定した画像に類似する画像を検索
df = explorer.get_similar(img="path/to/image.jpg")

# または、指定したインデックスに類似する画像を検索
df = explorer.get_similar(idx=0)
注

特定のデータセットとモデルの組み合わせに対する埋め込みテーブルは、一度だけ作成され、再利用されます。内部ではLanceDBを使用しており、ディスク上でスケールするため、メモリ不足になることなく、COCOのような大規模データセットの埋め込みを作成して再利用できます。

埋め込みテーブルを強制的に更新するには、create_embeddings_tableメソッドにforce=Trueを渡します。

高度な分析を行うには、LanceDBのテーブルオブジェクトに直接アクセスできます。詳細は埋め込みテーブルの操作のセクションをご覧ください。

類似度検索は、ベクトル検索とも呼ばれ、指定した画像に類似する画像を検索する手法です。類似した画像は類似した埋め込みを持つという考えに基づいています。埋め込みテーブルを作成した後は、次のいずれかの方法で類似度検索を実行できます。

  • データセット内の指定したインデックスまたはインデックスのリストを対象にする場合: exp.get_similar(idx=[1,10], limit=10)
  • データセットに含まれない任意の画像または画像のリストを対象にする場合: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

複数の入力がある場合は、それらの埋め込みの集約値が使用されます。

入力に最も類似するlimit個のデータポイントと、埋め込み空間での距離を含むpandasのDataFrameが返されます。このデータセットを使って、さらにフィルタリングできます。

セマンティック検索
from ultralytics import Explorer

# Explorerオブジェクトを作成
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

similar = exp.get_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
print(similar.head())

# 複数の画像を使って検索
similar = exp.get_similar(
    img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
    limit=10,
)
print(similar.head())

類似画像のプロット#

plot_similarメソッドを使って類似画像をプロットすることもできます。このメソッドはget_similarと同じ引数を受け取り、類似画像をグリッド状にプロットします。

類似画像のプロット
from ultralytics import Explorer

# Explorerオブジェクトを作成
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

plt = exp.plot_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
plt.show()

2. Ask AI(自然言語クエリ)#

この機能では、SQLを書かずに自然言語でデータセットをフィルタリングできます。AIを活用したクエリ生成ツールがプロンプトをクエリに変換し、一致する結果を返します。たとえば、「人が1人と犬が2匹だけ写っている画像を100枚見せてください。他の物体が写っていてもかまいません」と尋ねると、クエリが生成され、該当する結果が表示されます。 注: この機能はLLMを使用するため、結果は確率的であり、不正確な場合があります。

Ask AI
from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# Explorerオブジェクトを作成
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

df = exp.ask_ai("show me 100 images with exactly one person and 2 dogs. There can be other objects too")
print(df.head())

# 結果をプロット
plt = plot_query_result(df)
plt.show()

3. SQLクエリ#

sql_queryメソッドを使って、データセットに対してSQLクエリを実行できます。このメソッドはSQLクエリを入力として受け取り、結果を含むpandasのDataFrameを返します。

SQLクエリ
from ultralytics import Explorer

# Explorerオブジェクトを作成
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

df = exp.sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%'")
print(df.head())

SQLクエリの結果をプロット#

plot_sql_queryメソッドを使って、SQLクエリの結果をプロットすることもできます。このメソッドはsql_queryと同じ引数を受け取り、結果をグリッド状にプロットします。

SQLクエリの結果をプロット
from ultralytics import Explorer

# Explorerオブジェクトを作成
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# SQLクエリをプロット
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. 埋め込みテーブルの操作#

埋め込みテーブルを直接操作することもできます。埋め込みテーブルの作成後、Explorer.tableを使ってアクセスできます。

ヒント

Explorerは内部でLanceDBのテーブルを使用します。Explorer.tableオブジェクトを使ってこのテーブルに直接アクセスし、rawクエリの実行や、前処理・後処理フィルターのプッシュダウンなどを行えます。

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()
table = exp.table

テーブルで実行できる操作の例を以下に示します。

埋め込みを取得#

例
from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()
table = exp.table

embeddings = table.to_pandas()["vector"]
print(embeddings)

前処理・後処理フィルターを使った高度なクエリ#

例
from ultralytics import Explorer

exp = Explorer(model="yolo11n.pt")
exp.create_embeddings_table()
table = exp.table

# ダミー埋め込み
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

ベクトルインデックスを作成#

大規模データセットを使用する場合は、クエリを高速化する専用のベクトルインデックスも作成できます。これは、LanceDBテーブルでcreate_indexメソッドを使って行います。

table.create_index(num_partitions=..., num_sub_vectors=...)

5. 埋め込みの活用例#

埋め込みテーブルを使って、さまざまな探索的分析を行えます。以下に例を示します。

類似度インデックス#

Explorerにはsimilarity_index操作が備わっています。

  • この操作では、各データポイントがデータセット内の他のデータポイントとどの程度類似しているかを推定します。
  • 生成された埋め込み空間で、現在の画像からmax_dist以内にある画像の埋め込み数を数えることで類似度を推定します。一度に考慮する類似画像の数はtop_kです。

次の列を含むpandasのDataFrameが返されます。

  • idx: データセット内の画像のインデックス
  • im_file: 画像ファイルへのパス
  • count: 現在の画像からmax_dist以内にある、データセット内の画像の数
  • sim_im_files: 類似度がcount番目までの画像のパスのリスト
ヒント

特定のデータセット、モデル、max_dist、top_kについては、一度生成した類似度インデックスが再利用されます。データセットを変更した場合や、類似度インデックスを再生成する必要がある場合は、force=Trueを渡してください。

類似度インデックス
from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

類似度インデックスを使用して、データセットをフィルタリングするためのカスタム条件を作成できます。たとえば、次のコードでは、データセット内に類似画像が30枚を超えて存在する画像を一覧表示します。これらは近似重複画像の削除に適した候補です。

import numpy as np

sim_count = np.array(sim_idx["count"])
sim_idx["im_file"][sim_count > 30]

埋め込み空間を可視化#

選択したプロットツールを使用して、埋め込み空間を可視化することもできます。以下は、PCAで埋め込みの次元を削減し、Matplotlibでプロットする簡単な例です。

import matplotlib.pyplot as plt
from sklearn.decomposition import PCA

# 可視化のため、PCAを使用して次元を3つの成分に削減
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Matplotlib Axes3Dを使って3D散布図を作成
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# 散布図
ax.scatter(reduced_data[:, 0], reduced_data[:, 1], reduced_data[:, 2], alpha=0.5)
ax.set_title("3D Scatter Plot of Reduced 256-Dimensional Data (PCA)")
ax.set_xlabel("Component 1")
ax.set_ylabel("Component 2")
ax.set_zlabel("Component 3")

plt.show()

Explorer APIを使って、独自のCVデータセット探索レポートの作成を始めましょう。アイデアを得るには、VOC探索の例をご覧ください。

Ultralytics Explorerを使って構築されたアプリ#

Explorer GUIはExplorer APIを基盤として構築されています。

よくある質問#

  • Ultralytics Explorer APIは、データセット探索用に設計されています。SQLクエリ、ベクトル類似度検索、セマンティック検索を使用してデータセットをフィルタリングおよび検索でき、Ultralyticsモデルを使用するコンピュータービジョンタスクの大規模データセットにも対応します。

  • Ultralytics Explorer APIとその依存関係をインストールするには、次のコマンドを使用します。

    pip install "ultralytics[explorer]==8.3.11"

    これにより、Explorer APIの機能に必要な外部ライブラリがすべて自動的にインストールされます。追加のセットアップについては、ドキュメントのインストールのセクションを参照してください。

  • Ultralytics Explorer APIでは、埋め込みテーブルを作成し、類似画像をクエリすることで類似検索を実行できます。基本的な例を次に示します。

    from ultralytics import Explorer
    
    # Explorerオブジェクトを作成
    explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
    explorer.create_embeddings_table()
    
    # 指定した画像に類似する画像を検索
    similar_images_df = explorer.get_similar(img="path/to/image.jpg")
    print(similar_images_df.head())

    詳しくは、類似検索のセクションをご覧ください。

  • Ultralytics Explorerの内部で使用されるLanceDBは、スケーラブルなディスク上の埋め込みテーブルを提供します。これにより、メモリ不足に陥ることなく、COCOなどの大規模なデータセットの埋め込みを作成して再利用できます。これらのテーブルは一度だけ作成すれば再利用できるため、データ処理の効率が向上します。

  • Ask AI機能では、自然言語のクエリを使用してデータセットをフィルタリングできます。この機能はLLMを活用し、バックグラウンドでクエリをSQLクエリに変換します。例を次に示します。

    from ultralytics import Explorer
    
    # Explorerオブジェクトを作成
    explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
    explorer.create_embeddings_table()
    
    # 自然言語でクエリを実行
    query_result = explorer.ask_ai("show me 100 images with exactly one person and 2 dogs. There can be other objects too")
    print(query_result.head())

    その他の例については、Ask AIのセクションをご覧ください。

コメント2

質問したり、結果を共有したり、ほかの人をサポートしたりできます。

  1. Jie Liu

    I have downloaded ultralytics-8.3.118 github zip package and install it with pip install -e .. Then I use pip install ultralytics[explorer] to install explorer, but I got a error as followed

    Requirement already satisfied: ultralytics[explorer] in /data/miniconda3/envs/app/lib/python3.10/site-packages (8.3.118)
    WARNING: ultralytics 8.3.118 does not provide the extra 'explorer'
    Requirement already satisfied: numpy<=2.1.1,>=1.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.26.4)
    Requirement already satisfied: matplotlib>=3.3.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (3.10.1)
    Requirement already satisfied: opencv-python>=4.6.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.11.0.86)
    Requirement already satisfied: pillow>=7.1.2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (11.2.1)
    Requirement already satisfied: pyyaml>=5.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (6.0.2)
    Requirement already satisfied: requests>=2.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.32.3)
    Requirement already satisfied: scipy>=1.4.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.15.2)
    Requirement already satisfied: torch>=1.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.3.1)
    Requirement already satisfied: torchvision>=0.9.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.18.1)
    Requirement already satisfied: tqdm>=4.64.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.67.1)
    Requirement already satisfied: psutil in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (7.0.0)
    Requirement already satisfied: py-cpuinfo in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (9.0.0)
    Requirement already satisfied: pandas>=1.1.4 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.2.3)
    Requirement already satisfied: seaborn>=0.11.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.13.2)
    Requirement already satisfied: ultralytics-thop>=2.0.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.0.14)
    Requirement already satisfied: contourpy>=1.0.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.3.2)
    Requirement already satisfied: cycler>=0.10 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (0.12.1)
    Requirement already satisfied: fonttools>=4.22.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (4.57.0)
    Requirement already satisfied: kiwisolver>=1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.4.8)
    Requirement already satisfied: packaging>=20.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (24.2)
    Requirement already satisfied: pyparsing>=2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (3.2.3)
    Requirement already satisfied: python-dateutil>=2.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (2.9.0.post0)
    Requirement already satisfied: pytz>=2020.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2022.7.1)
    Requirement already satisfied: tzdata>=2022.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2025.2)
    Requirement already satisfied: charset-normalizer<4,>=2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.4.1)
    Requirement already satisfied: idna<4,>=2.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.10)
    Requirement already satisfied: urllib3<3,>=1.21.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (1.26.20)
    Requirement already satisfied: certifi>=2017.4.17 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (2025.4.26)
    Requirement already satisfied: filelock in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.18.0)
    Requirement already satisfied: typing-extensions>=4.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (4.13.2)
    Requirement already satisfied: sympy in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (1.13.3)
    Requirement already satisfied: networkx in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.4.2)
    Requirement already satisfied: jinja2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.1.6)
    Requirement already satisfied: fsspec in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2025.3.2)
    Requirement already satisfied: nvidia-cuda-nvrtc-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cuda-runtime-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cuda-cupti-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cudnn-cu12==8.9.2.26 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (8.9.2.26)
    Requirement already satisfied: nvidia-cublas-cu12==12.1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.3.1)
    Requirement already satisfied: nvidia-cufft-cu12==11.0.2.54 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.0.2.54)
    Requirement already satisfied: nvidia-curand-cu12==10.3.2.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (10.3.2.106)
    Requirement already satisfied: nvidia-cusolver-cu12==11.4.5.107 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.4.5.107)
    Requirement already satisfied: nvidia-cusparse-cu12==12.1.0.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.0.106)
    Requirement already satisfied: nvidia-nccl-cu12==2.20.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.20.5)
    Requirement already satisfied: nvidia-nvtx-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: triton==2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.3.1)
    Requirement already satisfied: nvidia-nvjitlink-cu12 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from nvidia-cusolver-cu12==11.4.5.107->torch>=1.8.0->ultralytics[explorer]) (12.8.93)
    Requirement already satisfied: six>=1.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from python-dateutil>=2.7->matplotlib>=3.3.0->ultralytics[explorer]) (1.17.0)
    Requirement already satisfied: MarkupSafe>=2.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from jinja2->torch>=1.8.0->ultralytics[explorer]) (3.0.2)
    Requirement already satisfied: mpmath<1.4,>=1.1.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from sympy->torch>=1.8.0->ultralytics[explorer]) (1.3.0)

    when run code

    from ultralytics import Explorer
    
    # Create an Explorer object
    explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
    
    # Create embeddings for your dataset
    explorer.create_embeddings_table()
    
    # Search for similar images to a given image/images
    dataframe = explorer.get_similar(img="path/to/image.jpg")
    
    # Or search for similar images to a given index/indices
    dataframe = explorer.get_similar(idx=0)

    The error has arisen

    Traceback (most recent call last):
      File "/data/liujie/data/ultralytics-8.3.13/tutorial/debug/explorer.py", line 1, in <module>
        from ultralytics import Explorer
    ImportError: cannot import name 'Explorer' from 'ultralytics' (/data/liujie/data/ultralytics-8.3.118/ultralytics/__init__.py)

    please help me to install and use explorer

    1. Glenn JocherUltralytics(編集済み)

      Hi @keeper-jie,

      The issue you're experiencing is because Ultralytics Explorer has been removed since version 8.3.12, and you're using version 8.3.118. That's why you're seeing the warning that the 'explorer' extra is not provided and why you can't import the Explorer class.

      As noted in our documentation, we've moved this functionality to Ultralytics Platform, our platform that offers similar and enhanced capabilities for exploring, visualizing, and managing your datasets without writing code.

      If you specifically need the Explorer API functionality in your code, you would need to downgrade to a version prior to 8.3.12. However, we recommend trying Ultralytics Platform instead, as it provides an improved experience with all the dataset exploration features you're looking for.

      Let me know if you need any further assistance with Ultralytics Platform or if you have any other questions.