企业官网建设流程全解析

FiftyOne 数据集实战：Sama-COCO 高精度重标注数据集的加载与局部下载

【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone

本文以 FiftyOne 数据集的官方文档 Sama-COCO 数据页 为主线，系统讲解 Sama-COCO 数据集的规格、与 COCO-2017 的关系，以及如何通过load_zoo_dataset()与 CLI 按需加载检测框、分割掩码等子集。读完本文，你将掌握split、label_types、classes、image_ids、max_samples等局部下载参数的正确用法，并理解其底层"已有数据优先复用、只下载缺失内容"的实现原理，从而在 25.67 GB 的庞大数据集上做到按需取用、高效迭代。

Sama-COCO 是什么：COCO-2017 的高精度重标注版本

Sama-COCO 是COCO-2017 的重标注（relabeling）版本，是一个大规模的目标检测与分割数据集。与原始 COCO-2017 标注相比，Sama-COCO 的掩码（mask）更紧凑（tighter），并且大量拥挤场景（crowd）中的实例被分解为独立个体分别标注，因此非常适合训练对边界精细度要求更高的检测与实例分割模型。

从数据集内容上看，该版本沿用了 COCO-2017 的图像，以及 Sama 提供的边界框（bounding boxes）与分割掩码（segmentation masks）标注。

官方文档给出了四点重要说明（Notes）：

• Sama-COCO 定义了91 个类别，但数据实际只使用了80 个类别（与 COCO-2017 一致）；
• train 与 validation 分割中的部分图像没有标注；
• test 分割没有任何标注（仅提供图像与 image info）；
• Sama-COCO 的分割方式与 COCO-2017 完全一致（identical splits），便于与 COCO-2017 直接对比实验。

数据集关键规格（Details）

完整分割统计（Full split stats）

在源码中，这些数字被固化在 fiftyone/utils/sama.py 的_SPLIT_SIZES = {"train": 118287, "test": 40670, "validation": 5000}中，用于判断某个分割是否已完整下载。

底层实现：下载与准备流程的源码视角

为了准确理解局部下载参数的作用，先看数据集在后端是如何被拉取和组织的。SamaCOCODataset继承自FiftyOneDataset，其supports_partial_downloads属性返回True，并通过_download_and_prepare()委托给 fiftyone/utils/sama.py 中的download_sama_coco_dataset_split()执行实际下载。

从源码可以看到几个关键事实：

• 图像始终来自 COCO 官方源：_IMAGE_DOWNLOAD_LINKS指向train2017.zip、val2017.zip、test2017.zip；
• 标注来自 Sama：_ANNOTATION_DOWNLOAD_LINKS指向 Sama 的sama-coco-train.zip、sama-coco-val.zip，解压后得到annotations/sama_coco_train.json、annotations/sama_coco_validation.json；
• test 分割只下载 image info：_TEST_INFO_DOWNLOAD_LINK下载image_info_test2017.zip，因为 test 没有标注；
• 标注合并：train/validation 的标注压缩包内包含多个 JSON 片段，_merge_annotations()会将其合并为一份完整标注文件；
• 标注缓存复用：完整标注文件存放在与数据集目录平级的raw目录（_get_raw_dir()），后续再次加载同一分割时不会重复下载标注；
• 图像与标注均按需落盘到data/与labels.json，导入时使用COCODetectionDataset类型与 COCODetectionDatasetImporter（fiftyone.utils.coco）完成解析。

因此，load_zoo_dataset()的局部下载参数最终都会进入download_sama_coco_dataset_split()（其完整参数签名见 fiftyone/utils/sama.py），并与 fiftyone/utils/coco.py 中的 COCO 工具函数协同工作。

局部下载（Partial downloads）：按需获取子集

Sama-COCO 完整下载约 25.67 GB，FiftyOne 为此提供了一组参数，让你可以只下载自己需要的子集。其核心策略是：当指定新的子集时，FiftyOne 会优先复用本地已下载的数据，只有在确实缺少内容时才从网络补下载。因此，先下载整个 validation 分割后，再多次按不同条件局部加载 validation，都不会重复下载任何图像。

以下参数均可通过 load_zoo_dataset() 传入（括号内为默认值）：

include_license的可选值

• "False"（默认）：不加载许可证；
• True/"name"：存储许可证名称字符串；
• "id"：存储许可证 ID（整数）；
• "url"：存储许可证 URL。

max_samples的选取优先级

当同时指定label_types和/或classes时，FiftyOne优先选取同时满足所有指定标签类型和类别的样本，其次才选取满足其中任意一项的样本。实际加载数量可能小于max_samples——如果数据集中满足条件的样本不足，则只会加载可用的部分。

image_ids的三种指定方式

image_ids支持三种输入形式，底层由 fiftyone/utils/coco.py 的_parse_image_ids()统一解析：

1. <image-id>的 int 或字符串列表（如[123, 456]）；
2. <split>/<image-id>字符串列表（如["validation/123"]），可跨分割混用；
3. 一个文件的路径，文件内容为上述两种格式之一的 ID 列表：
   • TXT：每行一个 ID（_load_image_ids_txt）；
   • JSON：ID 数组（_load_image_ids_json）；
   • CSV：自动嗅探分隔符后读取（_load_image_ids_csv，支持,、;、:、空格、Tab、换行）。

解析后会对每个 ID 做存在性校验，无效 ID 会直接抛出ValueError并给出示例。

实战示例一：Python 加载

