API do Ultralytics Explorer#

Introdução#

A Explorer API é uma API Python para explorar os teus conjuntos de dados. Ela suporta a filtragem e a pesquisa no teu conjunto de dados utilizando consultas SQL, pesquisa por similaridade de vetores e pesquisa semântica.

Instalação#

O Explorer depende de bibliotecas externas para algumas das suas funcionalidades. Estas são instaladas automaticamente quando utilizas o Explorer. Para instalar manualmente estas dependências, utiliza o seguinte comando:

pip install ultralytics[explorer]

Utilização#

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)

Se quiseres forçar a atualização da tabela de embeddings, podes passar force=True ao método create_embeddings_table.

Podes aceder diretamente ao objeto da tabela LanceDB para realizar análises avançadas. Obtém mais informações na secção Trabalhar com a tabela de embeddings

1. Pesquisa por similaridade#

A pesquisa por similaridade é uma técnica para encontrar imagens semelhantes a uma determinada imagem. Baseia-se na ideia de que imagens semelhantes terão embeddings semelhantes. Depois de criar a tabela de embeddings, podes executar uma pesquisa semântica das seguintes formas:

• Num índice ou numa lista de índices específicos do conjunto de dados: exp.get_similar(idx=[1,10], limit=10)
• Em qualquer imagem ou lista de imagens que não esteja no conjunto de dados: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

No caso de várias entradas, é utilizado o agregado dos respetivos embeddings.

Obténs um DataFrame do pandas com os limit pontos de dados mais semelhantes à entrada, juntamente com a respetiva distância no espaço de embeddings. Podes utilizar este conjunto de dados para realizar filtragens adicionais.

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

Representar imagens semelhantes#

Também podes representar as imagens semelhantes utilizando o método plot_similar. Este método aceita os mesmos argumentos que get_similar e representa as imagens semelhantes numa grelha.

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. Perguntar à IA (consultas em linguagem natural)#

Esta funcionalidade permite filtrar o teu conjunto de dados utilizando linguagem natural, sem escrever SQL. O gerador de consultas baseado em IA converte o teu prompt numa consulta e devolve os resultados correspondentes. Por exemplo, podes perguntar: "mostra-me 100 imagens com exatamente uma pessoa e 2 cães. Também podem existir outros objetos" e a consulta será gerada, mostrando-te esses resultados. Nota: esta funcionalidade utiliza LLMs, pelo que os resultados são probabilísticos e podem 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#

Podes executar consultas SQL no teu conjunto de dados utilizando o método sql_query. Este método aceita uma consulta SQL como entrada e devolve um DataFrame do pandas com os 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())

Representar resultados de consultas SQL#

Também podes representar os resultados de uma consulta SQL utilizando o método plot_sql_query. Este método aceita os mesmos argumentos que sql_query e representa os resultados numa grelha.

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. Trabalhar com a tabela de embeddings#

Também podes trabalhar diretamente com a tabela de embeddings. Depois de criares a tabela de embeddings, podes aceder-lhe utilizando Explorer.table

from ultralytics import Explorer

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

Eis alguns exemplos do que podes fazer com a tabela:

Obter embeddings não processados#

from ultralytics import Explorer

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

embeddings = table.to_pandas()["vector"]
print(embeddings)

Consultas avançadas com pré-filtros e pós-filtros#

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)

Criar índice vetorial#

Ao utilizar grandes conjuntos de dados, também podes criar um índice vetorial dedicado para realizar consultas mais rapidamente. Isto é feito utilizando o método create_index na tabela LanceDB.

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

5. Aplicações de embeddings#

Podes utilizar a tabela de embeddings para realizar vários tipos de análise exploratória. Eis alguns exemplos:

Índice de similaridade#

O Explorer inclui uma operação similarity_index:

• Esta operação tenta estimar o grau de semelhança de cada ponto de dados com o restante conjunto de dados.
• Fá-lo contando quantos embeddings de imagens estão mais próximos do que max_dist da imagem atual no espaço de embeddings gerado, considerando top_k imagens semelhantes de cada vez.

Devolve um DataFrame do pandas com as seguintes colunas:

• idx: índice da imagem no conjunto de dados
• im_file: caminho para o ficheiro de imagem
• count: número de imagens no conjunto de dados que estão mais próximas do que max_dist da imagem atual
• sim_im_files: lista de caminhos para as count imagens semelhantes

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

Podes utilizar o índice de similaridade para criar condições personalizadas que filtrem o conjunto de dados. Por exemplo, podes excluir imagens que não sejam semelhantes a nenhuma outra imagem do conjunto de dados utilizando o seguinte código:

import numpy as np

sim_count = np.array(sim_idx["count"])
sim_idx["im_file"][sim_count > 30]

Visualizar o espaço de embeddings#

Também podes visualizar o espaço de embeddings utilizando a ferramenta de representação da tua preferência. Por exemplo, eis um exemplo simples que utiliza 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()

Começa a criar os teus próprios relatórios de exploração de conjuntos de dados de CV utilizando a API do Explorer. Para obteres inspiração, consulta o exemplo de exploração de VOC.

Aplicações criadas com o Ultralytics Explorer#

Experimenta a nossa demonstração da GUI baseada na API do Explorer

Perguntas frequentes#