尧图网页设计 
使用 Ultralytics Explorer API 深度探索 YOLO 数据集语义搜索、SQL 查询与嵌入分析实战指南【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10本指南以 Ultralytics Explorer API 文档为主体结合 yolov10 仓库中ultralytics/data/explorer/的源码实现系统讲解如何在 YOLO 系列模型检测 / 分割 / 姿态数据集上使用语义相似度搜索、SQL 过滤、自然语言查询Ask AI与嵌入空间分析。读完本文你将掌握Explorer类的完整 API 用法、底层嵌入表的存储原理LanceDB 磁盘持久化以及如何用相似度索引清洗与筛选训练数据。一、Explorer API 是什么Explorer API 是 Ultralytics 提供的一个 Python 数据集探索接口面向计算机视觉CV数据集提供以下三类核心能力向量相似度搜索根据图像嵌入embedding相近即语义相近的思想查找与给定图片或数据索引最相似的一批样本SQL 查询对嵌入表中的结构化元数据类别标签、边界框、掩码、关键点等执行 SQL 风格的过滤语义搜索 / 自然语言查询Ask AI用大白话描述过滤条件例如100 张恰好包含 1 个人和 2 条狗的图片由 LLM 自动翻译为 SQL 执行。该 API 同时驱动了仓库内置的 GUI 探索工具yolo explorer命令详见 dash.py你也可以基于它编写自己的 Jupyter Notebook 或脚本产出数据集洞察报告。仓库还附带完整的交互式演示 explorer.ipynb可供对照练习。二、安装与依赖Explorer 的部分功能依赖第三方库这些库会在首次使用时自动安装。也可以手动安装全部可选依赖pip install ultralytics[explorer]从源码看Explorer 的依赖被严格校验在 explorer.py 的构造函数中lancedb 0.4.3嵌入式向量数据库负责嵌入表的持久化与向量检索duckdb 0.9.2SQL 查询引擎源码注释明确提到duckdb0.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 的使用分为三步创建对象 → 构建嵌入表 → 执行查询。from ultralytics import Explorer # 创建 Explorer 对象 explorer Explorer(datacoco128.yaml, modelyolov8n.pt) # 为数据集创建嵌入表 explorer.create_embeddings_table() # 用图片路径搜索相似图片 dataframe explorer.get_similar(imgpath/to/image.jpg) # 或用数据集内的索引搜索 dataframe explorer.get_similar(idx0)3.1 关键参数说明来自源码构造函数签名见 explorer.py参数默认值说明datacoco128.yaml数据集配置文件须位于 ultralytics/cfg/datasets/ 目录或可被check_det_dataset解析modelyolov8n.pt用于生成嵌入的特征提取模型支持检测 / 分割 / 姿态等各类 YOLO 模型uri用户配置目录下的explorer文件夹LanceDB 数据库的存储位置决定嵌入表落盘路径嵌入表的命名规则为数据集配置名_小写 _ 模型名_小写源码 L67例如coco128_yolov8n.pt。3.2 嵌入表的构建与复用重要机制create_embeddings_table(forceFalse, splittrain)的行为如下源码 L78-L128若同名表已存在且forceFalse直接复用不重复计算日志会提示Pass forceTrue to overwrite it若forceTrue强制覆盖重建首次构建时遍历数据集split参数指定使用哪个划分默认train逐张图片用model.embed()提取特征连同标签、边界框、掩码、关键点等元数据写入表。LanceDB 采用磁盘持久化存储因此即使 COCO 这样的大规模数据集也不会因内存不足而失败构建一次后即可反复复用。这正是数据集 模型配对只建一次表的官方设计意图。3.3 嵌入是怎么来的嵌入由 engine/model.py 的embed()方法生成它是predict()的封装默认提取模型倒数第二层kwargs[embed] [len(self.model.model) - 2]的特征作为图片向量。也就是说嵌入的语义质量与所选模型的表征能力直接相关这也是 Explorer 允许为同一数据集搭配不同模型反复构建嵌入表的原因。四、相似性搜索Similarity Search相似性搜索基于相似图片拥有相似嵌入的假设。嵌入表构建完成后可通过两种方式发起搜索按数据集索引exp.get_similar(idx[1, 10], limit10)按任意图片可在数据集之外支持 URL 或本地路径exp.get_similar(img[path/to/img1, path/to/img2], limit10)传入多个输入时会取其嵌入的均值作为查询向量见 query 方法 L168-L171torch.mean(torch.stack(embeds), 0)相当于以这批图片的共同语义作为检索基准。返回的是 pandas DataFrame包含limit个最相似的数据点及其在嵌入空间中的距离可在此基础上继续做二次过滤。4.1 用图片搜索from ultralytics import Explorer exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() # 单张图片搜索 similar exp.get_similar(imghttps://ultralytics.com/images/bus.jpg, limit10) print(similar.head()) # 多张图片搜索取均值 similar exp.get_similar( img[https://ultralytics.com/images/bus.jpg, https://ultralytics.com/images/bus.jpg], limit10 ) print(similar.head())4.2 用数据集索引搜索from ultralytics import Explorer exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() similar exp.get_similar(idx1, limit10) print(similar.head()) # 多个索引 similar exp.get_similar(idx[1, 10], limit10) print(similar.head())get_similar的完整签名源码 L244-L280img图片路径 / URL 或路径列表与idx二选一源码_check_imgs_or_idxs会校验二者只能传其一不能同时传、也不能都不传idx数据集内索引或索引列表limit返回结果条数默认 25return_typepandas或arrow默认pandas。4.3 绘制相似图片网格plot_similar与get_similar参数一致区别在于它会把相似结果渲染成网格图并返回 PIL.Image# 用图片 exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() plt exp.plot_similar(imghttps://ultralytics.com/images/bus.jpg, limit10) plt.show() # 用索引 exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() plt exp.plot_similar(idx1, limit10) plt.show()底层由 utils.py 的plot_query_result完成按 640 边长做 LetterBox 缩放并把边界框bboxes、掩码masks、关键点kpts等标注一并绘制到图上便于直观对比候选样本的标注质量。五、Ask AI自然语言查询Ask AI 允许用户用自然语言描述过滤条件无需掌握 SQL。例如输入show me 100 images with exactly one person and 2 dogs. There can be other objects too即可返回满足条件的图片。from ultralytics import Explorer from ultralytics.data.explorer import plot_query_result exp Explorer(datacoco128.yaml, modelyolov8n.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()5.1 实现原理与注意事项从源码看utils.py L112-L165ask_ai的执行链路是prompt_sql_query(query)调用 OpenAI 的gpt-3.5-turbo模型把嵌入表的字段 Schemaim_file、labels、cls、bboxes、masks、keypoints、vector连同用户请求一起送入 System Prompt要求 LLM 只输出一条SELECT * FROM table WHERE ...形式的 SQLask_ai拿到生成的 SQL 后交给sql_query执行explorer.py L431-L455若生成的 SQL 非法会打印错误日志并返回None。因此 Ask AI 的结果是概率性的官方文档明确提示偶尔会出错建议对结果做人工抽验。同时它依赖 OpenAI API需要配置 API Key可通过yolo settings openai_api_key...写入全局设置未配置时prompt_sql_query会提示交互式输入 Key 并自动持久化到设置utils.py L117-L120。六、SQL 查询sql_query方法直接对嵌入表执行 SQL 风格查询返回 pandas DataFrame默认或 pyarrow Tablefrom ultralytics import Explorer exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() df exp.sql_query(WHERE labels LIKE %person% AND labels LIKE %dog%) print(df.head())6.1 查询语法约定源码强制校验见 sql_query 实现 L173-L217查询必须以SELECT或WHERE开头否则抛出ValueError以WHERE开头时源码会自动补全为SELECT * FROM table 你的 WHERE 子句查询引擎为 DuckDB表结构即嵌入表 Schema可直接使用LIKE、ARRAY_LENGTH、FILTER等 DuckDB 支持的函数与数组操作。6.2 绘制 SQL 查询结果from ultralytics import Explorer exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() # 绘制 SQL 查询结果网格图 exp.plot_sql_query(WHERE labels LIKE %person% AND labels LIKE %dog% LIMIT 10)plot_sql_query(query, labelsTrue)内部先以return_typearrow执行查询再交给plot_query_result绘制若结果为空会打印No results found.并返回Noneexplorer.py L219-L242。6.3 嵌入表的字段 Schema可查询的字段定义在 utils.py 的 get_table_schema L18-L31随任务类型动态填充字段类型说明im_filestring图片文件路径labelsliststring图片中所有目标的类别名如person、dogclslistint对应类别的整数 ID与labels一一映射bboxeslistlistfloat各目标的边界框坐标maskslistlistlistint分割掩码仅分割模型keypointslistlistlistfloat姿态关键点仅姿态模型vector定长浮点向量图片嵌入维度由所选模型决定这也是 Ask AI 的 System Prompt 中向 LLM 提供的完整表结构描述utils.py L126-L159。七、高级直接操作嵌入表嵌入表一旦构建完成可通过Explorer.table直接访问 LanceDB 表对象执行原生查询、下推 pre/post 过滤等高级操作from ultralytics import Explorer exp Explorer() exp.create_embeddings_table() table exp.table提示LanceDB 表同时支持to_pandas()与to_arrow()两种结果形态也支持 dict 转换方便与现有数据分析流程衔接。7.1 读取原始嵌入from ultralytics import Explorer exp Explorer() exp.create_embeddings_table() table exp.table embeddings table.to_pandas()[vector] print(embeddings)7.2 带 pre / post 过滤的原生向量检索可以直接用 LanceDB 的查询 API 做向量检索 过滤 限量的组合操作from ultralytics import Explorer exp Explorer(modelyolov8n.pt) exp.create_embeddings_table() table exp.table # 用一个 256 维的哑向量演示指定余弦距离度量 空过滤条件 返回前 10 条 embedding [i for i in range(256)] rs table.search(embedding).metric(cosine).where().limit(10)7.3 为大规模数据集创建向量索引数据量大时可为嵌入表建立专门的向量索引以加速查询使用 LanceDB 表的create_index方法table.create_index(num_partitions..., num_sub_vectors...)num_partitions划分的分区数num_sub_vectors每个向量的子向量数PQ 量化相关。更完整的索引类型与参数说明可查阅 LanceDB 的 ANN 索引文档。仓库目前尚未在 Explorer API 层直接封装索引创建需通过table对象调用官方文档明确说明未来会加入 API 级支持。八、嵌入的应用相似度索引与可视化利用嵌入表可以做多种探索性分析。8.1 相似度索引Similarity Indexsimilarity_index(max_dist0.2, top_kNone, forceFalse)会估算每个数据点与数据集其余部分的相似程度对每个图片在嵌入空间中统计距离小于max_dist的邻居数量每次最多考虑top_k个最近邻源码 L315-L372。返回的 DataFrame 包含四列idx图片在数据集中的索引im_file图片文件路径count与当前图片距离小于max_dist的图片数量sim_im_files这count张相似图片的路径列表。参数校验规则来自源码top_k必须是0.0 ~ 1.0之间的小数表示取最近邻的比例max_dist必须非负。生成的结果表会以相似索引基名_thres_{max_dist}_top_{top_k}命名并持久化同一(数据集, 模型, max_dist, top_k)组合只计算一次数据集发生变化或需要重算时传forceTrue即可。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]即只保留count 30的图片剔除那些与其余数据距离过远的异常样本。similarity_index还配套了plot_similarity_index方法可一键绘制每张图片相似邻居数量的柱状图直观定位分布explorer.py L374-L416。8.2 可视化嵌入空间可以借助任意绘图工具把高维嵌入降到低维后观察数据分布。下面是用 PCA 降到 3 维、再用 matplotlib 绘制 3D 散点图的示例import numpy as np from sklearn.decomposition import PCA import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D # 用 PCA 将嵌入降到 3 维便于 3D 可视化 pca PCA(n_components3) reduced_data pca.fit_transform(embeddings) fig plt.figure(figsize(8, 6)) ax fig.add_subplot(111, projection3d) ax.scatter(reduced_data[:, 0], reduced_data[:, 1], reduced_data[:, 2], alpha0.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()这类降维可视化常用于发现类别重叠、检查标注噪声、判断不同子集的分布差异进而指导数据增补策略。九、CLI 与 GUIyolo explorerExplorer API 也是仓库 GUI 探索工具的后端。在终端执行yolo explorer该命令由 cfg/init.py 的 handle_explorer L412-L416 实现本质是streamlit run ultralytics/data/explorer/gui/dash.py随后在浏览器中打开交互界面可完成选择数据集与模型、创建嵌入表带进度条见 dash.py 的 _get_explorer、相似图片搜索、SQL 查询与语义搜索。注意GUI 中的 Ask AI 同样依赖 OpenAI首次使用会被提示设置 API Keyyolo settings openai_api_key...GUI 的完整使用说明见 docs/en/datasets/explorer/index.md。十、多任务支持与测试验证仓库测试 tests/test_explorer.py 对 Explorer 覆盖了四种任务场景可直接作为 API 用法的权威示例test_similarity默认数据集 模型下验证get_similar索引 / 图片 / 多索引返回条数、similarity_index与sql_query可用性test_det检测datacoco8.yaml, modelyolov8n.pt断言嵌入表含bboxesplot_similar返回 PIL.Imagetest_seg分割datacoco8-seg.yaml, modelyolov8n-seg.pt断言表含maskstest_pose姿态datacoco8-pose.yaml, modelyolov8n-pose.pt断言表含keypoints。由此可见Explorer 天然支持检测、分割、姿态三类任务create_embeddings_table(forceTrue)在测试中被用于强制重建验证了force参数的语义。对应数据集配置均位于 ultralytics/cfg/datasets/如coco8.yaml、coco8-seg.yaml、coco8-pose.yaml。十一、官方规划中的功能官方文档的 Coming Soon 部分列出了 Explorer 后续计划支持的能力可据此规划自己的数据集工作流合并不同数据集的指定类别标签例如把 COCO 的所有person标签与 Cityscapes 的car标签导入同一数据集按相似度阈值自动移除图片即删除相似度指数高于给定阈值的样本合并 / 移除条目后自动持久化新数据集更高级的数据集可视化能力。总结Explorer API 为 YOLO 生态提供了开箱即用的数据集探索方案create_embeddings_table构建 LanceDB 持久化嵌入表get_similar/plot_similar完成向量相似检索sql_query/plot_sql_query提供结构化过滤ask_ai将自然语言翻译为 SQLsimilarity_index支持离群样本清洗而Explorer.table则把底层数据库完全开放给高级用户。无论你是要做训练前的数据质量审计、构建难例挖掘流水线还是生成数据集洞察报告都可以直接基于本仓库的 explorer.py 与配套测试示例快速落地。【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Ultralytics Explorer API 深度探索 YOLO 数据集：语义搜索、SQL 查询与嵌入分析实战指南
使用 Ultralytics Explorer API 深度探索 YOLO 数据集语义搜索、SQL 查询与嵌入分析实战指南【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10本指南以 Ultralytics Explorer API 文档为主体结合 yolov10 仓库中ultralytics/data/explorer/的源码实现系统讲解如何在 YOLO 系列模型检测 / 分割 / 姿态数据集上使用语义相似度搜索、SQL 过滤、自然语言查询Ask AI与嵌入空间分析。读完本文你将掌握Explorer类的完整 API 用法、底层嵌入表的存储原理LanceDB 磁盘持久化以及如何用相似度索引清洗与筛选训练数据。一、Explorer API 是什么Explorer API 是 Ultralytics 提供的一个 Python 数据集探索接口面向计算机视觉CV数据集提供以下三类核心能力向量相似度搜索根据图像嵌入embedding相近即语义相近的思想查找与给定图片或数据索引最相似的一批样本SQL 查询对嵌入表中的结构化元数据类别标签、边界框、掩码、关键点等执行 SQL 风格的过滤语义搜索 / 自然语言查询Ask AI用大白话描述过滤条件例如100 张恰好包含 1 个人和 2 条狗的图片由 LLM 自动翻译为 SQL 执行。该 API 同时驱动了仓库内置的 GUI 探索工具yolo explorer命令详见 dash.py你也可以基于它编写自己的 Jupyter Notebook 或脚本产出数据集洞察报告。仓库还附带完整的交互式演示 explorer.ipynb可供对照练习。二、安装与依赖Explorer 的部分功能依赖第三方库这些库会在首次使用时自动安装。也可以手动安装全部可选依赖pip install ultralytics[explorer]从源码看Explorer 的依赖被严格校验在 explorer.py 的构造函数中lancedb 0.4.3嵌入式向量数据库负责嵌入表的持久化与向量检索duckdb 0.9.2SQL 查询引擎源码注释明确提到duckdb0.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 的使用分为三步创建对象 → 构建嵌入表 → 执行查询。from ultralytics import Explorer # 创建 Explorer 对象 explorer Explorer(datacoco128.yaml, modelyolov8n.pt) # 为数据集创建嵌入表 explorer.create_embeddings_table() # 用图片路径搜索相似图片 dataframe explorer.get_similar(imgpath/to/image.jpg) # 或用数据集内的索引搜索 dataframe explorer.get_similar(idx0)3.1 关键参数说明来自源码构造函数签名见 explorer.py参数默认值说明datacoco128.yaml数据集配置文件须位于 ultralytics/cfg/datasets/ 目录或可被check_det_dataset解析modelyolov8n.pt用于生成嵌入的特征提取模型支持检测 / 分割 / 姿态等各类 YOLO 模型uri用户配置目录下的explorer文件夹LanceDB 数据库的存储位置决定嵌入表落盘路径嵌入表的命名规则为数据集配置名_小写 _ 模型名_小写源码 L67例如coco128_yolov8n.pt。3.2 嵌入表的构建与复用重要机制create_embeddings_table(forceFalse, splittrain)的行为如下源码 L78-L128若同名表已存在且forceFalse直接复用不重复计算日志会提示Pass forceTrue to overwrite it若forceTrue强制覆盖重建首次构建时遍历数据集split参数指定使用哪个划分默认train逐张图片用model.embed()提取特征连同标签、边界框、掩码、关键点等元数据写入表。LanceDB 采用磁盘持久化存储因此即使 COCO 这样的大规模数据集也不会因内存不足而失败构建一次后即可反复复用。这正是数据集 模型配对只建一次表的官方设计意图。3.3 嵌入是怎么来的嵌入由 engine/model.py 的embed()方法生成它是predict()的封装默认提取模型倒数第二层kwargs[embed] [len(self.model.model) - 2]的特征作为图片向量。也就是说嵌入的语义质量与所选模型的表征能力直接相关这也是 Explorer 允许为同一数据集搭配不同模型反复构建嵌入表的原因。四、相似性搜索Similarity Search相似性搜索基于相似图片拥有相似嵌入的假设。嵌入表构建完成后可通过两种方式发起搜索按数据集索引exp.get_similar(idx[1, 10], limit10)按任意图片可在数据集之外支持 URL 或本地路径exp.get_similar(img[path/to/img1, path/to/img2], limit10)传入多个输入时会取其嵌入的均值作为查询向量见 query 方法 L168-L171torch.mean(torch.stack(embeds), 0)相当于以这批图片的共同语义作为检索基准。返回的是 pandas DataFrame包含limit个最相似的数据点及其在嵌入空间中的距离可在此基础上继续做二次过滤。4.1 用图片搜索from ultralytics import Explorer exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() # 单张图片搜索 similar exp.get_similar(imghttps://ultralytics.com/images/bus.jpg, limit10) print(similar.head()) # 多张图片搜索取均值 similar exp.get_similar( img[https://ultralytics.com/images/bus.jpg, https://ultralytics.com/images/bus.jpg], limit10 ) print(similar.head())4.2 用数据集索引搜索from ultralytics import Explorer exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() similar exp.get_similar(idx1, limit10) print(similar.head()) # 多个索引 similar exp.get_similar(idx[1, 10], limit10) print(similar.head())get_similar的完整签名源码 L244-L280img图片路径 / URL 或路径列表与idx二选一源码_check_imgs_or_idxs会校验二者只能传其一不能同时传、也不能都不传idx数据集内索引或索引列表limit返回结果条数默认 25return_typepandas或arrow默认pandas。4.3 绘制相似图片网格plot_similar与get_similar参数一致区别在于它会把相似结果渲染成网格图并返回 PIL.Image# 用图片 exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() plt exp.plot_similar(imghttps://ultralytics.com/images/bus.jpg, limit10) plt.show() # 用索引 exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() plt exp.plot_similar(idx1, limit10) plt.show()底层由 utils.py 的plot_query_result完成按 640 边长做 LetterBox 缩放并把边界框bboxes、掩码masks、关键点kpts等标注一并绘制到图上便于直观对比候选样本的标注质量。五、Ask AI自然语言查询Ask AI 允许用户用自然语言描述过滤条件无需掌握 SQL。例如输入show me 100 images with exactly one person and 2 dogs. There can be other objects too即可返回满足条件的图片。from ultralytics import Explorer from ultralytics.data.explorer import plot_query_result exp Explorer(datacoco128.yaml, modelyolov8n.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()5.1 实现原理与注意事项从源码看utils.py L112-L165ask_ai的执行链路是prompt_sql_query(query)调用 OpenAI 的gpt-3.5-turbo模型把嵌入表的字段 Schemaim_file、labels、cls、bboxes、masks、keypoints、vector连同用户请求一起送入 System Prompt要求 LLM 只输出一条SELECT * FROM table WHERE ...形式的 SQLask_ai拿到生成的 SQL 后交给sql_query执行explorer.py L431-L455若生成的 SQL 非法会打印错误日志并返回None。因此 Ask AI 的结果是概率性的官方文档明确提示偶尔会出错建议对结果做人工抽验。同时它依赖 OpenAI API需要配置 API Key可通过yolo settings openai_api_key...写入全局设置未配置时prompt_sql_query会提示交互式输入 Key 并自动持久化到设置utils.py L117-L120。六、SQL 查询sql_query方法直接对嵌入表执行 SQL 风格查询返回 pandas DataFrame默认或 pyarrow Tablefrom ultralytics import Explorer exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() df exp.sql_query(WHERE labels LIKE %person% AND labels LIKE %dog%) print(df.head())6.1 查询语法约定源码强制校验见 sql_query 实现 L173-L217查询必须以SELECT或WHERE开头否则抛出ValueError以WHERE开头时源码会自动补全为SELECT * FROM table 你的 WHERE 子句查询引擎为 DuckDB表结构即嵌入表 Schema可直接使用LIKE、ARRAY_LENGTH、FILTER等 DuckDB 支持的函数与数组操作。6.2 绘制 SQL 查询结果from ultralytics import Explorer exp Explorer(datacoco128.yaml, modelyolov8n.pt) exp.create_embeddings_table() # 绘制 SQL 查询结果网格图 exp.plot_sql_query(WHERE labels LIKE %person% AND labels LIKE %dog% LIMIT 10)plot_sql_query(query, labelsTrue)内部先以return_typearrow执行查询再交给plot_query_result绘制若结果为空会打印No results found.并返回Noneexplorer.py L219-L242。6.3 嵌入表的字段 Schema可查询的字段定义在 utils.py 的 get_table_schema L18-L31随任务类型动态填充字段类型说明im_filestring图片文件路径labelsliststring图片中所有目标的类别名如person、dogclslistint对应类别的整数 ID与labels一一映射bboxeslistlistfloat各目标的边界框坐标maskslistlistlistint分割掩码仅分割模型keypointslistlistlistfloat姿态关键点仅姿态模型vector定长浮点向量图片嵌入维度由所选模型决定这也是 Ask AI 的 System Prompt 中向 LLM 提供的完整表结构描述utils.py L126-L159。七、高级直接操作嵌入表嵌入表一旦构建完成可通过Explorer.table直接访问 LanceDB 表对象执行原生查询、下推 pre/post 过滤等高级操作from ultralytics import Explorer exp Explorer() exp.create_embeddings_table() table exp.table提示LanceDB 表同时支持to_pandas()与to_arrow()两种结果形态也支持 dict 转换方便与现有数据分析流程衔接。7.1 读取原始嵌入from ultralytics import Explorer exp Explorer() exp.create_embeddings_table() table exp.table embeddings table.to_pandas()[vector] print(embeddings)7.2 带 pre / post 过滤的原生向量检索可以直接用 LanceDB 的查询 API 做向量检索 过滤 限量的组合操作from ultralytics import Explorer exp Explorer(modelyolov8n.pt) exp.create_embeddings_table() table exp.table # 用一个 256 维的哑向量演示指定余弦距离度量 空过滤条件 返回前 10 条 embedding [i for i in range(256)] rs table.search(embedding).metric(cosine).where().limit(10)7.3 为大规模数据集创建向量索引数据量大时可为嵌入表建立专门的向量索引以加速查询使用 LanceDB 表的create_index方法table.create_index(num_partitions..., num_sub_vectors...)num_partitions划分的分区数num_sub_vectors每个向量的子向量数PQ 量化相关。更完整的索引类型与参数说明可查阅 LanceDB 的 ANN 索引文档。仓库目前尚未在 Explorer API 层直接封装索引创建需通过table对象调用官方文档明确说明未来会加入 API 级支持。八、嵌入的应用相似度索引与可视化利用嵌入表可以做多种探索性分析。8.1 相似度索引Similarity Indexsimilarity_index(max_dist0.2, top_kNone, forceFalse)会估算每个数据点与数据集其余部分的相似程度对每个图片在嵌入空间中统计距离小于max_dist的邻居数量每次最多考虑top_k个最近邻源码 L315-L372。返回的 DataFrame 包含四列idx图片在数据集中的索引im_file图片文件路径count与当前图片距离小于max_dist的图片数量sim_im_files这count张相似图片的路径列表。参数校验规则来自源码top_k必须是0.0 ~ 1.0之间的小数表示取最近邻的比例max_dist必须非负。生成的结果表会以相似索引基名_thres_{max_dist}_top_{top_k}命名并持久化同一(数据集, 模型, max_dist, top_k)组合只计算一次数据集发生变化或需要重算时传forceTrue即可。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]即只保留count 30的图片剔除那些与其余数据距离过远的异常样本。similarity_index还配套了plot_similarity_index方法可一键绘制每张图片相似邻居数量的柱状图直观定位分布explorer.py L374-L416。8.2 可视化嵌入空间可以借助任意绘图工具把高维嵌入降到低维后观察数据分布。下面是用 PCA 降到 3 维、再用 matplotlib 绘制 3D 散点图的示例import numpy as np from sklearn.decomposition import PCA import matplotlib.pyplot as plt from mpl_toolkits.mplot3d import Axes3D # 用 PCA 将嵌入降到 3 维便于 3D 可视化 pca PCA(n_components3) reduced_data pca.fit_transform(embeddings) fig plt.figure(figsize(8, 6)) ax fig.add_subplot(111, projection3d) ax.scatter(reduced_data[:, 0], reduced_data[:, 1], reduced_data[:, 2], alpha0.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()这类降维可视化常用于发现类别重叠、检查标注噪声、判断不同子集的分布差异进而指导数据增补策略。九、CLI 与 GUIyolo explorerExplorer API 也是仓库 GUI 探索工具的后端。在终端执行yolo explorer该命令由 cfg/init.py 的 handle_explorer L412-L416 实现本质是streamlit run ultralytics/data/explorer/gui/dash.py随后在浏览器中打开交互界面可完成选择数据集与模型、创建嵌入表带进度条见 dash.py 的 _get_explorer、相似图片搜索、SQL 查询与语义搜索。注意GUI 中的 Ask AI 同样依赖 OpenAI首次使用会被提示设置 API Keyyolo settings openai_api_key...GUI 的完整使用说明见 docs/en/datasets/explorer/index.md。十、多任务支持与测试验证仓库测试 tests/test_explorer.py 对 Explorer 覆盖了四种任务场景可直接作为 API 用法的权威示例test_similarity默认数据集 模型下验证get_similar索引 / 图片 / 多索引返回条数、similarity_index与sql_query可用性test_det检测datacoco8.yaml, modelyolov8n.pt断言嵌入表含bboxesplot_similar返回 PIL.Imagetest_seg分割datacoco8-seg.yaml, modelyolov8n-seg.pt断言表含maskstest_pose姿态datacoco8-pose.yaml, modelyolov8n-pose.pt断言表含keypoints。由此可见Explorer 天然支持检测、分割、姿态三类任务create_embeddings_table(forceTrue)在测试中被用于强制重建验证了force参数的语义。对应数据集配置均位于 ultralytics/cfg/datasets/如coco8.yaml、coco8-seg.yaml、coco8-pose.yaml。十一、官方规划中的功能官方文档的 Coming Soon 部分列出了 Explorer 后续计划支持的能力可据此规划自己的数据集工作流合并不同数据集的指定类别标签例如把 COCO 的所有person标签与 Cityscapes 的car标签导入同一数据集按相似度阈值自动移除图片即删除相似度指数高于给定阈值的样本合并 / 移除条目后自动持久化新数据集更高级的数据集可视化能力。总结Explorer API 为 YOLO 生态提供了开箱即用的数据集探索方案create_embeddings_table构建 LanceDB 持久化嵌入表get_similar/plot_similar完成向量相似检索sql_query/plot_sql_query提供结构化过滤ask_ai将自然语言翻译为 SQLsimilarity_index支持离群样本清洗而Explorer.table则把底层数据库完全开放给高级用户。无论你是要做训练前的数据质量审计、构建难例挖掘流水线还是生成数据集洞察报告都可以直接基于本仓库的 explorer.py 与配套测试示例快速落地。【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考