数据集版本

class datasetversion.DatasetVersion()

```DatasetVersion``` 表示数据集中的特定版本。

警告

请勿直接实例化。请改用 DatasetVersion.get_version 方法。

BulkContext

class BulkContext

一个用于批量修改帧（即添加/更新/删除）的上下文管理器。

使用 ```DatasetVersion.get_bulk_context``` 获取。

批量上下文允许逐个添加/更新/删除帧来修改版本，但实际的更新请求将以批量方式发生。更新请求（刷新）将每隔 ```flush_threshold``` 次更新发生一次，或在 ```__exit__``` 时发生。

创建用于自动刷新帧的批量上下文

参数
- dv (DatasetVersion) – 要使用的 DatasetVersion 对象
- flush_threshold (Optional[int]) – 如果提供，则每隔 X 帧刷新一次
- log (Optional[Logger]) – 可选，提供外部日志记录器
- refresh_version_stats (Optional[bool]) – 自动刷新版本统计信息（默认值：True）
- auto_upload_destination (Optional[str]) – 如果指定，SingleFrame/FrameGroup 链接的任何本地文件将自动上传到目标存储。
- local_dataset_root_path (Union [ str , Path ] ) – 如果提供了 ```auto_upload_destination```，则为必需。它应指向所有本地源文件的公共文件夹
- allow_update (bool) – 如果为 False（默认值），所有帧操作将使用“添加”操作，“更新”将不被使用（即，即使使用 BulkContext.update() 调用收集的帧也将被添加，而不是更新）。这是一个高级设置，仅在您理解使用更新的限制时才更改。请注意，使用更新时，提供的帧数据会与现有的索引帧数据合并 - 这意味着在使用更新操作时无法删除帧字段。

add_frame

BulkContext.add_frame(frame, warn_on_duplicate_frames=False)

注意！如果帧已包含 frame.id 字段，它们将更新（覆盖）现有帧。如果未提供，则 frame.id 根据源 URI 生成。如果需要上传本地文件但该文件之前已被上传过，则将重用该文件的现有 URI，否则将上传该文件。

信息

仅在版本仍处于草稿（可写）模式时可用

参数
- frame (DatasetVersion.Frame ) – 要添加到版本的帧。
- warn_on_duplicate_frames (Optional[bool]) – 如果为 True，则在添加具有已添加到此实例的 ID 的帧时发出警告（默认值 False）
返回类型

None

delete_frame

BulkContext.delete_frame(frame, delete_sources=False)

从当前 ```DatasetVersion``` 中删除帧。

帧可以由 ID 字符串或 ```DatasetVersion.Frame``` 对象表示。帧按其 ID 删除，所有其他帧属性（如果存在）将被忽略。

信息

仅在版本仍处于草稿（可写）模式时可用。

参数
- frame (Union[FrameGroup, SingleFrame, str, ForwardRef]) – 要删除的帧（帧对象或 ID 字符串）
- delete_sources (bool) – 删除数据集中与已删除帧相关的源。支持的源位置有：s3、gs 和 azure。如果无法建立与云提供商的连接或源删除失败，操作将中止。
返回类型

None

flush

BulkContext.flush()

发送所有待处理的版本更改。

使用此 ```BulkContext``` 进行的任何更新都将发送到服务器。

返回类型

None

update_frame

BulkContext.update_frame(frame)

更新当前 ```DatasetVersion``` 中的现有帧。

根据帧 ID 找到帧，并将其属性更改为与 frame 中传入的帧对象匹配。如果帧之前已被添加（例如通过 ```update_frame```），或者存在于父版本中，则帧存在于版本中。如果帧对象没有 ID，则创建一个新帧。

信息

仅在版本仍处于草稿（可写）模式时可用。

参数

frame (DatasetVersion.Frame ) – 要更新的帧。
返回类型

None

version_id

property version_id

此特定数据集/版本的版本 ID 字符串

返回类型

str

version_name

property version_name

数据集版本名称，不一定唯一

返回类型

str

dataset_id

property dataset_id

此特定数据集的数据集 ID 字符串

返回类型

str

dataset_name

property dataset_name

数据集名称，必须是唯一的名称

返回类型

str

