5.2 Ultralytics Explorer API

5.2 Ultralytics Explorer API

简介

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

注意：嵌入表只会为给定的数据集和模型对创建一次并可重用。它们在底层使用 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 数据框以及它们在嵌入空间中的距离。

使用相似性搜索示例

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

2. 使用 AI 查询（自然语言查询）

您可以使用自然语言来过滤您的数据集，而无需掌握 SQL 查询的编写。AI 查询生成器会自动在后台处理。例如：您可以说“给我显示包含一个人和两只狗的100张图像，即使包含其他对象也可以”，它会生成相应的 SQL 查询并返回结果。

使用 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("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 数据框。

SQL 查询示例

from ultralytics import Explorer

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

# 使用 SQL 查询
df = exp.sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%'")
print(df.head())

4. 操作嵌入表

一旦嵌入表被创建，您可以使用 Explorer.table 直接访问它。Explorer 使用 LanceDB 表来处理嵌入，您可以运行原始查询、执行前置和后置过滤等操作。

获取原始嵌入示例

from ultralytics import Explorer

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

# 获取原始嵌入
data = table.to_pandas()["vector"]
print(data)

通过这些功能，Ultralytics Explorer API 为您提供了多种探索和分析计算机视觉数据集的方式，使得数据处理和探索变得更加简单高效。