数据集和数据集版本

ClearML Enterprise的数据集和数据集版本提供了内部数据结构和功能，用于以下目的：

• 将源数据连接到ClearML Enterprise平台
• 使用ClearML Enterprise的类似Git的数据集版本控制
• 将Dataviews的强大功能与实验相结合
• 注释 图片和视频

数据集由包含SingleFrames和/或FrameGroups的版本组成。每个数据集可以包含多个版本，这些版本可以有多个继承其父版本内容的子版本。

掩码标签在数据集版本级别定义，并应用于数据集版本中的所有掩码。

示例数据集​

ClearML Enterprise 提供了完整的示例数据集，包括帧，并准备好供您进行实验。您可以在 ClearML Enterprise WebApp (UI) 中找到这些示例数据集。它们在 WebApp (UI) 中会显示一个“示例”横幅。

用法​

创建数据集​

使用Dataset.create方法来创建一个数据集。它将包含一个名为Current的空版本。

from allegroai import Dataset

myDataset = Dataset.create(dataset_name='myDataset')

或者，使用DatasetVersion.create_new_dataset方法。

from allegroai import DatasetVersion

myDataset = DatasetVersion.create_new_dataset(dataset_name='myDataset Two')

创建数据集时，您可以将其放入项目中。在这种情况下，数据集将遵循为其所在项目指定的访问规则。使用dataset_project参数在Dataset.create或DatasetVersion.create_new_dataset中指定项目名称。

myDataset_1 = Dataset.create(dataset_name="myDataset", dataset_project="myDataset Project")

myDataset_2 = DatasetVersion.create_new_dataset(
  dataset_name="myDataset_2", dataset_project="myDatasetProject_2"
)

如果数据集存在，要引发ValueError异常，请将raise_if_exists参数指定为True。

• 使用 Dataset.create:

  try:
      myDataset = Dataset.create(dataset_name='myDataset One', raise_if_exists=True)
  except ValueError:
      print('Dataset exists.')
  

• 或者使用 DatasetVersion.create_new_dataset：

  try:
      myDataset = DatasetVersion.create_new_dataset(dataset_name='myDataset Two', raise_if_exists=True)
  except ValueError:
      print('Dataset exists.')
  

此外，创建一个带有标签和描述的数据集。

myDataset = DatasetVersion.create_new_dataset(
  dataset_name='myDataset', 
  tags=['One Tag', 'Another Tag', 'And one more tag'], 
  description='some description text'
)

访问当前数据集​

要获取当前的数据集，请使用DatasetVersion.get_current方法。

myDataset = DatasetVersion.get_current(dataset_name='myDataset')

删除数据集​

使用Dataset.delete类方法来删除一个数据集：

• 删除一个空的数据集（无版本）：

  Dataset.delete(dataset_name='MyDataset', delete_all_versions=False, force=False)
  

• 删除一个仅包含状态为草稿版本的数据集：

  Dataset.delete(dataset_name='MyDataset', delete_all_versions=True, force=False)
  

• 删除一个数据集，即使它包含状态为已发布的版本：

  Dataset.delete(dataset_name='MyDataset', delete_all_versions=True, force=True)
  

• 删除一个数据集及其删除帧关联的源：

  Dataset.delete(
    dataset_name='MyDataset', delete_all_versions=True, force=True, delete_sources=True
  )
  

  这支持删除位于AWS S3、GCP和Azure存储（非本地存储）中的源。如果delete_all_versions为False，则忽略delete_sources参数。您可以通过传递show_progress=True（需要tqdm）来查看删除过程的进度。

标记数据集​

可以为数据集添加标签，以便轻松识别和分组实验。

向数据集添加标签：

MyDataset.add_tags(["coco", "dogs"])

从数据集中移除标签：

MyDataset.remove_tags(["dogs"])

数据集版本控制​

数据集版本控制是指ClearML企业版SDK和WebApp（UI）中用于创建、修改和删除数据集版本的功能组。

ClearML Enterprise 支持简单和高级的数据集版本控制范式。一个简单版本结构由单个不断演进的版本组成，包含历史静态快照。持续将您的更改推送到您的单一数据集版本，并拍摄快照以记录特定时间点的数据集内容。

或者，您可以使用任何高级结构，其中每个版本并行发展，您可以控制哪些版本被锁定以进行进一步更改，哪些可以修改。详情请参见下方。

数据集版本状态​

数据集版本可以是草稿或已发布状态。

一个草稿版本是可编辑的，因此可以添加、删除和/或修改帧。

一个已发布的版本是只读的，这确保了实验的可重复性并保留了数据集版本的内容。 子版本只能从已发布的版本创建，因为它们继承了其前身版本的内容。

数据集版本结构​

为了实现一个简单的版本结构，其中数据集不断演变，具有一系列历史快照，父版本可以有一个且仅有一个子版本，数据集版本树中的最后一个子版本处于草稿状态。不同的版本结构，例如至少有一个父版本有多个子版本，或者数据集版本树中唯一的最后一个子版本是已发布的，被认为是高级版本结构。

有关以编程方式实现简单和高级版本结构的详细信息，请分别参见下面的创建快照和创建子版本。

数据集版本使用​

使用ClearML企业版SDK中的DatasetVersion类管理数据集版本控制。

创建快照​

如果数据集仅包含一个状态为草稿的版本，则可以创建当前版本的快照。 创建快照时，当前版本变为快照（它保留相同的版本ID）， 而新创建的版本（带有其新的版本ID）成为当前版本。

要创建快照，请使用 DatasetVersion.create_snapshot 方法。

快照命名​

在简单的版本结构中，ClearML Enterprise 支持两种快照命名方法：

