Ultralytics Explorer API

Introduzione

L'API Explorer è un'API Python per esplorare i tuoi dataset. Supporta il filtraggio e la ricerca nel tuo dataset utilizzando query SQL, ricerca per similarità vettoriale e ricerca semantica.

Installazione

Explorer dipende da librerie esterne per alcune delle sue funzionalità. Queste vengono installate automaticamente quando usi Explorer. Per installare manualmente queste dipendenze, usa il seguente comando:

pip install ultralytics[explorer]

Utilizzo

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)

Nel caso in cui tu voglia forzare l'aggiornamento della tabella degli embeddings, puoi passare force=True al metodo create_embeddings_table.

Puoi accedere direttamente all'oggetto tabella LanceDB per eseguire analisi avanzate. Scopri di più nella sezione Lavorare con la tabella degli Embeddings

Ricerca per similarità

La ricerca per similarità è una tecnica per trovare immagini simili a una data immagine. Si basa sull'idea che immagini simili abbiano embeddings simili. Una volta creata la tabella degli embeddings, puoi eseguire la ricerca semantica in uno dei seguenti modi:

• Su un indice specifico o una lista di indici nel dataset: exp.get_similar(idx=[1,10], limit=10)
• Su qualsiasi immagine o lista di immagini non presenti nel dataset: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

In caso di input multipli, viene utilizzato l'aggregato dei loro embeddings.

Otterrai un DataFrame pandas con il numero limit di punti dati più simili all'input, insieme alla loro distanza nello spazio degli embeddings. Puoi usare questo dataset per eseguire ulteriori filtraggi.

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

Visualizzazione di immagini simili

Puoi anche tracciare le immagini simili usando il metodo plot_similar. Questo metodo accetta gli stessi argomenti di get_similar e traccia le immagini simili in una griglia.

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

Chiedi all'AI (Interrogazione in linguaggio naturale)

Questa funzionalità ti permette di filtrare il tuo dataset usando il linguaggio naturale, senza scrivere SQL. Il generatore di query basato su AI converte il tuo prompt in una query e restituisce i risultati corrispondenti. Ad esempio, puoi chiedere: "mostrami 100 immagini con esattamente una persona e 2 cani. Possono esserci anche altri oggetti" e genererà la query mostrandoti quei risultati. Nota: Questa funzione usa LLM, quindi i risultati sono probabilistici e potrebbero essere imprecisi.

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

Interrogazione SQL

Puoi eseguire query SQL sul tuo dataset usando il metodo sql_query. Questo metodo accetta una query SQL come input e restituisce un DataFrame pandas con i risultati.

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

Visualizzazione dei risultati della query SQL

Puoi anche tracciare i risultati di una query SQL usando il metodo plot_sql_query. Questo metodo accetta gli stessi argomenti di sql_query e traccia i risultati in una griglia.

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

Lavorare con la tabella degli Embeddings

Puoi anche lavorare direttamente con la tabella degli embeddings. Una volta creata la tabella, puoi accedervi usando Explorer.table

from ultralytics import Explorer

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

Ecco alcuni esempi di cosa puoi fare con la tabella:

Ottieni gli Embeddings grezzi

from ultralytics import Explorer

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

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

Interrogazione avanzata con pre-filtri e post-filtri

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)

Crea Indice Vettoriale

Quando usi dataset di grandi dimensioni, puoi anche creare un indice vettoriale dedicato per query più veloci. Questo si fa usando il metodo create_index sulla tabella LanceDB.

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

Applicazioni degli Embeddings

Puoi usare la tabella degli embeddings per eseguire una varietà di analisi esplorative. Ecco alcuni esempi:

Indice di similarità

Explorer viene fornito con un'operazione similarity_index:

• Tenta di stimare quanto ogni punto dati è simile al resto del dataset.
• Lo fa contando quante immagini nell'embedding space generato si trovano a una distanza inferiore a max_dist dall'immagine corrente, considerando top_k immagini simili alla volta.

Restituisce un DataFrame pandas con le seguenti colonne:

• idx: Indice dell'immagine nel dataset
• im_file: Percorso del file immagine
• count: Numero di immagini nel dataset più vicine di max_dist all'immagine corrente
• sim_im_files: Lista di percorsi alle count immagini simili

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Puoi usare l'indice di similarità per creare condizioni personalizzate per filtrare il dataset. Ad esempio, puoi filtrare le immagini che non sono simili a nessun'altra immagine nel dataset usando il seguente codice:

import numpy as np

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

Visualizza lo spazio degli embedding

Puoi anche visualizzare lo spazio degli embedding usando lo strumento di plotting che preferisci. Ad esempio, ecco un semplice esempio usando 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()

Inizia a creare i tuoi report di esplorazione del dataset CV usando l'API Explorer. Per ispirazione, dai un'occhiata all'Esempio di esplorazione VOC.

App create usando Ultralytics Explorer

Prova la nostra Demo GUI basata sull'API Explorer

FAQ

A cosa serve l'API Ultralytics Explorer?

L'API Ultralytics Explorer è progettata per un'esplorazione completa dei dataset. Permette agli utenti di filtrare e cercare nei dataset usando query SQL, ricerca per similarità vettoriale e ricerca semantica. Questa potente API Python può gestire grandi dataset, rendendola ideale per vari compiti di computer vision usando i modelli Ultralytics.

Come installo l'API Ultralytics Explorer?

Per installare l'API Ultralytics Explorer insieme alle sue dipendenze, usa il seguente comando:

pip install ultralytics[explorer]

Questo installerà automaticamente tutte le librerie esterne necessarie per la funzionalità dell'API Explorer. Per dettagli aggiuntivi sulla configurazione, consulta la sezione di installazione della nostra documentazione.

Come posso usare l'API Ultralytics Explorer per la ricerca per similarità?

Puoi usare l'API Ultralytics Explorer per eseguire ricerche per similarità creando una tabella di embeddings e interrogandola per immagini simili. Ecco un esempio base:

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

Per maggiori dettagli, visita la sezione Ricerca per similarità.

Quali sono i vantaggi dell'uso di LanceDB con Ultralytics Explorer?

LanceDB, utilizzato internamente da Ultralytics Explorer, fornisce tabelle di embeddings scalabili su disco. Ciò garantisce che tu possa creare e riutilizzare embeddings per grandi dataset come COCO senza esaurire la memoria. Queste tabelle vengono create solo una volta e possono essere riutilizzate, migliorando l'efficienza nella gestione dei dati.

Come funziona la funzione Chiedi all'AI nell'API Ultralytics Explorer?

La funzione Chiedi all'AI consente agli utenti di filtrare i dataset usando query in linguaggio naturale. Questa funzione sfrutta LLM per convertire queste query in query SQL dietro le quinte. Ecco un esempio:

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

Per altri esempi, dai un'occhiata alla sezione Chiedi all'AI.