Ultralytics Explorer-API#

Einführung#

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

Installation#

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

pip install "ultralytics[explorer]==8.3.11"

Verwendung#

from ultralytics import Explorer

# Explorer-Objekt erstellen
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# Einbettungen für deinen Datensatz erstellen
explorer.create_embeddings_table()

# Nach ähnlichen Bildern zu einem oder mehreren Bildern suchen
df = explorer.get_similar(img="path/to/image.jpg")

# Oder nach ähnlichen Bildern zu einem oder mehreren Indizes suchen
df = explorer.get_similar(idx=0)

Wenn du die Tabelle mit Einbettungen 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 Arbeiten mit der Tabelle für Einbettungen.

1. Ähnlichkeitssuche#

Bei der Ähnlichkeitssuche werden Bilder gesucht, die einem bestimmten Bild ähneln. Grundlage dafür ist die Annahme, dass ähnliche Bilder auch ähnliche Einbettungen haben. Sobald die Tabelle mit Einbettungen erstellt wurde, kannst du die Ähnlichkeitssuche auf folgende 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 der Mittelwert ihrer Einbettungen verwendet.

Du erhältst einen pandas DataFrame mit den limit ähnlichsten Datenpunkten zur Eingabe sowie deren Abstand im Einbettungsraum. Diesen Datensatz kannst du anschließend weiter filtern.

from ultralytics import Explorer

# Explorer-Objekt erstellen
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())

# Mit mehreren Bildern suchen
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#

Mit der Methode plot_similar kannst du ähnliche Bilder auch darstellen. Diese Methode akzeptiert dieselben Argumente wie get_similar und stellt die ähnlichen Bilder in einem Raster dar.

from ultralytics import Explorer

# Explorer-Objekt erstellen
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 (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 deinen Prompt in eine Abfrage um und gibt passende Ergebnisse zurück. Du kannst zum Beispiel fragen: „Zeige mir 100 Bilder mit genau einer Person und 2 Hunden. Es dürfen auch andere Objekte zu sehen sein.“ Die Funktion erstellt dann die Abfrage und zeigt dir die Ergebnisse. Hinweis: Diese Funktion verwendet große Sprachmodelle (LLMs). Daher sind die Ergebnisse probabilistisch und möglicherweise ungenau.

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# Explorer-Objekt erstellen
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())

# Ergebnisse darstellen
plt = plot_query_result(df)
plt.show()

3. SQL-Abfragen#

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

from ultralytics import Explorer

# Explorer-Objekt erstellen
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#

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

from ultralytics import Explorer

# Explorer-Objekt erstellen
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# SQL-Abfrage darstellen
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. Mit der Tabelle für Einbettungen arbeiten#

Du kannst auch direkt mit der Tabelle für Einbettungen arbeiten. Sobald die 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 Einbettungen 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-Einbettung
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

Vektorindex erstellen#

Bei großen Datensätzen kannst du auch einen dedizierten Vektorindex erstellen, um Abfragen schneller auszuführen. Verwende dazu die Methode create_index für die LanceDB-Tabelle.

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

5. Anwendungen für Einbettungen#

Mit der Tabelle für Einbettungen kannst du verschiedene explorative Analysen durchführen. Hier sind einige Beispiele:

Ähnlichkeitsindex#

Explorer bietet die Operation similarity_index:

• Sie versucht zu schätzen, wie ähnlich die einzelnen Datenpunkte dem restlichen Datensatz sind.
• Dazu zählt sie, wie viele Bildeinbettungen im erzeugten Einbettungsraum näher als max_dist am aktuellen Bild liegen. Dabei berücksichtigt sie jeweils top_k ähnliche Bilder.

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 als max_dist am aktuellen Bild liegen
• sim_im_files: Liste der Pfade zu den count ähnlichsten Bildern

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Mit dem Ähnlichkeitsindex kannst du benutzerdefinierte Bedingungen erstellen, um den Datensatz zu filtern. Mit dem folgenden Code kannst du zum Beispiel Bilder herausfiltern, die keinem anderen Bild im Datensatz ähneln:

import numpy as np

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

Einbettungsraum visualisieren#

Du kannst den Einbettungsraum auch mit einem Visualisierungswerkzeug deiner Wahl darstellen. Hier ist zum Beispiel ein einfaches Beispiel mit Matplotlib:

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

# Dimensionen mit PCA für die 3D-Visualisierung auf 3 Komponenten reduzieren
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Ein 3D-Streudiagramm mit Matplotlib Axes3D erstellen
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

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

Erstelle mit der Explorer-API eigene Berichte zur Erkundung von CV-Datensätzen. Lass dich vom Beispiel zur Erkundung von VOC inspirieren.

Mit Ultralytics Explorer erstellte Apps#

Probiere unsere Demo der grafischen Benutzeroberfläche auf Basis der Explorer-API aus.

Häufig gestellte Fragen#