# datasets

Python API: `luxonis_ml.data.datasets`

LDF 的数据集句柄、记录、元数据和存储抽象。

此包拥有持久的 Luxonis 数据格式 (LDF) 数据集契约。主要入口点是
[LuxonisDataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)，它创建或打开数据集，并提供添加记录、定义拆分、设置类顺序和关键点骨架、合并或克隆数据集、导出数据集以及同步远程媒体的方法。

确切的注释负载模式位于
[luxonis_ml.ldf.annotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
中。此包级文档侧重于数据集生命周期和存储。

目录

 * [数据集生命周期](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
 * [创建和追加模式](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
 * [数据集记录](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
 * [存储布局](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
 * [克隆、合并和同步](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)
 * [类排序](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets.md)

## 数据集生命周期

数据集由 `dataset_name` 和可选的存储设置标识。构建
[LuxonisDataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
会在数据集存在时打开现有数据集，或者在没有匹配数据集时初始化新数据集。

```python
from luxonis_ml.data import BucketStorage, LuxonisDataset

dataset = LuxonisDataset(
    "parking_lot",
    bucket_storage=BucketStorage.LOCAL,
)
```

典型的修改流程：

 1. 从生成器中生成
    [DatasetRecord](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)-兼容字典。
 2. 将生成器传递给
    [LuxonisDataset.add](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)。
 3. 调用
    [LuxonisDataset.make_splits](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
    以定义拆分成员资格。
 4. 可选地通过
    [LuxonisDataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
    方法或 CLI 克隆、合并、导出、推送、拉取、检查、清理或删除。

```python
def records():
    yield {
        "file": "path/to/image.jpg",
        "task_name": "detection",
        "annotation": {
            "class": "car",
            "boundingbox": {
                "x": 0.1,
                "y": 0.2,
                "w": 0.3,
                "h": 0.4,
            },
        },
    }

dataset.add(records())
dataset.make_splits({"train": 0.8, "val": 0.1, "test": 0.1})
```

> **注意**
> 尽管 `"train"`、`"val"` 和 `"test"` 是传统的拆分名称，但 [LuxonisDataset.make_splits](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md) 在项目需要自定义视图时接受任意拆分名称。

## 创建和追加模式

[LuxonisDataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
默认创建本地数据集。传递 `bucket_storage=BucketStorage.GCS`、`BucketStorage.S3` 或其他受支持的存储后端以创建远程支持的数据集。远程数据集保留与本地数据集相同的本地元数据结构，而媒体文件与对象存储同步。

打开同名现有数据集会重用它。要强制使用干净的本地数据集，请传递 `delete_local=True`。要强制使用干净的远程数据集，请在添加记录之前使用 `delete_local=True` 和 `delete_remote=True` 删除两侧。

```python
dataset = LuxonisDataset(
    "parking_lot",
    bucket_storage=BucketStorage.LOCAL,
    delete_local=True,
)
dataset.add(records(), batch_size=100_000_000)
dataset.make_splits((0.8, 0.1, 0.1))
```

要追加新数据，请使用 `delete_local=False` 打开数据集并再次调用
[LuxonisDataset.add](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)。新的注释记录将被追加，而具有相同信息
UUID 的媒体记录将替换该媒体项的先前注释。

[LuxonisDataset.add](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
`batch_size` 控制在写入 Parquet 分片之前缓冲多少注释记录。对于远程数据集，相同的批处理边界还控制何时将媒体和注释分片推送到云存储。

## 数据集记录

[LuxonisDataset.add](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
接受
[DatasetRecord](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)-兼容项的迭代器。记录可以使用
`"file"` 表示单个源，或使用 `"files"` 表示多个同步源。

记录级字段

| 字段 | 含义 |
| --- | --- |
| `file` | 单个媒体源的路径。 |
| `files` | 从源名称到同步媒体路径的映射。 |
| `task_name` | 加载器和元数据使用的可选组名。 |
| `sample_metadata` | 可选的记录级元数据，与样本一起保留，并由
[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
作为
[LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md)
返回。 |
| `annotation` | 由
[Detection](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md)
验证的可选注释负载。 |

多源记录保留
[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
的源名称，允许训练代码接收诸如 `{"rgb": ..., "depth": ...}` 之类的字典。记录级元数据与注释元数据是分开的：`sample_metadata` 描述样本，而 `annotation["metadata"]` 创建元数据标签任务。

```json
{
  "file": "images/frame_001.jpg",
  "task_name": "detection",

  "sample_metadata": {
    "record_id": 123,
    "camera": "left",
    "tags": ["night", "warehouse"]
  },

  "annotation": {
    "class": "person",
    "boundingbox": {
      "x": 0.1,
      "y": 0.2,
      "w": 0.3,
      "h": 0.4
    }
  }
}
```

前端注意事项： `sample_metadata` 是样本数据，而不是注释目标。

> **另请参阅**
> [DatasetRecord](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md) 用于记录验证，[Detection](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md) 用于负载分组，以及 [luxonis_ml.ldf.annotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/ldf/annotation.md) 用于详细注释模式。

## 存储布局

默认情况下，本地数据集位于 `LUXONISML_BASE_PATH / data / LUXONISML_TEAM_ID / datasets / dataset_name` 下。默认基本路径是 `Path.home() /
"luxonis_ml"`，默认团队标识符是 `"offline"`。

数据集存储布局

| 路径 | 内容 |
| --- | --- |
| `annotations/*.parquet` | 包含媒体路径、源名称、任务名称、类名称、实例 ID、任务类型、序列化注释负载、序列化 `sample_metadata` JSON 和 UUID 的 Parquet 分片。 |
| `media/` | 远程媒体的本地副本，命名为 `<uuid><suffix>`。仅限本地的数据集可以保持此目录为空并继续引用原始文件。 |
| `metadata/metadata.json` | 数据集元数据、源描述符、类映射、任务元数据、分类编码、骨架定义和 LDF 版本元数据。 |
| `metadata/splits.json` | 从拆分名称到数据集样本标识符的映射。 |

远程数据集使用相同的本地元数据结构，并与配置的对象存储同步媒体和注释状态。在存储桶中，数据集位于 `<bucket_storage>://<bucket>/<team_id>/datasets/<dataset_name>/`，并保留相同的
`annotations/`、`media/` 和 `metadata/` 子文件夹。数组注释添加第四个 `arrays/` 子文件夹。

远程数据集会重命名其媒体对象。每个文件都变为 `<uuid><original suffix>`，其中 UUID 来自文件内容。原始文件名保留在 Parquet 分片的 `file` 列中。

> **警告**
> 删除标志独立控制本地和远程状态。要完全重新创建远程数据集，请传递 `delete_local=True` 和 `delete_remote=True`。要从现有远程数据集重建损坏的本地副本，请传递 `delete_local=True` 和 `delete_remote=False`。

> **警告**
> 本地路径不包含存储桶存储组件。因此，同名的本地数据集和远程数据集共享一个本地目录。请使用不同的名称，否则可能会相互覆盖本地状态。

## 克隆、合并和同步

[LuxonisDataset.clone](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
在新数据集名称下创建副本。
[LuxonisDataset.merge_with](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
将两个数据集合并到原地或合并到新数据集。

```python
clone = dataset.clone(new_dataset_name="parking_lot_clone")

dataset1.merge_with(dataset2, inplace=True)

merged = dataset1.merge_with(
    dataset2,
    inplace=False,
    new_dataset_name="parking_lot_merged",
)
```

远程同步是显式的，由
[UpdateMode](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/enums.md)
控制：

```python
from luxonis_ml.data import BucketStorage, UpdateMode

dataset.pull_from_cloud(update_mode=UpdateMode.MISSING)
dataset.push_to_cloud(
    bucket_storage=BucketStorage.GCS,
    update_mode=UpdateMode.ALL,
)
```

> **重要**
> 注释分片和元数据始终同步。媒体更新模式控制是传输所有媒体文件还是仅传输缺失的媒体文件。

## 类排序

[LuxonisDataset.set_class_order_per_task](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
为每个任务应用视图时间类顺序，而无需重写存储的元数据。提供的映射必须使用数据集中已有的确切任务名称和确切类名称。

```python
dataset.set_class_order_per_task(
    {
        "vehicle_detection": ["car", "motorcycle"],
        "color_segmentation": ["background", "red", "green", "blue"],
    }
)
```

在构建
[LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md)
之前调用此函数，因为加载器初始化使用数据集的活动类排序。如果后续添加引入新类，请再次使用完整的所需顺序调用
[set_class_order_per_task](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)。

## 子页面

 * [annotation](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/annotation.md)
 * [base_dataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/base_dataset.md)
 * [luxonis_dataset](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/luxonis_dataset.md)
 * [metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/metadata.md)
 * [migration](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/migration.md)
 * [source](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/source.md)
 * [utils](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/datasets/utils.md)
