企业官网建设流程全解析

YOLOv10 仓库数据集探索实战：Ultralytics Explorer 语义搜索、SQL 查询与向量相似度检索全指南

【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10

导读：本文以 YOLOv10 仓库内 Ultralytics Explorer 官方文档 为主体，系统讲解面向 CV 数据集的数据探索工具 Explorer。你将掌握如何通过pip install ultralytics[explorer]安装依赖、用 Python API 对数据集执行语义搜索 / 向量相似度检索 / SQL 过滤 / 自然语言查询（Ask AI），并通过yolo explorer一键启动基于 Streamlit 的图形化探索界面。读完本文，你可以像查询数据库一样洞察你的训练集：找相似样本、揪出异常标注、统计类别分布，为数据清洗与模型迭代提供决策依据。

Explorer 是 YOLOv10 仓库（其核心为 Ultralytics 全家桶源码）内置的 CV 数据集探索工具：既是一个可直接在浏览器中使用的 GUI，也是一套功能等价的 Python API。它支持语义搜索（Semantic Search）、SQL 查询（SQL Querying）、向量相似度检索（Vector Similarity Search），甚至支持自然语言提问（Ask AI）。其底层由 LanceDB 这类 serverless 向量数据库驱动——与纯内存数据库不同，它持久化在磁盘上且不牺牲性能，因此可以本地扩展到 COCO 这样的大规模数据集而不用担心内存耗尽。

一、Explorer 的能力概览与适用场景

Explorer 解决的问题非常具体：当你拥有一个 CV 数据集（目标检测 / 实例分割 / 姿态估计），如何高效地理解它、清洗它、分析它。它提供四种互补的探索手段：

从源码看，Explorer 的实现位于 ultralytics/data/explorer/explorer.py，其Explorer类在 ultralytics/init.py 中被导出，因此你可以通过from ultralytics import Explorer直接使用。仓库的测试文件 tests/test_explorer.py 覆盖了检测、分割、姿态三类任务的相似度检索、SQL 查询与相似度指数，是快速了解 API 行为的最佳参考。

二、安装与可选依赖

Explorer 的某些功能依赖外部库，这些依赖会在首次使用时自动安装。若要手动安装全部可选依赖，执行：

pip install ultralytics[explorer]

从源码看，Explorer 构造时会主动检查核心依赖（见 explorer.py）：

• lancedb>=0.4.3：向量数据库，负责 embedding 的存储与向量检索；
• duckdb<=0.9.2：用于 SQL 查询执行（源码注释中特别标注了 duckdb==0.10.0 存在已知 bug，因此版本被上限约束）。

此外，按功能拆分：

• Ask AI（自然语言查询）依赖openai>=1.6.1，在 utils.py 的prompt_sql_query中检查；
• GUI 界面依赖streamlit>=1.29.0与streamlit-select>=0.3，在 dash.py 中检查。

三、Explorer API 快速上手

Explorer API 与 GUI 共用同一套后端逻辑，你可以用它编写自己的探索 notebook 或脚本。核心流程只有两步：创建 embedding 表 → 发起查询。

from ultralytics import Explorer # 创建 Explorer 对象：指定数据集配置与用于提取特征的模型 explorer = Explorer(data='coco128.yaml', model='yolov8n.pt') # 为数据集创建 embeddings 表（首次运行会逐图提取特征） explorer.create_embeddings_table() # 方式一：给定一张图片路径，检索最相似的图片 dataframe = explorer.get_similar(img='path/to/image.jpg') # 方式二：给定数据集中的索引（下标）检索 dataframe = explorer.get_similar(idx=0)

3.1 Explorer 构造参数

从 Explorer.init可以看到三个关键参数：

• data（默认coco128.yaml）：数据集配置文件路径；
• model（默认yolov8n.pt）：用于生成 embedding 的 YOLO 模型权重，其embed方法输出的特征向量即图片的向量化表示；
• uri（默认USER_CONFIG_DIR / "explorer"）：LanceDB 表在磁盘上的存储目录。

同时Explorer内部会依据"数据集名 + 模型名"生成表名：table_name = Path(data).name.lower() + "_" + model.lower()。这意味着同一数据集 + 同一模型组合的 embedding 表只会创建一次并被自动复用。

