API Explorer di Ultralytics#

Introduzione#

L'API Explorer è un'API Python per esplorare i tuoi dataset. Supporta il filtraggio e la ricerca nel tuo dataset tramite query SQL, ricerca per somiglianza 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="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)

Se vuoi 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 Working with Embeddings Table

1. Ricerca per similarità#

La ricerca per similarità è una tecnica per trovare immagini simili a un'immagine data. 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 determinato indice o elenco di indici nel dataset: exp.get_similar(idx=[1,10], limit=10)
• Su una qualsiasi immagine o elenco di immagini non presenti nel dataset: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

In caso di più input, viene utilizzato l'aggregato dei relativi embeddings.

Ottieni un pandas DataFrame con i limit elementi più simili all'input, insieme alla relativa 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="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())

Visualizzazione delle immagini simili#

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

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. Chiedi all'IA (query in linguaggio naturale)#

Questa funzionalità ti consente di filtrare il tuo dataset usando il linguaggio naturale, senza scrivere SQL. Il generatore di query basato sull'IA 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 ti mostrerà quei 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

# 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. 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 pandas DataFrame con i risultati.

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

Visualizzazione dei risultati della query SQL#

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

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. Utilizzo della tabella degli embeddings#

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

from ultralytics import Explorer

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

Ecco alcuni esempi di ciò che puoi fare con la tabella:

Ottenere gli embeddings 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

# Dummy embedding
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. L'operazione viene eseguita usando il metodo create_index sulla tabella LanceDB.

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

5. Applicazioni degli embeddings#

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

Indice di similarità#

Explorer include un'operazione similarity_index:

• Cerca di stimare quanto ogni punto dati sia simile al resto del dataset.
• Lo fa contando quanti embeddings di immagini si trovano a una distanza inferiore a max_dist dall'immagine corrente nello spazio degli embeddings generato, considerando top_k immagini simili alla volta.

Restituisce un pandas DataFrame con le colonne seguenti:

• 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 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 con cui filtrare il dataset. Ad esempio, puoi escludere le immagini che non sono simili a nessun'altra immagine del dataset usando il codice seguente:

import numpy as np

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

Visualizzare lo spazio degli embeddings#

Puoi anche visualizzare lo spazio degli embeddings usando lo strumento di plotting che preferisci. Ecco, ad esempio, un esempio semplice con 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 di dataset CV usando l'API Explorer. Per trovare ispirazione, dai un'occhiata al VOC Exploration Example.

App create usando Ultralytics Explorer#

Prova la nostra GUI Demo basata sull'API Explorer

FAQ#