API do Ultralytics Explorer
A partir de ultralytics>=8.3.12, o Ultralytics Explorer foi removido. Para usar o Explorer, instala pip install ultralytics==8.3.11. Recursos semelhantes (e ampliados) para explorar conjuntos de dados estão disponíveis na Ultralytics Platform.
Introdução#
A API do Explorer é uma API de Python para explorar seus conjuntos de dados. Ela permite filtrar e pesquisar seu conjunto de dados usando consultas SQL, busca por similaridade vetorial e busca semântica.
Assista: Visão geral da Explorer API do Ultralytics
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)A tabela de embeddings para um determinado par de conjunto de dados e modelo é criada apenas uma vez e reutilizada. Ela usa o LanceDB internamente, que escala com armazenamento em disco; assim, você pode criar e reutilizar embeddings para grandes conjuntos de dados, como COCO, sem ficar sem memória.
Para forçar a atualização da tabela de incorporações, passe 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, também conhecida como busca vetorial, é uma técnica para encontrar imagens semelhantes a uma imagem fornecida. Ela se baseia na ideia de que imagens semelhantes terão incorporações semelhantes. Depois que a tabela de incorporações for criada, você poderá 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 seu conjunto de dados usando linguagem natural, sem escrever SQL. O gerador de consultas com IA converte seu comando em uma consulta e retorna resultados correspondentes. Por exemplo, você pode pedir: "mostre 100 imagens com exatamente uma pessoa e 2 cães. Também pode haver outros objetos"; o recurso gerará a consulta e mostrará os 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.
Internamente, o Explorer trabalha com tabelas do LanceDB. Você pode acessar essa tabela diretamente usando o objeto Explorer.table e executar consultas brutas, aplicar filtros antecipados e posteriores, etc.
from ultralytics import Explorer
exp = Explorer()
exp.create_embeddings_table()
table = exp.tableVeja 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_distda imagem atual no espaço de embeddings gerado, considerandotop_kimagens semelhantes de cada vez.
Ela retorna um DataFrame do pandas com as seguintes colunas:
idx: Índice da imagem no conjunto de dadosim_file: Caminho para o arquivo de imagemcount: Número de imagens no conjunto de dados que estão a uma distância menor quemax_distda imagem atualsim_im_files: Lista de caminhos para ascountimagens semelhantes
Para um determinado conjunto de dados, modelo, max_dist e top_k, o índice de similaridade será reutilizado depois de gerado. Se o conjunto de dados tiver mudado ou você precisar gerar novamente o índice de similaridade, passe force=True.
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 de filtragem do conjunto de dados. Por exemplo, o código a seguir lista imagens que têm mais de 30 imagens semelhantes no conjunto de dados, boas candidatas à remoção de quase duplicatas:
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 incorporações usando a ferramenta de plotagem que preferir. Veja um exemplo simples que reduz as incorporações com PCA e as plota com 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#
A GUI do Explorer é criada sobre a API do Explorer.
Perguntas frequentes#
A API do Ultralytics Explorer foi desenvolvida para explorar conjuntos de dados. Ela permite filtrar e pesquisar conjuntos de dados usando consultas SQL, busca por similaridade vetorial e busca semântica, além de escalar para conjuntos de dados grandes em tarefas de visão computacional com modelos Ultralytics.
Para instalar a API Ultralytics Explorer juntamente com as respetivas dependências, usa o seguinte comando:
pip install "ultralytics[explorer]==8.3.11"Isto instalará automaticamente todas as bibliotecas externas necessárias para o funcionamento da API Explorer. Para veres mais detalhes de configuração, consulta a secção de instalação da nossa documentação.
Podes usar a API Ultralytics Explorer para fazer pesquisas por similaridade criando uma tabela de embeddings e consultando-a para encontrar imagens semelhantes. Aqui está um exemplo básico:
from ultralytics import Explorer # Criar um objeto Explorer explorer = Explorer(data="coco128.yaml", model="yolo11n.pt") explorer.create_embeddings_table() # Pesquisar imagens semelhantes a uma imagem específica similar_images_df = explorer.get_similar(img="path/to/image.jpg") print(similar_images_df.head())Para veres mais detalhes, visita a secção Pesquisa por similaridade.
O LanceDB, usado nos bastidores pelo Ultralytics Explorer, disponibiliza tabelas de embeddings escaláveis armazenadas em disco. Assim, podes criar e reutilizar embeddings para grandes conjuntos de dados, como o COCO, sem ficares sem memória. Estas tabelas são criadas apenas uma vez e podem ser reutilizadas, aumentando a eficiência na gestão dos dados.
A funcionalidade Ask AI permite filtrar conjuntos de dados usando consultas em linguagem natural. Esta funcionalidade utiliza LLMs para converter essas consultas em consultas SQL nos bastidores. Aqui está um exemplo:
from ultralytics import Explorer # Criar um objeto Explorer explorer = Explorer(data="coco128.yaml", model="yolo11n.pt") explorer.create_embeddings_table() # Consultar com linguagem natural 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 veres mais exemplos, consulta a secção Ask AI.
Comentários2
Faz uma pergunta, partilha os teus resultados ou ajuda alguém.
Jie LiuI have downloaded
ultralytics-8.3.118 github zip packageand install it withpip install -e .. Then I usepip install ultralytics[explorer]to install explorer, but I got a error as followedRequirement already satisfied: ultralytics[explorer] in /data/miniconda3/envs/app/lib/python3.10/site-packages (8.3.118) WARNING: ultralytics 8.3.118 does not provide the extra 'explorer' Requirement already satisfied: numpy<=2.1.1,>=1.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.26.4) Requirement already satisfied: matplotlib>=3.3.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (3.10.1) Requirement already satisfied: opencv-python>=4.6.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.11.0.86) Requirement already satisfied: pillow>=7.1.2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (11.2.1) Requirement already satisfied: pyyaml>=5.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (6.0.2) Requirement already satisfied: requests>=2.23.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.32.3) Requirement already satisfied: scipy>=1.4.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (1.15.2) Requirement already satisfied: torch>=1.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.3.1) Requirement already satisfied: torchvision>=0.9.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.18.1) Requirement already satisfied: tqdm>=4.64.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (4.67.1) Requirement already satisfied: psutil in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (7.0.0) Requirement already satisfied: py-cpuinfo in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (9.0.0) Requirement already satisfied: pandas>=1.1.4 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.2.3) Requirement already satisfied: seaborn>=0.11.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (0.13.2) Requirement already satisfied: ultralytics-thop>=2.0.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from ultralytics[explorer]) (2.0.14) Requirement already satisfied: contourpy>=1.0.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.3.2) Requirement already satisfied: cycler>=0.10 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (0.12.1) Requirement already satisfied: fonttools>=4.22.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (4.57.0) Requirement already satisfied: kiwisolver>=1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (1.4.8) Requirement already satisfied: packaging>=20.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (24.2) Requirement already satisfied: pyparsing>=2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (3.2.3) Requirement already satisfied: python-dateutil>=2.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from matplotlib>=3.3.0->ultralytics[explorer]) (2.9.0.post0) Requirement already satisfied: pytz>=2020.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2022.7.1) Requirement already satisfied: tzdata>=2022.7 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from pandas>=1.1.4->ultralytics[explorer]) (2025.2) Requirement already satisfied: charset-normalizer<4,>=2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.4.1) Requirement already satisfied: idna<4,>=2.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (3.10) Requirement already satisfied: urllib3<3,>=1.21.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (1.26.20) Requirement already satisfied: certifi>=2017.4.17 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from requests>=2.23.0->ultralytics[explorer]) (2025.4.26) Requirement already satisfied: filelock in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.18.0) Requirement already satisfied: typing-extensions>=4.8.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (4.13.2) Requirement already satisfied: sympy in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (1.13.3) Requirement already satisfied: networkx in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.4.2) Requirement already satisfied: jinja2 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (3.1.6) Requirement already satisfied: fsspec in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2025.3.2) Requirement already satisfied: nvidia-cuda-nvrtc-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cuda-runtime-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cuda-cupti-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: nvidia-cudnn-cu12==8.9.2.26 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (8.9.2.26) Requirement already satisfied: nvidia-cublas-cu12==12.1.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.3.1) Requirement already satisfied: nvidia-cufft-cu12==11.0.2.54 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.0.2.54) Requirement already satisfied: nvidia-curand-cu12==10.3.2.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (10.3.2.106) Requirement already satisfied: nvidia-cusolver-cu12==11.4.5.107 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (11.4.5.107) Requirement already satisfied: nvidia-cusparse-cu12==12.1.0.106 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.0.106) Requirement already satisfied: nvidia-nccl-cu12==2.20.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.20.5) Requirement already satisfied: nvidia-nvtx-cu12==12.1.105 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (12.1.105) Requirement already satisfied: triton==2.3.1 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from torch>=1.8.0->ultralytics[explorer]) (2.3.1) Requirement already satisfied: nvidia-nvjitlink-cu12 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from nvidia-cusolver-cu12==11.4.5.107->torch>=1.8.0->ultralytics[explorer]) (12.8.93) Requirement already satisfied: six>=1.5 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from python-dateutil>=2.7->matplotlib>=3.3.0->ultralytics[explorer]) (1.17.0) Requirement already satisfied: MarkupSafe>=2.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from jinja2->torch>=1.8.0->ultralytics[explorer]) (3.0.2) Requirement already satisfied: mpmath<1.4,>=1.1.0 in /data/miniconda3/envs/app/lib/python3.10/site-packages (from sympy->torch>=1.8.0->ultralytics[explorer]) (1.3.0)when run code
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)The error has arisen
Traceback (most recent call last): File "/data/liujie/data/ultralytics-8.3.13/tutorial/debug/explorer.py", line 1, in <module> from ultralytics import Explorer ImportError: cannot import name 'Explorer' from 'ultralytics' (/data/liujie/data/ultralytics-8.3.118/ultralytics/__init__.py)please help me to install and use explorer
Glenn JocherUltralytics(editado)Hi @keeper-jie,
The issue you're experiencing is because Ultralytics Explorer has been removed since version 8.3.12, and you're using version 8.3.118. That's why you're seeing the warning that the 'explorer' extra is not provided and why you can't import the Explorer class.
As noted in our documentation, we've moved this functionality to Ultralytics Platform, our platform that offers similar and enhanced capabilities for exploring, visualizing, and managing your datasets without writing code.
If you specifically need the Explorer API functionality in your code, you would need to downgrade to a version prior to 8.3.12. However, we recommend trying Ultralytics Platform instead, as it provides an improved experience with all the dataset exploration features you're looking for.
Let me know if you need any further assistance with Ultralytics Platform or if you have any other questions.