ClearML 数据 SDK

可以使用ClearML Data的python接口创建、修改和管理数据集。您可以通过设置数据集的上传目的地（参见output_url参数的Dataset.upload()）将数据集上传到您选择的任何存储服务（S3 / GS / Azure / 网络存储）。一旦您上传了数据集，您就可以从任何机器访问它。

以下页面概述了如何使用Dataset类的最基本方法。有关可用方法的完整列表，请参阅Dataset参考页面。

导入Dataset类，让我们开始吧！

from clearml import Dataset

创建数据集​

ClearML 数据支持多种编程方式创建数据集，适用于各种用例：

• Dataset.create() - 创建一个新的数据集。可以指定父数据集，新数据集将从父数据集继承其数据
• Dataset.squash() - 通过将一组相关数据集压缩在一起生成一个新的数据集

您可以使用Dataset.set_metadata()向您的数据集添加元数据， 并使用Dataset.get_metadata()访问这些元数据。

Dataset.create()​

使用Dataset.create类方法来创建一个数据集。

以编程方式创建数据集在预处理数据时特别有帮助，这样预处理代码和生成的数据集可以保存在一个任务中（参见Dataset.create中的use_current_task参数）。

# Preprocessing code here
dataset = Dataset.create(
  dataset_name='dataset name',
  dataset_project='dataset project', 
  parent_datasets=[PARENT_DS_ID_1, PARENT_DS_ID_2],
  dataset_version="1.0",
  output_uri="gs://bucket-name/folder",
  description='my dataset description'
)

使用output_uri参数指定一个网络存储目标，用于上传数据集文件及相关信息（如预览）。例如：

• 一个共享文件夹：/mnt/share/folder
• S3: s3://bucket/folder
• 非AWS S3类似服务（如MinIO）：s3://host_addr:port/bucket
• Google Cloud Storage: gs://bucket-name/folder
• Azure 存储: azure://.blob.core.windows.net/path/to/file

默认情况下，数据集会上传到ClearML的文件服务器。Dataset.upload()的output_uri参数会覆盖此参数的值。

创建的数据集继承了parent_datasets的内容。当列出多个数据集父项时，它们按指定的顺序合并。每个父项会覆盖之前父项数据集中的任何重叠文件。

Dataset.squash()​

为了提高深度数据集DAG存储和速度，引入了数据集压缩。 Dataset.squash 类方法通过压缩一组数据集版本来生成一个新的数据集，并合并其谱系DAG中引入的所有更改，创建一个新的、扁平的、独立的版本。

可以通过ID或项目和名称对来指定要压缩到单个数据集中的数据集。

# option 1 - list dataset IDs
squashed_dataset_1 = Dataset.squash(
  dataset_name='squashed dataset\'s name',
  dataset_ids=[DS1_ID, DS2_ID, DS3_ID]
)

# option 2 - list project and dataset pairs 
squashed_dataset_2 = Dataset.squash(
  dataset_name='squashed dataset 2',
  dataset_project_name_pairs=[('dataset1 project', 'dataset1 name'), 
                              ('dataset2 project', 'dataset2 name')]
)

此外，可以使用Dataset.squash()的output_uri参数指定压缩数据集的目标存储位置。

访问数据集​

一旦数据集被创建并上传到服务器，就可以从任何地方以编程方式访问该数据集。

使用Dataset.get类方法通过提供数据集的以下任一属性来访问特定的数据集对象：数据集ID、项目、名称、标签和/或版本。如果多个数据集匹配查询，则返回最近的一个。

dataset = Dataset.get(
        dataset_id=None,  
        dataset_project="Example Project",
        dataset_name="Example Dataset",
        dataset_tags="my tag",
        dataset_version="1.2",
        only_completed=True, 
        only_published=False, 
)

传递 auto_create=True，如果没有数据集匹配查询，将根据输入属性（项目名称、数据集名称和标签）动态创建一个数据集。

在任务中使用数据集的情况下（例如消费数据集），您可以将数据集的ID存储在任务的超参数中：传递alias=，使用数据集的任务将数据集的ID存储在Datasets超参数部分下的dataset_alias_string参数中。这样，您可以轻松跟踪任务正在使用的数据集。如果您使用alias并设置overridable=True，您可以从UI的配置 > 超参数 > Datasets部分覆盖数据集ID，从而允许您在远程运行任务时更改使用的数据集。

