API de Ultralytics Explorer
Desde ultralytics>=8.3.12, Ultralytics Explorer ya no está disponible. Para usar Explorer, instala pip install ultralytics==8.3.11. En Ultralytics Platform tienes funciones similares y ampliadas para explorar conjuntos de datos.
Introducción#
La API de Explorer es una API de Python para explorar tus conjuntos de datos. Permite filtrarlos y buscarlos mediante consultas SQL, búsqueda por similitud vectorial y búsqueda semántica.
Ver: Descripción general de la API Explorer de Ultralytics
Instalación#
Explorer depende de bibliotecas externas para algunas de sus funciones. Se instalan automáticamente al usar Explorer. Para instalar estas dependencias manualmente, usa el siguiente comando:
pip install "ultralytics[explorer]==8.3.11"Uso#
from ultralytics import Explorer
# Crear un objeto Explorer
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
# Crear embeddings para tu conjunto de datos
explorer.create_embeddings_table()
# Buscar imágenes similares a una o varias imágenes dadas
df = explorer.get_similar(img="path/to/image.jpg")
# O buscar imágenes similares a uno o varios índices dados
df = explorer.get_similar(idx=0)La tabla de embeddings para un par determinado de conjunto de datos y modelo solo se crea una vez y se reutiliza. Esta tabla usa LanceDB internamente, que escala en disco, así que puedes crear y reutilizar embeddings para conjuntos de datos grandes como COCO sin quedarte sin memoria.
Para forzar la actualización de la tabla de embeddings, pasa force=True al método create_embeddings_table.
Puedes acceder directamente al objeto de tabla de LanceDB para realizar análisis avanzados. Descubre más en la sección Trabajo con la tabla de embeddings.
1. Búsqueda por similitud#
La búsqueda por similitud, también conocida como búsqueda vectorial, es una técnica para encontrar imágenes similares a una imagen determinada. Se basa en la idea de que las imágenes similares tendrán embeddings similares. Una vez creada la tabla de embeddings, puedes ejecutar una búsqueda por similitud de cualquiera de las siguientes formas:
- Con un índice o una lista de índices determinados del conjunto de datos:
exp.get_similar(idx=[1,10], limit=10) - Con una imagen o una lista de imágenes que no estén en el conjunto de datos:
exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)
Si hay varias entradas, se usa el conjunto agregado de sus embeddings.
Obtendrás un DataFrame de pandas con el número limit de puntos de datos más similares a la entrada, junto con su distancia en el espacio de embeddings. Puedes usar este conjunto de datos para aplicar filtros adicionales.
from ultralytics import Explorer
# crear un objeto 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())
# Buscar con varias imágenes
similar = exp.get_similar(
img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
limit=10,
)
print(similar.head())Representación de imágenes similares#
También puedes representar las imágenes similares con el método plot_similar. Este método acepta los mismos argumentos que get_similar y representa las imágenes similares en una cuadrícula.
from ultralytics import Explorer
# crear un objeto 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 (consultas en lenguaje natural)#
Esta función te permite filtrar tu conjunto de datos mediante lenguaje natural, sin escribir SQL. El generador de consultas basado en IA convierte tu instrucción en una consulta y devuelve los resultados coincidentes. Por ejemplo, puedes pedir: «muéstrame 100 imágenes con exactamente una persona y 2 perros. También puede haber otros objetos» y generará la consulta y te mostrará esos resultados. Nota: Esta función utiliza LLM, por lo que los resultados son probabilísticos y pueden ser inexactos.
from ultralytics.data.explorer import plot_query_result
from ultralytics import Explorer
# crear un objeto 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())
# representar los resultados
plt = plot_query_result(df)
plt.show()3. Consultas SQL#
Puedes ejecutar consultas SQL en tu conjunto de datos con el método sql_query. Este método acepta una consulta SQL como entrada y devuelve un DataFrame de pandas con los resultados.
from ultralytics import Explorer
# crear un objeto 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())Representación de los resultados de consultas SQL#
También puedes representar los resultados de una consulta SQL con el método plot_sql_query. Este método acepta los mismos argumentos que sql_query y representa los resultados en una cuadrícula.
from ultralytics import Explorer
# crear un objeto Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()
# representar la consulta SQL
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")4. Trabajo con la tabla de embeddings#
También puedes trabajar directamente con la tabla de embeddings. Una vez creada, puedes acceder a ella con Explorer.table.
Explorer trabaja internamente con tablas de LanceDB. Puedes acceder directamente a esta tabla con el objeto Explorer.table y ejecutar consultas sin procesar, aplicar filtros previos y posteriores, etc.
from ultralytics import Explorer
exp = Explorer()
exp.create_embeddings_table()
table = exp.tableEstos son algunos ejemplos de lo que puedes hacer con la tabla:
Obtener embeddings sin procesar#
from ultralytics import Explorer
exp = Explorer()
exp.create_embeddings_table()
table = exp.table
embeddings = table.to_pandas()["vector"]
print(embeddings)Consultas avanzadas con filtros previos y posteriores#
from ultralytics import Explorer
exp = Explorer(model="yolo11n.pt")
exp.create_embeddings_table()
table = exp.table
# Embedding ficticio
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)Crear un índice vectorial#
Al trabajar con conjuntos de datos grandes, también puedes crear un índice vectorial específico para agilizar las consultas. Para ello, usa el método create_index en la tabla de LanceDB.
table.create_index(num_partitions=..., num_sub_vectors=...)5. Aplicaciones de los embeddings#
Puedes usar la tabla de embeddings para realizar distintos análisis exploratorios. Aquí tienes algunos ejemplos:
Índice de similitud#
Explorer incluye una operación similarity_index:
- Intenta calcular el grado de similitud de cada punto de datos con el resto del conjunto de datos.
- Para ello, cuenta cuántos embeddings de imágenes están más cerca de la imagen actual que
max_disten el espacio de embeddings generado, teniendo en cuentatop_kimágenes similares cada vez.
Devuelve un DataFrame de pandas con las siguientes columnas:
idx: índice de la imagen en el conjunto de datosim_file: ruta al archivo de imagencount: número de imágenes del conjunto de datos que están más cerca de la imagen actual quemax_distsim_im_files: lista de rutas a lascountimágenes similares
Para un conjunto de datos, un modelo, max_dist y top_k, se reutilizará el índice de similitud una vez generado. Si tu conjunto de datos ha cambiado o necesitas volver a generar el índice de similitud, pasa force=True.
from ultralytics import Explorer
exp = Explorer()
exp.create_embeddings_table()
sim_idx = exp.similarity_index()Puedes utilizar el índice de similitud para crear condiciones personalizadas para filtrar el conjunto de datos. Por ejemplo, el siguiente código enumera las imágenes que tienen más de 30 imágenes similares en el conjunto de datos, que son buenas candidatas para eliminar duplicados aproximados:
import numpy as np
sim_count = np.array(sim_idx["count"])
sim_idx["im_file"][sim_count > 30]Visualizar el espacio de embeddings#
También puedes visualizar el espacio de embeddings con la herramienta de representación gráfica que prefieras. Aquí tienes un ejemplo sencillo que reduce los embeddings con PCA y los representa con Matplotlib:
import matplotlib.pyplot as plt
from sklearn.decomposition import PCA
# Reducir las dimensiones a 3 componentes con PCA para visualizarlas en 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)
# Crear un gráfico de dispersión 3D con Matplotlib Axes3D
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")
# Gráfico de dispersión
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()Empieza a crear tus propios informes de exploración de conjuntos de datos de visión artificial con la API de Explorer. Si necesitas inspiración, consulta el ejemplo de exploración de VOC.
Aplicaciones creadas con Ultralytics Explorer#
La interfaz gráfica de Explorer está construida sobre la API de Explorer.
Preguntas frecuentes#
La API de Ultralytics Explorer está diseñada para explorar conjuntos de datos. Te permite filtrarlos y buscarlos mediante consultas SQL, búsqueda por similitud vectorial y búsqueda semántica, y puede escalar a conjuntos de datos grandes para tareas de visión artificial con modelos de Ultralytics.
Para instalar la API Explorer de Ultralytics junto con sus dependencias, usa el siguiente comando:
pip install "ultralytics[explorer]==8.3.11"Esto instalará automáticamente todas las bibliotecas externas necesarias para que funcione la API Explorer. Para obtener más información sobre la configuración, consulta la sección de instalación de nuestra documentación.
Puedes usar la API Explorer de Ultralytics para realizar búsquedas por similitud creando una tabla de embeddings y consultándola para encontrar imágenes similares. Aquí tienes un ejemplo básico:
from ultralytics import Explorer # Crear un objeto Explorer explorer = Explorer(data="coco128.yaml", model="yolo11n.pt") explorer.create_embeddings_table() # Buscar imágenes similares a una imagen determinada similar_images_df = explorer.get_similar(img="path/to/image.jpg") print(similar_images_df.head())Para obtener más información, visita la sección Búsqueda por similitud.
LanceDB, que Ultralytics Explorer utiliza internamente, proporciona tablas de embeddings escalables almacenadas en disco. Así puedes crear y reutilizar embeddings para grandes conjuntos de datos, como COCO, sin quedarte sin memoria. Estas tablas solo se crean una vez y se pueden reutilizar, lo que mejora la eficiencia en la gestión de datos.
La función Ask AI permite filtrar conjuntos de datos mediante consultas en lenguaje natural. Esta función aprovecha los LLMs para convertir estas consultas en consultas SQL en segundo plano. Aquí tienes un ejemplo:
from ultralytics import Explorer # Crear un objeto Explorer explorer = Explorer(data="coco128.yaml", model="yolo11n.pt") explorer.create_embeddings_table() # Consultar en lenguaje natural 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())Para ver más ejemplos, consulta la sección Ask AI.
Comentarios2
Haz una pregunta, comparte tus resultados o ayuda a otra persona.
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(editado)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.