API de Ultralytics Explorer#

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.

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)

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 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 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 por similitud de cualquiera de estas 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 en lenguaje natural, sin escribir SQL. El generador de consultas basado en IA convierte tu prompt 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»; la función generará la consulta y te mostrará esos resultados. Nota: esta función usa modelos de lenguaje grandes, 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.

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

# 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_dist en el espacio de embeddings generado, teniendo en cuenta 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 más cerca de la imagen actual que max_dist
• 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 que permitan filtrar el conjunto de datos. Por ejemplo, puedes excluir las imágenes que no sean similares a ninguna otra imagen del conjunto de datos con 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 con la herramienta de representación que prefieras. Aquí tienes un ejemplo sencillo 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#

Prueba nuestra demo de la interfaz gráfica basada en la API de Explorer

Preguntas frecuentes#