draft

property draft

数据集/版本的草稿标志，即此版本是否仍可写入或已锁定且无法更改。

返回类型

bool

last_updated

property last_updated

返回数据集版本中最后更新帧的时间戳

返回类型

datetime

comment

property comment

返回特定数据集版本的字符串注释

返回类型

str

DatasetVersion.create_new_dataset

classmethod create_new_dataset(dataset_name=None, description=None, tags=None, raise_if_exists=False, dataset_project=None)

在系统中创建一个新数据集并返回其 ```Dataset``` 对象。

参数
- dataset_name (str ) – 新数据集的名称。
- description (str ) – 描述数据集的自由文本。
- tags (list ) – 用于对数据集进行分类的标签列表（短字符串）。
- raise_if_exists (bool ) – 如果为 False（默认值）且存在名称为 ```dataset_name``` 的数据集，则返回现有 ```Dataset```。如果为 True 且存在名称为 ```dataset_name``` 的数据集，则引发 ```ValueError``` 异常。
- dataset_project (str ) – 新创建数据集的项目名称。
返回类型

数据集
返回

新创建数据集的新 ```Dataset``` 对象。

DatasetVersion.get_current

classmethod get_current(dataset_id=None, dataset_name=None, auto_upload_destination=None, local_dataset_root_path=None, dataset_project=None)

返回数据集当前可写版本的 ```DatasetVersion``` 对象

参数
- dataset_id (str ) – 要检索的版本所属数据集的 ID。
- dataset_name (str ) – 要检索的版本所属数据集的名称。
- auto_upload_destination (str ) – 如果指定，SingleFrame/FrameGroup 链接的任何本地文件将自动上传到目标存储。
- local_dataset_root_path (Union [ str , Path ] ) – 如果提供了 ```auto_upload_destination```，则为必需。它应指向所有本地源文件的公共文件夹
- dataset_project (Optional[str]) – 要检索的数据集所属的项目。
返回类型

ForwardRef
返回

表示所选版本的 ```DatasetVersion``` 对象。

信息

dataset_id 和 dataset_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

DatasetVersion.remove_version

classmethod remove_version(dataset_id=None, dataset_name=None, version_id=None, version_name=None, force=False, dataset_project=None)

从系统中移除数据集的版本。

信息

dataset_id 和 dataset_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

信息

version_id 和 version_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

参数
- dataset_id (str ) – 要移除的数据集的 ID。
- dataset_name (str ) – 要移除的数据集的名称。
- version_id (str ) – 要移除的版本 ID。
- version_name (str ) – 要移除的版本名称。
- force (bool ) – 如果 ```True```，即使版本已发布也删除。默认值：```False```
- dataset_project (str ) – 要移除的数据集所属的项目。
返回类型

None

DatasetVersion.get_version

classmethod get_version(dataset_id=None, dataset_name=None, version_id=None, version_name=None, auto_upload_destination=None, local_dataset_root_path=None, raise_on_multiple=False, dataset_project=None)

返回特定版本的 ```DatasetVersion``` 对象

信息

如果未提供版本名称/ID，则返回数据集的当前版本。

信息

dataset_id 和 dataset_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

参数
- dataset_id (str ) – 要检索的版本所属数据集的 ID。
- dataset_name (str ) – 要检索的版本所属数据集的名称。
- version_id (str ) – [可选] 要检索的版本 ID。
- version_name (str ) – [可选] 要检索的版本名称。
- auto_upload_destination (str ) – 如果指定，SingleFrame/FrameGroup 链接的任何本地文件将自动上传到目标存储。
- local_dataset_root_path (Union [ str , Path ] ) – 如果提供了 ```auto_upload_destination```，则为必需。它应指向所有本地源文件的公共文件夹
- raise_on_multiple (bool ) – 如果找到多个版本，则引发错误
- dataset_project (str ) – 要检索的版本所属数据集的项目。
返回类型

ForwardRef
返回

表示所选版本的 ```DatasetVersion``` 对象。

DatasetVersion.get_single_frame

classmethod get_single_frame(frame_id, dataset_id=None, dataset_name=None, version_id=None, version_name=None, dataset_project=None)

