Ultralytics Explorer API

はじめに

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

見る: Ultralytics Explorer APIの概要

インストール

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

pip install ultralytics[explorer]

使用法

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)

埋め込みテーブルの更新を強制したい場合は、以下を渡すことができます。 force=True 宛先 create_embeddings_table メソッド。

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

1. 類似性検索

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

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

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

pandasのデータフレームを取得します。 limit 入力に最も類似したデータポイントの数と、埋め込み空間でのそれらの距離。このデータセットを使用して、さらにフィルタリングを実行できます。

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())

from ultralytics import Explorer

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

similar = exp.get_similar(idx=1, limit=10)
print(similar.head())

# Search using multiple indices
similar = exp.get_similar(idx=[1, 10], limit=10)
print(similar.head())

類似画像のプロット

類似画像をプロットすることもできます。 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()

from ultralytics import Explorer

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

plt = exp.plot_similar(idx=1, limit=10)
plt.show()

2. 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()

3. SQLクエリ

データセットに対してSQLクエリを実行するには、以下を使用します。 sql_query メソッド。このメソッドは、SQLクエリを入力として受け取り、結果を含むpandasデータフレームを返します。

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())

SQLクエリ結果のプロット

SQLクエリの結果をプロットすることもできます。 plot_sql_query メソッド。このメソッドは、と同じ引数を取ります 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")

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

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

ベクターインデックスを作成します

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

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

利用可能なベクトルインデックスの種類と構成パラメータの詳細については、LanceDBインデックス作成のドキュメントを参照してください。将来的には、Explorer APIを介して直接ベクトルインデックスを作成できるようにする予定です。

5. 埋め込みの応用

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

類似度指標

Explorerには以下が付属しています。 similarity_index operation:

• 各データポイントがデータセットの残りの部分とどれだけ類似しているかを推定しようとします。
• これは、生成された埋め込み空間において、ある画像埋め込みがどれだけ他の画像よりも近いかを数えることによって行われます。 max_dist 生成された埋め込み空間内の現在の画像に対して、以下を考慮します。 top_k 一度に表示する類似画像数。

以下の列を含むpandasデータフレームを返します。

• 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

# 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 Exploration Exampleをご覧ください。

Ultralytics Explorerを使用して構築されたアプリ

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

近日公開

• [ ] データセットから特定のラベルをマージする。例 - すべてをインポート person COCOからのラベルと car シティスケープのラベル
• [ ] 指定された閾値よりも類似性インデックスが高い画像を削除する
• [ ] エントリのマージ/削除後、新しいデータセットを自動的に永続化する
• [ ] 高度なデータセットの可視化

よくある質問

Ultralytics Explorer APIは何に使用されますか？

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

Ultralytics Explorer APIをインストールするにはどうすればよいですか？

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

pip install ultralytics[explorer]

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

類似性検索に Ultralytics 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())

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

Ultralytics Explorer で LanceDB を使用する利点は何ですか？

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

Ultralytics 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())

より多くの例については、AIに質問するセクションをご覧ください。

📅 1年前に作成 ✏️ 5日前に更新

コメント