Ultralytics Explorer：用向量检索、SQL 查询与 Ask AI 探索 CV 数据集的完整指南

本文基于 Ultralytics 官方文档，系统讲解 Ultralytics Explorer 这一 CV 数据集探索工具：如何安装可选依赖、构建图像 embedding 表、执行向量相似检索、SQL 查询与自然语言查询（Ask AI），以及如何直接操作底层 LanceDB 表进行高级分析。读完后，你可以将语义检索、标签过滤和 LLM 驱动的查询能力组合到自己的数据集检查流程（notebook / 脚本）中，快速定位重复样本、异常样本与模型表现不佳的数据切片。

版本边界：先确认你的 ultralytics 版本

在使用任何操作之前，必须先明确一个关键版本约束：

自 ultralytics>=8.3.12 起，Explorer 已从代码库中移除。 如需使用 Explorer，请安装 pip install ultralytics==8.3.11。类似的（且更扩展的）数据集探索能力由 Ultralytics Platform 提供。

这一点在当前仓库中可以得到印证：ultralytics/init.py 中 __version__ 为 8.4.138，且对整个 ultralytics/ 源码树检索 Explorer、lancedb、get_similar 等标识符均无结果——说明当前仓库版本确实已不再包含 Explorer 实现，文档中的全部 API 示例针对的是 8.3.11 及更早的安装版本。因此本文所有示例均以"已安装 ultralytics==8.3.11（含 [explorer] 扩展依赖）"为运行前提。

安装可选依赖

Explorer 的部分功能依赖外部库，使用 Explorer 时会自动安装；如需手动安装，执行：

pip install ultralytics[explorer]

为什么选择 LanceDB？ Explorer 的 embedding/语义检索与 SQL 查询能力由 LanceDB serverless 向量数据库驱动。与传统内存数据库不同，它把数据持久化在磁盘上而不牺牲性能，因此可以在本地扩展到 COCO 这样的大规模数据集而不会内存溢出。

Explorer Python API 基础：创建对象与 embedding 表

Explorer API 是探索数据集的 Python 接口，GUI 版本也基于同一套 API 构建。最简工作流如下（数据集配置文件如 coco128.yaml，YOLO 模型用于生成 embedding）：

from ultralytics import Explorer

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

# 为你的数据集创建 embedding 表
explorer.create_embeddings_table()

# 搜索与某张图片相似的图片
df = explorer.get_similar(img="path/to/image.jpg")

# 或者按数据集内索引搜索相似图片
df = explorer.get_similar(idx=0)

两个重要机制：

1. embedding 表只建一次、自动复用：对于给定的"数据集 + 模型"组合，embedding 表只创建一次，后续直接复用。由于底层使用 LanceDB 的磁盘扩展存储，可以为 COCO 等大库建表而不会撑爆内存。
2. 强制重建：如果数据集发生变化或需要重建表，向 create_embeddings_table 传 force=True。

1. 向量相似检索（get_similar / plot_similar）

相似检索的原理是：相似的图片在 embedding 空间中距离相近。构建好 embedding 表后，有两种检索入口：

• 按数据集索引：exp.get_similar(idx=[1, 10], limit=10)
• 按任意图片（可不在数据集中）：exp.get_similar(img=["path/to/img1", "path/to/img2"], limit=10)

传入多个输入时，会使用它们 embedding 的聚合值作为查询向量。返回值是一个 pandas DataFrame，包含最相似的 limit 条数据点及其在 embedding 空间中的距离，可在此基础上继续过滤。

用图片检索

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

# 使用多张图片检索（聚合 embedding）
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

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）

plot_similar 接受与 get_similar 相同的参数，并以网格形式画出相似图片：

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

plt = exp.plot_similar(idx=1, limit=10)
plt.show()

在官方的 VOC 探索示例（见 VOC Exploration Example）中，还支持 labels=False 参数隐藏标签绘制，例如 exp.plot_similar(img="https://ultralytics.com/images/bus.jpg", limit=10, labels=False)。

2. Ask AI：自然语言过滤数据集

Ask AI 让你不写 SQL 就能用自然语言过滤数据集：AI 查询生成器把你的 prompt 转成查询并返回匹配结果。注意：该功能由 LLM 驱动，结果是概率性的，可能不准确；若 LLM 无法生成有效查询，会返回 None。

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

例如在 VOC 数据集上询问 "show me images containing more than 10 objects with at least 2 persons"，即可获得满足条件的样本 DataFrame；也可以用 plot_query_result(exp.ask_ai("show me 10 images containing exactly 2 persons")) 直接出图。

3. SQL 查询（sql_query / plot_sql_query）

sql_query 方法直接在数据集上执行 SQL 并返回 pandas DataFrame。查询有两种写法：

• 以 WHERE 开头的简写形式——自动选择全部列；
• 完整 SELECT 查询——可指定要查询的列。

from ultralytics import 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())

典型场景：如果你的模型在"同时含人与狗"的图片上表现差，可以用如下查询把这些样本挑出来做重点检查：

WHERE labels LIKE '%person, person%' AND labels LIKE '%dog%'

