API do Ultralytics Explorer#

Introdução#

A API do Explorer é uma API Python para explorar os seus conjuntos de dados. Ela permite filtrar e pesquisar o seu conjunto de dados usando consultas SQL, busca por similaridade vetorial e busca semântica.

Instalação#

O Explorer depende de bibliotecas externas para algumas das suas funcionalidades. Elas são instaladas automaticamente quando você usa o Explorer. Para instalar manualmente essas dependências, use o seguinte comando:

pip install "ultralytics[explorer]==8.3.11"

Uso#

from ultralytics import Explorer

# Criar um objeto Explorer
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# Criar embeddings para o seu conjunto de dados
explorer.create_embeddings_table()

# Buscar imagens semelhantes a uma ou mais imagens
df = explorer.get_similar(img="path/to/image.jpg")

# Ou buscar imagens semelhantes a um ou mais índices
df = explorer.get_similar(idx=0)

Se você quiser forçar a atualização da tabela de embeddings, pode passar force=True para o método create_embeddings_table.

Você pode acessar diretamente o objeto da tabela do LanceDB para realizar análises avançadas. Saiba mais na seção Trabalhar com a tabela de embeddings.

1. Busca por similaridade#

A busca por similaridade é uma técnica para encontrar imagens semelhantes a uma determinada imagem. Ela se baseia na ideia de que imagens semelhantes terão embeddings semelhantes. Depois que a tabela de embeddings for criada, você pode executar a busca por similaridade de qualquer uma das seguintes maneiras:

• Em um determinado índice ou lista de índices no 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)

Quando houver várias entradas, será usado o agregado dos embeddings delas.

Você recebe um DataFrame do pandas com os limit pontos de dados mais semelhantes à entrada, junto com a distância deles no espaço de embeddings. Você pode usar esse conjunto de dados para realizar filtragens adicionais.

from ultralytics import Explorer

# criar um 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 usando várias imagens
similar = exp.get_similar(
    img=["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/bus.jpg"],
    limit=10,
)
print(similar.head())

Plotar imagens semelhantes#

Você também pode plotar as imagens semelhantes usando o método plot_similar. Esse método recebe os mesmos argumentos que get_similar e plota as imagens semelhantes em uma grade.

from ultralytics import Explorer

# criar um 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 em linguagem natural)#

Esse recurso permite filtrar o seu conjunto de dados usando linguagem natural, sem escrever SQL. O gerador de consultas com IA converte o seu prompt em uma consulta e retorna os resultados correspondentes. Por exemplo, você pode pedir: "mostre 100 imagens com exatamente uma pessoa e 2 cães. Também pode haver outros objetos" e ele vai gerar a consulta e mostrar esses resultados. Observação: esse recurso usa LLMs, então os resultados são probabilísticos e podem ser imprecisos.

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

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

# plotar os resultados
plt = plot_query_result(df)
plt.show()

3. Consultas SQL#

Você pode executar consultas SQL no seu conjunto de dados usando o método sql_query. Esse método recebe uma consulta SQL como entrada e retorna um DataFrame do pandas com os resultados.

from ultralytics import Explorer

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

Plotar resultados de consultas SQL#

Você também pode plotar os resultados de uma consulta SQL usando o método plot_sql_query. Esse método recebe os mesmos argumentos que sql_query e plota os resultados em uma grade.

from ultralytics import Explorer

# criar um objeto Explorer
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# plotar a consulta SQL
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. Trabalhar com a tabela de embeddings#

Você também pode trabalhar diretamente com a tabela de embeddings. Depois de criar a tabela de embeddings, você pode acessá-la usando Explorer.table.

from ultralytics import Explorer

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

Veja alguns exemplos do que você pode fazer com a tabela:

Obter embeddings brutos#

from ultralytics import Explorer

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

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

Consultas avançadas com filtros antecipados e posteriores#

from ultralytics import Explorer

exp = Explorer(model="yolo11n.pt")
exp.create_embeddings_table()
table = exp.table

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

Criar índice vetorial#

Ao usar conjuntos de dados grandes, você também pode criar um índice vetorial dedicado para acelerar as consultas. Isso é feito usando o método create_index na tabela do LanceDB.

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

5. Aplicações de embeddings#

Você pode usar a tabela de embeddings para realizar vários tipos de análise exploratória. Veja alguns exemplos:

Índice de similaridade#

O Explorer inclui uma operação similarity_index:

• Ela tenta estimar o grau de semelhança de cada ponto de dados em relação ao restante do conjunto de dados.
• Ela faz isso contando quantos embeddings de imagem estão a uma distância menor que max_dist da imagem atual no espaço de embeddings gerado, considerando top_k imagens semelhantes de cada vez.

Ela retorna um DataFrame do pandas com as seguintes colunas:

• idx: Índice da imagem no conjunto de dados
• im_file: Caminho para o arquivo de imagem
• count: Número de imagens no conjunto de dados que estão a uma distância menor 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()

Você pode usar o índice de similaridade para criar condições personalizadas que filtrem o conjunto de dados. Por exemplo, você pode filtrar imagens que não sejam semelhantes a nenhuma outra imagem do conjunto de dados usando 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#

Você também pode visualizar o espaço de embeddings usando a ferramenta de plotagem que preferir. Veja, por exemplo, um exemplo simples usando Matplotlib:

import matplotlib.pyplot as plt
from sklearn.decomposition import PCA

# Reduzir as dimensões usando PCA a 3 componentes para visualização em 3D
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# Criar um gráfico de dispersão 3D usando Axes3D do Matplotlib
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# Gráfico de dispersão
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()

Comece a criar os seus próprios relatórios de exploração de conjuntos de dados de visão computacional usando a API do Explorer. Para se inspirar, confira o Exemplo de exploração do VOC.

Aplicativos criados com o Ultralytics Explorer#

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

Perguntas frequentes#