Ultralytics Explorer API#

Introduction#

The Explorer API is a Python API for exploring your datasets. It supports filtering and searching your dataset using SQL queries, vector similarity search, and semantic search.

Installation#

Explorer dépend de bibliothèques externes pour certaines de ses fonctionnalités. Celles-ci sont installées automatiquement lorsque tu utilises Explorer. Pour installer manuellement ces dépendances, utilise la commande suivante :

pip install ultralytics[explorer]

Utilisation#

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)

Si tu souhaites forcer la mise à jour de la table des embeddings, tu peux passer force=True à la méthode create_embeddings_table.

Tu peux accéder directement à l'objet table LanceDB pour effectuer une analyse avancée. Apprends-en plus dans la section Working with Embeddings Table

1. Recherche de similarité#

La recherche de similarité est une technique permettant de trouver des images similaires à une image donnée. Elle repose sur l'idée que des images similaires auront des embeddings similaires. Une fois la table des embeddings construite, tu peux lancer une recherche sémantique de l'une des manières suivantes :

• Sur un index donné ou une liste d'indices dans le dataset : exp.get_similar(idx=[1,10], limit=10)
• Sur n'importe quelle image ou liste d'images ne se trouvant pas dans le dataset : exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

En cas d'entrées multiples, l'agrégat de leurs embeddings est utilisé.

Tu obtiens un DataFrame pandas avec le nombre limit de points de données les plus similaires à l'entrée, ainsi que leur distance dans l'espace des embeddings. Tu peux utiliser ce dataset pour effectuer un filtrage supplémentaire.

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

Tracé d'images similaires#

Tu peux également tracer les images similaires à l'aide de la méthode plot_similar. Cette méthode prend les mêmes arguments que get_similar et trace les images similaires dans une grille.

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. Demander à l'IA (Requêtes en langage naturel)#

Cette fonctionnalité te permet de filtrer ton dataset en utilisant le langage naturel, sans écrire de SQL. Le générateur de requêtes alimenté par l'IA convertit ton invite en requête et renvoie les résultats correspondants. Par exemple, tu peux demander : "montre-moi 100 images avec exactement une personne et 2 chiens. Il peut y avoir d'autres objets aussi" et il générera la requête et te montrera ces résultats. Remarque : Cette fonctionnalité utilise des LLMs, les résultats sont donc probabilistes et peuvent être inexacts.

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. Requêtes SQL#

Tu peux exécuter des requêtes SQL sur ton dataset en utilisant la méthode sql_query. Cette méthode prend une requête SQL en entrée et renvoie un DataFrame pandas avec les résultats.

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

Tracé des résultats de la requête SQL#

Tu peux également tracer les résultats d'une requête SQL en utilisant la méthode plot_sql_query. Cette méthode prend les mêmes arguments que sql_query et trace les résultats dans une grille.

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. Travailler avec la table des embeddings#

Tu peux également travailler directement avec la table des embeddings. Une fois que la table des embeddings est créée, tu peux y accéder en utilisant le Explorer.table

from ultralytics import Explorer

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

Voici quelques exemples de ce que tu peux faire avec la table :

Obtenir des embeddings bruts#

from ultralytics import Explorer

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

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

Requêtes avancées avec filtres en amont et en aval#

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)

Créer un index vectoriel#

Lors de l'utilisation de grands datasets, tu peux également créer un index vectoriel dédié pour des requêtes plus rapides. Pour ce faire, utilise la méthode create_index sur la table LanceDB.

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

5. Applications des embeddings#

Tu peux utiliser la table des embeddings pour effectuer diverses analyses exploratoires. En voici quelques exemples :

Index de similarité#

Explorer propose une opération similarity_index :

• Elle essaie d'estimer à quel point chaque point de données est similaire au reste du dataset.
• Pour ce faire, on compte combien d'embeddings d'images se trouvent plus près que max_dist de l'image actuelle dans l'espace des embeddings généré, en considérant top_k images similaires à la fois.

Elle renvoie un DataFrame pandas avec les colonnes suivantes :

• idx : Index de l'image dans le dataset
• im_file : Chemin d'accès au fichier image
• count : Nombre d'images dans le dataset qui sont plus proches que max_dist de l'image actuelle
• sim_im_files : Liste des chemins d'accès vers les count images similaires

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Tu peux utiliser l'index de similarité pour créer des conditions personnalisées afin de filtrer le dataset. Par exemple, tu peux filtrer les images qui ne sont similaires à aucune autre image du dataset en utilisant le code suivant :

import numpy as np

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

Visualiser l'espace des embeddings#

Tu peux également visualiser l'espace des embeddings à l'aide de l'outil de traçage de ton choix. Par exemple, voici un exemple simple utilisant 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()

Commence à créer tes propres rapports d'exploration de datasets de vision par ordinateur en utilisant l'API Explorer. Pour trouver l'inspiration, consulte l'exemple VOC Exploration Example.

Applications créées avec Ultralytics Explorer#

Essaie notre GUI Demo basée sur l'API Explorer

FAQ#