企业官网建设流程全解析

• MLOps
• LLMOps
• 人工智能

摘要

ClearML 提供了一整套数据集管理与版本化解决方案，其中clearml-data命令行工具让数据科学家和工程师能够通过简单的命令完成数据集创建、文件添加、上传与版本化。本文基于 examples/datasets/README.md 的官方 CLI 示例，深入剖析从单个文件、文件夹到多父版本合并的完整工作流，并结合仓库源码解释底层实现机制，帮助你快速掌握 ClearML 数据集管理的实战技巧。

适用前提：本文所有命令均基于 ClearML SDK/CLI 的clearml-data子命令。使用前需确保已安装clearml并配置好 ClearML Server（可通过clearml-init完成凭据配置）。

目录

• 安装与环境准备
• 1. 从单个文件创建数据集
• 2. 从文件夹创建数据集
• 3. 一步完成创建与同步（sync 模式）
• 4. 创建带父版本的数据集（Child Dataset）
• 5. 数据集管理核心生命周期
• 6. 结合 Python SDK 的进阶用法
• 7. 版本化与依赖机制的原理
• 8. 数据消费与检索

安装与环境准备

在开始使用clearml-data前，确保在你的环境中安装 ClearML：

$ pip3 install clearml

安装完成后，需要配置 ClearML Server 连接凭据。如果尚未配置，运行clearml-init并按照提示填写你的 API 凭据（API Server、Web Server、File Server 地址及 API Key）。这些凭据将被保存到本地的clearml.conf配置文件中，供所有后续命令使用。

1. 从单个文件创建数据集

最简单的数据集创建方式是从一个文件开始。以 CSV 文件为例：

创建数据集

clearml-data create --project Datasets_Examples_CLI --name Simple_CSV_dataset_CLI

• --project：数据集所属项目名，用于在 ClearML 中归类组织。
• --name：数据集名称（必填）。

执行后，CLI 会在服务器上注册一个新的数据集任务（Task），并在控制台输出该数据集的 ID（形如New dataset created id=xxxx）。

添加文件

clearml-data add --files YOUR_CSV_DATASET.csv

add子命令支持以下参数（详见 clearml/cli/data/main.py）：

add_files会计算每个文件的哈希并与父版本比较，标记需要上传的文件（参见 clearml/datasets/dataset.py）。未指定--id时，命令会通过 restore_state 自动从本地状态文件恢复上一次使用的数据集 ID，实现连续操作。

上传并定稿（关闭）

clearml-data close --verbose

close是“定稿（finalize）+ 上传”的联合操作：

• 如果存在待上传的本地文件，会自动调用Dataset.upload()上传；
• 上传完成后调用Dataset.finalize()关闭数据集，之后不可再修改；
• --verbose输出详细的处理过程。

注意：只有close（或finalize）后的数据集才被视为**完成（completed）**版本，可以被其他数据集继承或下载使用。

2. 从文件夹创建数据集

当数据由整个文件夹组成时，流程与单个文件类似：

clearml-data create --project Datasets_Examples_CLI --name Datset_From_Folder_CLI clearml-data add --files ./YOUR_DATASET_FOLDER clearml-data close --verbose

add --files指定文件夹路径时，默认递归扫描其下所有文件并加入数据集。可以通过--non-recursive关闭递归，或通过--wildcard '*.jpg'之类的通配符只添加特定类型的文件。

3. 一步完成创建与同步（sync 模式）

如果目录结构已经组织好，可以直接使用sync子命令，一条命令完成创建、添加、上传、定稿：

clearml-data sync --folder ./DATA/MNIST/TRAIN --project Datasets_Examples_CLI --name MNIST_training_dataset_CLI

sync会将本地文件夹与数据集双向同步：

• 计算本地文件夹与数据集已有文件之间的差异；
• 新增文件 → 添加；删除的文件 → 移除；内容变化的文件 → 标记为修改；
• 同步完成后自动上传并定稿数据集。

从源码看，ds_sync在检测到--project和--name时先创建数据集，然后调用 sync_folder，它先移除数据集中已不存在于本地文件夹的文件，再以递归方式添加本地文件，最后自动upload()与finalize()（参见 clearml/cli/data/main.py）。

