# 创建Workflow数据集导入节点
#### 功能介绍
通过对ModelArts数据集能力进行封装，实现数据集的数据导入功能。数据集导入节点主要用于将指定路径下的数据导入到数据集或者标注任务中，主要应用场景如下：
- 适用于数据不断迭代的场景，可以将一些新增的原始数据或者已标注数据导入到标注任务中，并通过后续的数据集标注节点进行标注。
- 对于一些已标注好的原始数据，可以直接导入到数据集或者标注任务中，并通过后续的数据集版本发布节点获取带有版本信息的数据集对象。
 
#### 属性总览
您可以使用**DatasetImportStep** 来构建数据集导入节点，**DatasetImportStep**结构如下。
表1**DatasetImportStep** 
| 属性           | 描述                                                                                         | 是否必填 | 数据类型                                        |
|:---|:---|:---|:---|
| name         | 数据集导入节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复。 | 是    | str                                         |
| inputs       | 数据集导入节点的输入列表。                                                                              | 是    | DatasetImportInput或者DatasetImportInput的列表   |
| outputs      | 数据集导入节点的输出列表。                                                                              | 是    | DatasetImportOutput或者DatasetImportOutput的列表 |
| properties   | 数据集导入相关的配置信息。                                                                              | 是    | ImportDataInfo                              |
| title        | title信息，主要用于前端的名称展示。                                                                       | 否    | str                                         |
| description  | 数据集导入节点的描述信息。                                                                              | 否    | str                                         |
| policy       | 节点执行的policy。                                                                               | 否    | StepPolicy                                  |
| depend_steps | 依赖的节点列表。                                                                                   | 否    | Step或者Step的列表                               |
   
表2**DatasetImportInput** 
| 属性   | 描述                                                                                   | 是否必填 | 数据类型                                                                                                                                                                                  |
|:---|:---|:---|:---|
| name | 数据集导入节点的输入名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)。同一个Step的输入名称不能重复。 | 是    | str                                                                                                                                                                                   |
| data | 数据集导入节点的输入数据对象。                                                                      | 是    | 数据集、OBS或标注任务相关对象，当前仅支持Dataset，DatasetConsumption，DatasetPlaceholder，OBSPath，OBSConsumption，OBSPlaceholder，LabelTask，LabelTaskPlaceholder，LabelTaskConsumption，DataConsumptionSelector |
   
表3**DatasetImportOutput** 
| 属性   | 描述                                                                                   | 是否必填 | 数据类型 |
|:---|:---|:---|:---|
| name | 数据集导入节点的输出名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)。同一个Step的输出名称不能重复。 | 是    | str  |
   
表4**ImportDataInfo** 
| 属性                       | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                | 是否必填 | 数据类型                   |
|:---|:---|:---|:---|
| annotation_format_config | 导入的标注格式的配置参数。                                                                                                                                                                                                                                                                                                                                                                                                                     | 否    | AnnotationFormatConfig |
| excluded_labels          | 不导入包含指定标签的样本。                                                                                                                                                                                                                                                                                                                                                                                                                     | 否    | Label的列表               |
| import_annotated         | 用于导入智能标注结果的任务，是否导入原数据集中已标注的样本到待确认，默认值为"false"即不导入原数据集中已标注的样本到待确认。可选值如下： - true：导入原数据集中已标注的样本到待确认  - false：不导入原数据集中已标注的样本到待确认   | 否    | bool                   |
| import_annotations       | 是否导入标签。可选值如下： - true：导入标签（默认值）  - false：不导入标签                                                                                       | 否    | bool                   |
| import_samples           | 是否导入样本。可选值如下： - true：导入样本（默认值）  - false：不导入样本                                                                                   | 否    | bool                   |
| import_type              | 导入方式。可选值如下： - dir：目录导入  - manifest：按manifest文件导入                                                                                      | 否    | ImportTypeEnum         |
| included_labels          | 导入包含指定标签的样本。                                                                                                                                                                                                                                                                                                                                                                                                                      | 否    | Label的列表               |
| label_format             | 标签格式，此参数仅文本类数据集使用。                                                                                                                                                                                                                                                                                                                                                                                                                | 否    | LabelFormat            |
   
表5**AnnotationFormatConfig** 
| 属性          | 描述         | 是否必填 | 数据类型                       |
|:---|:---|:---|:---|
| format_name | 标注格式的名称。   | 否    | AnnotationFormatEnum       |
| parameters  | 标注格式的高级参数。 | 否    | AnnotationFormatParameters |
| scene       | 标注场景，可选参数。 | 否    | LabelTaskTypeEnum          |
   
