API Ultralytics Explorer
Depuis ultralytics>=8.3.12, Ultralytics Explorer a été supprimé. Pour utiliser Explorer, installe pip install ultralytics==8.3.11. Des fonctionnalités similaires (et étendues) d’exploration des jeux de données sont disponibles sur Ultralytics Platform.
Introduction#
L’API Explorer est une API Python qui permet d’explorer tes jeux de données. Elle permet de filtrer et de rechercher dans ton jeu de données à l’aide de requêtes SQL, de la recherche par similarité vectorielle et de la recherche sémantique.
Regarder : Présentation d’Explorer API d’Ultralytics
Installation#
Explorer dépend de bibliothèques externes pour certaines fonctionnalités. Celles-ci sont installées automatiquement lorsque tu utilises Explorer. Pour installer ces dépendances manuellement, exécute la commande suivante :
pip install "ultralytics[explorer]==8.3.11"Utilisation#
from ultralytics import Explorer
# Créer un objet Explorer
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
# Créer des plongements pour ton jeu de données
explorer.create_embeddings_table()
# Rechercher des images similaires à une ou plusieurs images données
df = explorer.get_similar(img="path/to/image.jpg")
# Ou rechercher des images similaires à un ou plusieurs index donnés
df = explorer.get_similar(idx=0)La table Embeddings correspondant à une paire donnée de jeu de données et de modèle n’est créée qu’une seule fois, puis réutilisée. Elle s’appuie sur LanceDB, qui passe à l’échelle sur disque, ce qui te permet de créer et de réutiliser des plongements pour de grands jeux de données comme COCO sans manquer de mémoire.
Pour forcer la mise à jour de la table des plongements, passe force=True à la méthode create_embeddings_table.
Tu peux accéder directement à l’objet table LanceDB pour effectuer des analyses avancées. Pour en savoir plus, consulte la section Utilisation de la table des plongements.
1. Recherche par similarité#
La recherche de similarité, également appelée recherche vectorielle, est une technique qui permet de trouver des images similaires à une image donnée. Elle repose sur l’idée que des images similaires auront des plongements similaires. Une fois la table des plongements créée, tu peux effectuer une recherche de similarité de l’une des façons suivantes :
- À partir d’un index donné ou d’une liste d’index du jeu de données :
exp.get_similar(idx=[1,10], limit=10) - À partir d’une image ou d’une 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 présence de plusieurs entrées, l’agrégat de leurs plongements est utilisé.
Tu obtiens un DataFrame pandas contenant limit points de données les plus similaires à l’entrée, ainsi que leur distance dans l’espace des plongements. Tu peux utiliser ce jeu de données pour effectuer d’autres filtrages.
from ultralytics import Explorer
# créer un objet Explorer
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())
# Effectuer une recherche à partir de plusieurs images
similar = exp.get_similar(
img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
limit=10,
)
print(similar.head())Tracer les 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 affiche les images similaires sous forme de grille.
from ultralytics import Explorer
# créer un objet Explorer
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. Ask AI (requêtes en langage naturel)#
Cette fonctionnalité te permet de filtrer ton jeu de données en langage naturel, sans écrire de requêtes SQL. Le générateur de requêtes propulsé par l’IA convertit ta demande 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 aussi y avoir d’autres objets » ; la fonctionnalité générera la requête et affichera les résultats. Remarque : cette fonctionnalité utilise des LLM, les résultats sont donc probabilistes et peuvent être inexacts.
from ultralytics.data.explorer import plot_query_result
from ultralytics import Explorer
# créer un objet Explorer
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())
# tracer les résultats
plt = plot_query_result(df)
plt.show()3. 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 DataFrame pandas contenant les résultats.
from ultralytics import Explorer
# créer un objet Explorer
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 é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 affiche les résultats sous forme de grille.
from ultralytics import Explorer
# créer un objet Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()
# tracer la requête SQL
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")4. Utilisation de la table des plongements#
Tu peux également travailler directement avec la table des plongements. Une fois cette table créée, tu peux y accéder avec Explorer.table.
En interne, Explorer fonctionne avec des tables LanceDB. Tu peux accéder directement à cette table à l’aide de l’objet Explorer.table et exécuter des requêtes brutes, appliquer des pré-filtres et des post-filtres, etc.
from ultralytics import Explorer
exp = Explorer()
exp.create_embeddings_table()
table = exp.tableVoici quelques exemples d’opérations possibles sur la table :
Récupérer les plongements 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 pré-filtres et post-filtres#
from ultralytics import Explorer
exp = Explorer(model="yolo11n.pt")
exp.create_embeddings_table()
table = exp.table
# Plongement factice
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 jeux de données, tu peux également créer un index vectoriel dédié pour accélérer les requêtes. Pour cela, utilise la méthode create_index sur la table LanceDB.
table.create_index(num_partitions=..., num_sub_vectors=...)5. Applications des plongements#
Tu peux utiliser la table des plongements pour effectuer diverses analyses exploratoires. En voici quelques exemples :
Indice de similarité#
Explorer inclut une opération similarity_index :
- Elle tente d’estimer le degré de similarité entre chaque point de données et le reste du jeu de données.
- Pour ce faire, elle compte le nombre de plongements d’images situés à une distance inférieure à
max_distde l’image actuelle dans l’espace des plongements généré, en considéranttop_kimages similaires à la fois.
Elle renvoie un DataFrame pandas contenant les colonnes suivantes :
idx: index de l’image dans le jeu de donnéesim_file: chemin d’accès au fichier imagecount: nombre d’images du jeu de données situées à une distance inférieure àmax_distde l’image actuellesim_im_files: liste des chemins d’accès aux images similairescount
Pour un jeu de données et un modèle donnés, l’index de similarité sera réutilisé une fois généré avec max_dist et top_k. Si ton jeu de données a changé ou si tu dois régénérer l’index de similarité, passe force=True.
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 jeu de données. Par exemple, le code suivant répertorie les images ayant plus de 30 images similaires dans le jeu de données ; elles sont de bonnes candidates à la suppression des quasi-doublons :
import numpy as np
sim_count = np.array(sim_idx["count"])
sim_idx["im_file"][sim_count > 30]Visualiser l’espace des plongements#
Tu peux également visualiser l’espace des plongements à l’aide de l’outil de traçage de ton choix. Voici un exemple simple qui réduit les plongements avec PCA et les représente avec Matplotlib :
import matplotlib.pyplot as plt
from sklearn.decomposition import PCA
# Réduire les dimensions à 3 composantes avec PCA pour une visualisation en 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)
# Créer un nuage de points 3D avec Matplotlib Axes3D
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")
# Nuage de points
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 de vision par ordinateur à l’aide de l’API Explorer. Pour trouver l’inspiration, consulte l’exemple d’exploration de VOC.
Applications créées avec Ultralytics Explorer#
L’interface graphique Explorer repose sur l’API Explorer.
FAQ#
L’API Ultralytics Explorer est conçue pour l’exploration de jeux de données. Elle te permet de filtrer et de rechercher dans les jeux de données à l’aide de requêtes SQL, de la recherche par similarité vectorielle et de la recherche sémantique. Elle peut traiter de grands jeux de données pour les tâches de vision par ordinateur avec les modèles Ultralytics.
Pour installer l'API Explorer d'Ultralytics avec ses dépendances, utilise la commande suivante :
pip install "ultralytics[explorer]==8.3.11"Cette commande installera automatiquement toutes les bibliothèques externes nécessaires au fonctionnement de l'API Explorer. Pour plus de détails sur la configuration, consulte la section consacrée à l'installation de notre documentation.
Tu peux utiliser l'API Explorer d'Ultralytics pour effectuer des recherches par similarité en créant une table d'embeddings, puis en interrogeant cette table pour trouver des images similaires. Voici un exemple de base :
from ultralytics import Explorer # Créer un objet Explorer explorer = Explorer(data="coco128.yaml", model="yolo11n.pt") explorer.create_embeddings_table() # Rechercher des images similaires à une image donnée similar_images_df = explorer.get_similar(img="path/to/image.jpg") print(similar_images_df.head())Pour plus de détails, consulte la section consacrée à la recherche par similarité.
LanceDB, utilisé en coulisses par Ultralytics Explorer, fournit des tables d'embeddings évolutives stockées sur disque. Tu peux ainsi 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.
La fonctionnalité Ask AI permet aux utilisateurs de filtrer les jeux de données à l'aide de requêtes en langage naturel. Elle s'appuie sur des LLM pour convertir ces requêtes en requêtes SQL en arrière-plan. Voici un exemple :
from ultralytics import Explorer # Créer un objet Explorer explorer = Explorer(data="coco128.yaml", model="yolo11n.pt") explorer.create_embeddings_table() # Interroger en langage naturel 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.
Commentaires2
Pose une question, partage tes résultats ou aide quelqu’un d’autre.
Jie LiuI have downloaded
ultralytics-8.3.118 github zip packageand install it withpip install -e .. Then I usepip install ultralytics[explorer]to install explorer, but I got a error as followedRequirement already satisfied: ultralytics[explorer] in /data/miniconda3/envs/app/lib/python3.10/site-packages (8.3.118) WARNING: ultralytics 8.3.118 does not provide the extra 'explorer' Requirement already satisfied: numpy<=2.1.1,>=1.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.26.4) Requirement already satisfied: matplotlib>=3.3.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (3.10.1) Requirement already satisfied: opencv-python>=4.6.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.11.0.86) Requirement already satisfied: pillow>=7.1.2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (11.2.1) Requirement already satisfied: pyyaml>=5.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (6.0.2) Requirement already satisfied: requests>=2.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.32.3) Requirement already satisfied: scipy>=1.4.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.15.2) Requirement already satisfied: torch>=1.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.3.1) Requirement already satisfied: torchvision>=0.9.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.18.1) Requirement already satisfied: tqdm>=4.64.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.67.1) Requirement already satisfied: psutil in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (7.0.0) Requirement already satisfied: py-cpuinfo in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (9.0.0) Requirement already satisfied: pandas>=1.1.4 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.2.3) Requirement already satisfied: seaborn>=0.11.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.13.2) Requirement already satisfied: ultralytics-thop>=2.0.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.0.14) Requirement already satisfied: contourpy>=1.0.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.3.2) Requirement already satisfied: cycler>=0.10 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (0.12.1) Requirement already satisfied: fonttools>=4.22.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (4.57.0) Requirement already satisfied: kiwisolver>=1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.4.8) Requirement already satisfied: packaging>=20.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (24.2) Requirement already satisfied: pyparsing>=2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (3.2.3) Requirement already satisfied: python-dateutil>=2.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (2.9.0.post0) Requirement already satisfied: pytz>=2020.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2022.7.1) Requirement already satisfied: tzdata>=2022.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2025.2) Requirement already satisfied: charset-normalizer<4,>=2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.4.1) Requirement already satisfied: idna<4,>=2.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.10) Requirement already satisfied: urllib3<3,>=1.21.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (1.26.20) Requirement already satisfied: certifi>=2017.4.17 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (2025.4.26) Requirement already satisfied: filelock in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.18.0) Requirement already satisfied: typing-extensions>=4.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (4.13.2) Requirement already satisfied: sympy in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (1.13.3) Requirement already satisfied: networkx in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.4.2) Requirement already satisfied: jinja2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.1.6) Requirement already satisfied: fsspec in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2025.3.2) Requirement already satisfied: nvidia-cuda-nvrtc-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cuda-runtime-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cuda-cupti-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cudnn-cu12==8.9.2.26 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (8.9.2.26) Requirement already satisfied: nvidia-cublas-cu12==12.1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.3.1) Requirement already satisfied: nvidia-cufft-cu12==11.0.2.54 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.0.2.54) Requirement already satisfied: nvidia-curand-cu12==10.3.2.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (10.3.2.106) Requirement already satisfied: nvidia-cusolver-cu12==11.4.5.107 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.4.5.107) Requirement already satisfied: nvidia-cusparse-cu12==12.1.0.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.0.106) Requirement already satisfied: nvidia-nccl-cu12==2.20.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.20.5) Requirement already satisfied: nvidia-nvtx-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: triton==2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.3.1) Requirement already satisfied: nvidia-nvjitlink-cu12 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from nvidia-cusolver-cu12==11.4.5.107->torch>=1.8.0->ultralytics[explorer]) (12.8.93) Requirement already satisfied: six>=1.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from python-dateutil>=2.7->matplotlib>=3.3.0->ultralytics[explorer]) (1.17.0) Requirement already satisfied: MarkupSafe>=2.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from jinja2->torch>=1.8.0->ultralytics[explorer]) (3.0.2) Requirement already satisfied: mpmath<1.4,>=1.1.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from sympy->torch>=1.8.0->ultralytics[explorer]) (1.3.0)when run code
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)The error has arisen
Traceback (most recent call last): File "/data/liujie/data/ultralytics-8.3.13/tutorial/debug/explorer.py", line 1, in <module> from ultralytics import Explorer ImportError: cannot import name 'Explorer' from 'ultralytics' (/data/liujie/data/ultralytics-8.3.118/ultralytics/__init__.py)please help me to install and use explorer
Glenn JocherUltralytics(modifié)Hi @keeper-jie,
The issue you're experiencing is because Ultralytics Explorer has been removed since version 8.3.12, and you're using version 8.3.118. That's why you're seeing the warning that the 'explorer' extra is not provided and why you can't import the Explorer class.
As noted in our documentation, we've moved this functionality to Ultralytics Platform, our platform that offers similar and enhanced capabilities for exploring, visualizing, and managing your datasets without writing code.
If you specifically need the Explorer API functionality in your code, you would need to downgrade to a version prior to 8.3.12. However, we recommend trying Ultralytics Platform instead, as it provides an improved experience with all the dataset exploration features you're looking for.
Let me know if you need any further assistance with Ultralytics Platform or if you have any other questions.