Link to this sectionUltralytics Explorer API#

Link to this sectionIntroduzione#

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

Link to this sectionInstallazione#

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

pip install ultralytics[explorer]

Link to this sectionUtilizzo#

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)

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

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

Link to this section1. Ricerca di similarità#

La ricerca di 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 dato indice 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.

Ottieni un DataFrame pandas con il numero limit di punti dati più simili all'input, insieme alla loro distanza nello spazio degli embedding. Puoi utilizzare 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())

Link to this sectionTracciare immagini simili#

Puoi anche tracciare le immagini simili utilizzando 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="yolo11n.pt")
exp.create_embeddings_table()

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

Link to this section2. Chiedi all'AI (Query in linguaggio naturale)#

Questa funzionalità ti permette di filtrare il tuo dataset utilizzando 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. Ci possono essere anche altri oggetti" e genererà la query mostrandoti quei risultati. Nota: questa funzionalità utilizza LLM, quindi i risultati sono probabilistici e potrebbero essere inaccurati.

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

Link to this section3. Query SQL#

Puoi eseguire query SQL sul tuo dataset utilizzando 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="yolo11n.pt")
exp.create_embeddings_table()

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

Link to this sectionTracciare i risultati della query SQL#

Puoi anche tracciare i risultati di una query SQL utilizzando 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="yolo11n.pt")
exp.create_embeddings_table()

# plot the SQL Query
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

Link to this section4. Lavorare con la tabella degli Embeddings#

Puoi anche lavorare direttamente con la tabella degli embeddings. Una volta creata la tabella, puoi accedervi utilizzando 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:

Link to this sectionOttenere embeddings grezzi#

from ultralytics import Explorer

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

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

Link to this sectionQuery avanzate con pre-filtri e post-filtri#

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)

Link to this sectionCreare indice vettoriale#

Quando utilizzi dataset di grandi dimensioni, puoi anche creare un indice vettoriale dedicato per una query più veloce. Questo si fa utilizzando il metodo create_index sulla tabella LanceDB.

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

Link to this section5. Applicazioni degli Embeddings#

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

Link to this sectionIndice di similarità#

Explorer include un'operazione di similarity_index:

• Tenta 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 di 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 sono 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 utilizzare 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 utilizzando il seguente codice:

import numpy as np

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

Link to this sectionVisualizzare lo spazio degli embedding#

Puoi anche visualizzare lo spazio degli embedding utilizzando lo strumento di tracciamento che preferisci. Ad esempio, ecco un semplice esempio utilizzando 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 dei dataset CV utilizzando l'Explorer API. Per ispirazione, dai un'occhiata all'Esempio di esplorazione VOC.

Link to this sectionApp costruite utilizzando Ultralytics Explorer#

Prova la nostra GUI Demo basata sull'Explorer API

Link to this sectionFAQ#

Link to this sectionA cosa serve l'Ultralytics Explorer API?#

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

Link to this sectionCome installo l'Ultralytics Explorer API?#

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

pip install ultralytics[explorer]

Questo installerà automaticamente tutte le librerie esterne necessarie per la funzionalità dell'Explorer API. Per ulteriori dettagli sull'installazione, fai riferimento alla sezione installazione della nostra documentazione.

Link to this sectionCome posso utilizzare l'Ultralytics Explorer API per la ricerca di similarità?#

Puoi utilizzare l'Ultralytics Explorer API per eseguire ricerche di 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="yolo11n.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 di similarità.

Link to this sectionQuali sono i vantaggi di utilizzare 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 dataset di grandi dimensioni come COCO senza esaurire la memoria. Queste tabelle vengono create solo una volta e possono essere riutilizzate, migliorando l'efficienza nella gestione dei dati.

Link to this sectionCome funziona la funzionalità Chiedi all'AI nell'Ultralytics Explorer API?#

La funzionalità Chiedi all'AI permette agli utenti di filtrare i dataset utilizzando query in linguaggio naturale. Questa funzionalità sfrutta gli 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="yolo11n.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 ulteriori esempi, dai un'occhiata alla sezione Chiedi all'AI.