API de Ultralytics Explorer#

Introducción#

La API de Explorer es una API de Python para explorar tus conjuntos de datos. Es compatible con el filtrado y la búsqueda 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 algunas de sus funciones. Estas se instalan automáticamente cuando usas Explorer. Para instalar manualmente estas dependencias, 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 en la sección Trabajar con la tabla de embeddings.

1. Búsqueda por similitud#

La búsqueda por similitud 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 realizar búsquedas semánticas de cualquiera de las siguientes formas:

• En un índice o una lista de índices determinados del 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 tener varias entradas, se utiliza el agregado de sus embeddings.

Obtendrás un DataFrame de pandas con los limit puntos de datos más similares a la entrada, junto con su distancia en el espacio de embeddings. Puedes utilizar este conjunto de datos para realizar más filtros.

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

Representación de imágenes similares#

También puedes representar las imágenes similares mediante 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

# 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. Pregunta a la IA (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 indicació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 LLM, por lo que los resultados son probabilísticos y pueden ser imprecisos.

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 mediante 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

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

Representación de los resultados de la consulta SQL#

También puedes representar los resultados de una consulta SQL mediante 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

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

También puedes trabajar directamente con la tabla de embeddings. Una vez creada, puedes acceder a ella mediante Explorer.table.

from ultralytics import Explorer

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

Estos 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

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

Crear un índice vectorial#

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

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

5. Aplicaciones de los embeddings#

Puedes utilizar la tabla de embeddings para realizar diversos análisis exploratorios. Estos son algunos ejemplos:

Índice de similitud#

Explorer incluye una operación similarity_index:

• Intenta estimar 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 a una distancia inferior a max_dist de la imagen actual en el espacio de embeddings generado, considerando top_k imágenes similares cada 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 del conjunto de datos que están a una distancia inferior a 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 utilizar el índice de similitud para crear condiciones personalizadas que filtren el conjunto de datos. Por ejemplo, puedes filtrar las imágenes que no sean similares a ninguna otra imagen del conjunto de datos mediante 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 mediante la herramienta de representación que prefieras. Por ejemplo, aquí tienes un ejemplo sencillo con 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 mediante la API de Explorer. Para inspirarte, consulta el ejemplo de exploración de VOC.

Aplicaciones creadas con Ultralytics Explorer#

Prueba nuestra demo de GUI basada en la API de Explorer

Preguntas frecuentes#