表6**AnnotationFormatParameters** 
| 属性                     | 描述                                                                                                                                                                                                                                                                                                                                                      | 是否必填 | 数据类型     |
|:---|:---|:---|:---|
| difficult_only         | 是否只导入难例。可选值如下： - true：只导入难例样本  - false：导入全部样本（默认值）   | 否    | bool     |
| included_labels        | 导入包含指定标签的样本。                                                                                                                                                                                                                                                                                                                                            | 否    | Label的列表 |
| label_separator        | 标签与标签之间的分隔符，默认为逗号分隔，分隔符需转义。分隔符仅支持一个字符，必须为大小写字母，数字和"!@#$%\^\&\*_=\|?/':.;,"其中的某一字符。                                                                                                                                                                                                                                                                      | 否    | str      |
| sample_label_separator | 文本与标签之间的分隔符，默认为Tab键分隔，分隔符需转义。分隔符仅支持一个字符，必须为大小写字母，数字和"!@#$%\^\&\*_=\|?/':.;,"其中的某一字符。                                                                                                                                                                                                                                                                    | 否    | str      |
   
#### 使用案例
主要包含三种场景的用例：
- 场景一：将指定存储路径下的数据导入到目标数据集中。适用于需要对数据集进行数据更新的操作。
  - 用户将指定路径下已标注的数据导入到数据集中（同时导入标签信息），后续可增加数据集版本发布节点进行版本发布。 数据准备：提前在[ModelArts管理控制台](https://console.huaweicloud.com/modelarts/)，创建数据集，并将已标注的数据上传至OBS中。
    ```
    from modelarts import workflow as wf
    # 通过DatasetImportStep将指定路径下的数据导入到数据集中，输出数据集对象
    # 定义数据集对象
    dataset = wf.data.DatasetPlaceholder(name="input_dataset")
    # 定义OBS数据对象
    obs = wf.data.OBSPlaceholder(name = "obs_placeholder_name", object_type = "directory" ) # object_type必须是file或者directory
    dataset_import = wf.steps.DatasetImportStep(
        name="data_import", # 数据集导入节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
        title="数据集导入", # 标题信息，不填默认使用name值
        inputs=[
            wf.steps.DatasetImportInput(name="input_name_1", data=dataset), # 目标数据集在运行时配置；data字段也可使用wf.data.Dataset(dataset_name="dataset_name")表示
            wf.steps.DatasetImportInput(name="input_name_2", data=obs) # 导入的数据存储路径，运行时配置；data字段也可使用wf.data.OBSPath(obs_path="obs_path")表示
        ],# DatasetImportStep的输入
        outputs=wf.steps.DatasetImportOutput(name="output_name"), # DatasetImportStep的输出
        properties=wf.steps.ImportDataInfo(
            annotation_format_config=[
                wf.steps.AnnotationFormatConfig(
                    format_name=wf.steps.AnnotationFormatEnum.MA_IMAGE_CLASSIFICATION_V1, # 已标注数据的标注格式，示例为图像分类
                    scene=wf.data.LabelTaskTypeEnum.IMAGE_CLASSIFICATION # 标注的场景类型
                )
            ]
        )
    )
    workflow = wf.Workflow(
        name="dataset-import-demo",
        desc="this is a demo workflow",
        steps=[dataset_import]
    )
    ```
    
  
  - 用户将指定路径下未标注的数据导入到数据集中，后续可增加数据集标注节点对新增数据进行标注。 数据准备：提前在ModelArts界面创建数据集，并将未标注的数据上传至OBS中。
    ```
    from modelarts import workflow as wf
    # 通过DatasetImportStep将指定路径下的数据导入到数据集中，输出数据集对象
    # 定义数据集对象
    dataset = wf.data.DatasetPlaceholder(name="input_dataset")
    # 定义OBS数据对象
    obs = wf.data.OBSPlaceholder(name = "obs_placeholder_name", object_type = "directory" ) # object_type必须是file或者directory
    dataset_import = wf.steps.DatasetImportStep(
        name="data_import", # 数据集导入节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
        title="数据集导入", # 标题信息，不填默认使用name值
        inputs=[
            wf.steps.DatasetImportInput(name="input_name_1", data=dataset), # 目标数据集在运行时配置；data字段也可使用wf.data.Dataset(dataset_name="dataset_name")表示
            wf.steps.DatasetImportInput(name="input_name_2", data=obs) # 导入的数据存储路径，运行时配置；data字段也可使用wf.data.OBSPath(obs_path="obs_path")表示
        ],# DatasetImportStep的输入
        outputs=wf.steps.DatasetImportOutput(name="output_name") # DatasetImportStep的输出
    )
    workflow = wf.Workflow(
        name="dataset-import-demo",
        desc="this is a demo workflow",
        steps=[dataset_import]
    )
    ```
    
   
- 场景二：将指定存储路径下的数据导入到指定标注任务中。适用于需要对标注任务进行数据更新的操作。
  - 用户将指定路径下已标注的数据导入到标注任务中（同时导入标签信息），后续可增加数据集版本发布节点进行版本发布。 数据准备：基于使用的数据集，提前创建标注任务，并将已标注的数据上传至OBS中。
    ```
    from modelarts import workflow as wf
    # 通过DatasetImportStep将指定路径下的数据导入到标注任务中，输出标注任务对象
    # 定义标注任务对象
    label_task = wf.data.LabelTaskPlaceholder(name="label_task_placeholder_name")
    # 定义OBS数据对象
    obs = wf.data.OBSPlaceholder(name = "obs_placeholder_name", object_type = "directory" ) # object_type必须是file或者directory
    dataset_import = wf.steps.DatasetImportStep(
        name="data_import", # 数据集导入节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
        title="数据集导入", # 标题信息，不填默认使用name值
        inputs=[
            wf.steps.DatasetImportInput(name="input_name_1", data=label_task), # 目标标注任务对象，在运行时配置；data字段也可使用wf.data.LabelTask(dataset_name="dataset_name", task_name="label_task_name")表示
            wf.steps.DatasetImportInput(name="input_name_2", data=obs) # 导入的数据存储路径，运行时配置；data字段也可使用wf.data.OBSPath(obs_path="obs_path")表示
        ],# DatasetImportStep的输入
        outputs=wf.steps.DatasetImportOutput(name="output_name"), # DatasetImportStep的输出
        properties=wf.steps.ImportDataInfo(
            annotation_format_config=[
                wf.steps.AnnotationFormatConfig(
                    format_name=wf.steps.AnnotationFormatEnum.MA_IMAGE_CLASSIFICATION_V1, # 已标注数据的标注格式，示例为图像分类
                    scene=wf.data.LabelTaskTypeEnum.IMAGE_CLASSIFICATION # 标注的场景类型
                )
            ]
        )
    )
    workflow = wf.Workflow(
        name="dataset-import-demo",
        desc="this is a demo workflow",
        steps=[dataset_import]
    )
    ```
    
  
  - 用户将指定路径下未标注的数据导入到标注任务中，后续可增加数据集标注节点对新增数据进行标注。 数据准备：基于使用的数据集，提前创建标注任务，并将未标注的数据上传至OBS中。
    ```
    from modelarts import workflow as wf
    # 通过DatasetImportStep将指定路径下的数据导入到标注任务中，输出标注任务对象
    # 定义标注任务对象
    label_task = wf.data.LabelTaskPlaceholder(name="label_task_placeholder_name")
    # 定义OBS数据对象
    obs = wf.data.OBSPlaceholder(name = "obs_placeholder_name", object_type = "directory" ) # object_type必须是file或者directory
    dataset_import = wf.steps.DatasetImportStep(
        name="data_import", # 数据集导入节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
        title="数据集导入", # 标题信息，不填默认使用name值
        inputs=[
            wf.steps.DatasetImportInput(name="input_name_1", data=label_task), # 目标标注任务对象，在运行时配置；data字段也可使用wf.data.LabelTask(dataset_name="dataset_name", task_name="label_task_name")表示
            wf.steps.DatasetImportInput(name="input_name_2", data=obs) # 导入的数据存储路径，运行时配置；data字段也可使用wf.data.OBSPath(obs_path="obs_path")表示
        ],# DatasetImportStep的输入
        outputs=wf.steps.DatasetImportOutput(name="output_name") # DatasetImportStep的输出
    )
    workflow = wf.Workflow(
        name="dataset-import-demo",
        desc="this is a demo workflow",
        steps=[dataset_import]
    )
    ```
    
   
- 场景三：基于数据集创建节点构建数据集导入节点。数据集创建节点的输出作为数据集导入节点的输入。
  ```
  from modelarts import workflow as wf
  # 通过DatasetImportStep将指定路径下的数据导入到数据集中，输出数据集对象
  # 定义OBS数据对象
  obs = wf.data.OBSPlaceholder(name = "obs_placeholder_name", object_type = "directory" ) # object_type必须是file或者directory
  dataset_import = wf.steps.DatasetImportStep(
      name="data_import", # 数据集导入节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
      title="数据集导入", # 标题信息，不填默认使用name值
      inputs=[
          wf.steps.DatasetImportInput(name="input_name_1", data=create_dataset.outputs["create_dataset_output"].as_input()), # 数据集创建节点的输出作为导入节点的输入
          wf.steps.DatasetImportInput(name="input_name_2", data=obs) # 导入的数据存储路径，运行时配置；data字段也可使用wf.data.OBSPath(obs_path="obs_path")表示
      ],# DatasetImportStep的输入
      outputs=wf.steps.DatasetImportOutput(name="output_name"), # DatasetImportStep的输出
      depend_steps=create_dataset # 依赖的数据集创建节点对象
  )
  # create_dataset是 wf.steps.CreateDatasetStep的一个实例，create_dataset_output是wf.steps.CreateDatasetOutput的name字段值
  workflow = wf.Workflow(
      name="dataset-import-demo",
      desc="this is a demo workflow",
      steps=[dataset_import]
  )
  ```