Ultralytics Explorer API

Einführung

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

Pass auf: Ultralytics Explorer API Übersicht

Installation

Der Explorer ist für einige seiner Funktionen auf externe Bibliotheken angewiesen. Diese werden bei der Verwendung automatisch installiert. 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='yolov8n.pt')

# Create embeddings for your dataset
explorer.create_embeddings_table()

# Search for similar images to a given image/images
dataframe = explorer.get_similar(img='path/to/image.jpg')

# Or search for similar images to a given index/indices
dataframe = explorer.get_similar(idx=0)

Wenn du die Aktualisierung der Einbettungstabelle erzwingen willst, kannst du force=True zu create_embeddings_table Methode.

Du kannst direkt auf das Tabellenobjekt LanceDB zugreifen, um erweiterte Analysen durchzuführen. Mehr dazu erfährst du im Abschnitt Arbeiten mit Einbettungstabellen

1. Ähnlichkeitssuche

Die Ähnlichkeitssuche ist eine Technik, um ähnliche Bilder wie ein bestimmtes Bild zu finden. Sie basiert auf der Idee, dass ähnliche Bilder auch ähnliche Einbettungen haben. Sobald die Einbettungstabelle erstellt ist, kannst du die semantische Suche auf eine der folgenden Arten durchführen:

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

Wenn es mehrere Eingaben gibt, wird die Summe ihrer Einbettungen verwendet.

Du erhältst einen Pandas-Datenrahmen mit dem limit Anzahl der Datenpunkte, die der Eingabe am ähnlichsten sind, zusammen mit ihrem Abstand im Einbettungsraum. Du kannst diesen Datensatz verwenden, um weitere Filterungen vorzunehmen

from ultralytics import Explorer

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

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data='coco128.yaml', model='yolov8n.pt')
exp.create_embeddings_table()

similar = exp.get_similar(idx=1, limit=10)
print(similar.head())

# Search using multiple indices
similar = exp.get_similar(idx=[1,10], limit=10)
print(similar.head())

Ähnliche Bilder einzeichnen

Du kannst die ähnlichen Bilder auch mit der plot_similar Methode. Diese Methode nimmt die gleichen 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='yolov8n.pt')
exp.create_embeddings_table()

plt = exp.plot_similar(img='https://ultralytics.com/images/bus.jpg', limit=10)
plt.show()

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data='coco128.yaml', model='yolov8n.pt')
exp.create_embeddings_table()

plt = exp.plot_similar(idx=1, limit=10)
plt.show()

2. Ask AI (Natural Language Querying)

So kannst du in natürlicher Sprache schreiben, wie du deinen Datensatz filtern willst. Du musst dich nicht mit dem Schreiben von SQL-Abfragen auskennen. Unser KI-gestützter Abfragegenerator erledigt das automatisch unter der Haube. Du kannst zum Beispiel sagen: "Zeige mir 100 Bilder mit genau einer Person und 2 Hunden. Es können auch andere Objekte dabei sein", und schon wird die Abfrage intern erstellt und dir die Ergebnisse angezeigt. Hinweis: Dies funktioniert mit LLMs unter der Haube, daher sind die Ergebnisse probabilistisch und können manchmal falsch sein.

from ultralytics import Explorer
from ultralytics.data.explorer import plot_query_result


# create an Explorer object
exp = Explorer(data='coco128.yaml', model='yolov8n.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-Abfrage

Du kannst SQL-Abfragen auf deinem Datensatz ausführen, indem du die sql_query Methode. Diese Methode nimmt eine SQL-Abfrage als Eingabe und gibt einen Pandas-Datenrahmen mit den Ergebnissen zurück.

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data='coco128.yaml', model='yolov8n.pt')
exp.create_embeddings_table()

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

Plotten von SQL-Abfrageergebnissen

Du kannst die Ergebnisse einer SQL-Abfrage auch mit der Funktion plot_sql_query Methode. Diese Methode nimmt die gleichen 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='yolov8n.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 Einbettungstabelle

Du kannst auch direkt mit der Einbettungstabelle arbeiten. Sobald die Einbettungstabelle erstellt ist, kannst du sie mit der Funktion Explorer.table

from ultralytics import Explorer

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

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

Rohe Einbettungen erhalten

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="yolov8n.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

Wenn du große Datensätze verwendest, kannst du auch einen eigenen Vektorindex erstellen, um die Abfrage zu beschleunigen. Dies geschieht mit dem create_index Methode für die Tabelle LanceDB.

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

Weitere Details zu den verfügbaren Vektorindizes und Parametern findest du hier. In Zukunft werden wir die Erstellung von Vektorindizes direkt über die Explorer API unterstützen.

5. Einbettungen Anwendungen

Du kannst die Tabelle mit den Einbettungen für eine Vielzahl von explorativen Analysen nutzen. Hier sind einige Beispiele:

Ähnlichkeitsindex

Explorer kommt mit einer similarity_index Betrieb:

• Sie versucht abzuschätzen, wie ähnlich jeder Datenpunkt dem Rest des Datensatzes ist.
• Dabei wird gezählt, wie viele Bildeinbettungen näher liegen als max_dist zum aktuellen Bild im generierten Einbettungsraum, unter Berücksichtigung top_k ähnliche Bilder zu einer Zeit.

Sie gibt einen Pandas-Datenrahmen 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 sind als max_dist zum aktuellen Bild
• sim_im_files: Liste der Pfade zu den count ähnliche Bilder

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. Mit dem folgenden Code kannst du zum Beispiel 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]

Einbettungsraum visualisieren

Du kannst den Einbettungsraum auch mit einem Diagrammwerkzeug deiner Wahl visualisieren. Hier ist zum Beispiel ein einfaches Beispiel mit matplotlib:

import numpy as np
from sklearn.decomposition import PCA
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D

# 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 mit der Explorer-API deine eigenen Berichte zur Erkundung von Lebenslaufdaten. Als Inspiration kannst du dir die

Mit Ultralytics Explorer erstellte Apps

Teste unsere GUI-Demo auf Basis der Explorer API

Demnächst

• [ ] Führe bestimmte Beschriftungen aus Datensätzen zusammen. Beispiel - Alle importieren person Etiketten von COCO und car Etiketten von Cityscapes
• [ ] Bilder entfernen, die einen höheren Ähnlichkeitsindex als den angegebenen Schwellenwert haben
• [ ] Neue Datensätze nach dem Zusammenführen/Entfernen von Einträgen automatisch beibehalten
• [Erweiterte Datensatzvisualisierungen

Kommentare