Link to this sectionAPI Explorer Ultralytics#

Link to this sectionIntroduction#

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

Link to this sectionInstallation#

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

pip install ultralytics[explorer]

Link to this sectionUtilisation#

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 à ce sujet dans la section Travailler avec la table d'Embeddings.

Link to this section1. 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 auront des embeddings similaires. Une fois la table d'embeddings construite, tu peux lancer une recherche sémantique de l'une des manières suivantes :

• Sur un index ou une liste d'indices donnés dans le jeu de données : exp.get_similar(idx=[1,10], limit=10)
• Sur n'importe quelle image ou 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 cas d'entrées multiples, l'agrégat de leurs embeddings est utilisé.

Tu obtiens un pandas DataFrame 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 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())

Link to this sectionTracer des 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()

Link to this section2. Demander à l'IA (Requêtes en langage naturel)#

Cette fonctionnalité te permet de filtrer ton jeu de données en utilisant le langage naturel, sans écrire de SQL. Le générateur de requêtes alimenté par l'IA convertit ton invite en une 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 LLM, les résultats sont donc probabilistes et peuvent être imprécis.

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

Link to this section3. 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 pandas DataFrame 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())

Link to this sectionTracer les résultats de requêtes 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 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")

Link to this section4. Travailler avec la table d'Embeddings#

Tu peux aussi 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 :

Link to this sectionObtenir des Embeddings bruts#

from ultralytics import Explorer

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

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

Link to this sectionRequê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

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

Link to this sectionCréer un index vectoriel#

Lorsque tu utilises de grands jeux de données, tu peux aussi créer un index vectoriel dédié pour des requêtes plus rapides. Cela se fait en utilisant la méthode create_index sur la table LanceDB.

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

Link to this section5. Applications des Embeddings#

Tu peux utiliser la table des embeddings pour effectuer une variété d'analyses exploratoires. En voici quelques exemples :

Link to this sectionIndice de similarité#

Explorer est livré avec une opération similarity_index :

• Elle tente d'estimer à quel point chaque point de données est similaire au reste du jeu de données.
• Elle le fait 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 pandas DataFrame avec 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 dans le jeu de données qui sont plus proches que 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 construire des conditions personnalisées afin de filtrer le jeu de données. Par exemple, tu peux filtrer les images qui ne sont similaires à aucune autre image dans le jeu de données en utilisant le code suivant :

import numpy as np

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

Link to this sectionVisualiser l'espace d'Embeddings#

Tu peux aussi visualiser l'espace d'embeddings en utilisant 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 jeux de données CV en utilisant l'API Explorer. Pour trouver l'inspiration, consulte l'Exemple d'exploration VOC.

Link to this sectionApplications construites avec Ultralytics Explorer#

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

Link to this sectionFAQ#

Link to this sectionÀ quoi sert l'API Explorer d'Ultralytics ?#

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

Link to this sectionComment installer l'API Explorer d'Ultralytics ?#

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

pip install ultralytics[explorer]

Cela installera automatiquement toutes les bibliothèques externes nécessaires aux fonctionnalités de l'API Explorer. Pour des détails de configuration supplémentaires, reporte-toi à la section d'installation de notre documentation.

Link to this sectionComment puis-je utiliser l'API Explorer d'Ultralytics pour une recherche par similarité ?#

Tu peux utiliser l'API Explorer d'Ultralytics pour effectuer des recherches par 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, merci de visiter la section Recherche par similarité.

Link to this sectionQuels sont les avantages d'utiliser LanceDB avec Ultralytics Explorer ?#

LanceDB, utilisé en arrière-plan par Ultralytics Explorer, fournit des tables d'embeddings évolutives sur disque. Cela garantit que tu peux créer et réutiliser des embeddings pour de grands jeux de données comme COCO sans manquer de mémoire. Ces tables ne sont créées qu'une seule fois et peuvent être réutilisées, améliorant ainsi l'efficacité du traitement des données.

Link to this sectionComment fonctionne la fonctionnalité Demander à l'IA dans l'API Explorer d'Ultralytics ?#

La fonctionnalité Demander à l'IA permet aux utilisateurs de filtrer les jeux de données à l'aide de requêtes en langage naturel. Cette fonctionnalité tire parti des LLM 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 Demander à l'IA.