Ultralytics Explorer API#

Introducción#

La Explorer API es una API de Python para explorar tus conjuntos de datos. Permite filtrar y buscar en tu conjunto de datos mediante consultas SQL, búsqueda de similitud de vectores y búsqueda semántica.

Instalación#

Explorer depende de bibliotecas externas para parte de su funcionalidad. Estas se instalan automáticamente cuando usas Explorer. Para instalar estas dependencias manualmente, usa el siguiente comando:

pip install ultralytics[explorer]

Uso#

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
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 quieres forzar la actualización de la tabla de embeddings, puedes pasar force=True al método create_embeddings_table.

Puedes acceder directamente al objeto de la tabla de LanceDB para realizar análisis avanzados. Obtén más información al respecto en la sección Trabajando con la tabla de embeddings.

1. Búsqueda de similitud#

La búsqueda de similitud es una técnica para encontrar imágenes similares a una imagen dada. Se basa en la idea de que las imágenes similares tendrán embeddings similares. Una vez que la tabla de embeddings esté construida, puedes realizar una búsqueda semántica de cualquiera de las siguientes maneras:

• En un índice determinado o una lista de índices en el conjunto de datos: exp.get_similar(idx=[1,10], limit=10)
• En cualquier imagen o 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)

En caso de múltiples entradas, se utiliza el agregado de sus embeddings.

Obtienes 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 realizar un filtrado adicional.

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

Graficar imágenes similares#

También puedes graficar las imágenes similares usando el método plot_similar. Este método toma los mismos argumentos que get_similar y grafica las imágenes similares en una cuadrícula.

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

2. Preguntar a la IA (Consultas en lenguaje natural)#

Esta función te permite filtrar tu conjunto de datos usando lenguaje natural, sin escribir SQL. El generador de consultas impulsado por 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 LLMs, por lo que los resultados son probabilísticos y pueden ser inexactos.

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# 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. Consultas SQL#

Puedes ejecutar consultas SQL en tu conjunto de datos usando el método sql_query. Este método toma una consulta SQL como entrada y devuelve un DataFrame de pandas con los resultados.

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

Graficar los resultados de la consulta SQL#

También puedes graficar los resultados de una consulta SQL usando el método plot_sql_query. Este método toma los mismos argumentos que sql_query y grafica los resultados en una cuadrícula.

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. Trabajando con la tabla de embeddings#

También puedes trabajar directamente con la tabla de embeddings. Una vez que se crea la tabla de embeddings, puedes acceder a ella usando Explorer.table.

from ultralytics import Explorer

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

Aquí tienes 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

# Dummy embedding
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

Crear índice de vectores#

Al utilizar conjuntos de datos grandes, también puedes crear un índice de vectores dedicado para realizar consultas más rápido. Esto se hace usando el método create_index en la tabla de LanceDB.

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

5. Aplicaciones de embeddings#

Puedes usar la tabla de embeddings para realizar una variedad de análisis exploratorios. Aquí tienes algunos ejemplos:

Índice de similitud#

Explorer incluye una operación de similarity_index:

• Intenta estimar cuán similar es cada punto de datos con el resto del conjunto de datos.
• Lo hace contando cuántos embeddings de imágenes se encuentran más cerca de max_dist de la imagen actual en el espacio de embeddings generado, considerando top_k imágenes similares a la vez.

Devuelve un DataFrame de pandas con las siguientes columnas:

• idx: Índice de la imagen en el conjunto de datos
• im_file: Ruta al archivo de imagen
• count: Número de imágenes en el conjunto de datos que están más cerca de max_dist de la imagen actual
• sim_im_files: Lista de rutas a las count imágenes similares

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Puedes usar el índice de similitud para construir condiciones personalizadas para filtrar el conjunto de datos. Por ejemplo, puedes filtrar las imágenes que no son similares a ninguna otra imagen en el conjunto de datos usando el siguiente código:

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 utilizando la herramienta de gráficos de tu preferencia. Por ejemplo, aquí tienes un ejemplo sencillo usando 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()

Empieza a crear tus propios informes de exploración de conjuntos de datos de CV utilizando la Explorer API. Como inspiración, consulta el Ejemplo de exploración de VOC.

Aplicaciones creadas con Ultralytics Explorer#

Prueba nuestra Demostración de la interfaz gráfica basada en la Explorer API

FAQ#

¿Para qué se utiliza la Ultralytics Explorer API?#

La Ultralytics Explorer API está diseñada para la exploración exhaustiva de conjuntos de datos. Permite a los usuarios filtrar y buscar en conjuntos de datos mediante consultas SQL, búsqueda de similitud de vectores y búsqueda semántica. Esta potente API de Python puede manejar conjuntos de datos grandes, lo que la hace ideal para varias tareas de visión artificial utilizando modelos de Ultralytics.

¿Cómo instalo la Ultralytics Explorer API?#

Para instalar la Ultralytics Explorer API junto con sus dependencias, utiliza el siguiente comando:

pip install ultralytics[explorer]

Esto instalará automáticamente todas las bibliotecas externas necesarias para el funcionamiento de la Explorer API. Para obtener detalles de configuración adicionales, consulta la sección de instalación de nuestra documentación.

¿Cómo puedo usar la Ultralytics Explorer API para la búsqueda de similitud?#

Puedes usar la Ultralytics Explorer API para realizar búsquedas de similitud creando una tabla de embeddings y consultándola para encontrar imágenes similares. Aquí tienes un ejemplo básico:

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

Para obtener más detalles, visita la sección de Búsqueda de similitud.

¿Cuáles son los beneficios de usar LanceDB con Ultralytics Explorer?#

LanceDB, utilizado internamente por Ultralytics Explorer, proporciona tablas de embeddings escalables en disco. Esto garantiza que puedas crear y reutilizar embeddings para conjuntos de datos grandes como COCO sin agotar la memoria. Estas tablas solo se crean una vez y se pueden reutilizar, lo que mejora la eficiencia en el manejo de datos.

¿Cómo funciona la función de Preguntar a la IA en la Ultralytics Explorer API?#

La función Preguntar a la IA permite a los usuarios 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

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

Para ver más ejemplos, consulta la sección de Preguntar a la IA.