Ultralytics Explorer API#

Introducción#

The Explorer API is a Python API for exploring your datasets. It supports filtering and searching your dataset using SQL queries, vector similarity search, and semantic search.

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)

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 tabla de LanceDB para realizar análisis avanzados. Obtén más información en la sección Working with Embeddings Table section

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 dado o 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 embedding. 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 trazar las imágenes similares usando el método plot_similar. Este método acepta los mismos argumentos que get_similar y traza 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 trazar los resultados de una consulta SQL usando el método plot_sql_query. Este método acepta los mismos argumentos que sql_query y traza 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 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="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#

Cuando utilices conjuntos de datos grandes, también puedes crear un índice vectorial 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 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 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 de max_dist que 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()

Comienza a crear tus propios informes de exploración de conjuntos de datos de visión por computador utilizando la Explorer API. Para inspirarte, consulta el VOC Exploration Example.

Aplicaciones creadas con Ultralytics Explorer#

Prueba nuestra GUI Demo basada en la Explorer API

FAQ#