以下示例完整继承自官方文档，展示了三种典型用法（运行前请确保已安装fiftyone且版本不低于 0.21.0）：

import fiftyone as fo import fiftyone.zoo as foz # # 加载 validation 分割中的 50 个随机样本 # # 仅会下载必要的图像（如果需要）。 # 默认情况下只加载 detections # dataset = foz.load_zoo_dataset( "sama-coco", split="validation", max_samples=50, shuffle=True, ) session = fo.launch_app(dataset) # # 加载 validation 分割中同时包含 cat 和 dog 的 25 个样本的分割掩码 # # 优先选择包含全部指定 `classes` 的图像，其次是包含至少一个 # 指定 `classes` 的图像。如果该分割中满足 `classes` 条件的图像 # 不足以达到 `max_samples`，则只加载可用的图像。 # # 图像仅在必要时才会被下载 # dataset = foz.load_zoo_dataset( "sama-coco", split="validation", label_types=["segmentations"], classes=["cat", "dog"], max_samples=25, ) session.dataset = dataset # # 下载整个 validation 分割，同时加载 detections 与 segmentations # # 此后对 validation 分割的任何局部加载都不再需要下载任何图像 # dataset = foz.load_zoo_dataset( "sama-coco", split="validation", label_types=["detections", "segmentations"], ) session.dataset = dataset

三个示例分别演示了：随机抽样子集加载、按类别 + 标签类型 + 数量上限的组合过滤加载，以及完整分割加载。第二个示例尤其适合快速构建"猫狗二分类/分割"的小型实验集——只下载包含目标类别的图像，避免全量下载。

实战示例二：CLI 加载

不习惯 Python 的话，FiftyOne 提供了等价的命令行接口fiftyone zoo datasets load，通过--kwargs传递上述参数；加载完成后可用fiftyone app launch启动 App 浏览：

# # 加载 validation 分割中的 50 个随机样本 # # 仅会下载必要的图像（如果需要）。 # 默认情况下只加载 detections # fiftyone zoo datasets load sama-coco \ --split validation \ --kwargs \ max_samples=50 fiftyone app launch sama-coco-validation-50 # # 加载 validation 分割中同时包含 cat 和 dog 的 25 个样本的分割掩码 # # 优先选择包含全部指定 `classes` 的图像，其次是包含至少一个 # 指定 `classes` 的图像。如果该分割中满足 `classes` 条件的图像 # 不足以达到 `max_samples`，则只加载可用的图像。 # # 图像仅在必要时才会被下载 # fiftyone zoo datasets load sama-coco \ --split validation \ --kwargs \ label_types=segmentations \ classes=cat,dog \ max_samples=25 fiftyone app launch sama-coco-validation-25 # # 下载整个 validation 分割，同时加载 detections 与 segmentations # # 此后对 validation 分割的任何局部加载都不再需要下载任何图像 # fiftyone zoo datasets load sama-coco \ --split validation \ --kwargs \ label_types=detections,segmentations fiftyone app launch sama-coco-validation

注意 CLI 中列表参数（如label_types、classes）使用逗号分隔书写，例如label_types=detections,segmentations。

局部下载的源码级原理

理解下面几个 fiftyone/utils/coco.py 中的内部函数，就能准确把握局部下载的行为：

• _get_existing_ids()（约 L1895）：比对data/目录下已存在的文件名与目标 ID 集合，将 ID 分为"已存在"与"待下载"两组，实现已有数据零重复下载；
• _get_images_with_classes()（约 L1938）：按类别过滤图像，返回all_ids（包含全部指定类别的图像）与any_ids（仅包含至少一个指定类别的图像）两个列表，这正是max_samples优先级语义的实现基础——下载顺序为all_ids在前、any_ids在后；
• _download_images()（约 L1909）：调用recommend_thread_pool_workers()计算线程池规模，通过multiprocessing.dummy.Pool并行下载单张图像，并带有ProgressBar进度反馈；
• _parse_image_ids()（约 L1972）：解析image_ids的三种输入形式并校验 ID 合法性（详见上文）。

此外，fiftyone/utils/sama.py 中还有一个值得注意的细节：当split == "test"时，即使传入classes，代码也会警告"Test split is unlabeled; ignoring classes requirement"并自动忽略类别过滤——因为 test 分割没有标注，无法按类别筛选。

注意事项与最佳实践

1. 类别体系：Sama-COCO 定义 91 类但实际仅使用 80 类，与 COCO-2017 的 80 类一致；classes参数必须使用这 80 个类别名，传入不支持的类别会抛出ValueError: Unsupported classes。
2. test 分割无标注：test 只用于推理/提交评测，无法按classes、label_types过滤。
3. 无标注图像：train/validation 中部分图像没有标注，按类别过滤或统计样本数时需留意实际可用的标注样本量。
4. 增量复用：建议先完整下载某个分割（如 validation），再做各种局部实验，之后所有局部加载均无需重新下载图像；完整标注文件会被缓存到raw目录，避免重复下载。
5. 对比实验友好：由于 Sama-COCO 与 COCO-2017 使用完全相同的图像与分割，可以直接用同一组图像对比"原始 COCO 标注 vs Sama 精细标注"对模型性能的影响。
6. 进一步阅读：load_zoo_dataset()的全部可选关键字参数说明，可参见 SamaCOCODataset 的类文档与 COCODetectionDatasetImporter 的导入器文档；下载实现的完整源码位于 fiftyone/utils/sama.py，类别过滤、ID 解析与并行下载的辅助逻辑位于 fiftyone/utils/coco.py。

【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone