API di Ultralytics Explorer#

Introduzione#

L'API di Explorer è un'API Python per esplorare i tuoi dataset. Consente di filtrare e cercare nel dataset usando query SQL, ricerca per similarità vettoriale e ricerca semantica.

Installazione#

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

pip install "ultralytics[explorer]==8.3.11"

Utilizzo#

from ultralytics import Explorer

# Crea un oggetto Explorer
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# Crea embedding per il tuo dataset
explorer.create_embeddings_table()

# Cerca immagini simili a una o più immagini specificate
df = explorer.get_similar(img="path/to/image.jpg")

# Oppure cerca immagini simili a uno o più indici specificati
df = explorer.get_similar(idx=0)

Se vuoi forzare l'aggiornamento della tabella degli embedding, puoi passare force=True al metodo create_embeddings_table.

Puoi accedere direttamente all'oggetto della tabella LanceDB per eseguire analisi avanzate. Scopri di più nella sezione Uso della tabella degli embedding.

1. Ricerca per similarità#

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

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

In caso di più input, viene usato l'aggregato dei relativi embedding.

Otterrai un DataFrame pandas con i limit punti dati più simili all'input e la relativa distanza nello spazio degli embedding. Puoi usare questo dataset per applicare altri filtri.

from ultralytics import Explorer

# crea un oggetto Explorer
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())

# Cerca usando più immagini
similar = exp.get_similar(
    img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
    limit=10,
)
print(similar.head())

Tracciare immagini simili#

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

from ultralytics import Explorer

# crea un oggetto Explorer
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. Ask AI (query in linguaggio naturale)#

Questa funzionalità ti consente di filtrare il dataset in linguaggio naturale, senza scrivere query SQL. Il generatore di query basato sull'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 la funzionalità genererà la query e mostrerà i risultati. Nota: questa funzionalità usa LLM, quindi i risultati sono probabilistici e potrebbero essere imprecisi.

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# crea un oggetto Explorer
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())

# traccia i risultati
plt = plot_query_result(df)
plt.show()

3. Query 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

# crea un oggetto Explorer
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())

Tracciare i risultati delle 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 dispone i risultati in una griglia.

from ultralytics import Explorer

# crea un oggetto Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# traccia la query SQL
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. Uso della tabella degli embedding#

Puoi anche lavorare direttamente con la tabella degli embedding. Dopo averla creata, puoi accedervi usando Explorer.table.

from ultralytics import Explorer

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

Ecco alcuni esempi di operazioni che puoi eseguire sulla tabella:

Recuperare gli embedding grezzi#

from ultralytics import Explorer

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

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

Query avanzate con filtri preliminari e successivi#

from ultralytics import Explorer

exp = Explorer(model="yolo11n.pt")
exp.create_embeddings_table()
table = exp.table

# Embedding fittizio
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

Creare un indice vettoriale#

Quando usi dataset di grandi dimensioni, puoi anche creare un indice vettoriale dedicato per velocizzare le query. Per farlo, usa il metodo create_index sulla tabella LanceDB.

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

5. Applicazioni degli embedding#

Puoi usare la tabella degli embedding per eseguire diversi tipi di analisi esplorativa. Ecco alcuni esempi:

Indice di similarità#

Explorer include un'operazione similarity_index:

• Prova a stimare quanto ciascun punto dati sia simile al resto del dataset.
• Lo fa contando quanti embedding di immagini si trovano a una distanza inferiore a max_dist dall'immagine corrente nello spazio degli embedding generato, 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 che si trovano a una distanza inferiore a max_dist dall'immagine corrente
• sim_im_files: elenco dei percorsi delle count immagini più 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 che filtrino il dataset. Ad esempio, puoi escludere le immagini che non sono simili a nessun'altra immagine del dataset usando il seguente codice:

import numpy as np

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

Visualizzare lo spazio degli embedding#

Puoi anche visualizzare lo spazio degli embedding usando lo strumento di tracciamento che preferisci. Ecco, ad esempio, un semplice esempio con Matplotlib:

import matplotlib.pyplot as plt
from sklearn.decomposition import PCA

# Riduci le dimensioni a 3 componenti usando PCA per la visualizzazione in 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Crea un grafico a dispersione 3D usando Axes3D di Matplotlib
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# Grafico a dispersione
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 sull'esplorazione di dataset di CV usando l'API di Explorer. Per trovare ispirazione, dai un'occhiata all'esempio di esplorazione di VOC.

Applicazioni realizzate con Ultralytics Explorer#

Prova la nostra demo della GUI basata sull'API di Explorer

Domande frequenti#