Ultralytics Explorer API

Introducción

La API Explorer 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 vectorial y búsqueda semántica.

Instalación

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

pip install ultralytics[explorer]

Uso

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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)

En caso de que quieras 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. Aprende más sobre ello en la sección Trabajando con la tabla de embeddings.

Búsqueda de similitud

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

• En un índice dado 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 entradas múltiples, 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 embedding. Puedes utilizar este conjunto de datos para realizar un filtrado adicional.

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo26n.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())

Representación gráfica de imágenes similares

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

from ultralytics import Explorer

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

plt = exp.plot_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
plt.show()

Pregunta 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 petición en una consulta y devuelve los resultados coincidentes. Por ejemplo, puedes preguntar: "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 podrían ser inexactos.

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo26n.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()

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="yolo26n.pt")
exp.create_embeddings_table()

df = exp.sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%'")
print(df.head())

Representación gráfica de resultados de consultas SQL

También puedes representar gráficamente los resultados de una consulta SQL usando el método plot_sql_query. Este método toma los mismos argumentos que sql_query y muestra los resultados en una cuadrícula.

from ultralytics import Explorer

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

# plot the SQL Query
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

Trabajando con la tabla de embeddings

También puedes trabajar directamente con la tabla de embeddings. Una vez creada 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="yolo26n.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 vectorial

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

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

Aplicaciones de los embeddings

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

Índice de similitud

Explorer viene con una operación similarity_index:

• Intenta estimar qué tan similar es cada punto de datos con el resto del conjunto de datos.
• Lo hace contando cuántos embeddings de imagen se encuentran más cerca que max_dist de la imagen actual en el espacio de embedding 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 que 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 crear 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 embedding

También puedes visualizar el espacio de embedding usando la herramienta de representación gráfica de tu elección. 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 usando la API Explorer. Para inspirarte, consulta el Ejemplo de exploración de VOC.

Apps construidas usando Ultralytics Explorer

Prueba nuestra Demo GUI basada en la API Explorer

Preguntas frecuentes

¿Para qué se utiliza la API Ultralytics Explorer?

La API Ultralytics Explorer está diseñada para la exploración integral de conjuntos de datos. Permite a los usuarios filtrar y buscar conjuntos de datos mediante consultas SQL, búsqueda de similitud vectorial 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 computer vision usando modelos de Ultralytics.

¿Cómo instalo la API Ultralytics Explorer?

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

pip install ultralytics[explorer]

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

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

Puedes usar la API Ultralytics Explorer 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="yolo26n.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 más detalles, por favor 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 asegura 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 pueden reutilizarse, mejorando la eficiencia en el manejo de datos.

¿Cómo funciona la función Pregunta a la IA en la API Ultralytics Explorer?

La función Pregunta 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="yolo26n.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 más ejemplos, consulta la sección Pregunta a la IA.