绘制 SQL 结果：

exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

SQL 过滤与向量检索可以组合使用：先用语义检索圈定视觉相似的样本，再用 WHERE 条件精确收敛，或反之。

4. 高级用法：直接操作 LanceDB embedding 表

Explorer 内部就是 LanceDB 表。建表后可通过 Explorer.table 直接拿到表对象，执行原始查询、下推 pre-filter / post-filter 等：

from ultralytics import Explorer

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

获取原始 embedding

图像向量存储在 vector 列中：

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

带 pre/post 过滤的向量检索

LanceDB 中距离度量支持 L2、Cosine、Dot 三种；Explorer 的相似检索默认使用 L2。示例如下（where("") 表示不使用前置过滤）：

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)

数据格式互转

df = table.to_pandas()
pa_table = table.to_arrow()

为大库创建向量索引

数据集规模大时，可通过 LanceDB 表的 create_index 方法创建专用向量索引以加速查询：

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

5. Embedding 分析应用

Similarity Index：估计样本与全库的相似程度

similarity_index 操作估计每个数据点与数据集其余部分的相似程度：在生成的 embedding 空间中，统计有多少图像 embedding 与当前图像的距离小于 max_dist，同时每次只考虑 top_k 个最相似的图像。返回的 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()

给定数据集、模型、max_dist 与 top_k，相似性索引生成一次后即被复用；数据集变更或需要重建时传 force=True。VOC 示例中的调用方式为 exp.similarity_index(max_dist=0.2, top_k=0.01)，并可配套 exp.plot_similarity_index(max_dist=0.2, top_k=0.01) 直接可视化。

基于 count 列可以构造自定义过滤条件，例如挑出与库中其他样本高度相似的图片（疑似重复）：

import numpy as np

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

可视化 embedding 空间

取出 vector 列后可用 PCA 降维到 3 维，再用 Matplotlib 做 3D 散点图观察聚类结构：

import matplotlib.pyplot as plt
from sklearn.decomposition import PCA

# 用 PCA 降到 3 个主成分，便于 3D 可视化
pca = PCA(n_components=3)
reduced_data = pca.fit_transform(embeddings)

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

GUI 版 Explorer 的使用

GUI 版在浏览器中运行，可完成与 API 相同的能力：创建数据集 embedding、检索相似图片、执行 SQL 查询与语义检索。启动命令：

yolo explorer

Ask AI 的 OpenAI 密钥配置：GUI 首次运行时会被提示设置 OpenAI API key（Ask AI 功能基于 OpenAI）。可提前用以下命令设置：

yolo settings openai_api_key="YOUR_API_KEY"

GUI 中语义检索的典型操作是：选中一张或多张图片（如 VOC 数据集中的若干飞机图片），点击执行相似搜索，界面即返回视觉相近的样本集合——这与 API 中 get_similar(idx=[...]) 的语义一致。GUI 与 API 的详细说明分别见 Explorer Dashboard Demo 与 Explorer API。

FAQ

Ultralytics Explorer 是什么？对 CV 数据集有什么帮助？

Explorer 是一个通过语义检索、SQL 查询、向量相似检索和自然语言探索 CV 数据集的工具，提供 GUI 与 Python API 两种交互方式。借助 LanceDB，它可以对大库做高效、可扩展的检索而无需大量内存，适合做数据集分析与模式挖掘。

依赖怎么安装？

pip install ultralytics[explorer]

这些依赖是语义检索与 SQL 查询功能的完整可用前提；由于基于 LanceDB 的磁盘持久化，即使对 COCO 级别的大数据集也能保持高效。

Ask AI 是怎么工作的？

Ask AI 允许用自然语言查询数据集，由 LLM 在幕后把 prompt 转成 SQL 类查询。它使用 OpenAI，结果具有概率性、可能不准确；使用方式见上文"Ask AI"小节与 yolo settings openai_api_key="..." 密钥配置。

能否在 Google Colab 中运行？

可以。官方提供了预配置好全部依赖的 Explorer Colab notebook（安装 ultralytics[explorer] 与 openai 后运行 yolo checks 即可），可参考 Google Colab 集成指南。VOC 探索 notebook 的安装步骤示例：

uv pip install ultralytics[explorer] openai
yolo checks

小结与延伸阅读

Explorer 的核心价值是把"数据集理解"从人肉翻图变成可复用的工程操作：embedding 表一次构建、磁盘持久、按（数据集, 模型）对复用；在其之上，get_similar、ask_ai、sql_query 与 similarity_index 分别覆盖视觉相似、自然语言、结构化过滤和重复度估计四类需求，且均可直接退化为 pandas DataFrame 供后续任意分析。请再次注意：以上能力仅存在于 ultralytics==8.3.11 及更早版本（当前仓库版本 8.4.138 已移除该模块），更大规模的探索需求可转向 Ultralytics Platform。

延伸阅读：

• Explorer API 参考文档——各方法的完整参数与示例
• Explorer GUI（Dashboard）文档——浏览器版功能详解
• VOC Exploration Example——基于 VOC 数据集的完整探索 notebook 流程