Ultralytics Explorer API
コミュニティノート ⚠️
〜の時点で ultralytics>=8.3.10
、Ultralyticsエクスプローラーのサポートは非推奨となりました。しかし、ご心配なく!同様の、さらに強化された機能に、以下からアクセスできるようになりました。 Ultralytics HUBは、ワークフローを効率化するために設計された、直感的でコード不要のプラットフォームです。Ultralytics HUBを使用すると、コードを1行も記述せずに、データの探索、視覚化、管理を簡単に行うことができます。ぜひチェックして、その強力な機能を活用してください!🚀
はじめに
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)
注
特定のデータセットとモデルのペアに対する埋め込みテーブルは、一度だけ作成され、再利用されます。これらは内部でLanceDBを使用しており、オンディスクでスケールするため、メモリ不足になることなく、COCOのような大規模なデータセットの埋め込みを作成および再利用できます。
埋め込みテーブルの更新を強制したい場合は、以下を渡すことができます。 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を使用して動作するため、結果は確率的であり、場合によっては誤った結果になることがあります。
AIに質問
from ultralytics import Explorer
from ultralytics.data.explorer import plot_query_result
# 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データフレームを返します。
SQLクエリ
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
そして、結果をグリッドでプロットします。
SQLクエリ結果のプロット
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
ヒント
Explorerは以下で動作します。 LanceDB テーブルを内部的に使用します。このテーブルには、以下を使用して直接アクセスできます。 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
類似画像
ヒント
特定のデータセット、モデルについて max_dist
& top_k
一度生成された類似度インデックスは再利用されます。データセットが変更された場合、または単に類似度インデックスを再生成する必要がある場合は、以下を渡すことができます。 force=True
.
類似度指標
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に質問するセクションをご覧ください。