跳转至内容

Ultralytics Explorer API

社区提示 ⚠️

截至 ultralytics>=8.3.10,Ultralytics explorer 支持已弃用。但是不用担心!您现在可以通过以下方式访问类似甚至增强的功能 Ultralytics HUB,我们直观的无代码平台旨在简化您的工作流程。借助 Ultralytics HUB,您可以继续轻松地探索、可视化和管理您的数据,而无需编写任何代码。请务必查看并利用其强大的功能!🚀

简介

在 Colab 中打开 Explorer API 是一个 python API,用于浏览您的数据集。它支持使用 SQL 查询、向量相似性搜索和语义搜索来过滤和搜索您的数据集。



观看: Ultralytics Explorer API 概述

安装

Explorer 的某些功能依赖于外部库。这些库会在使用时自动安装。要手动安装这些依赖项,请使用以下命令:

pip install ultralytics[explorer]

用法

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)

注意

给定数据集和模型对的 嵌入 表仅创建一次并重复使用。这些在底层使用 LanceDB,它可以在磁盘上扩展,因此您可以为像 COCO 这样的大型数据集创建和重用嵌入,而不会耗尽内存。

如果您想强制更新嵌入表,您可以传递 force=Truecreate_embeddings_table 方法。

您可以直接访问 LanceDB 表对象以执行高级分析。有关更多信息,请参阅使用嵌入表部分

相似性搜索是一种查找与给定图像相似的图像的技术。它基于相似的图像将具有相似嵌入的理念。一旦构建了嵌入表,您可以通过以下任何方式运行语义搜索:

  • 在数据集中的给定索引或索引列表上: exp.get_similar(idx=[1,10], limit=10)
  • 对于不在数据集中的任何图像或图像列表: exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

如果有多个输入,则使用它们的嵌入的聚合。

您将获得一个带有 limit 与输入最相似的若干数据点,以及它们在嵌入空间中的距离。您可以使用此数据集执行进一步的筛选。

语义搜索

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

绘制相似图像

您还可以使用以下工具绘制相似的图像 plot_similar method。此方法采用与以下方法相同的参数 get_similar 并在网格中绘制相似的图像。

绘制相似图像

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. 询问 AI(自然语言查询)

这允许您使用自然语言编写如何过滤数据集。您无需精通编写SQL查询。我们的AI驱动的查询生成器将在后台自动执行此操作。例如,您可以说-“向我展示100张只有一个人和2条狗的图像。也可以有其他物体”,它将在内部生成查询并向您显示这些结果。 注意:这在后台使用LLM,因此结果是概率性的,有时可能会出错

询问 AI

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. SQL 查询

您可以使用以下工具在数据集上运行 SQL 查询 sql_query method。此方法将 SQL 查询作为输入,并返回带有结果的 pandas dataframe。

SQL 查询

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

绘制 SQL 查询结果

您还可以使用以下工具绘制SQL查询的结果 plot_sql_query method。此方法采用与以下方法相同的参数 sql_query 并在网格中绘制结果。

绘制 SQL 查询结果

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. 使用嵌入表

您还可以直接使用嵌入表。创建嵌入表后,您可以使用 Explorer.table

提示

Explorer 适用于 LanceDB 在内部建立表格。您可以使用以下方式直接访问此表: Explorer.table 对象并运行原始查询,下推预过滤器和后过滤器等。

from ultralytics import Explorer

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

以下是您可以使用该表执行的一些操作示例:

获取原始嵌入

示例

from ultralytics import Explorer

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

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

使用预过滤器和后过滤器进行高级查询

示例

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)

创建向量索引

当使用大型数据集时,您还可以创建一个专用的向量索引,以便更快地查询。这可以通过以下方式完成 create_index LanceDB 表上的 method。

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

LanceDB 索引文档 中查找有关可用向量索引类型和配置参数的更多详细信息。将来,我们计划支持直接通过 Explorer API 创建向量索引。

5. 嵌入应用

您可以使用嵌入表来执行各种探索性分析。 以下是一些示例:

相似度指数

Explorer 自带 similarity_index 操作:

  • 它尝试评估每个数据点与数据集中其余数据点的相似程度。
  • 它通过计算有多少图像嵌入比以下值更接近来实现这一点 max_dist 到生成的嵌入空间中的当前图像,考虑到 top_k 一次显示多张相似图像。

它返回一个包含以下列的pandas dataframe:

  • idx:数据集中图像的索引
  • im_file:图像文件的路径
  • count:数据集中距离小于的图像数量 max_dist 到当前图像
  • sim_im_files:路径列表 count 相似图像

提示

对于给定的数据集、模型, max_dist & top_k 一旦生成相似度索引,它将被重复使用。如果您的数据集已更改,或者您只需要重新生成相似度索引,您可以传递 force=True.

相似度指数

from ultralytics import Explorer

exp = Explorer()
exp.create_embeddings_table()

sim_idx = exp.similarity_index()

您可以使用相似度索引来构建自定义条件以过滤数据集。 例如,您可以使用以下代码过滤掉与数据集中任何其他图像不相似的图像:

import numpy as np

sim_count = np.array(sim_idx["count"])
sim_idx["im_file"][sim_count > 30]

可视化嵌入空间

您还可以使用您选择的绘图工具可视化嵌入空间。例如,这是一个使用 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()

开始使用 Explorer API 创建您自己的 CV 数据集探索报告。如需灵感,请查看VOC 探索示例

使用 Ultralytics Explorer 构建的应用程序

试试我们基于 Explorer API 的 GUI 演示

即将推出

  • [ ] 合并来自数据集的特定标签。示例 - 导入所有 person 来自 COCO 的标签和 car 来自 Cityscapes 的标签
  • [ ] 删除相似度指数高于给定阈值的图像
  • [ ] 合并/删除条目后自动持久化新数据集
  • [ ] 高级数据集可视化

常见问题

Ultralytics Explorer API 用于什么?

Ultralytics Explorer API 专为全面的数据集探索而设计。它允许用户使用 SQL 查询、向量相似性搜索和语义搜索来过滤和搜索数据集。这个强大的 python API 可以处理大型数据集,非常适合使用 Ultralytics 模型的各种计算机视觉任务。

如何安装 Ultralytics Explorer API?

要安装 Ultralytics Explorer API 及其依赖项,请使用以下命令:

pip install ultralytics[explorer]

这将自动安装 Explorer API 功能所需的所有外部库。有关其他设置详细信息,请参阅我们文档的安装部分

您可以使用 Ultralytics Explorer API,通过创建嵌入表并查询相似图像来进行相似性搜索。这是一个基本示例:

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

有关更多详细信息,请访问相似性搜索部分

将 LanceDB 与 Ultralytics Explorer 结合使用有哪些好处?

Ultralytics Explorer 在底层使用了 LanceDB,它提供了可扩展的、基于磁盘的嵌入表。这确保您可以为像 COCO 这样的大型数据集创建和重用嵌入,而不会耗尽内存。这些表只需创建一次,即可重复使用,从而提高数据处理效率。

Ultralytics Explorer API 中的 Ask AI 功能是如何工作的?

Ask AI 功能允许用户使用自然语言查询来过滤数据集。此功能利用 LLM 在后台将这些查询转换为 SQL 查询。这是一个示例:

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

更多示例,请查看Ask AI 部分



📅 创建于 1 年前 ✏️ 更新于 4 个月前

评论