从特定数据集版本中返回具有请求的 frame_id (UUID) 的 ```SingleFrame``` / ```FrameGroup``` 对象

参数
- frame_id (str ) – 请求的帧 ID 的 UUID
- dataset_id (str ) – 要检索的版本所属数据集的 ID。
- dataset_name (str ) – 要检索的版本所属数据集的名称。
- version_id (str ) – 要检索的版本 ID。
- version_name (str ) – 要检索的版本名称。
- dataset_project (str ) – 要检索的版本所属数据集的项目。
返回类型

Union[FrameGroup, SingleFrame]
返回

表示请求帧的 SingleFrame / FrameGroup 对象

信息

dataset_id 和 dataset_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

DatasetVersion.get_frames_by_source

classmethod get_frames_by_source(source_uri, dataset_id=None, dataset_name=None, version_id=None, version_name=None, dataset_project=None)

从特定数据集版本中返回具有请求的 source_uri 模式的 ```SingleFrame``` / ```FrameGroup``` 对象列表

参数
- source_uri (str ) – 源 uri 匹配模式。示例：‘/home/folder/’ 或 ‘/folder/*’ 或 ‘https://domain.com/folder/*’ 或 ‘s3://bucket/folder/*’ 等。
- dataset_id (str ) – 要检索的版本所属数据集的 ID。
- dataset_name (str ) – 要检索的版本所属数据集的名称。
- version_id (str ) – 要检索的版本 ID。
- version_name (str ) – 要检索的版本名称。
- dataset_project (str ) – 要检索的版本所属数据集的项目。
返回类型

List[Union[SingleFrame, FrameGroup]]
返回

表示请求帧的 SingleFrame / FrameGroup 对象列表

信息

dataset_id 和 dataset_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

DatasetVersion.get_frames_by_ids

classmethod get_frames_by_ids(frame_ids, projection=None, dataset_id=None, dataset_name=None, version_id=None, version_name=None, dataset_project=None)

从特定数据集版本中返回具有请求的帧 ID 的 ```SingleFrame``` / ```FrameGroup``` 对象列表

信息

从版本 3.8 开始，调用 DatasetVersion.get_frames_by_ids 已被弃用，并将在 2023 年第四季度被实例方法调用 dataset_version.get_frames_by_ids 取代。

参数
- frame_ids (Collection[str]) – 帧 ID 字符串集合。
- projection (Optional[Collection[str]]) – 用于选择要返回的帧的哪些部分。每个字符串代表一个字段或子字段（使用点分隔表示法）。要指定特定的数组元素，请使用数组索引作为字段名。要指定所有数组元素，请使用“*”。要查看投影支持的字段，请参阅 backend_api.services.frames.Frame 的模式。如果设置了此参数，迭代器返回的值将是表示每个帧的字典
例如
```
dataview.get_iterator(projection=['id', 'dataset.id', 'sources'])
# will return an iterator that yields dictionaries with the following fields:
#  {
#    'id': '514504adbb6a91620eefa3e21ecfcc31',
#    'dataset': {
#      'id': 'df3638ec95454589bf86ba97f344f697'
#    },
#    'sources': [
#      {
#        'id': 'Frame',
#        'uri': 'https://clearml-public.s3.amazonaws.com/datasets/food_dataset/pizza/3724187.jpg',
#        'timestamp': 0,
#        'preview': {
#          'uri': 'https://clearml-public.s3.amazonaws.com/datasets/food_dataset/pizza/3724187.jpg',
#          'timestamp': 0
#        }
#      }
#    ]
#  }
```
- dataset_id (str ) – 要检索的版本所属数据集的 ID。
- dataset_name (str ) – 要检索的版本所属数据集的名称。
- version_id (str ) – 要检索的版本 ID。
- version_name (str ) – 要检索的版本名称。
- dataset_project (str ) – 要检索的版本所属数据集的项目。
信息
当作为实例方法调用此方法时，dataset_id、dataset_name、dataset_project、version_id 和 version_name 不是必需的。
返回类型

Union[List[Union[SingleFrame, FrameGroup]], List[dict]]
返回

表示请求帧的 SingleFrame / FrameGroup 对象列表或字典列表。

信息
dataset_id 和 dataset_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

DatasetVersion.create_snapshot

classmethod create_snapshot(version_name=None, version_id=None, dataset_name=None, dataset_id=None, publish_name=None, publish_comment=None, publish_metadata=None, child_name=None, child_comment=None, child_metadata=None, dataset_project=None)

发布指定版本并创建草稿子版本

参数
- version_name (str ) – 用于快照的草稿版本名称。
- version_id (str ) – 用于快照的草稿版本 ID。
- dataset_name (str ) – 数据集名称。
- dataset_id (str ) – 要在其中创建版本的数据集 ID。
- publish_name (str ) – 已发布版本的新名称。默认值为“snapshot <date-time>”。
- publish_comment (str ) – 已发布版本的新注释。默认值为“published at <date-time> by <user>”。
- publish_metadata (dict ) – 已发布版本的用户指定元数据对象。键不能包含“$”和“.”。
- child_name (str ) – 子版本的名称。如果未提供，则使用父版本的名称。
- child_comment (str ) – 子版本的注释。
- child_metadata (dict ) – 子版本的用户指定元数据对象。键不能包含“$”和“.”。
- dataset_project (str ) – 数据集所属的项目
返回类型

ForwardRef
返回

表示新草稿子版本的 ```DatasetVersion``` 对象。

信息

如果未提供 version_name/id，则数据集的当前版本即为快照版本。

信息

dataset_id 和 dataset_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

信息

version_id 和 version_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

DatasetVersion.create_version

classmethod create_version(version_name, description=None, dataset_id=None, dataset_name=None, parent_version_ids=None, parent_version_names=None, raise_if_exists=False, auto_upload_destination=None, local_dataset_root_path=None, dataset_project=None)

在数据集中创建具有特定名称的新版本。

如果该名称的版本已存在且处于草稿模式（即可写），则返回该版本，除非 ```raise_if_exists``` 为 ```True```，否则引发 ```ValueError```

参数
- version_name (str ) – 新版本的名称。
- description (str ) – 新数据集版本的描述
- dataset_id (str ) – 要在其中创建版本的数据集 ID。
- dataset_name (str ) – 要在其中创建版本的数据集名称。
- parent_version_ids (list ) – 新版本父版本的 ID 列表。所有 ID 必须是此数据集中现有版本的 ID。目前，一个版本仅支持一个父版本。此列表是为了将来的兼容性。
- parent_version_names (list ) – 新版本父版本的名称列表。所有名称必须是此数据集中现有版本的名称。目前，一个版本仅支持一个父版本。此列表是为了将来的兼容性。
- raise_if_exists (bool ) – 如果为 ```True``` 且名称为 ```name``` 的版本已存在，则引发 ```ValueError```。如果为 ```False``` 且该名称的版本已存在，则返回该版本。
- auto_upload_destination (str ) – 如果指定，SingleFrame/FrameGroup 链接的任何本地文件将自动上传到目标存储。
- local_dataset_root_path (Union [ str , Path ] ) – 如果提供了 ```auto_upload_destination```，则为必需。它应指向所有本地源文件的公共文件夹
- dataset_project (str ) – 要在其中创建版本的数据集所属的项目。
返回类型

ForwardRef
返回

表示新版本的新 ```DatasetVersion``` 对象。

信息

dataset_id 和 dataset_name 是互斥的。将两者设置为非 None 值将引发 UsageError 异常。

DatasetVersion.get_versions

classmethod get_versions(dataset_name=None, dataset_id=None, only_published=False, only_draft=False, dataset_project=None)

返回数据集中所有版本的列表。

参数
- dataset_name (str ) – 数据集名称。如果存在多个同名数据集，则选择其中任意一个。
- dataset_id (str ) – 要列出的数据集 ID。
- only_published (bool ) – 如果为 ```True```，则仅返回已发布版本。如果为 ```False```，则返回所有版本。
- only_draft (bool ) – 如果为 ```True```，则仅返回草稿（可写）版本。如果为 ```False```，则返回所有版本。
- dataset_project (Optional[str]) – 要列出的数据集所属的项目
返回类型

List[ForwardRef]
返回

```DatasetVersion``` 列表，列表中的每个元素代表数据集的一个版本。版本按更新时间排序，从最新更新 ([0]) 到最旧

DatasetVersion.get_datasets

classmethod get_datasets(tags=None)

返回系统中所有数据集的列表，按创建时间排序。

参数

tags (list ) – 根据请求的标签列表（字符串）进行过滤。要排除某个标签，请在标签前添加“-”前缀。示例：```["best", "-debug"]```。默认行为是使用逻辑“或”运算符连接所有标签。若要改用逻辑“与”运算符连接所有标签，请使用“\_\_$all”作为第一个字符串，例如
```
["__$all", "best", "experiment", "ever"]
```
若要使用“与”连接所有标签，但排除某个标签，请在该排除标签前使用“\_\_$not”，例如
```
["__$all", "best", "experiment", "ever", "__$not", "internal", "__$not", "test"]
```
“或”和“与”运算符适用于它们后面的所有标签，直到指定了另一个运算符。非运算符仅适用于紧随其后的标签。例如
```
["__$all", "a", "b", "c", "__$or", "d", "__$not", "e", "__$and", "__$or" "f", "g"]
```
此示例表示（“a” 与 “b” 与 “c” 与（“d” 或非“e”）与（“f” 或 “g”））。更多信息请参见 https://clearml.org.cn/docs/latest/docs/clearml_sdk/task_sdk/#tag-filters。
返回类型

List[None]
返回

```datasets.Dataset``` 列表，列表中的每个元素代表一个数据集。数据集按创建时间排序，从最旧到最新

get_iterator

get_iterator(projection=None)

获取此版本的迭代器。

参数

projection (Optional [ Sequence [ str ] ] ) – 用于选择要返回的帧的哪些部分。每个字符串代表一个字段或子字段（使用点分隔表示法）。要指定特定的数组元素，请使用数组索引作为字段名。要指定所有数组元素，请使用“*”。如果设置了此参数，迭代器返回的值将是表示每个帧的字典

例如

version.get_iterator(projection=['id', 'dataset.id', 'sources'])
# will return an iterator that yields dictionaries with the following fields:
#  {
#    'id': '514504adbb6a91620eefa3e21ecfcc31',
#    'dataset': {
#      'id': 'df3638ec95454589bf86ba97f344f697'
#    },
#    'sources': [
#      {
#        'id': 'Frame',
#        'uri': 'https://clearml-public.s3.amazonaws.com/datasets/food_dataset/pizza/3724187.jpg',
#        'timestamp': 0,
#        'preview': {
#          'uri': 'https://clearml-public.s3.amazonaws.com/datasets/food_dataset/pizza/3724187.jpg',
#          'timestamp': 0
#        }
#      }
#    ]
#  }

返回类型

Generator[Union[“DatasetVersion.Frame”, dict]]
返回

所有版本帧的迭代器。

add_frames

add_frames(frames, warn_on_duplicate_frames=False, batch_size=1000, refresh_version_stats=True, auto_upload_destination=None, local_dataset_root_path=None, force_upload=False, progress_report=1, register_on_upload_failure=False, upload_retries=5, src_to_dst_mapping=None, unregister_on_upload_fail=True, max_request_size_mb=None)

将帧添加到此 ```DatasetVersion```。注意！如果帧已包含 frame.id 字段，它们将更新（覆盖）现有帧。如果未提供，则 frame.id 根据源 URI 生成。如果需要上传本地文件但该文件之前已被上传过，则将重用该文件的现有 URI，否则将上传该文件。

信息

仅在版本仍处于草稿（可写）模式时可用

参数
- frames (list ) – 要保存的新帧列表。
- warn_on_duplicate_frames (bool ) – 如果为 True，则在添加具有已添加到此实例的 ID 的帧时发出警告（默认值 False）
- batch_size (int) – 单个添加请求中的帧数（默认值：1000），batch_size 会影响上传速度与可靠性。它不限制每次调用的帧数，在大多数情况下无需更改。
- refresh_version_stats (Optional[bool]) – 添加帧后自动调用 ```commit_version``` 以刷新此版本的统计信息。
- auto_upload_destination (Optional[str]) – 如果指定，SingleFrame/FrameGroup 链接的任何本地文件将自动上传到目标存储。示例：‘s3://bucket/datasets/’、‘gs://bucket/dataset’、‘azure://bucket/dataset’、‘http://clearml-server/bucket/dataset’
信息
注意
1. 上传的文件将在指定存储中的 dataset_id/version_name.version_id/ 文件夹下保持相同的结构
2. 如果文件内容哈希已注册，它将自动链接到现有的远程文件，而不是重新上传本地副本
3. 在数据集/版本文件夹中，文件存储的路径与本地存储中的路径相同，相对于提供的 local_root_dataset_folder
- local_dataset_root_path (Union [ str , Path ] ) – 如果提供了 ```auto_upload_destination```，则为必需。与 src_to_dst_mapping 互斥。它应指向所有本地源文件的公共文件夹，此根文件夹用于检测单个源文件的相对路径，以便上传到远程存储。示例：```'auto_upload_destination='s3://bucket/datasets/', local_dataset_root_path='/home/user/data/'``` 将确保文件 ‘/home/user/data/images/01/1.jpg’ 将上传到：‘s3://bucket/datasets/dataset_id/version_id/images/01/1.jpg’
- force_upload (Optional[bool]) – 如果为 True 且提供了 ```auto_upload_destination```，将强制上传帧
- progress_report (Optional[int]) – 每上传/注册 ```progress_report``` 帧报告一次帧上传情况，粒度为 ```batch_size```。（默认值：每批次报告一次）
- register_on_upload_failure – 如果为 True，即使帧上传失败也注册它们
- upload_retries (int) – 在上传失败时应重试上传帧的次数，之后会将帧标记为上传失败并继续上传其他帧
- src_to_dst_mapping (Optional[Dict[str, str]]) – 字典，将帧的源映射到上传目的地。字典中找到的每个源都将上传到相应的目的地。与 auto_upload_destination 互斥
- unregister_on_upload_fail (bool) – 布尔值，控制是否删除上传失败的帧。
- max_request_size_mb (Optional[float]) – 添加帧时发送到服务器的最大请求大小，单位为兆字节。如果请求大小超出此限制，将分解为多个请求。如果单个帧的大小超出此限制，则该帧将不会被添加并返回错误消息。
返回类型

List[Dict]
返回

包含上传或注册失败的帧的列表。列表中的每个条目是

包含以下键值对的字典
- ‘frame’ - 添加失败的帧
- ‘error’ - 描述错误的字符串
- ‘error_type’ - 可以是 ‘upload’、‘validation’ 或 ‘register’。指示错误发生在哪里

update_frames

update_frames(frames, batch_size=1000, refresh_version_stats=True, without_fields=None)

更新此 ```DatasetVersion``` 中的现有帧。

根据帧 ID 找到每个帧，并将其属性更改为与 frames 中传入的帧对象匹配。如果帧之前已被添加（例如通过 ```update_frames```），或者存在于父版本中，则帧存在于版本中。如果帧对象没有 ID，则创建一个新帧。

信息

仅在版本仍处于草稿（可写）模式时可用

参数
- frames (list ) – 要更新的帧列表。
- batch_size (int ) – 单个更新请求中的帧数（默认值：1000）batch_size 会影响上传速度与可靠性。它不限制每次调用的帧数，在大多数情况下无需更改。
- refresh_version_stats (Optional[bool]) – 更新帧后自动调用 ```commit_version``` 以刷新此版本的统计信息。
- without_fields (Optional[List[str]]) – 在发送更新调用时，要从帧对象中过滤掉的字段列表。这些字段对应于 allegroai.backend_api.services.datasets.Frame 中的字段。提供此列表时，调用将生成更新操作，否则将使用添加操作（参见 ```add_frames```）。在此参数中使用非 None 值（例如 [] 或 False）可以指定不提供任何字段的更新操作。
信息
使用更新操作时，忽略已删除的帧字段（例如，更新不能用于从元结构中删除字段）。

例如，为了避免发送元数据
```
dataset_version.update_frames(frames, without_fields=["meta"])
```
返回类型

None

delete_frames

delete_frames(frames, batch_size=1000, refresh_version_stats=True, delete_sources=False)

从此 ```DatasetVersion``` 中删除帧。

帧可以由 ID 字符串或 ```DatasetVersion.Frame``` 对象表示。帧按其 ID 删除，所有其他帧属性（如果存在）将被忽略。

信息

仅在版本仍处于草稿（可写）模式时可用。

参数
- frames (Sequence[Union[FrameGroup, SingleFrame, dict, ForwardRef]]) – 帧对象列表或帧 ID（字符串）。
- batch_size (int ) – 单个删除请求中的帧 ID 数（默认值：1000）batch_size 会影响上传速度与可靠性。它不限制每次调用的帧数，在大多数情况下无需更改。
- refresh_version_stats (Optional[bool]) – 删除帧后自动调用 ```commit_version``` 以刷新此版本的统计信息。
- delete_sources (bool) – 删除数据集中与已删除帧相关的源。支持的源位置有：s3、gs 和 azure。如果无法建立与云提供商的连接或源删除失败，操作将中止。
返回类型

None

get_bulk_context

get_bulk_context(flush_threshold=None, log=None, refresh_version_stats=True, auto_upload_destination=None, local_dataset_root_path=None, allow_update=False)

获取此版本的批量更新上下文管理器。

批量上下文允许在此版本上批量添加/编辑/删除数据帧，而不是逐个操作。

信息

每个 DatasetVersion 只能有一个 BulkContext。第二次调用 get_bulk_context 将返回同一个对象。

信息

仅在版本仍处于草稿（可写）模式时可用。

参数
- flush_threshold (int ) – 每 ```flush_threshold``` 次更新提交一次对帧的更新。更新是指调用 ```BulkContext.add_frame```、```BulkContext.update_frame``` 或 ```BulkContext.delete_frame``` 之一。
- log (Optional[Logger]) – 上下文用于记录日志的 Logger 对象。默认为 datasetversion 模块日志记录器。
- refresh_version_stats (Optional[bool]) – 删除帧后自动调用 ```commit_version``` 以刷新此版本的统计信息。
- auto_upload_destination (Optional[str]) – 如果指定，SingleFrame/FrameGroup 链接的任何本地文件将自动上传到目标存储。示例：‘s3://bucket/datasets/’、‘gs://bucket/dataset’、‘azure://bucket/dataset’、‘http://clearml-server/bucket/dataset’
信息
注意
1. 上传的文件将在指定存储中的 dataset_id/version_name.version_id/ 文件夹下保持相同的结构
2. 如果文件内容哈希已注册，它将自动链接到现有的远程文件，而不是重新上传本地副本
3. 在数据集/版本文件夹中，文件存储的路径与本地存储中的路径相同，相对于提供的 local_root_dataset_folder
- local_dataset_root_path (Union [ str , Path ] ) – 如果提供了 ```auto_upload_destination```，则为必需。它应指向所有本地源文件的公共文件夹，此根文件夹用于检测单个源文件的相对路径，以便上传到远程存储。示例：```'auto_upload_destination='s3://bucket/datasets/', local_dataset_root_path='/home/user/data/'``` 将确保文件 ‘/home/user/data/images/01/1.jpg’ 将上传到：‘s3://bucket/datasets/dataset_id/version_id/images/01/1.jpg’
- allow_update (bool) – 如果为 False（默认值），所有帧操作将使用“添加”操作，“更新”将不被使用（即，即使使用 BulkContext.update() 调用收集的帧也将被添加，而不是更新）。这是一个高级设置，仅在您理解使用更新的限制时才更改。请注意，使用更新时，提供的帧数据会与现有的索引帧数据合并 - 这意味着在使用更新操作时无法删除帧字段。
返回类型

ForwardRef
返回

此 ```DatasetVersion``` 的批量更新上下文管理器

flush

flush(refresh_version_stats=True)

发送所有待处理的版本更改。

如果通过 ```get_bulk_context``` 获取了 ```BulkContext```，则使用它进行的任何更新都将发送到服务器。否则，此操作无效。

参数

refresh_version_stats (Optional[bool]) – 自动调用 ```commit_version``` 以刷新此版本的统计信息。
返回类型

None

commit_version

commit_version(**kwargs)

提交此 **草稿** ```DatasetVersion```，包含迄今为止所做的所有更改。

提交版本会将其所做的更改与父版本合并。仍然可以对版本进行进一步的更改。这是发布版本之前必须执行的步骤。

警告

这是一个阻塞方法，可能需要时间才能完成。

返回类型

CallResult
参数

kwargs (Any ) –

publish_version

publish_version()

发布此 ```DatasetVersion```。

发布版本后，它不再是草稿版本，不允许对此版本进行进一步更改。

返回类型

bool
返回

如果成功则为 ```True```，否则为 ```False```。

get_stats

get_stats()

返回此版本的统计信息

返回类型

None

get_parent

get_parent()

返回此版本父版本的 ID

返回类型

str

get_metadata

get_metadata()

返回类型

dict
返回

返回为特定数据集版本存储的用户定义值元数据（字典）

set_metadata

set_metadata(metadata)

存储为特定数据集版本存储的用户定义值元数据（字典）

参数

metadata (dict ) – 键/值字典（支持嵌套字典）
返回类型

bool
返回

如果成功则为 True（锁定/已发布版本无法更改版本元数据）

set_version_name

set_version_name(name)

为此数据集版本设置新名称

参数

name (str) – 版本新名称
返回类型

bool
返回

如果成功则为 True

set_masks_labels

set_masks_labels(mask_value_label_mapping)

存储一个全局（数据集版本范围）查找表，用于将每个像素的掩码值映射到标签。例如

{
  (0,0,0): ["background"],
  (1,1,1): ["person", "sitting"],
  (2,2,2): ["cat"],
}

像素掩码标签查找表作为数据集版本元数据的一个属性存储。具体来说：```dataset.get_metadata()['mask_labels'] = {...}```

参数

mask_value_label_mapping (dict ) – 键/值字典。键是一个整数元组，值是一个字符串列表/元组
返回类型

bool
返回

如果成功则为 True（锁定/已发布版本无法更改版本元数据）

get_masks_labels

get_masks_labels()

获取全局（数据集版本范围）查找表，用于将每个像素的掩码值映射到标签。例如

{
  (0,0,0): ["background"],
  (1,1,1): ["person", "sitting"],
  (2,2,2): ["cat"],
}

像素掩码标签查找表作为数据集版本元数据的一个属性存储。具体来说：```dataset.get_metadata()['mask_labels'] = {...}```

返回类型

Dict[tuple, tuple]
返回

键/值字典。键是一个整数元组，值是一个字符串列表/元组

class datasetversion.DatasetVersion()​

BulkContext​

add_frame​

delete_frame​

flush​

update_frame​

version_id​

version_name​

dataset_id​

dataset_name​

draft​

last_updated​

comment​

DatasetVersion.create_new_dataset​

DatasetVersion.get_current​

DatasetVersion.remove_version​

DatasetVersion.get_version​

DatasetVersion.get_single_frame​

DatasetVersion.get_frames_by_source​

DatasetVersion.get_frames_by_ids​

DatasetVersion.create_snapshot​

DatasetVersion.create_version​

DatasetVersion.get_versions​

DatasetVersion.get_datasets​

get_iterator​

add_frames​

update_frames​

delete_frames​

get_bulk_context​

flush​

commit_version​

publish_version​

get_stats​

get_parent​

get_metadata​

set_metadata​

set_version_name​

set_masks_labels​

get_masks_labels​

class datasetversion.DatasetVersion()

BulkContext

add_frame

delete_frame

flush

update_frame

version_id

version_name

dataset_id

dataset_name

draft

last_updated

comment

DatasetVersion.create_new_dataset

DatasetVersion.get_current

DatasetVersion.remove_version

DatasetVersion.get_version

DatasetVersion.get_single_frame

DatasetVersion.get_frames_by_source

DatasetVersion.get_frames_by_ids

DatasetVersion.create_snapshot

DatasetVersion.create_version

DatasetVersion.get_versions

DatasetVersion.get_datasets

get_iterator

add_frames

update_frames

delete_frames

get_bulk_context

flush

commit_version

publish_version

get_stats

get_parent

get_metadata

set_metadata

set_version_name

set_masks_labels

get_masks_labels