Ultralytics Explorer API

社区提示 ⚠️

截至 ultralytics>=8.3.10，Ultralytics Explorer 支持已被弃用。但别担心！您现在可以通过 Ultralytics HUB 访问类似甚至更强大的功能，这是一个直观的无代码平台，旨在简化您的工作流程。通过 Ultralytics HUB，您可以继续轻松地探索、可视化和管理您的数据，而无需编写一行代码。请务必查看并利用其强大的功能！🚀

简介

Explorer API 是一个用于探索数据集的 Python API。它支持使用 SQL 查询、向量相似性搜索和语义搜索来过滤和搜索您的数据集。

观看： Ultralytics Explorer API 概述

安装

Explorer 依赖于一些外部库来实现其部分功能。这些库在使用时会自动安装。要手动安装这些依赖项，请使用以下命令：

pip install ultralytics[explorer]

使用

from ultralytics import Explorer

# 创建一个 Explorer 对象
explorer = Explorer(data="coco128.yaml", model="yolo11n.pt")

# 为您的数据集创建嵌入表
explorer.create_embeddings_table()

# 搜索与给定图像/图像相似的图像
dataframe = explorer.get_similar(img="path/to/image.jpg")

# 或者搜索与给定索引/索引相似的图像
dataframe = explorer.get_similar(idx=0)

Note

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

如果您想强制更新嵌入表，可以将 force=True 传递给 create_embeddings_table 方法。

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

1. 相似性搜索

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

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

在有多个输入的情况下，使用它们的嵌入的聚合。

您将获得一个 pandas 数据框，其中包含与输入最相似的 limit 数量的数据点，以及它们在嵌入空间中的距离。您可以使用此数据集进行进一步过滤

语义搜索

使用图像使用数据集索引

from ultralytics import Explorer

# 创建一个 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())

# 使用多个索引进行搜索
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

# 创建一个 Explorer 对象
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

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

# 使用多个索引进行搜索
similar = exp.get_similar(idx=[1, 10], limit=10)
print(similar.head())

绘制相似图像

你还可以使用 plot_similar 方法绘制相似的图像。此方法接受与 get_similar 相同的参数，并以网格形式绘制相似的图像。

绘制相似图像

使用图像使用数据集索引

from ultralytics import Explorer

# 创建一个 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()

from ultralytics import Explorer

# 创建一个 Explorer 对象
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

# 创建一个 Explorer 对象
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

df = exp.ask_ai("给我展示 100 张正好有一个人和 2 只狗的图片。也可以有其他物体")
print(df.head())

# 绘制结果
plt = plot_query_result(df)
plt.show()

3. SQL 查询

你可以使用 sql_query 方法对你的数据集运行 SQL 查询。此方法接受一个 SQL 查询作为输入，并返回一个包含结果的 pandas 数据框。

SQL 查询

from ultralytics import Explorer

# 创建一个 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())

绘制 SQL 查询结果

你还可以使用 plot_sql_query 方法绘制 SQL 查询的结果。此方法接受与 sql_query 相同的参数，并以网格形式绘制结果。

绘制 SQL 查询结果

from ultralytics import Explorer

# 创建一个 Explorer 对象
exp = Explorer(data="coco128.yaml", model="yolo11n.pt")
exp.create_embeddings_table()

# 绘制 SQL 查询
exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

4. 使用嵌入表

你也可以直接使用嵌入表。一旦创建了嵌入表，你可以使用 Explorer.table 访问它。

Tip

Explorer 在内部使用 LanceDB 表。你可以直接使用 Explorer.table 对象访问此表，并运行原始查询、推送预过滤和后过滤等。

from ultralytics import Explorer

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

以下是一些你可以使用表进行的操作示例：

获取原始嵌入

Example

from ultralytics import Explorer

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

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

使用预过滤和后过滤的高级查询

Example

from ultralytics import Explorer

exp = Explorer(model="yolo11n.pt")
exp.create_embeddings_table()
table = exp.table

# 虚拟嵌入
embedding = [i for i in range(256)]
rs = table.search(embedding).metric("cosine").where("").limit(10)

创建向量索引

在使用大型数据集时，你还可以创建一个专用的向量索引以加快查询速度。这是通过 LanceDB 表上的 create_index 方法完成的。

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

在这里可以找到更多关于可用向量索引类型和参数的详细信息。未来，我们将增加直接从 Explorer API 创建向量索引的支持。

5. 嵌入应用

你可以使用嵌入表进行各种探索性分析。以下是一些示例：

相似性索引

Explorer 自带 similarity_index 操作：

它试图估计每个数据点与数据集中其他数据点的相似程度。
它通过计算在生成的嵌入空间中，有多少图像嵌入与当前图像的距离小于 max_dist，并一次考虑 top_k 个相似图像。

它返回一个包含以下列的 pandas 数据框：

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

Tip

对于给定的数据集、模型、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

# 使用 PCA 将维度减少到 3 个分量以在 3D 中可视化
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

# 使用 Matplotlib Axes3D 创建 3D 散点图
fig = plt.figure(figsize=(8, 6))
ax = fig.add_subplot(111, projection="3d")

# 散点图
ax.scatter(reduced_data[:, 0], reduced_data[:, 1], reduced_data[:, 2], alpha=0.5)
ax.set_title("降维后的 256 维数据 3D 散点图 (PCA)")
ax.set_xlabel("分量 1")
ax.set_ylabel("分量 2")
ax.set_zlabel("分量 3")

plt.show()

开始使用 Explorer API 创建您自己的 CV 数据集探索报告。获取灵感，请查看

使用 Ultralytics Explorer 构建的应用

尝试基于 Explorer API 的 GUI 演示

即将推出

[ ] 合并数据集中的特定标签。例如 - 从 COCO 导入所有 person 标签，从 Cityscapes 导入 car 标签
[ ] 移除相似性索引高于给定阈值的图像
[ ] 合并/移除条目后自动持久化新数据集
[ ] 高级数据集可视化

常见问题