Ultralytics Explorer API#

はじめに#

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

インストール#

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)

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

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

1. 類似検索#

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

• データセット内の指定したインデックスまたはインデックスのリストを対象にする場合: 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を使用するため、結果は確率的であり、不正確な場合があります。

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を返します。

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と同じ引数を受け取り、結果をグリッド状にプロットします。

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を使ってアクセスできます。

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番目までの画像のパスのリスト

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

類似度インデックスを使って、データセットをフィルタリングする独自の条件を作成できます。たとえば、次のコードを使って、データセット内に類似画像がない画像を除外できます。

import numpy as np

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

埋め込み空間を可視化#

任意のプロットツールを使って、埋め込み空間を可視化することもできます。たとえば、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 APIをベースにしたGUIデモをお試しください

よくある質問#