Ultralytics Explorer API#

简介#

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

安装#

Explorer 的部分功能依赖外部库。使用 Explorer 时，系统会自动安装这些库。你也可以使用以下命令手动安装这些依赖项：

pip install "ultralytics[explorer]==8.3.11"

用法#

from ultralytics import Explorer

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

# 为数据集创建嵌入向量
explorer.create_embeddings_table()

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

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

如果要强制更新嵌入向量表，可以将 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 DataFrame，其中包含与输入最相似的 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())

绘制相似图像#

你还可以使用 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()

2. Ask AI（自然语言查询）#

此功能让你无需编写 SQL，即可使用自然语言筛选数据集。AI 驱动的查询生成器会将你的提示转换为查询，并返回匹配的结果。例如，你可以询问：“显示 100 张恰好有 1 个人和 2 条狗的图像。也可以有其他物体”，它会生成查询并显示相应结果。 注意：此功能使用 LLM，因此结果具有概率性，可能不准确。

from ultralytics.data.explorer import plot_query_result

from ultralytics import Explorer

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

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

3. SQL 查询#

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

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 相同的参数，并以网格形式绘制结果。

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 访问它。

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

# 虚拟嵌入向量
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=...)

5. 嵌入向量的应用#

你可以使用嵌入向量表开展各种探索性分析。以下是一些示例：

相似度指数#

Explorer 提供了 similarity_index 操作：

• 此操作会尝试估算每个数据点与数据集中其余数据点的相似程度。
• 它会统计在生成的嵌入空间中，距离当前图像比 max_dist 更近的图像嵌入向量数量，每次将 top_k 张相似图像纳入计算。

它会返回一个 pandas DataFrame，其中包含以下列：

• idx：图像在数据集中的索引
• im_file：图像文件路径
• count：数据集中距离当前图像比 max_dist 更近的图像数量
• sim_im_files：count 张相似图像的路径列表

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("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 开始创建自己的计算机视觉数据集探索报告。如需获取灵感，请参阅 VOC 探索示例。

使用 Ultralytics Explorer 构建的应用#

试用基于 Explorer API 的 GUI 演示

常见问题#