Link to this sectionAPI do Ultralytics Explorer#

Link to this sectionIntrodução#

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

Link to this sectionInstalação#

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

pip install ultralytics[explorer]

Link to this sectionUso#

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)

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

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

Link to this sectionPesquisa de Similaridade#

A pesquisa de 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 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 esteja 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 do pandas com o número limit de pontos de dados mais semelhantes à entrada, juntamente com sua distância no espaço de embedding. Você pode usar esse 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())

Link to this sectionPlotando Imagens Semelhantes#

Você também pode plotar as imagens semelhantes usando o método plot_similar. Este método aceita 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()

Link to this sectionAsk AI (Consulta em Linguagem Natural)#

Este recurso permite que você filtre seu conjunto de dados usando linguagem natural, sem escrever SQL. O gerador de consultas com IA converte seu prompt em uma consulta e retorna resultados correspondentes. Por exemplo, você pode perguntar: "mostre-me 100 imagens com exatamente uma pessoa e 2 cães. Também pode haver outros objetos" e ele gerará a consulta e mostrará esses resultados. Nota: Este recurso usa LLMs, portanto 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()

Link to this sectionConsulta SQL#

Você pode executar consultas SQL em seu conjunto de dados usando o método sql_query. Este método aceita uma consulta SQL como entrada e retorna 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())

Link to this sectionPlotando Resultados de Consulta SQL#

Você também pode plotar os resultados de uma consulta SQL usando o método plot_sql_query. Este método aceita 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")

Link to this sectionTrabalhando com a Tabela de Embeddings#

Você também pode trabalhar diretamente com a tabela de embeddings. Depois que a tabela de embeddings for criada, você pode acessá-la usando 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:

Link to this sectionObter Embeddings brutos#

from ultralytics import Explorer

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

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

Link to this sectionConsulta 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)

Link to this sectionCriar Í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 método create_index na tabela LanceDB.

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

Link to this sectionAplicações de Embeddings#

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

Link to this sectionÍndice de Similaridade#

O Explorer vem com uma operação similarity_index:

• Ele tenta estimar quão semelhante cada ponto de dados é com o restante do conjunto de dados.
• 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 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 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()

Você pode usar o índice de similaridade para criar 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]

Link to this sectionVisualizar 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 Explorer API. Para inspiração, confira o Exemplo de Exploração VOC.

Link to this sectionAplicativos Criados Usando o Ultralytics Explorer#

Experimente nossa Demonstração da GUI baseada na Explorer API

Link to this sectionFAQ#

Link to this sectionPara que serve a API do Ultralytics Explorer?#

A API do Ultralytics Explorer 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.

Link to this sectionComo instalo a API do Ultralytics Explorer?#

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

pip install ultralytics[explorer]

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

Link to this sectionComo posso usar a API do Ultralytics Explorer para pesquisa de similaridade?#

Você pode usar a API do Ultralytics Explorer para realizar pesquisas 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 de Pesquisa de Similaridade.

Link to this sectionQuais são os benefícios de usar LanceDB com o Ultralytics Explorer?#

O 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 tratamento de dados.

Link to this sectionComo o recurso Ask AI funciona na API do 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, confira a seção Ask AI.