Inizia

API di Ultralytics Explorer

Nota della community ⚠️

A partire da ultralytics>=8.3.12, Ultralytics Explorer è stato rimosso. Per usare Explorer, installa pip install ultralytics==8.3.11. Funzionalità simili (e ampliate) per esplorare i dataset sono disponibili su Ultralytics Platform.

Introduzione#

L'API 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.



Guarda: Panoramica di Explorer API di Ultralytics

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

La tabella degli embedding per una determinata coppia di dataset e modello viene creata una sola volta e poi riutilizzata. La tabella usa LanceDB internamente e si adatta ai dati su disco, così puoi creare e riutilizzare embedding per dataset di grandi dimensioni come COCO senza esaurire la memoria.

Per forzare l'aggiornamento della tabella degli embedding, passa 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.

La ricerca per similarità, detta anche ricerca vettoriale, è una tecnica per trovare immagini simili a un'immagine data. Si basa sull'idea che immagini simili abbiano embedding simili. Una volta creata la tabella degli embedding, puoi eseguire ricerche 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.

Ricerca semantica
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.

Tracciare immagini simili
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 funzione ti consente di filtrare il dataset usando il linguaggio naturale, senza scrivere query SQL. Il generatore di query basato sull'IA converte il tuo prompt in una query e restituisce i risultati corrispondenti. Per esempio, puoi chiedere: "mostrami 100 immagini con esattamente una persona e 2 cani. Possono esserci anche altri oggetti"; la funzione genererà la query e ti mostrerà i risultati. Nota: questa funzione usa LLM, quindi i risultati sono probabilistici e potrebbero essere imprecisi.

Ask AI
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.

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

Tracciare i risultati delle query SQL
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.

Suggerimento

Explorer usa internamente le tabelle LanceDB. Puoi accedere direttamente a questa tabella usando l'oggetto Explorer.table ed eseguire query dirette, applicare filtri preliminari e successivi e altro ancora.

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#

Esempio
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#

Esempio
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
Suggerimento

Per un determinato dataset, modello, max_dist e top_k, l'indice di similarità, una volta generato, verrà riutilizzato. Se il dataset è cambiato o devi rigenerare l'indice di similarità, passa force=True.

Indice di similarità
from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Puoi usare l'indice di similarità per definire condizioni personalizzate per filtrare il dataset. Per esempio, il codice seguente elenca le immagini che hanno più di 30 immagini simili nel dataset e che sono quindi buone candidate per la rimozione dei quasi duplicati:

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 grafici che preferisci. Ecco un semplice esempio che riduce gli embedding con PCA e li rappresenta 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#

L'interfaccia grafica di Explorer è basata sull'API Explorer.

Domande frequenti#

  • L'API Ultralytics Explorer è progettata per esplorare i dataset. Ti consente di filtrare e cercare nei dataset usando query SQL, ricerca per similarità vettoriale e ricerca semantica, e può gestire dataset di grandi dimensioni per le attività di visione artificiale con i modelli Ultralytics.

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

    pip install "ultralytics[explorer]==8.3.11"

    In questo modo verranno installate automaticamente tutte le librerie esterne necessarie per le funzionalità dell'Explorer API. Per ulteriori dettagli sulla configurazione, consulta la sezione sull'installazione della documentazione.

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

    from ultralytics import Explorer
    
    # Crea un oggetto Explorer
    explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
    explorer.create_embeddings_table()
    
    # Cerca immagini simili a un'immagine data
    similar_images_df = explorer.get_similar(img="path/to/image.jpg")
    print(similar_images_df.head())

    Per ulteriori dettagli, visita la sezione sulla ricerca di similarità.

  • LanceDB, usato internamente da Ultralytics Explorer, fornisce tabelle di embedding su disco scalabili. Questo ti permette di creare e riutilizzare embedding per dataset di grandi dimensioni come COCO senza esaurire la memoria. Queste tabelle vengono create una sola volta e possono essere riutilizzate, migliorando l'efficienza nella gestione dei dati.

  • La funzionalità Ask AI consente agli utenti di filtrare i dataset usando query in linguaggio naturale. Questa funzionalità sfrutta gli LLM per convertire queste query in query SQL in background. Ecco un esempio:

    from ultralytics import Explorer
    
    # Crea un oggetto Explorer
    explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
    explorer.create_embeddings_table()
    
    # Interroga usando il linguaggio naturale
    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, consulta la sezione Ask AI.

Commenti2

