Ultralytics Explorer API

Einführung

Die Explorer API ist eine Python-API zur Untersuchung deiner Datensätze. Sie unterstützt das Filtern und Durchsuchen deines Datensatzes mithilfe von SQL-Abfragen, Vektor-Ähnlichkeitssuche 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, nutze den folgenden Befehl:

pip install ultralytics[explorer]

Verwendung

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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 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 fortgeschrittene Analysen durchzuführen. Erfahre mehr darüber im Abschnitt Arbeiten mit der Embeddings-Tabelle.

1. Ähnlichkeitssuche

Die Ähnlichkeitssuche ist eine Technik, um Bilder zu finden, die einem gegebenen Bild ähnlich sind. 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 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 jedes Bild oder jede 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 Durchschnitt ihrer Embeddings verwendet.

Du erhältst einen pandas DataFrame mit der durch limit angegebenen Anzahl der ähnlichsten Datenpunkte zum Input, zusammen mit ihrer Distanz im Embedding-Raum. Du kannst diesen Datensatz für weitere Filterungen nutzen.

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo26n.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())

Plotten ähnlicher Bilder

Du kannst die ähnlichen Bilder auch mit der Methode plot_similar grafisch darstellen. 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="yolo26n.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 mithilfe natürlicher Sprache filtern, ohne SQL schreiben zu müssen. Der KI-gestützte Abfragegenerator wandelt deine Eingabe in eine Abfrage um und liefert die passenden Ergebnisse. Zum Beispiel kannst du 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 nutzt LLMs, daher sind die Ergebnisse probabilistisch und können ungenau sein.

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo26n.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 Datensatz mithilfe der Methode sql_query ausführen. Diese Methode akzeptiert 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="yolo26n.pt")
exp.create_embeddings_table()

df = exp.sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%'")
print(df.head())

SQL-Abfrageergebnisse plotten

Du kannst die Ergebnisse einer SQL-Abfrage auch mit der Methode plot_sql_query grafisch darstellen. 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="yolo26n.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 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:

Roh-Embeddings abrufen

from ultralytics import Explorer

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

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

Erweiterte Abfrage mit Pre- und Post-Filtern

from ultralytics import Explorer

exp = Explorer(model="yolo26n.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)

Vektor-Index erstellen

Bei der Arbeit mit großen Datensätzen kannst du einen dedizierten Vektor-Index für schnellere Abfragen erstellen. Dies geschieht mithilfe der Methode create_index auf der LanceDB-Tabelle.

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

5. Embeddings-Anwendungen

Du kannst die Embeddings-Tabelle verwenden, um eine Vielzahl von explorativen Analysen durchzuführen. Hier sind einige Beispiele:

Ähnlichkeitsindex

Explorer bietet eine similarity_index-Operation:

• 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 am aktuellen Bild liegen, unter Berücksichtigung von top_k ähnlichen Bildern gleichzeitig.

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 Filtern des Datensatzes zu erstellen. Zum Beispiel 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 dem Plotting-Tool deiner Wahl visualisieren. Hier ist zum Beispiel 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 dem Erstellen deiner eigenen Berichte zur Erkundung von CV-Datensätzen mithilfe der Explorer API. Zur Inspiration sieh dir das VOC Exploration Example an.

Apps, die mit Ultralytics Explorer erstellt wurden

Probiere unsere GUI Demo basierend auf der Explorer API aus

FAQ

Wofür wird die Ultralytics Explorer API verwendet?

Die Ultralytics Explorer API ist für die umfassende Untersuchung von Datensätzen 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 somit ideal für verschiedene Aufgaben im Bereich Computer Vision mit 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]

Dies installiert automatisch alle notwendigen externen Bibliotheken für die Funktionalität der Explorer API. Weitere Details zur Einrichtung findest du im Abschnitt Installation 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 grundlegendes Beispiel:

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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 Einzelheiten findest du im Abschnitt Ähnlichkeitssuche.

Was sind die Vorteile der Verwendung von LanceDB mit Ultralytics Explorer?

LanceDB, das von Ultralytics Explorer im Hintergrund 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 ausgeht. 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 Anfragen in natürlicher Sprache zu filtern. Diese Funktion nutzt LLMs, um diese Anfragen im Hintergrund in SQL-Abfragen umzuwandeln. Hier ist ein Beispiel:

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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.