如果你想获取一个可修改的数据集，你可以通过传递writable_copy=True来获取一个新创建的可变数据集，该数据集以当前数据集作为其父数据集。

一旦获得了特定的数据集对象，使用以下选项之一获取数据集的本地副本：

• Dataset.get_local_copy() - 获取整个数据集的只读本地副本。 此方法返回本地缓存中数据集的路径（如果数据集尚未在缓存中，则下载数据集）。

• Dataset.get_mutable_local_copy() - 获取整个数据集的可写本地副本。此方法将数据集下载到指定的文件夹（非缓存），通过target_folder参数指定。如果指定的文件夹已经有内容，使用overwrite参数指定是否用数据集内容覆盖其内容。

  注意

  Dataset.get_mutable_local_copy() 最初会将本地副本下载到缓存目录中，然后将其移动到 target_folder 中指定的位置。如果默认的缓存目录没有足够的磁盘空间，你可以通过设置 CLEARML_CACHE_DIR 环境变量来更改目录。

ClearML 支持并行下载数据集。使用 Dataset.get_local_copy 或 Dataset.get_mutable_local_copy 方法的 max_workers 参数来指定下载数据集时要使用的线程数。默认情况下，它是您机器的逻辑核心数。

修改数据集​

一旦创建了数据集，其内容可以被修改和替换。当您的数据发生变化时，您可以添加更新的文件或删除不必要的文件。

add_files()​

要将本地文件或文件夹添加到当前数据集中，请使用Dataset.add_files方法。

如果文件已经在数据集中，但已被修改，可以再次添加，ClearML 将上传文件的差异。

dataset = Dataset.create(dataset_name="my dataset", dataset_project="example project")
dataset.add_files(path="path/to/folder_or_file")

您可以使用wildcard参数基于单个字符串或字符串列表的通配符匹配来添加一组文件。使用recursive参数指定是否递归匹配通配符文件。

例如：

dataset.add_files(
  path="path/to/folder",
  wildcard="~/data/*.jpg",
  recursive=True
)

add_external_files()​

要将文件或文件夹添加到当前数据集中，同时保留它们在原始位置，请使用Dataset.add_external_files方法。输入source_url参数，该参数可以是来自云存储（s3://、gs://、azure://）或本地/网络存储（file://）的链接或链接列表。

dataset = Dataset.create(dataset_name="my dataset", dataset_project="example project")
dataset.add_external_files(
  source_url="s3://my/bucket/path_to_folder_or_file", 
  dataset_path="/my_dataset/new_folder/"
)
dataset.add_external_files(
  source_url=[
    "s3://my/bucket/path_to_folder_or_file",
    "s3://my/bucket/path_to_another_folder_or_file", 
  ],
  dataset_path="/my_dataset/new_folder/"
)

您可以使用wildcard参数基于单个字符串或通配符列表的通配符匹配来添加一组文件。使用recursive参数指定是否递归匹配通配符文件。

# Add all jpg files located in s3 bucket called "my_bucket" to the dataset:
dataset.add_external_files(
  source_url="s3://my/bucket/", 
  wildcard = "*.jpg",
  dataset_path="/my_dataset/new_folder/"
)

remove_files()​

要从当前数据集中删除文件，请使用Dataset.remove_files()。 在dataset_path参数中输入要删除的文件夹或文件的路径。该路径是相对于数据集的。 要删除链接，请指定它们的URL（例如，s3://bucket/file）。

你也可以在dataset_path中输入通配符来删除一组匹配通配符的文件。 将recursive参数设置为True以递归匹配所有通配符文件

例如：

dataset.remove_files(dataset_path="*.csv", recursive=True)

数据集预览​

向数据集中添加信息性指标、图表或媒体。使用Dataset.get_logger()访问数据集的日志记录器对象，然后使用Logger对象提供的方法向数据集中添加任何附加信息。

您可以添加一些数据集摘要（如表格报告）以创建数据存储的预览，以便更好地查看，或附加数据摄取过程中生成的任何统计信息。

例如：

# Attach a table to the dataset
dataset.get_logger().report_table(
    title="Raw Dataset Metadata", series="Raw Dataset Metadata", csv="path/to/csv"
)

# Attach a historgram to the table
dataset.get_logger().report_histogram(
    title="Class distribution",
    series="Class distribution",
    values=histogram_data,
    iteration=0,
    xlabels=histogram_data.index.tolist(),
    yaxis="Number of samples",
)

