Link to this sectionUltralytics Explorer API#

Link to this sectionはじめに#

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

Link to this sectionインストール#

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

pip install ultralytics[explorer]

Link to this section使用方法#

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
df = explorer.get_similar(img="path/to/image.jpg")

# Or search for similar images to a given index/indices
df = explorer.get_similar(idx=0)

In case you want to force update the embeddings table, you can pass force=True to create_embeddings_table method.

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

Link to this section類似性検索#

類似性検索は、特定の画像に似た画像を見つけるための手法です。似た画像は似た埋め込みを持つという考えに基づいています。埋め込みテーブルが構築されたら、以下のいずれかの方法でセマンティック検索を実行できます。

• データセット内の特定のインデックスまたはインデックスのリストに対して: 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

# create an Explorer object
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())

# Search using multiple indices
similar = exp.get_similar(
    img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
    limit=10,
)
print(similar.head())

Link to this section類似画像のプロット#

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

from ultralytics import Explorer

# create an Explorer object
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()

Link to this sectionAsk AI（自然言語クエリ）#

この機能を使用すると、SQLを書かずに自然言語でデータセットをフィルタリングできます。AI駆動のクエリジェネレーターがプロンプトをクエリに変換し、一致する結果を返します。例えば、「ちょうど1人の人間と2匹の犬が写っている画像を100枚表示して。他のオブジェクトが含まれていても構わない」と尋ねると、クエリが生成され、その結果が表示されます。 注意：この機能はLLMを使用するため、結果は確率的であり、不正確な場合があります。

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# create an Explorer object
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())

# plot the results
plt = plot_query_result(df)
plt.show()

Link to this sectionSQLクエリ#

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

from ultralytics import Explorer

# create an Explorer object
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())

Link to this sectionSQLクエリ結果のプロット#

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

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# plot the SQL Query
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

Link to this section埋め込みテーブルの操作#

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

from ultralytics import Explorer

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

テーブルで実行できる操作の例をいくつか示します。

Link to this section生の埋め込みを取得する#

from ultralytics import Explorer

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

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

Link to this sectionプリフィルタとポストフィルタによる高度なクエリ#

from ultralytics import Explorer

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

# Dummy embedding
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

Link to this sectionベクトルインデックスの作成#

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

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

Link to this section埋め込みのアプリケーション#

埋め込みテーブルを使用して、さまざまな探索的分析を実行できます。いくつかの例を挙げます。

Link to this section類似性インデックス#

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]

Link to this section埋め込み空間の可視化#

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

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

# Reduce dimensions using PCA to 3 components for visualization in 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Create a 3D scatter plot using Matplotlib Axes3D
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# Scatter plot
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探索例を確認してください。

Link to this sectionUltralytics Explorerを使用して構築されたアプリ#

Explorer APIに基づいたGUIデモをお試しください

Link to this sectionFAQ#

Link to this sectionUltralytics Explorer APIは何に使用されますか？#

Ultralytics Explorer APIは、包括的なデータセット探索のために設計されています。SQLクエリ、ベクトル類似性検索、セマンティック検索を使用してデータセットをフィルタリングおよび検索できます。この強力なPython APIは大規模データセットを処理でき、Ultralyticsモデルを使用したさまざまなコンピュータビジョンタスクに最適です。

Link to this sectionUltralytics Explorer APIのインストール方法を教えてください。#

Ultralytics Explorer APIとその依存関係をインストールするには、以下のコマンドを使用してください。

pip install ultralytics[explorer]

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

Link to this sectionUltralytics Explorer APIを使用して類似性検索を行うにはどうすればよいですか？#

Ultralytics Explorer APIを使用すると、埋め込みテーブルを作成し、それを照会して類似画像を検索することで、類似性検索を実行できます。基本的な例を次に示します。

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
explorer.create_embeddings_table()

# Search for similar images to a given image
similar_images_df = explorer.get_similar(img="path/to/image.jpg")
print(similar_images_df.head())

詳細については、類似性検索セクションをご覧ください。

Link to this sectionUltralytics ExplorerでLanceDBを使用する利点は何ですか？#

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

Link to this sectionUltralytics Explorer APIのAsk AI機能はどのように機能しますか？#

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

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
explorer.create_embeddings_table()

# Query with natural language
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セクションを確認してください。