sync的其他常用参数：

4. 创建带父版本的数据集（Child Dataset）

ClearML 数据集支持版本化继承：新数据集可以指定一个或多个父数据集，继承其全部文件并在此基础上增量修改。这非常适合“训练集 + 测试集 → 完整数据集”的场景。

步骤 1：分别创建训练集与测试集

clearml-data sync --folder ./YOUR_DATASET/TRAIN --project Datasets_Examples_CLI --name MNIST_training_dataset_CLI_2 clearml-data sync --folder ./YOUR_DATASET/TEST --project Datasets_Examples_CLI --name MNIST_testing_dataset_CLI_2

两条命令分别创建两个已完成（finalized）的数据集版本，执行时注意记录输出的数据集 ID。

步骤 2：创建子数据集（合并父版本）

clearml-data create --project Datasets_Examples_CLI --name MNIST_complete_dataset_CLI_2 --parents ID_OF_TRAIN_DATASET ID_OF_TEST_DATASET clearml-data close --verbose

--parents支持多个数据集 ID，含义是“合并所有父版本”。合并规则（见 Dataset.create 源码）：

• 父数据集按传入顺序合并，后一个父版本中的同名文件会覆盖前一个；
• 数据集继承父版本全部文件，无需重新上传，只上传新增/修改的部分；
• 要求父数据集必须已处于 finalized/closed 状态（源码中显式校验is_final()，否则抛出ValueError）。

之后执行clearml-data close --verbose将合并结果定稿，完成子数据集的发布。

5. 数据集管理核心生命周期

一个数据集从创建到可被消费，经历以下状态流转：

create（创建/草稿） ↓ add / sync（添加文件，处于 dirty 状态） upload（上传到存储） ↓ close / finalize（定稿，状态变为 completed） ↓ publish（可选，公开发布） ↓ get（消费：下载本地副本）

对应的clearml-data子命令还包括：

大部分命令都支持--id指定数据集 ID；不指定时默认使用上一次创建/访问的数据集（状态保存在~/.clearml_data.json）。

6. 结合 Python SDK 的进阶用法

CLI 命令在底层都映射到clearml.datasets.Dataset类的 Python API（入口见 clearml/datasets/init.py）。你可以在脚本中直接使用同样的能力，实现数据集的程序化创建与管理。

创建 CSV 数据集（对应示例 csv_dataset_creation.py）

from clearml import StorageManager, Dataset manager = StorageManager() # 下载远程 CSV 文件到本地 csv_file_path = manager.get_local_copy( remote_url="https://allegro-datasets.s3.amazonaws.com/datasets/Iris_Species.csv" ) # 创建数据集（默认上传到 ClearML fileserver） simple_dataset = Dataset.create(dataset_project="dataset_examples", dataset_name="CSV_Dataset") # 添加文件 simple_dataset.add_files(path=csv_file_path) # 上传并定稿 simple_dataset.upload() simple_dataset.finalize()

Dataset.create()支持output_uri参数指定自定义存储（如s3://bucket/data、gs://bucket/data、azure://bucket/data、本地共享目录），默认使用 ClearML 自带的文件服务器（files_server）。

创建带单父版本的数据集（对应示例 single_parent_child_dataset.py）

from pathlib2 import Path from clearml import Dataset, StorageManager manager = StorageManager() mnist_dataset = Path( manager.get_local_copy(remote_url="https://allegro-datasets.s3.amazonaws.com/datasets/MNIST.zip", name="MNIST") ) # 训练数据集 train_dataset = Dataset.create(dataset_project="dataset_examples", dataset_name="MNIST Training Dataset") train_dataset.add_files(path=mnist_dataset / "TRAIN", dataset_path="TRAIN") train_dataset.upload() train_dataset.finalize() # 子数据集：继承 train_dataset，并追加 TEST 数据 child_dataset = Dataset.create( dataset_project="dataset_examples", dataset_name="MNIST Complete Dataset", parent_datasets=[train_dataset.id] ) child_dataset.add_files(path=mnist_dataset / "TEST", dataset_path="TEST") child_dataset.upload() child_dataset.finalize()

创建多父版本数据集（对应示例 multi_parent_child_dataset.py）

train_dataset = Dataset.create(dataset_project="dataset_examples/MNIST", dataset_name="MNIST Training Dataset") train_dataset.add_files(path=mnist_dataset_train, dataset_path="TRAIN") train_dataset.upload(); train_dataset.finalize() test_dataset = Dataset.create(dataset_project="dataset_examples/MNIST", dataset_name="MNIST Testing Dataset") test_dataset.add_files(path=mnist_dataset_test, dataset_path="TEST") test_dataset.upload(); test_dataset.finalize() # 合并两个父版本（train 在前，test 在后） child_dataset = Dataset.create( dataset_project="dataset_examples/MNIST", dataset_name="MNIST Complete Dataset", parent_datasets=[train_dataset.id, test_dataset.id], ) child_dataset.upload(); child_dataset.finalize()

文件夹同步（对应示例 dataset_folder_syncing.py）

mnist_dataset = Dataset.create( dataset_project="dataset_examples", dataset_name="MNIST Complete Dataset (Syncing Example)" ) # 将 TRAIN 数据拷入本地目录并同步 shutil.copytree(mnist_dataset_train, mnist_train_path) mnist_dataset.sync_folder(mnist_path) mnist_dataset.upload() # 将 TEST 数据拷入本地目录并再次同步 shutil.copytree(mnist_dataset_train, mnist_test_path) mnist_dataset.sync_folder(mnist_path) mnist_dataset.upload() mnist_dataset.finalize()

sync_folder是增量同步的利器：它对比本地文件夹与数据集内容，自动移除已删除的文件、添加新文件、标记内容变化的文件（返回removed, added, modified三个计数），非常适合持续更新的数据管线。

7. 版本化与依赖机制的原理

从源码层面看（clearml/datasets/dataset.py），ClearML 数据集本质上是带系统标签的Task（任务），每个数据集版本对应服务器上的一个任务记录：

• 文件条目（FileEntry）：记录每个文件的相对路径、SHA-256 哈希、大小以及其来源父数据集 ID（见 FileEntry 定义）。通过哈希比较实现“未修改文件无需重复上传”的去重逻辑；
• 依赖图（dependency_graph）：记录当前版本与父版本的继承关系，Dataset.create(parent_datasets=...)时构建，支持多层级的版本链；
• 增量存储：子版本只上传自身新增/修改的文件分块（chunk），旧文件直接从父版本继承引用，从而极大节省存储与带宽。

因此当你执行clearml-data get下载某个子数据集时，SDK 会依据依赖图递归合并所有父版本的文件，得到完整的数据副本（默认使用软链接指向缓存目录，节省磁盘空间）。

8. 数据消费与检索

在训练脚本中消费数据集

数据集定稿后即可在任意脚本中拉取使用（参考 data_ingestion.py）：

from clearml import Dataset # 按名称/项目获取数据集（需已定稿/关闭） dataset_path = Dataset.get( dataset_name="cifar_dataset", dataset_project="dataset_examples", only_completed=False ).get_local_copy() # dataset_path 即为数据在本地的根目录，可直接用于 DataLoader 等

Dataset.get()支持按 ID、按名称+项目、按名称/项目+版本号定位；get_local_copy()返回只读缓存副本（默认软链接），get_mutable_local_copy(target_folder)则返回可写的独立副本。

检索与对比

# 按项目/名称搜索数据集 clearml-data search --project Datasets_Examples_CLI # 列出某数据集内容 clearml-data list --id <dataset_id> # 对比两个版本差异（target vs source 基线） clearml-data compare --source <source_id> --target <target_id>

compare会输出 新增/修改/删除 三类文件的统计与明细（--verbose查看全部变更列表），便于在数据版本升级后评估影响面。

通过本文的 4 个 CLI 场景（单文件、文件夹、一键 sync、多父合并）以及对应的 Python SDK 等价实现，你可以完整掌握 ClearML 数据集创建、版本继承、增量上传与消费的全链路。更完整的可运行示例（含 CIFAR 数据集创建、音频预处理等）请参考仓库 examples/datasets 目录，例如 dataset_creation.py 与 urbansounds_dataset_preprocessing.py。

• MLOps
• LLMOps
• 人工智能