上传文件​

要将数据集文件上传到网络存储，请使用 Dataset.upload()。

使用 output_url 参数来指定存储目标，例如 S3 / GS / Azure。例如：

• 一个共享文件夹：/mnt/share/folder
• S3: s3://bucket/folder
• 非AWS S3类似服务（如MinIO）：s3://host_addr:port/bucket
• Google Cloud Storage: gs://bucket-name/folder
• Azure 存储: azure://.blob.core.windows.net/path/to/file

默认情况下，数据集会上传到ClearML的文件服务器。此目标存储会覆盖Dataset.create()的output_uri值。

ClearML 支持并行上传数据集。使用 max_workers 参数来指定上传数据集时要使用的线程数。默认情况下，它是您机器的逻辑核心数。

数据集文件必须在数据集最终确定之前上传。

完成数据集​

使用 Dataset.finalize() 来关闭当前的数据集。这会将数据集任务标记为 已完成，此时数据集将无法再进行修改。

在关闭数据集之前，必须先上传其文件。

同步本地存储​

使用Dataset.sync_folder()来根据特定文件夹的内容变化更新数据集。使用local_path参数指定要同步的文件夹（该方法假定文件夹内的所有文件都是递归的）。

这种方法在存在单一真实来源的情况下非常有用，无论是本地文件夹还是网络文件夹，都会定期更新。 文件夹的更改将反映在新的数据集版本中。这种方法节省了时间，因为您不必手动更新（添加/删除）数据集中的文件。

删除数据集​

使用Dataset.delete()类方法删除数据集。输入你想要删除的数据集的任何属性，包括ID、项目名称、版本和/或数据集名称。如果查询匹配多个数据集，将会引发异常，除非你传递entire_dataset=True和force=True。在这种情况下，所有匹配的数据集都将被删除。

如果一个数据集是其他数据集的父数据集，你必须传递force=True才能删除它。

Dataset.delete(
  dataset_id=None,
  dataset_project="example project",
  dataset_name="example dataset", 
  force=False,  
  dataset_version="3.0",
  entire_dataset=False
) 

重命名数据集​

使用Dataset.rename()类方法重命名数据集。所有具有给定dataset_project和dataset_name的数据集将被重命名。

Dataset.rename(
  new_dataset_name="New name",
  dataset_project="Example project", 
  dataset_name="Example dataset",  
)

将数据集移动到另一个项目​

使用Dataset.move_to_project()类方法将数据集移动到另一个项目。所有具有给定dataset_project和dataset_name的数据集将被移动到新的数据集项目。

Dataset.move_to_project(
  new_dataset_project="New project",
  dataset_project="Example project", 
  dataset_name="Example dataset",  
)

离线模式​

您可以在离线模式下处理数据集，其中所有数据和日志都存储在本地会话文件夹中，稍后可以上传到ClearML Server。

您可以通过以下方式之一启用离线模式：

• 在创建数据集之前，使用 Dataset.set_offline() 并将 offline_mode 参数设置为 True：

  from clearml import Dataset
  
  # Use the set_offline class method before creating a Dataset
  Dataset.set_offline(offline_mode=True)
  # Create a dataset
  dataset = Dataset.create(dataset_name="Dataset example", dataset_project="Example project")
  # add files to dataset
  dataset.add_files(path='my_image.jpg')
  

• 在创建数据集之前，设置 CLEARML_OFFLINE_MODE=1

所有数据集的信息都被压缩并保存在本地。

数据集任务的控制台输出显示任务的ID和本地数据集文件夹的路径：

ClearML Task: created new task id=offline-372657bb04444c25a31bc6af86552cc9
...
...
ClearML Task: Offline session stored in /home/user/.clearml/cache/offline/b786845decb14eecadf2be24affc7418.zip

请注意，在离线模式下，任何需要与服务器通信的方法都不会生效（例如 squash()、 finalize()、get_local_copy()、get()、move_to_project() 等）。

使用Dataset.import_offline_session()将离线数据集上传到ClearML服务器。 在session_folder_zip参数中，插入包含数据集的zip文件夹的路径。要上传 数据集的数据到网络存储，将upload设置为True。要完成数据集， 这将关闭它并防止对数据集的进一步修改，将finalize设置为True。

Dataset.import_offline_session(session_folder_zip="<path_to_offline_dataset>", upload=True, finalize=True)