API Ultralytics Explorer#

Introduction#

L’API Explorer est une API Python permettant d’explorer tes jeux de données. Elle permet de filtrer et de rechercher dans ton jeu de données à l’aide de requêtes SQL, de la recherche par similarité vectorielle et de la recherche sémantique.

Installation#

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

pip install "ultralytics[explorer]==8.3.11"

Utilisation#

from ultralytics import Explorer

# Créer un objet Explorer
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# Créer des plongements pour ton jeu de données
explorer.create_embeddings_table()

# Rechercher des images similaires à une ou plusieurs images données
df = explorer.get_similar(img="path/to/image.jpg")

# Ou rechercher des images similaires à un ou plusieurs index donnés
df = explorer.get_similar(idx=0)

Si tu veux forcer la mise à jour de la table des plongements, tu peux transmettre force=True à la méthode create_embeddings_table.

Tu peux accéder directement à l’objet table LanceDB pour effectuer des analyses avancées. Pour en savoir plus, consulte la section Utilisation de la table des plongements.

1. Recherche par similarité#

La recherche par similarité est une technique qui permet de trouver des images similaires à une image donnée. Elle repose sur l’idée que des images similaires auront des plongements similaires. Une fois la table des plongements créée, tu peux lancer une recherche par similarité de l’une des façons suivantes :

• À partir d’un index donné ou d’une liste d’index du jeu de données : exp.get_similar(idx=[1,10], limit=10)
• À partir d’une image ou d’une liste d’images ne figurant pas dans le jeu de données : exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

En présence de plusieurs entrées, l’agrégat de leurs plongements est utilisé.

Tu obtiens un DataFrame pandas contenant limit points de données les plus similaires à l’entrée, ainsi que leur distance dans l’espace des plongements. Tu peux utiliser ce jeu de données pour effectuer d’autres filtrages.

from ultralytics import Explorer

# créer un objet 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())

# Effectuer une recherche à partir de plusieurs images
similar = exp.get_similar(
    img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
    limit=10,
)
print(similar.head())

Tracer les 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 affiche les images similaires sous forme de grille.

from ultralytics import Explorer

# créer un objet 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 (requêtes en langage naturel)#

Cette fonctionnalité te permet de filtrer ton jeu de données en 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 aussi y avoir d’autres objets" ; la requête sera générée et les résultats correspondants affichés. Remarque : cette fonctionnalité utilise des LLM ; les résultats sont donc probabilistes et peuvent être inexacts.

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# créer un objet 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())

# tracer les résultats
plt = plot_query_result(df)
plt.show()

3. Requêtes SQL#

Tu peux exécuter des requêtes SQL sur ton jeu de données à l’aide de la méthode sql_query. Cette méthode prend une requête SQL en entrée et renvoie un DataFrame pandas contenant les résultats.

from ultralytics import Explorer

# créer un objet 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())

Tracer les résultats d’une requête SQL#

Tu peux également tracer les résultats d’une requête SQL à l’aide de la méthode plot_sql_query. Cette méthode prend les mêmes arguments que sql_query et affiche les résultats sous forme de grille.

from ultralytics import Explorer

# créer un objet Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# tracer la requête SQL
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. Utilisation de la table des plongements#

Tu peux également travailler directement avec la table des plongements. Une fois cette table créée, tu peux y accéder avec Explorer.table.

from ultralytics import Explorer

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

Voici quelques exemples d’opérations possibles sur la table :

Récupérer les plongements 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 pré-filtres et post-filtres#

from ultralytics import Explorer

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

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

Créer un index vectoriel#

Lorsque tu utilises de grands jeux de données, tu peux également créer un index vectoriel dédié pour accélérer les requêtes. Pour cela, utilise la méthode create_index sur la table LanceDB.

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

5. Applications des plongements#

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

Indice de similarité#

Explorer inclut une opération similarity_index :

• Elle tente d’estimer le degré de similarité entre chaque point de données et le reste du jeu de données.
• Pour ce faire, elle compte le nombre de plongements d’images situés à une distance inférieure à max_dist de l’image actuelle dans l’espace des plongements généré, en considérant top_k images similaires à la fois.

Elle renvoie un DataFrame pandas contenant les colonnes suivantes :

• idx : index de l’image dans le jeu de données
• im_file : chemin d’accès au fichier image
• count : nombre d’images du jeu de données situées à une distance inférieure à max_dist de l’image actuelle
• sim_im_files : liste des chemins d’accès aux images similaires count

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Tu peux utiliser l’indice de similarité pour définir des conditions personnalisées afin de filtrer le jeu de données. Par exemple, tu peux exclure les images qui ne sont similaires à aucune autre image du jeu de données à l’aide du code suivant :

import numpy as np

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

Visualiser l’espace des plongements#

Tu peux également visualiser l’espace des plongements avec l’outil de traçage de ton choix. Voici un exemple simple utilisant Matplotlib :

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

# Réduire les dimensions à 3 composantes avec PCA pour une visualisation en 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Créer un nuage de points 3D avec Matplotlib Axes3D
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# Nuage de points
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 jeux de données de vision par ordinateur à l’aide de l’API Explorer. Pour trouver l’inspiration, consulte l’exemple d’exploration de VOC.

Applications créées avec Ultralytics Explorer#

Essaie notre démo avec interface graphique basée sur l’API Explorer

FAQ#