3.2 创建 Embeddings 表

create_embeddings_table(force: bool = False, split: str = "train")会遍历数据集（默认 train 划分）中的每张图片，用指定模型提取特征向量并写入 LanceDB 表，其核心流程见 explorer.py：

1. 若表已存在且force=False，直接复用并打印提示；
2. 通过check_det_dataset解析数据集配置，验证split划分是否存在；
3. 使用ExplorerDataset（基于YOLODataset的轻量化加载器，见 explorer.py）逐图读取，不做 resize 等重采样变换，保留原始标注；
4. 依据model.embed()的输出维度确定向量大小，创建表结构，将"图片路径、标签、类别、框、掩码、关键点、特征向量"逐批写入。

每条记录的表结构定义在 utils.py 的 get_table_schema，包含：

💡提示：若数据集发生变化或你想强制重建，给create_embeddings_table传入force=True即可覆盖旧表。

四、相似度搜索 / 语义搜索

相似度搜索基于一个朴素而有效的假设：相似的图片在 embedding 空间中距离更近。因此一旦 embedding 表构建完成，即可用以下任意一种方式检索相似图片：

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

当传入多张图片 / 多个索引时，会先对各输入的特征向量取均值，再用聚合向量检索（见 query 方法 中的torch.mean(torch.stack(embeds), 0)）。

get_similar返回一个 pandas DataFrame，包含limit个最相似的数据点及其在 embedding 空间中的距离，便于你在此基础上做二次过滤。img与idx二选一（同时传入会报错，见 _check_imgs_or_idxs）。

4.1 按图片检索

from ultralytics import Explorer # 创建 Explorer 对象 exp = Explorer(data='coco128.yaml', model='yolov8n.pt') exp.create_embeddings_table() # 用单张图片检索 similar = exp.get_similar(img='path/to/bus.jpg', limit=10) print(similar.head()) # 用多张图片检索（自动取 embedding 均值） similar = exp.get_similar( img=['path/to/bus.jpg', 'path/to/zidane.jpg'], limit=10 ) print(similar.head())

仓库自带的测试图片 ultralytics/assets/bus.jpg 与 ultralytics/assets/zidane.jpg 可直接作为此类查询的输入样例使用。

4.2 按数据集索引检索

