Skip to content

Ultralytics API de l'explorateur

Community Note ⚠️

As of ultralytics>=8.3.10, Ultralytics explorer support has been deprecated. But don't worry! You can now access similar and even enhanced functionality through Ultralytics HUB, our intuitive no-code platform designed to streamline your workflow. With Ultralytics HUB, you can continue exploring, visualizing, and managing your data effortlessly, all without writing a single line of code. Make sure to check it out and take advantage of its powerful features!🚀

Introduction

Open In Colab L'API Explorer est une API Python qui permet d'explorer tes ensembles de données. Elle prend en charge le filtrage et la recherche de tes ensembles de données à l'aide de requêtes SQL, la recherche par similarité vectorielle et la recherche sémantique.



Regarde : Ultralytics Aperçu de l'API Explorer

Installation

Explorer dépend de bibliothèques externes pour certaines de ses fonctionnalités. Celles-ci sont automatiquement installées lors de l'utilisation. 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
dataframe = explorer.get_similar(img="path/to/image.jpg")

# Or search for similar images to a given index/indices
dataframe = explorer.get_similar(idx=0)

Note

Embeddings table for a given dataset and model pair is only created once and reused. These use LanceDB under the hood, which scales on-disk, so you can create and reuse embeddings for large datasets like COCO without running out of memory.

Si tu veux forcer la mise à jour de la table d'encastrements, tu peux passer la commande force=True à create_embeddings_table méthode.

Tu peux accéder directement à l'objet tableau de LanceDB pour effectuer des analyses avancées. Tu trouveras plus d'informations à ce sujet dans la section Travailler avec le tableau Embeddings.

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 que la table des embeddings est construite, tu peux lancer une recherche sémantique de l'une des façons suivantes :

  • Sur un index donné ou une liste d'index dans l'ensemble de données : exp.get_similar(idx=[1,10], limit=10)
  • Sur n'importe quelle image ou liste d'images ne figurant pas dans l'ensemble de données : exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

En cas d'entrées multiples, c'est l'agrégat de leur intégration qui est utilisé.

Tu obtiens un cadre de données pandas avec l'attribut limit le nombre de points de données les plus similaires à l'entrée, ainsi que leur distance dans l'espace d'intégration. Tu peux utiliser cet ensemble de données pour effectuer d'autres filtrages

Recherche sémantique

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())
from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

similar = exp.get_similar(idx=1, limit=10)
print(similar.head())

# Search using multiple indices
similar = exp.get_similar(idx=[1, 10], limit=10)
print(similar.head())

Tracer des images similaires

Tu peux aussi tracer les images similaires à l'aide de la fonction plot_similar . Cette méthode prend les mêmes arguments que get_similar et place les images similaires dans une grille.

Tracer des images similaires

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()
from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

plt = exp.plot_similar(idx=1, limit=10)
plt.show()

2. Ask AI (interrogation en langage naturel)

Cela te permet d'écrire comment tu veux filtrer ton ensemble de données en utilisant le langage naturel. Tu n'as pas besoin de maîtriser l'écriture de requêtes SQL. Notre générateur de requêtes alimenté par l'IA le fera automatiquement sous le capot. Par exemple, tu peux dire : "Montre-moi 100 images avec exactement une personne et 2 chiens. Il peut y avoir d'autres objets aussi" et il générera en interne la requête et te montrera les résultats. Remarque : cette méthode utilise des LLM sous le capot, les résultats sont donc probabilistes et peuvent parfois se tromper.

Demande à l'IA

from ultralytics import Explorer
from ultralytics.data.explorer import plot_query_result

# 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ête SQL

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

Requête SQL

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

Tracer les résultats d'une requête SQL

Tu peux aussi tracer les résultats d'une requête SQL à l'aide de la fonction plot_sql_query . Cette méthode prend les mêmes arguments que sql_query et affiche les résultats dans une grille.

Tracer les résultats d'une requête SQL

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 les tableaux d'encodage

Tu peux aussi travailler directement avec le tableau des enchâssements. Une fois que le tableau des enchâssements est créé, tu peux y accéder à l'aide de la fonction Explorer.table

Astuce

Explorer fonctionne sur LanceDB en interne. Tu peux accéder à cette table directement, en utilisant Explorer.table et d'exécuter des requêtes brutes, de mettre en place des pré et post-filtres, etc.

from ultralytics import Explorer

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

Voici quelques exemples de ce que tu peux faire avec le tableau :

Obtenir les emboîtements bruts

Exemple

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é et post-filtres

Exemple

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 ensembles de données, tu peux également créer un index vectoriel dédié pour accélérer les requêtes. Cela se fait à l'aide de la fonction create_index sur la table LanceDB.

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

Tu trouveras plus de détails sur les types d'indices vectoriels disponibles et les paramètres ici À l'avenir, nous ajouterons la prise en charge de la création d'indices vectoriels directement à partir de l'API de l'explorateur.

5. Applications de l'intégration

Tu peux utiliser le tableau des enchâssements pour effectuer toute une série d'analyses exploratoires. Voici quelques exemples :

Indice de similitude

Explorer est livré avec un similarity_index l'opération :

  • Il tente d'estimer le degré de similitude de chaque point de données avec le reste de l'ensemble de données.
  • Pour ce faire, il compte le nombre d'images intégrées qui sont plus proches que max_dist à l'image actuelle dans l'espace d'intégration généré, en considérant que top_k des images similaires à la fois.

Il renvoie un cadre de données pandas avec les colonnes suivantes :

  • idx: Index de l'image dans l'ensemble de données
  • im_file: Chemin d'accès au fichier image
  • count: Nombre d'images dans l'ensemble de données qui sont plus proches que max_dist à l'image actuelle
  • sim_im_files: Liste des chemins d'accès au count images similaires

Astuce

Pour un ensemble de données donné, le modèle, max_dist & top_k l'index de similarité une fois généré sera réutilisé. Si ton jeu de données a changé, ou si tu as simplement besoin de régénérer l'indice de similarité, tu peux passer le paramètre force=True.

Indice de similitude

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 l'ensemble des données. Par exemple, tu peux filtrer les images qui ne sont similaires à aucune autre image de l'ensemble 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 d'intégration

Tu peux aussi visualiser l'espace d'encastrement à l'aide de l'outil de traçage 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 CV à l'aide de l'API Explorer. Pour t'inspirer, jette un coup d'œil à la page

Applications créées à l'aide de Ultralytics Explorer

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

Bientôt disponible

  • [Fusionner les étiquettes spécifiques des ensembles de données. Exemple - Importer tout person étiquettes de COCO et car étiquettes de paysages urbains
  • [Supprime les images dont l'indice de similarité est supérieur au seuil fixé.
  • [ ] Faire persister automatiquement les nouveaux jeux de données après avoir fusionné/supprimé des entrées.
  • [Visualisations avancées des ensembles de données

FAQ

À quoi sert l'API de Ultralytics Explorer ?

The Ultralytics Explorer API is designed for comprehensive dataset exploration. It allows users to filter and search datasets using SQL queries, vector similarity search, and semantic search. This powerful Python API can handle large datasets, making it ideal for various computer vision tasks using Ultralytics models.

Comment installer l'API Ultralytics Explorer ?

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

pip install ultralytics[explorer]

This will automatically install all necessary external libraries for the Explorer API functionality. For additional setup details, refer to the installation section of our documentation.

Tu peux utiliser l'API de Ultralytics Explorer pour effectuer des recherches de similarité en créant une table d'intégration 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())

For more details, please visit the Similarity Search section.

Quels sont les avantages de l'utilisation de LanceDB avec Ultralytics Explorer ?

LanceDB, utilisé sous le capot de Ultralytics Explorer, fournit des tables d'intégration évolutives sur disque. Cela garantit que tu peux créer et réutiliser des embeddings pour de grands ensembles 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 fonction Ask AI dans l'API de Ultralytics Explorer ?

La fonction Ask AI permet aux utilisateurs de filtrer des ensembles de données à l'aide de requêtes en langage naturel. Cette fonctionnalité s'appuie sur les LLM pour convertir ces requêtes en requêtes SQL dans les coulisses. 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 Demande à l'IA.

📅 Created 10 months ago ✏️ Updated 22 days ago

Commentaires