Ultralytics Explorer API

Introduction

L'Explorer API est une Python API pour explorer tes jeux de données. Elle prend en charge le filtrage et la recherche dans ton jeu de données en utilisant des requêtes SQL, la recherche par similarité vectorielle et 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="yolo26n.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 de table LanceDB pour effectuer une analyse avancée. Apprends-en plus à ce sujet dans la section Travailler avec la table des Embeddings

1. Recherche de similarité

La recherche de similarité est une technique pour trouver des images similaires à une image donnée. Elle est basée 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'index dans le jeu de données : exp.get_similar(idx=[1,10], limit=10)
• Sur n'importe quelle image ou liste d'images ne faisant pas partie du 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 d'embedding. 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="yolo26n.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())

Tracer des images similaires

Tu peux aussi tracer les images similaires en utilisant 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="yolo26n.pt")
exp.create_embeddings_table()

plt = exp.plot_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
plt.show()

2. Ask AI (Requête 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 basé sur l'IA convertit ton prompt 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. Note : Cette fonctionnalité utilise des LLMs, donc les résultats sont 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="yolo26n.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ête SQL

Tu peux exécuter des requêtes SQL sur ton jeu de données en utilisant 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="yolo26n.pt")
exp.create_embeddings_table()

df = exp.sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%'")
print(df.head())

Tracer les résultats de requête SQL

Tu peux aussi 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="yolo26n.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 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 :

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ête avancée avec pré-filtres et post-filtres

from ultralytics import Explorer

exp = Explorer(model="yolo26n.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 jeux de données, tu peux aussi créer un index vectoriel dédié pour une interrogation plus rapide. Cela se fait en utilisant 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 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'embedding 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]

Visualiser l'espace d'Embedding

Tu peux aussi visualiser l'espace d'embedding 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'Explorer API. Pour de l'inspiration, consulte l'Exemple d'exploration VOC.

Applications construites avec Ultralytics Explorer

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

FAQ

À quoi sert l'Ultralytics Explorer API ?

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

Comment installer l'Ultralytics Explorer API ?

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

pip install ultralytics[explorer]

Ceci installera automatiquement toutes les bibliothèques externes nécessaires pour la fonctionnalité de l'Explorer API. Pour plus de détails sur la configuration, reporte-toi à la section installation de notre documentation.

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

Tu peux utiliser l'Ultralytics Explorer API pour effectuer des recherches de similarité en créant une table d'embeddings et en l'interrogeant pour des images similaires. Voici un exemple de base :

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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, visite la section Recherche de similarité.

Quels 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, ce qui améliore l'efficacité du traitement des données.

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

La fonctionnalité Ask AI permet aux utilisateurs de filtrer les jeux de données en utilisant des requêtes en langage naturel. Cette fonctionnalité exploite des LLMs pour convertir ces requêtes en requêtes SQL en coulisses. Voici un exemple :

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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.