• 时间戳命名 - 如果只提供了数据集名称或ID，快照将被命名为snapshot，并附加一个时间戳。
  时间戳格式为ISO 8601（YYYY-MM-DDTHH:mm:ss.SSSSSS）。例如，snapshot 2020-03-26T16:55:38.441671。

  示例：

  from allegroai import DatasetVersion
  
  myDataset = DatasetVersion.create_snapshot(dataset_name='MyDataset')
  

  上述语句运行后，先前的当前版本保留其现有的版本ID，并成为一个带有时间戳附加的名为snapshot的快照。新创建的版本具有新的版本ID，成为当前版本，其名称为Current。

• 用户指定的快照命名 - 如果提供了publish_name参数，它将成为快照的名称。

  示例：

  myDataset = DatasetVersion.create_snapshot(dataset_name='MyDataset', publish_name='NewSnapshotName')
  

  在上述语句运行后，之前的当前版本保留其现有的版本ID，并成为一个名为NewSnapshotName的快照。 新创建的版本（带有新的版本ID）成为当前版本，其名称为Current。

当前版本命名​

在简单的版本结构中，ClearML Enterprise 支持两种当前版本命名的方法：

• 默认命名 - 如果未提供child_name参数，Current是当前版本名称。
• 用户指定的当前版本命名 - 如果提供了child_name参数，则该子名称将成为当前版本名称。

例如，在运行以下语句后，之前的当前版本保留其现有的版本ID，并成为一个名为snapshot的快照，并附加时间戳。 新创建的版本（带有新的版本ID）是当前版本，其名称为NewCurrentVersionName。

myDataset = DatasetVersion.create_snapshot(
  dataset_name='MyDataset', 
  child_name='NewCurrentVersionName'
)

添加元数据和注释​

向快照添加元数据字典和/或注释。

例如：

myDataset = DatasetVersion.create_snapshot(
  dataset_name='MyDataset',
  child_metadata={'abc':'1234','def':'5678'}, 
  child_comment='some text comment'
)

创建子版本​

从状态为已发布的任何版本创建新版本。

要创建新版本，请调用DatasetVersion.create_version方法，并提供：

• Dataset name or ID
• 子版本继承帧的父版本名称或ID
• Name of the new version.

例如，从现有版本PublishedVersion创建一个名为NewChildVersion的新版本，其中新版本继承了现有版本的框架。如果NewChildVersion已经存在，则返回该版本。

myVersion = DatasetVersion.create_version(
  dataset_name='MyDataset',
  parent_version_names=['PublishedVersion'], 
  version_name='NewChildVersion'
)

如果NewChildVersion存在，要引发ValueError异常，请将raise_if_exists设置为True。

myVersion = DatasetVersion.create_version(
  dataset_name='MyDataset',
  parent_version_names=['PublishedVersion'], 
  version_name='NewChildVersion',
  raise_if_exists=True
)

创建根级父版本​

在根级别创建一个新版本。这是一个没有父级的版本，并且它不包含任何框架。

myDataset = DatasetVersion.create_version(
  dataset_name='MyDataset', 
  version_name='NewRootVersion'
)

获取版本​

要获取一个或多个版本，请分别使用DatasetVersion.get_version 和DatasetVersion.get_versions 方法。

获取所有版本的列表

myDatasetversion = DatasetVersion.get_versions(dataset_name='MyDataset')

获取所有已发布版本的列表

myDatasetversion = DatasetVersion.get_versions(
  dataset_name='MyDataset', 
  only_published=True
)

获取所有草稿版本的列表

myDatasetversion = DatasetVersion.get_versions(
  dataset_name='MyDataset', 
  only_draft=True
)

获取当前版本

如果存在多个版本，ClearML Enterprise 会输出警告。

myDatasetversion = DatasetVersion.get_version(dataset_name='MyDataset')

获取特定版本

myDatasetversion = DatasetVersion.get_version(
  dataset_name='MyDataset', 
  version_name='VersionName'
)

删除版本​

使用Dataset.delete_version方法删除状态为草稿的版本。

from allegroai import Dataset

myDataset = Dataset.get(dataset_name='MyDataset')
myDataset.delete_version(version_name='VersionToDelete')

发布版本​

发布（使其只读）状态为草稿的版本，使用DatasetVersion.publish_version方法。如果数据集处于简单版本结构中，这包括当前版本。

myVersion = DatasetVersion.get_version(
  dataset_name='MyDataset', 
  version_name='VersionToPublish'
)

myVersion.publish_version()

管理版本掩码标签​

设置版本掩码标签映射​

为了在数据集版本中可视化掩码，需要将掩码值映射到它们的标签。掩码-标签映射存储在版本的元数据中。

要定义DatasetVersion级别的掩码标签映射，请使用DatasetVersion.set_masks_labels方法，并输入一个以RGB值元组为键和标签列表为值的字典。

from allegroai import DatasetVersion

# Getting a version 
myDatasetversion = DatasetVersion.get_version(dataset_name='MyDataset', 
                                              version_name='VersionName')

# Mapping out colors and labels of masks 
myDatasetversion.set_masks_labels(
    {
      (0, 0, 0): ["background"],
      (1, 1, 1): ["person", "sitting"],
      (2, 2, 2): ["cat"],
    }
)

访问版本掩码-标签映射​

掩码值和标签作为属性存储在数据集版本的元数据中。

mapping = myDatasetversion.get_metadata()['mask_labels']

print(mapping)

这应该返回一个包含版本掩码和标签的字典，它应该看起来像这样：

{'_all_': [{'value': [0, 0, 0], 'labels': ['background']}, {'value': [1, 1, 1], 'labels': ['person', 'sitting']}, {'value': [2, 2, 2], 'labels': ['cat']}]}