Skip to content

Ultralytics API de l'explorateur

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="yolov8n.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

La table des embeddings pour un ensemble de données et une paire de modÚles donnés n'est créée qu'une seule fois et réutilisée. Ceux-ci utilisent LanceDB sous le capot, qui s'étend sur le disque, de sorte que tu peux créer et réutiliser des embeddings pour de grands ensembles de données tels que COCO sans manquer de mémoire.

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="yolov8n.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="yolov8n.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="yolov8n.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="yolov8n.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="yolov8n.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="yolov8n.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="yolov8n.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

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="yolov8n.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
import numpy as np
from mpl_toolkits.mplot3d import Axes3D
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


Created 2024-01-07, Updated 2024-06-02
Authors: glenn-jocher (10), 0xSynapse (1), RizwanMunawar (2), AyushExel (2)

Commentaires