Ultralytics Explorer API#

Einführung#

The Explorer API is a Python API for exploring your datasets. It supports filtering and searching your dataset using SQL queries, vector similarity search, and semantic search.

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 die Einbettungstabelle erzwingend 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. Erfahre mehr darüber im Abschnitt „Arbeiten mit der Embeddings Table“.

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 Dataset: exp.get_similar(idx=[1,10], limit=10)
• Für jedes Bild oder jede Liste von Bildern, die nicht im Dataset 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 durch limit angegebenen Anzahl an ähnlichsten Datenpunkten zum Eingang sowie deren Abstand im Einbettungsraum. Du kannst dieses Dataset für weitere Filterungen 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 plotten. Diese Methode akzeptiert dieselben Argumente wie get_similar und plottet die ähnlichen Bilder in einem Raster.

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 auf deinem Dataset mit der Methode sql_query ausführen. Diese Methode nimmt eine SQL-Abfrage als Eingabe entgegen und gibt ein 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 plotten. Diese Methode akzeptiert dieselben Argumente wie sql_query und plottet die Ergebnisse in einem Raster.

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 Einbettungstabelle arbeiten. Sobald die Einbettungstabelle erstellt ist, 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:

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 Verwendung großer Datasets 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 wird mit einer similarity_index-Operation geliefert:

• Sie versucht abzuschätzen, wie ähnlich jeder Datenpunkt dem Rest des Datensatzes ist.
• Dies geschieht, indem gezählt wird, wie viele Bild-Einbettungen im generierten Einbettungsraum 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 Dataset
• im_file: Pfad zur Bilddatei
• count: Anzahl der Bilder im Dataset, 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 CV-Dataset-Erforschungsberichte mit der Explorer API. Lass dich vom VOC Exploration Example inspirieren.

Apps, die mit Ultralytics Explorer erstellt wurden#

Probiere unsere GUI Demo basierend auf der Explorer API aus.

FAQ#