Fai una domanda, condividi i tuoi risultati o aiuta qualcun altro.

  1. Jie Liu

    I have downloaded ultralytics-8.3.118 github zip package and install it with pip install -e .. Then I use pip install ultralytics[explorer] to install explorer, but I got a error as followed

    Requirement already satisfied: ultralytics[explorer] in /data/miniconda3/envs/app/lib/python3.10/site-packages (8.3.118)
    WARNING: ultralytics 8.3.118 does not provide the extra 'explorer'
    Requirement already satisfied: numpy<=2.1.1,>=1.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.26.4)
    Requirement already satisfied: matplotlib>=3.3.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (3.10.1)
    Requirement already satisfied: opencv-python>=4.6.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.11.0.86)
    Requirement already satisfied: pillow>=7.1.2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (11.2.1)
    Requirement already satisfied: pyyaml>=5.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (6.0.2)
    Requirement already satisfied: requests>=2.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.32.3)
    Requirement already satisfied: scipy>=1.4.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.15.2)
    Requirement already satisfied: torch>=1.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.3.1)
    Requirement already satisfied: torchvision>=0.9.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.18.1)
    Requirement already satisfied: tqdm>=4.64.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.67.1)
    Requirement already satisfied: psutil in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (7.0.0)
    Requirement already satisfied: py-cpuinfo in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (9.0.0)
    Requirement already satisfied: pandas>=1.1.4 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.2.3)
    Requirement already satisfied: seaborn>=0.11.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.13.2)
    Requirement already satisfied: ultralytics-thop>=2.0.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.0.14)
    Requirement already satisfied: contourpy>=1.0.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.3.2)
    Requirement already satisfied: cycler>=0.10 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (0.12.1)
    Requirement already satisfied: fonttools>=4.22.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (4.57.0)
    Requirement already satisfied: kiwisolver>=1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.4.8)
    Requirement already satisfied: packaging>=20.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (24.2)
    Requirement already satisfied: pyparsing>=2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (3.2.3)
    Requirement already satisfied: python-dateutil>=2.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (2.9.0.post0)
    Requirement already satisfied: pytz>=2020.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2022.7.1)
    Requirement already satisfied: tzdata>=2022.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2025.2)
    Requirement already satisfied: charset-normalizer<4,>=2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.4.1)
    Requirement already satisfied: idna<4,>=2.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.10)
    Requirement already satisfied: urllib3<3,>=1.21.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (1.26.20)
    Requirement already satisfied: certifi>=2017.4.17 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (2025.4.26)
    Requirement already satisfied: filelock in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.18.0)
    Requirement already satisfied: typing-extensions>=4.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (4.13.2)
    Requirement already satisfied: sympy in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (1.13.3)
    Requirement already satisfied: networkx in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.4.2)
    Requirement already satisfied: jinja2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.1.6)
    Requirement already satisfied: fsspec in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2025.3.2)
    Requirement already satisfied: nvidia-cuda-nvrtc-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cuda-runtime-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cuda-cupti-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: nvidia-cudnn-cu12==8.9.2.26 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (8.9.2.26)
    Requirement already satisfied: nvidia-cublas-cu12==12.1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.3.1)
    Requirement already satisfied: nvidia-cufft-cu12==11.0.2.54 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.0.2.54)
    Requirement already satisfied: nvidia-curand-cu12==10.3.2.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (10.3.2.106)
    Requirement already satisfied: nvidia-cusolver-cu12==11.4.5.107 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.4.5.107)
    Requirement already satisfied: nvidia-cusparse-cu12==12.1.0.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.0.106)
    Requirement already satisfied: nvidia-nccl-cu12==2.20.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.20.5)
    Requirement already satisfied: nvidia-nvtx-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105)
    Requirement already satisfied: triton==2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.3.1)
    Requirement already satisfied: nvidia-nvjitlink-cu12 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from nvidia-cusolver-cu12==11.4.5.107->torch>=1.8.0->ultralytics[explorer]) (12.8.93)
    Requirement already satisfied: six>=1.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from python-dateutil>=2.7->matplotlib>=3.3.0->ultralytics[explorer]) (1.17.0)
    Requirement already satisfied: MarkupSafe>=2.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from jinja2->torch>=1.8.0->ultralytics[explorer]) (3.0.2)
    Requirement already satisfied: mpmath<1.4,>=1.1.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from sympy->torch>=1.8.0->ultralytics[explorer]) (1.3.0)

    when run code

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

    The error has arisen

    Traceback (most recent call last):
      File "/data/liujie/data/ultralytics-8.3.13/tutorial/debug/explorer.py", line 1, in <module>
        from ultralytics import Explorer
    ImportError: cannot import name 'Explorer' from 'ultralytics' (/data/liujie/data/ultralytics-8.3.118/ultralytics/__init__.py)

    please help me to install and use explorer

    1. Glenn JocherUltralytics(modificato)

      Hi @keeper-jie,

      The issue you're experiencing is because Ultralytics Explorer has been removed since version 8.3.12, and you're using version 8.3.118. That's why you're seeing the warning that the 'explorer' extra is not provided and why you can't import the Explorer class.

      As noted in our documentation, we've moved this functionality to Ultralytics Platform, our platform that offers similar and enhanced capabilities for exploring, visualizing, and managing your datasets without writing code.

      If you specifically need the Explorer API functionality in your code, you would need to downgrade to a version prior to 8.3.12. However, we recommend trying Ultralytics Platform instead, as it provides an improved experience with all the dataset exploration features you're looking for.

      Let me know if you need any further assistance with Ultralytics Platform or if you have any other questions.