Ultralytics Explorer API#

Einführung#

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 ist für einige seiner Funktionen von externen Bibliotheken abhängig. 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)

Falls du das Aktualisieren der Embeddings-Tabelle erzwingen 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. Erfahre mehr darüber im Abschnitt Arbeiten mit der Embeddings-Tabelle.

1. Ähnlichkeitssuche#

Die Ähnlichkeitssuche ist eine Technik zum Finden von Bildern, die einem bestimmten Bild ähneln. Sie basiert auf der Idee, dass ähnliche Bilder ähnliche Embeddings aufweisen. Sobald die Embeddings-Tabelle erstellt ist, kannst du die semantische Suche auf eine der folgenden Weisen 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 der Anzahl von limit der ähnlichsten Datenpunkte zur Eingabe sowie deren Abstand im Embedding-Raum. Du kannst diesen Datensatz verwenden, um weitere Filterungen durchzuführen.

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 akzeptiert 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 schreiben zu müssen. Der KI-gestützte Abfragegenerator wandelt deinen Prompt in eine Abfrage um und gibt passende Ergebnisse zurück. Du kannst beispielsweise fragen: „Zeige mir 100 Bilder mit genau einer Person und 2 Hunden. Es können auch andere Objekte vorhanden sein“ – und es wird die Abfrage generieren und dir diese Ergebnisse anzeigen. Hinweis: Diese Funktion verwendet LLMs, daher sind die Ergebnisse 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 nimmt eine SQL-Abfrage als Eingabe entgegen 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 akzeptiert 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. Arbeiten mit der Embeddings-Tabelle#

Du kannst auch direkt mit der Embeddings-Tabelle arbeiten. Sobald die Embeddings-Tabelle erstellt ist, kannst du über 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:

Roh-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 Arbeit mit großen Datensätzen kannst du auch einen dedizierten Vektorindex für schnellere Abfragen erstellen. Dies geschieht über die Methode create_index in der LanceDB-Tabelle.

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

5. Embeddings-Anwendungen#

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

Ähnlichkeitsindex#

Explorer verfügt über eine Operation namens similarity_index:

• Sie versucht abzuschätzen, wie ähnlich jeder Datenpunkt dem Rest des Datensatzes ist.
• Dies geschieht durch Zählen, wie viele Bild-Embeddings im generierten Embedding-Raum näher als max_dist zum aktuellen Bild liegen, 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 als max_dist am aktuellen Bild sind
• 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 benutzerdefinierte Bedingungen zum Herausfiltern des Datensatzes zu erstellen. Beispielsweise kannst du Bilder herausfiltern, die keinem anderen Bild im Datensatz ähneln, indem du den folgenden Code verwendest:

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 einem Plotting-Tool deiner Wahl visualisieren. Hier ist 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()

Erstelle deine eigenen Berichte zur Erkundung von CV-Datensätzen mit der Explorer API. Schau dir zur Inspiration das VOC Exploration Example an.

Apps, die mit Ultralytics Explorer erstellt wurden#

Teste unsere GUI Demo basierend auf der Explorer API

FAQ#

Wofür wird die Ultralytics Explorer API verwendet?#

Die Ultralytics Explorer API ist für die umfassende Datensatzexploration konzipiert. Sie ermöglicht es Benutzern, Datensätze mithilfe von SQL-Abfragen, Vektorähnlichkeitssuche und semantischer Suche zu filtern und zu durchsuchen. Diese leistungsstarke Python API kann große Datensätze verarbeiten und ist daher ideal für verschiedene Aufgaben im Bereich des Computer Vision unter Verwendung von Ultralytics-Modellen.

Wie installiere ich die Ultralytics Explorer API?#

Um die Ultralytics Explorer API zusammen mit ihren Abhängigkeiten zu installieren, verwende den folgenden Befehl:

pip install ultralytics[explorer]

Dadurch werden automatisch alle erforderlichen externen Bibliotheken für die Funktionalität der Explorer API installiert. Weitere Details zur Einrichtung findest du im Installationsabschnitt unserer Dokumentation.

Wie kann ich die Ultralytics Explorer API für die Ähnlichkeitssuche verwenden?#

Du kannst die Ultralytics Explorer API verwenden, um Ähnlichkeitssuchen durchzuführen, indem du eine Embeddings-Tabelle erstellst und diese nach ähnlichen Bildern abfragst. Hier ist ein einfaches Beispiel:

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

Weitere Details findest du im Abschnitt Ähnlichkeitssuche.

Welche Vorteile bietet die Verwendung von LanceDB mit Ultralytics Explorer?#

LanceDB, das im Hintergrund von Ultralytics Explorer verwendet wird, bietet skalierbare Embeddings-Tabellen auf der Festplatte. Dies stellt sicher, dass du Embeddings für große Datensätze wie COCO erstellen und wiederverwenden kannst, ohne dass der Arbeitsspeicher knapp wird. Diese Tabellen werden nur einmal erstellt und können wiederverwendet werden, was die Effizienz bei der Datenverarbeitung steigert.

Wie funktioniert die Funktion „KI fragen“ in der Ultralytics Explorer API?#

Die Funktion „KI fragen“ ermöglicht es Benutzern, Datensätze mithilfe von Abfragen in natürlicher Sprache zu filtern. Diese Funktion nutzt LLMs, um diese Abfragen im Hintergrund in SQL-Abfragen umzuwandeln. Hier ist ein Beispiel:

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

Weitere Beispiele findest du im Abschnitt KI fragen.