Ultralytics Explorer API#

Einleitung#

Die Explorer API ist eine Python-API zum Erkunden deiner Datensätze. Sie unterstützt das Filtern und Durchsuchen deines Datensatzes mithilfe von SQL-Abfragen, Vektorähnlichkeitssuche und semantischer Suche.

Installation#

Explorer verwendet für einige Funktionen externe Bibliotheken. Diese werden automatisch installiert, wenn du Explorer verwendest. Um diese Abhängigkeiten manuell zu installieren, verwende den folgenden Befehl:

pip install ultralytics[explorer]

Verwendung#

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)

Wenn du die Tabelle mit den Embeddings zwangsweise aktualisieren möchtest, kannst du force=True an die Methode create_embeddings_table übergeben.

Du kannst direkt auf das LanceDB-Tabellenobjekt zugreifen, um erweiterte Analysen durchzuführen. Weitere Informationen findest du im Abschnitt zur Arbeit mit der Embedding-Tabelle.

1. Ähnlichkeitssuche#

Die Ähnlichkeitssuche ist eine Technik, um zu einem bestimmten Bild ähnliche Bilder zu finden. Sie basiert auf der Annahme, dass ähnliche Bilder ähnliche Embeddings haben. Sobald die Embedding-Tabelle erstellt wurde, kannst du die semantische Suche auf eine der folgenden Arten ausführen:

• Für einen bestimmten Index oder eine Liste von Indizes im Datensatz: exp.get_similar(idx=[1,10], limit=10)
• Für ein beliebiges Bild oder eine Liste von Bildern, die nicht im Datensatz enthalten sind: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

Bei mehreren Eingaben wird das Aggregat ihrer Embeddings verwendet.

Du erhältst einen pandas DataFrame mit den limit ähnlichsten Datenpunkten zur Eingabe sowie deren Abstand im Embedding-Raum. Diesen Datensatz kannst du zum weiteren Filtern verwenden.

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

Ähnliche Bilder darstellen#

Du kannst die ähnlichen Bilder auch mit der Methode plot_similar darstellen. Diese Methode verwendet dieselben Argumente wie get_similar und stellt die ähnlichen Bilder in einem Raster dar.

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

2. KI fragen (Abfragen in natürlicher Sprache)#

Mit dieser Funktion kannst du deinen Datensatz in natürlicher Sprache filtern, ohne SQL zu schreiben. Der KI-gestützte Abfragegenerator wandelt deine Eingabe in eine Abfrage um und gibt passende Ergebnisse zurück. Du kannst zum Beispiel fragen: "show me 100 images with exactly one person and 2 dogs. There can be other objects too". Daraufhin wird die Abfrage erstellt und die entsprechenden Ergebnisse werden angezeigt. Hinweis: Diese Funktion verwendet LLMs. Die Ergebnisse sind daher probabilistisch und möglicherweise ungenau.

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-Abfragen#

Du kannst SQL-Abfragen für deinen Datensatz mit der Methode sql_query ausführen. Diese Methode übernimmt eine SQL-Abfrage als Eingabe und gibt einen pandas DataFrame mit den Ergebnissen zurück.

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

Ergebnisse von SQL-Abfragen darstellen#

Du kannst die Ergebnisse einer SQL-Abfrage auch mit der Methode plot_sql_query darstellen. Diese Methode verwendet dieselben Argumente wie sql_query und stellt die Ergebnisse in einem Raster dar.

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. Mit der Embedding-Tabelle arbeiten#

Du kannst auch direkt mit der Embedding-Tabelle arbeiten. Sobald die Embedding-Tabelle erstellt wurde, kannst du mit Explorer.table darauf zugreifen.

from ultralytics import Explorer

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

Hier sind einige Beispiele dafür, was du mit der Tabelle tun kannst:

Rohe Embeddings abrufen#

from ultralytics import Explorer

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

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

Erweiterte Abfragen mit Vor- und Nachfiltern#

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)

Vektorindex erstellen#

Bei der Verwendung großer Datensätze kannst du außerdem einen dedizierten Vektorindex für schnellere Abfragen erstellen. Dazu verwendest du die Methode create_index für die LanceDB-Tabelle.

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

5. Anwendungen für Embeddings#

Du kannst die Embedding-Tabelle für verschiedene explorative Analysen verwenden. Hier sind einige Beispiele:

Ähnlichkeitsindex#

Explorer enthält eine similarity_index-Operation:

• Sie versucht zu schätzen, wie ähnlich jeder Datenpunkt dem restlichen Datensatz ist.
• Dazu wird gezählt, wie viele Bild-Embeddings im erzeugten Embedding-Raum näher am aktuellen Bild liegen als max_dist, wobei jeweils top_k ähnliche Bilder berücksichtigt werden.

Sie gibt einen pandas DataFrame mit den folgenden Spalten zurück:

• idx: Index des Bildes im Datensatz
• im_file: Pfad zur Bilddatei
• count: Anzahl der Bilder im Datensatz, die näher am aktuellen Bild liegen als max_dist
• sim_im_files: Liste der Pfade zu den count ähnlichen Bildern

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Du kannst den Ähnlichkeitsindex verwenden, um eigene Bedingungen zum Filtern des Datensatzes zu erstellen. Beispielsweise kannst du mit dem folgenden Code Bilder herausfiltern, die keinem anderen Bild im Datensatz ähnlich sind:

import numpy as np

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

Embedding-Raum visualisieren#

Du kannst den Embedding-Raum auch mit dem Darstellungswerkzeug deiner Wahl visualisieren. Hier ist beispielsweise ein einfaches Beispiel mit 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()

Beginne mit der Erstellung eigener Berichte zur Erkundung von Bilddatensätzen mithilfe der Explorer API. Inspiration findest du im Beispiel zur VOC-Erkundung.

Mit Ultralytics Explorer erstellte Anwendungen#

Probiere unsere auf der Explorer API basierende GUI-Demo aus.

FAQ#