API Explorer Ultralytics#

Introduction#

L'API Explorer est une API Python pour explorer tes datasets. Elle prend en charge le filtrage et la recherche dans ton dataset à l'aide de requêtes SQL, de recherches de similarité vectorielle et de recherches sémantiques.

Installation#

Explorer dépend de bibliothèques externes pour certaines de ses fonctionnalités. Elles 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 veux forcer la mise à jour de la table des embeddings, 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 Utiliser la table des embeddings

1. Recherche par similarité#

La recherche par similarité est une technique permettant de trouver des images similaires à une image donnée. Elle repose sur l’idée que des images similaires possèdent des embeddings similaires. Une fois la table des embeddings créée, tu peux effectuer une recherche sémantique de l’une des façons suivantes :

• Sur un index donné ou une liste d’indices du jeu de données : exp.get_similar(idx=[1,10], limit=10)
• Sur une image ou une liste d’images qui ne figurent pas dans le jeu de données : 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 contenant les limit points de données les plus similaires à l’entrée, ainsi que leur distance dans l’espace des embeddings. Tu peux utiliser ce jeu de données 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é des images similaires#

Tu peux également tracer les images similaires à l’aide de la méthode plot_similar. Cette méthode accepte 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. 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 basé sur l’IA convertit ton prompt en requête et renvoie les résultats correspondants. Par exemple, tu peux demander : « montre-moi 100 images contenant exactement une personne et 2 chiens. Il peut aussi y avoir d’autres objets », et la requête sera générée, puis ces résultats seront 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

# 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 jeu de données à l’aide de la méthode sql_query. Cette méthode accepte une requête SQL en entrée et renvoie un DataFrame pandas contenant 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 à l’aide de la méthode plot_sql_query. Cette méthode accepte 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. Utilisation de la table des embeddings#

Tu peux également travailler directement avec la table des embeddings. Une fois la table des embeddings créée, tu peux y accéder à l’aide de 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 les 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 pré- et post-filtres#

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#

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. Cette opération s’effectue à l’aide de 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. Voici quelques exemples :

Indice de similarité#

Explorer inclut une opération similarity_index :

• Elle tente d’estimer le degré de similarité de chaque point de données avec le reste du jeu de données.
• Pour cela, elle compte le nombre d’embeddings d’images situés à une distance inférieure à max_dist de l’image actuelle dans l’espace d’embeddings 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 vers le 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 vers les count images similaires

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Tu peux utiliser l’indice de similarité pour créer 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 embeddings#

Tu peux également visualiser l’espace des embeddings à l’aide de l’outil de tracé de ton choix. Voici par exemple 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 jeux de données de vision par ordinateur avec l’API Explorer. Pour trouver l’inspiration, consulte l’exemple d’exploration de VOC.

Applications créées avec Ultralytics Explorer#

Essaie notre démo GUI basée sur l’API Explorer

FAQ#