Ultralytics Explorer API#

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 la recherche de similarité vectorielle et de la recherche sémantique.

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 des analyses avancées. En savoir plus dans la section Working with Embeddings Table section

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 comme 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 la table des embeddings créée, tu peux y accéder en utilisant 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 est fourni avec une opération similarity_index :

• Elle essaie d'estimer à quel point chaque point de données est similaire au reste du dataset.
• Elle fait cela en comptant combien d'embeddings d'images se trouvent plus près que 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 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 aux 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 dataset CV à l'aide de l'API Explorer. Pour trouver l'inspiration, consulte l'exemple VOC Exploration Example.

Applications créées avec Ultralytics Explorer#

Essaie notre GUI Demo basé sur l'API Explorer

FAQ#

À quoi sert l'API Ultralytics Explorer ?#

L'API Ultralytics Explorer est conçue pour une exploration complète des datasets. Elle permet aux utilisateurs de filtrer et de rechercher dans les datasets à l'aide de requêtes SQL, de la recherche de similarité vectorielle et de la recherche sémantique. Cette puissante API Python peut gérer de grands datasets, ce qui la rend idéale pour diverses tâches de computer vision utilisant des modèles Ultralytics.

Comment installer l'API Ultralytics Explorer ?#

Pour installer l'API Ultralytics Explorer ainsi que ses dépendances, utilise la commande suivante :

pip install ultralytics[explorer]

Cela installera automatiquement toutes les bibliothèques externes nécessaires au fonctionnement de l'API Explorer. Pour plus de détails sur la configuration, réfère-toi à la section installation section de notre documentation.

Comment puis-je utiliser l'API Ultralytics Explorer pour la recherche de similarité ?#

Tu peux utiliser l'API Ultralytics Explorer pour effectuer des recherches de similarité en créant une table d'embeddings et en l'interrogeant pour trouver des images similaires. Voici un exemple de 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())

Pour plus de détails, consulte la section Similarity Search section.

Quels sont les avantages d'utiliser LanceDB avec Ultralytics Explorer ?#

LanceDB, utilisé sous le capot par Ultralytics Explorer, fournit des tables d'embeddings évolutives sur le disque. Cela garantit que tu peux créer et réutiliser des embeddings pour de grands datasets comme COCO sans manquer de mémoire. Ces tables ne sont créées qu'une seule fois et peuvent être réutilisées, ce qui améliore l'efficacité du traitement des données.

Comment fonctionne la fonctionnalité Ask AI dans l'API Ultralytics Explorer ?#

La fonctionnalité Ask AI permet aux utilisateurs de filtrer les datasets à l'aide de requêtes en langage naturel. Cette fonctionnalité exploite des LLMs pour convertir ces requêtes en requêtes SQL en arrière-plan. Voici un exemple :

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

Pour plus d'exemples, consulte la section Ask AI section.