API do Ultralytics Explorer

Introdução

A API Explorer é uma API Python para explorar seus conjuntos de dados. Ela oferece suporte à filtragem e pesquisa em seu conjunto de dados usando consultas SQL, pesquisa de similaridade vetorial e pesquisa semântica.

Assista: Visão Geral da API do Ultralytics Explorer

Instalação

O Explorer depende de bibliotecas externas para algumas de suas funcionalidades. Estas são instaladas automaticamente durante o uso. Para instalar manualmente estas dependências, use 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
dataframe = explorer.get_similar(img="path/to/image.jpg")

# Or search for similar images to a given index/indices
dataframe = explorer.get_similar(idx=0)

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

Você pode acessar diretamente o objeto da tabela LanceDB para realizar análises avançadas. Saiba mais sobre isso na seção Trabalhando com a Tabela de Incorporações.

1. Busca por Similaridade

A pesquisa de similaridade é uma técnica para encontrar imagens semelhantes a uma determinada imagem. Ela é baseada na ideia de que imagens semelhantes terão embeddings semelhantes. Uma vez que a tabela de embeddings é construída, você pode executar a pesquisa semântica 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 estejam no conjunto de dados: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

No caso de múltiplas entradas, o agregado de seus embeddings é usado.

Você obtém um dataframe pandas com o limit número de pontos de dados mais semelhantes à entrada, juntamente com sua distância no espaço de incorporação. Você pode usar este conjunto de dados para realizar filtragem 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())

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

similar = exp.get_similar(idx=1, limit=10)
print(similar.head())

# Search using multiple indices
similar = exp.get_similar(idx=[1, 10], limit=10)
print(similar.head())

Plotagem de Imagens Semelhantes

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

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

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

plt = exp.plot_similar(idx=1, limit=10)
plt.show()

2. Pergunte à IA (Consulta em Linguagem Natural)

Isso permite que você escreva como deseja filtrar seu conjunto de dados usando linguagem natural. Você não precisa ser proficiente em escrever consultas SQL. Nosso gerador de consultas com tecnologia de IA fará isso automaticamente nos bastidores. Por exemplo, você pode dizer - "mostre-me 100 imagens com exatamente uma pessoa e 2 cães. Pode haver outros objetos também" e ele gerará internamente a consulta e mostrará esses resultados. Observação: isso funciona usando LLMs nos bastidores, então os resultados são probabilísticos e podem errar às vezes

from ultralytics import Explorer
from ultralytics.data.explorer import plot_query_result

# 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. Consulta SQL

Pode executar consultas SQL no seu conjunto de dados usando o sql_query método. Este método recebe uma consulta SQL como entrada e retorna um dataframe 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())

Plotagem de Resultados de Consultas SQL

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

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. Trabalhando com a Tabela de Embeddings

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

from ultralytics import Explorer

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

Aqui estão 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)

Consulta Avançada com pré 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 usar grandes conjuntos de dados, você também pode criar um índice vetorial dedicado para consultas mais rápidas. Isso é feito usando o create_index método na tabela LanceDB.

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

Encontre mais detalhes sobre os tipos de índice de vetor disponíveis e parâmetros de configuração na documentação de indexação do LanceDB. No futuro, planejamos oferecer suporte à criação de índices de vetor diretamente através da API Explorer.

5. Aplicações de Embeddings

Você pode usar a tabela de embeddings para realizar uma variedade de análises exploratórias. Aqui estão alguns exemplos:

Índice de Similaridade

O Explorer vem com um similarity_index operação:

• Ele tenta estimar o quão similar cada ponto de dados é com o resto do conjunto de dados.
• Ele faz isso contando quantos embeddings de imagem estão mais próximos do que max_dist para a imagem atual no espaço de embedding gerado, considerando top_k imagens semelhantes por vez.

Retorna um dataframe 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 mais próximas do que max_dist para a imagem atual
• sim_im_files: Lista de caminhos para os 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 construir condições personalizadas para filtrar o conjunto de dados. Por exemplo, você pode filtrar imagens que não são semelhantes a nenhuma outra imagem no 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 Embedding

Você também pode visualizar o espaço de embedding usando a ferramenta de plotagem de sua escolha. Por exemplo, aqui está um exemplo simples 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()

Comece a criar seus próprios relatórios de exploração de conjuntos de dados de CV usando a API Explorer. Para se inspirar, consulte o Exemplo de Exploração VOC.

Aplicativos Criados Usando o Ultralytics Explorer

Experimente nossa GUI Demo baseada na API Explorer

Em breve

• [ ] Mesclar rótulos específicos de conjuntos de dados. Exemplo - Importar todos person etiquetas do COCO e car etiquetas do Cityscapes
• [ ] Remover imagens que tenham um índice de similaridade maior que o limite fornecido
• [ ] Persistir automaticamente novos conjuntos de dados após mesclar/remover entradas
• [ ] Visualizações avançadas de conjuntos de dados

FAQ

Para que serve a API Ultralytics Explorer?

A Ultralytics Explorer API foi projetada para uma exploração abrangente de conjuntos de dados. Ela permite que os usuários filtrem e pesquisem conjuntos de dados usando consultas SQL, pesquisa de similaridade vetorial e pesquisa semântica. Esta poderosa API python pode lidar com grandes conjuntos de dados, tornando-a ideal para várias tarefas de visão computacional usando modelos Ultralytics.

Como instalar a API Ultralytics Explorer?

Para instalar a API Ultralytics Explorer juntamente com as suas dependências, use o seguinte comando:

pip install ultralytics[explorer]

Isto instalará automaticamente todas as bibliotecas externas necessárias para a funcionalidade da API Explorer. Para detalhes de configuração adicionais, consulte a seção de instalação da nossa documentação.

Como posso usar a API do Ultralytics Explorer para pesquisa de similaridade?

Você pode usar a API Ultralytics Explorer para realizar buscas de similaridade criando uma tabela de embeddings e consultando-a para imagens semelhantes. Aqui está um exemplo básico:

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
explorer.create_embeddings_table()

# Search for similar images to a given image
similar_images_df = explorer.get_similar(img="path/to/image.jpg")
print(similar_images_df.head())

Para mais detalhes, visite a seção Pesquisa de Similaridade.

Quais são os benefícios de usar o LanceDB com o Ultralytics Explorer?

LanceDB, usado internamente pelo Ultralytics Explorer, fornece tabelas de embeddings escaláveis em disco. Isso garante que você possa criar e reutilizar embeddings para grandes conjuntos de dados como o COCO sem ficar sem memória. Essas tabelas são criadas apenas uma vez e podem ser reutilizadas, aumentando a eficiência no manuseio de dados.

Como funciona o recurso Ask AI na API Ultralytics Explorer?

O recurso Ask AI permite que os usuários filtrem conjuntos de dados usando consultas em linguagem natural. Este recurso aproveita LLMs para converter essas consultas em consultas SQL nos bastidores. Aqui está um exemplo:

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")
explorer.create_embeddings_table()

# Query with natural language
query_result = explorer.ask_ai("show me 100 images with exactly one person and 2 dogs. There can be other objects too")
print(query_result.head())

Para mais exemplos, consulte a seção Pergunte à IA.

📅 Criado há 1 ano ✏️ Atualizado há 3 meses

Comentários