from ultralytics import Explorer exp = Explorer(data='coco128.yaml', model='yolov8n.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())

4.3 可视化相似图片

plot_similar与get_similar参数一致，但会把结果以网格形式绘制出来（返回 PIL Image）：

from ultralytics import Explorer exp = Explorer(data='coco128.yaml', model='yolov8n.pt') exp.create_embeddings_table() plt_img = exp.plot_similar(img='path/to/bus.jpg', limit=10) plt_img.show()

底层通过 utils.py 的 plot_query_result 将im_file / bboxes / masks / keypoints / cls交给plot_images拼图渲染，因此支持检测框、掩码、关键点与类别标签的叠加显示（labels=True默认开启）。

五、Ask AI：自然语言查询

Ask AI 让你用一句大白话描述过滤条件，完全不需要会写 SQL。例如输入"show me 100 images with exactly one person and 2 dogs. There can be other objects too"，系统会在后台自动生成 SQL 并返回结果。

⚠️ 该能力基于 LLM 实现，结果是概率性的，偶尔可能出错——遇到失败时换个表述重试即可。

from ultralytics import Explorer from ultralytics.data.explorer import plot_query_result exp = Explorer(data='coco128.yaml', model='yolov8n.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_img = plot_query_result(df) plt_img.show()

5.1 底层原理

从源码看，Ask AI 的实现非常清晰（见 explorer.py 的 ask_ai）：ask_ai(query)调用 utils.py 的 prompt_sql_query，把完整的表结构 Schema 与用户请求一起作为系统提示词发给 OpenAI 的gpt-3.5-turbo，要求 LLM只输出一条以SELECT * FROM 'table'开头的 SQL；随后 Explorer 用sql_query执行该语句。若生成的 SQL 非法，会打印错误并返回None。

系统提示词中还包含一条示例查询，展示了如何在 DuckDB SQL 中表达组合条件：

SELECT * FROM 'table' WHERE ARRAY_LENGTH(cls) >= 2 AND ARRAY_LENGTH(FILTER(labels, x -> x = 'person')) >= 2 AND ARRAY_LENGTH(FILTER(labels, x -> x = 'dog')) >= 1;

5.2 配置 OpenAI API Key

Ask AI 依赖 OpenAI，首次使用时系统会提示你设置 API key。可以通过 CLI 设置：

yolo settings openai_api_key="..."

该 key 会持久化到 Ultralytics 的全局 SETTINGS 中（见 utils.py）；若设置文件中没有 key，终端会以getpass方式交互式询问，并将输入回写进 SETTINGS。

六、SQL 查询：像操作数据库一样过滤数据集

sql_query方法接收一条 SQL 作为输入，返回 pandas DataFrame。它同时接受完整 SELECT 语句或仅 WHERE 子句两种写法（源码 sql_query 中会为WHERE开头的语句自动补全SELECT * FROM 'table'），底层借助 DuckDB 对 LanceDB 表执行过滤，并支持按labels、cls、bboxes等列做条件筛选。

from ultralytics import Explorer exp = Explorer(data='coco128.yaml', model='yolov8n.pt') exp.create_embeddings_table() # 只传 WHERE 子句即可 df = exp.sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%'") print(df.head())

6.1 可视化 SQL 查询结果

plot_sql_query与sql_query参数一致，会将查询结果绘制成网格图：

from ultralytics import Explorer exp = Explorer(data='coco128.yaml', model='yolov8n.pt') exp.create_embeddings_table() # 绘制 SQL 查询结果（限制 10 条） exp.plot_sql_query("WHERE labels LIKE '%person%' AND labels LIKE '%dog%' LIMIT 10")

若查询结果为空，plot_sql_query会打印 "No results found." 并返回None。

七、GUI Explorer：浏览器里的可视化探索台

GUI 是构建在 Explorer API 之上的"游乐场"（源码见 dash.py），在浏览器中即可完成创建 embedding、语义搜索、SQL 查询与 Ask AI 全流程。启动命令：

yolo explorer

该命令由 CLI 入口解析（见 ultralytics/cfg/init.py），本质是执行：

streamlit run ultralytics/data/explorer/gui/dash.py --server.maxMessageSize 2048

7.1 界面交互流程

1. 初始化：从下拉框选择数据集（默认读取仓库 ultralytics/cfg/datasets 目录下的全部 yaml，如coco128.yaml）与特征提取模型（默认列出 yolov8n/x 的 detect / seg / pose 系列权重），并可勾选 "Force recreate embeddings" 强制重建表；点击 Explore 后后台线程开始建表，界面以进度条实时展示exp.progress（见 _get_explorer）。
2. 浏览样本：主区域以网格展示图片，支持调节 "Max Images Displayed" 与 "Start Index"，并可叠加显示标签、框、掩码与关键点。
3. SQL 查询：输入框默认预置WHERE labels LIKE '%person%' AND labels LIKE '%dog%'，点击 Query 执行。
4. Ask AI：输入自然语言描述，点击 Ask AI 执行（无 API key 时会提示先运行yolo settings openai_api_key="..."）。
5. 相似度搜索：在网格中多选若干图片，设置返回数量limit（默认 25），点击 Search 检索与所选图片集最相似的结果。

💡 在 GUI 中做语义搜索非常实用：当你发现某些图片推理效果不佳时，可以选中它们，一键找出数据集中所有"类似但可能同样有问题"的样本，进而针对性地补充或修正标注。

八、进阶：直接操作 Embeddings 表

Explorer 内部以 LanceDB 表为核心，表创建后可通过Explorer.table直接访问，执行原始查询、预过滤 / 后过滤等高级操作。

from ultralytics import Explorer exp = Explorer() exp.create_embeddings_table() table = exp.table

8.1 获取原始 Embeddings

from ultralytics import Explorer exp = Explorer() exp.create_embeddings_table() table = exp.table embeddings = table.to_pandas()["vector"] print(embeddings)

8.2 带预 / 后过滤的高级查询

from ultralytics import Explorer exp = Explorer(model="yolov8n.pt") exp.create_embeddings_table() table = exp.table # 用一个虚拟 embedding 做余弦相似度检索，并叠加过滤条件 embedding = [i for i in range(256)] rs = table.search(embedding).metric("cosine").where("").limit(10)

8.3 为大数据集创建向量索引

处理大型数据集时，可以调用 LanceDB 表的create_index方法创建专用向量索引以加速查询：

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

向量索引的类型与参数细节可查阅 LanceDB 的 ANN 索引文档；未来 Explorer API 计划直接在自身接口上支持创建向量索引。

九、Embeddings 应用：相似度指数（Similarity Index）

similarity_index操作尝试评估每个数据点与数据集中其余样本的相似程度：它逐一统计在 embedding 空间中，距离当前图片小于max_dist（默认 0.2）的图片数量，每次向量检索最多考虑top_k个最近邻。返回的 DataFrame 包含四列：

from ultralytics import Explorer exp = Explorer() exp.create_embeddings_table() sim_idx = exp.similarity_index()

与 embedding 表类似，同一数据集、模型、max_dist与top_k组合的相似度指数只会计算一次并复用（表名规则见 similarity_index）；数据集变化或需要重算时传force=True。

9.1 实战：用相似度指数清洗离群样本

一个典型的应用是过滤掉与数据集中任何其他图片都不相似的异常样本（可能是标注错误或损坏图片）：

import numpy as np sim_count = np.array(sim_idx["count"]) sim_idx['im_file'][sim_count > 30]

将max_dist、top_k传入plot_similarity_index还可以直接得到每个数据点相似计数的柱状图，快速掌握数据集的冗余与离群分布：

from ultralytics import Explorer exp = Explorer() exp.create_embeddings_table() plot_img = exp.plot_similarity_index() plot_img.show()

十、可视化 Embedding 空间

拿到全部 embedding 后，你还可以用任意绘图库可视化整个数据集在特征空间中的分布。下面是一个用 PCA 降到 3 维并用 matplotlib 绘制三维散点图的例子：

import numpy as np from sklearn.decomposition import PCA import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D # 将 256 维向量降到 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()

这种可视化有助于直观判断数据集是否存在明显的分布簇、类别是否可分、是否存在标注噪声聚集区。

十一、测试与可运行示例

仓库为 Explorer 提供了完整的自动化测试（见 tests/test_explorer.py），可作为 API 用法的权威参考：

• test_similarity：在默认数据集上验证get_similar(idx=...)、get_similar(img=...)、多索引检索、similarity_index()与sql_query("WHERE labels LIKE '%person%'")；
• test_det/test_seg/test_pose：分别基于coco8.yaml、coco8-seg.yaml、coco8-pose.yaml，配合yolov8n.pt/yolov8n-seg.pt/yolov8n-pose.pt验证检测、分割、姿态三类任务的相似度检索。

此外，docs/en/datasets/explorer/explorer.ipynb 是本主题配套的 Jupyter Notebook，包含从创建 embedding 到各类查询、可视化的完整可运行示例，适合作为动手实验的起点。与之配套的还有两篇同主题文档：Explorer API 详解（API 全量示例）与 Explorer GUI 使用说明（界面操作演示）。

十二、规划中的功能

Explorer 仍在持续演进，官方文档列出了以下规划方向：

• 合并数据集中的特定标签（例如：从 COCO 导入所有person标签、从 Cityscapes 导入car标签）；
• 移除相似度指数高于给定阈值的图片（自动去重）；
• 在合并 / 删除操作后自动持久化新数据集；
• 更高级的数据集可视化能力。

总结

Ultralytics Explorer 把"数据库查询"的体验带给了 CV 数据集：embedding 表让你可以用向量距离做语义检索，DuckDB 让你可以用 SQL 做精确过滤，LLM 让非 SQL 用户也能用自然语言提需求，相似度指数则直接服务于数据去重与异常样本清洗。无论你是通过yolo explorer使用 GUI，还是基于 Explorer API 编写自定义探索脚本，都能在训练 YOLOv10 / YOLOv8 系列模型之前，先把数据质量这个最关键的问题解决好。

【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10