Ultralytics Explorer API

Introdução

A Explorer API é uma API Python para explorar os teus datasets. Ela permite filtrar e pesquisar o teu dataset usando consultas SQL, pesquisa de similaridade vetorial e pesquisa semântica.

Instalação

O Explorer depende de bibliotecas externas para algumas de 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]

Utilização

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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)

Caso precises de 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. Sabe mais sobre isso na secção Trabalhar com a Tabela de Embeddings

1. Pesquisa de Similaridade

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

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

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

Obténs um pandas DataFrame com o número limit dos pontos de dados mais semelhantes à entrada, juntamente com a sua distância no espaço de embedding. Podes usar este dataset para realizar filtragens adicionais.

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo26n.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())

Plotar Imagens Semelhantes

Também podes plotar as imagens semelhantes usando o método plot_similar. Este método aceita os mesmos argumentos que o get_similar e plota as imagens semelhantes numa grelha.

from ultralytics import Explorer

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

plt = exp.plot_similar(img="https://ultralytics.com/images/bus.jpg", limit=10)
plt.show()

2. Ask AI (Consulta em Linguagem Natural)

Esta funcionalidade permite-te filtrar o teu dataset usando linguagem natural, sem escrever SQL. O gerador de consultas alimentado por IA converte o teu prompt numa consulta e devolve os resultados correspondentes. Por exemplo, podes pedir: "mostra-me 100 imagens com exatamente uma pessoa e 2 cães. Também pode haver outros objetos" e ele gerará a consulta e mostrar-te-á esses resultados. Nota: Esta funcionalidade usa 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="yolo26n.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

Podes executar consultas SQL no teu dataset usando o método sql_query. Este método aceita uma consulta SQL como entrada e devolve um pandas DataFrame com os resultados.

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo26n.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

Também podes plotar os resultados de uma consulta SQL usando o método plot_sql_query. Este método aceita os mesmos argumentos que o sql_query e plota os resultados numa grelha.

from ultralytics import Explorer

# create an Explorer object
exp = Explorer(data="coco128.yaml", model="yolo26n.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. Assim que a tabela de embeddings estiver criada, podes aceder a ela usando Explorer.table

from ultralytics import Explorer

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

Aqui tens alguns exemplos do que podes fazer com a tabela:

Obter Embeddings em bruto

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="yolo26n.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 datasets grandes, também podes criar um índice vetorial dedicado para consultas mais rápidas. Isto é feito usando o método create_index na tabela LanceDB.

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

5. Aplicações de Embeddings

Podes usar a tabela de embeddings para realizar uma variedade de análises exploratórias. Aqui tens alguns exemplos:

Índice de Similaridade

O Explorer vem com uma operação similarity_index:

• Ele tenta estimar quão semelhante cada ponto de dados é em relação ao resto do dataset.
• Ele faz isso contando quantos embeddings de imagem estão mais próximos do que max_dist da imagem atual no espaço de embedding gerado, considerando top_k imagens semelhantes de cada vez.

Ele devolve um pandas DataFrame com as seguintes colunas:

• idx: Índice da imagem no dataset
• im_file: Caminho para o ficheiro de imagem
• count: Número de imagens no dataset 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 usar o índice de similaridade para construir condições personalizadas para filtrar o dataset. Por exemplo, podes filtrar imagens que não são semelhantes a nenhuma outra imagem no dataset 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

Também podes visualizar o espaço de embedding usando a ferramenta de plotagem da tua preferência. 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()

Começa a criar os teus próprios relatórios de exploração de datasets de CV usando a Explorer API. Para inspiração, consulta o Exemplo de Exploração VOC.

Apps Construídas Usando o Ultralytics Explorer

Experimenta a nossa Demonstração GUI baseada na Explorer API

FAQ

Para que é usada a Ultralytics Explorer API?

A Ultralytics Explorer API foi concebida para uma exploração abrangente de datasets. Permite aos utilizadores filtrar e pesquisar datasets usando consultas SQL, pesquisa de similaridade vetorial e pesquisa semântica. Esta poderosa API Python pode lidar com grandes datasets, tornando-a ideal para várias tarefas de computer vision usando modelos Ultralytics.

Como instalo a Ultralytics Explorer API?

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

pip install ultralytics[explorer]

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

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

Podes usar a Ultralytics Explorer API para realizar pesquisas de similaridade criando uma tabela de embeddings e consultando-a por imagens semelhantes. Aqui tens um exemplo básico:

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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, visita a secção de Pesquisa de Similaridade.

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

O LanceDB, usado internamente pelo Ultralytics Explorer, fornece tabelas de embeddings escaláveis em disco. Isto garante que podes criar e reutilizar embeddings para datasets grandes, como o COCO, sem esgotar a memória. Estas tabelas são criadas apenas uma vez e podem ser reutilizadas, melhorando a eficiência no manuseamento de dados.

Como funciona a funcionalidade Ask AI na Ultralytics Explorer API?

A funcionalidade Ask AI permite aos utilizadores filtrar datasets usando consultas em linguagem natural. Esta funcionalidade aproveita LLMs para converter estas consultas em consultas SQL nos bastidores. Aqui tens um exemplo:

from ultralytics import Explorer

# Create an Explorer object
explorer = Explorer(data="coco128.yaml", model="yolo26n.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, consulta a secção Ask AI.