# 创建Workflow数据集标注节点
#### 功能介绍
通过对ModelArts数据集能力进行封装，实现数据集的标注功能。数据集标注节点主要用于创建标注任务或对已有的标注任务进行卡点标注，主要用于需要对数据进行人工标注的场景。
#### 属性总览
您可以使用**LabelingStep** 来构建数据集标注节点，**LabelingStep**结构如下：
表1**LabelingStep** 
| 属性           | 描述                                                                                        | 是否必填 | 数据类型                              |
|:---|:---|:---|:---|
| name         | 数据集标注节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复 | 是    | str                               |
| inputs       | 数据集标注节点的输入列表                                                                              | 是    | LabelingInput或者LabelingInput的列表   |
| outputs      | 数据集标注节点的输出列表                                                                              | 是    | LabelingOutput或者LabelingOutput的列表 |
| properties   | 数据集标注相关的配置信息                                                                              | 是    | LabelTaskProperties               |
| title        | title信息，主要用于前端的名称展示                                                                       | 否    | str                               |
| description  | 数据集标注节点的描述信息                                                                              | 否    | str                               |
| policy       | 节点执行的policy                                                                               | 否    | StepPolicy                        |
| depend_steps | 依赖的节点列表                                                                                   | 否    | Step或者Step的列表                     |
   
表2**LabelingInput** 
| 属性   | 描述                                                                                  | 是否必填 | 数据类型                                                                                                                                          |
|:---|:---|:---|:---|
| name | 数据集标注节点的输入名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)。同一个Step的输入名称不能重复 | 是    | str                                                                                                                                           |
| data | 数据集标注节点的输入数据对象                                                                      | 是    | 数据集或标注任务相关对象，当前仅支持Dataset， DatasetConsumption， DatasetPlaceholder，LabelTask，LabelTaskPlaceholder，LabelTaskConsumption，DataConsumptionSelector |
   
表3**LabelingOutput** 
| 属性   | 描述                                                                                  | 是否必填 | 数据类型 |
|:---|:---|:---|:---|
| name | 数据集标注节点的输出名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)。同一个Step的输出名称不能重复 | 是    | str  |
   
表4**LabelTaskProperties** 
| 属性                | 描述                                                                                                                                                                                                                                                                                                                                                                                            | 是否必填 | 数据类型              |
|:---|:---|:---|:---|
| task_type         | 标注任务类型，返回指定标注任务类型的任务列表。                                                                                                                                                                                                                                                                                                                                                                       | 是    | LabelTaskTypeEnum |
| task_name         | 标注任务名称，名称只能包含中文、字母、数字、中划线和下划线，长度为1-100位。 当输入是数据集对象时，该参数必填                                                                                                                                                                                                                                                                                      | 否    | str、Placeholder   |
| labels            | 待创建的标签列表                                                                                                                                                                                                                                                                                                                                                                                      | 否    | Label             |
| properties        | 标注任务的属性，可扩展字段，可以记录自定义信息。                                                                                                                                                                                                                                                                                                                                                                      | 否    | dict              |
| auto_sync_dataset | 标注任务的标注结果是否自动同步至数据集。可选值如下： - true：标注任务的标注结果自动同步至数据集（默认值）  - false：标注任务的标注结果不自动同步至数据集   | 否    | bool              |
| content_labeling  | 语音分割标注任务是否开启内容标注，默认开启。                                                                                                                                                                                                                                                                                                                                                                        | 否    | bool              |
| description       | 标注任务描述信息，长度为0-256位，不能包含\^!\<\>=\&"'特殊字符。                                                                                                                                                                                                                                                                                                                                                      | 否    | str               |
   
表5**Label** 
| 属性       | 描述                 | 是否必填 | 数据类型                |
|:---|:---|:---|:---|
| name     | 标签名称               | 否    | str                 |
| property | 标签基本属性键值对，如颜色、快捷键等 | 否    | str、dic、Placeholder |
| type     | 标签类型               | 否    | LabelTypeEnum       |
   
| 枚举类型              | 枚举值                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|:---|:---|
| LabelTaskTypeEnum | IMAGE_CLASSIFICATION OBJECT_DETECTION IMAGE_SEGMENTATION TEXT_CLASSIFICATION NAMED_ENTITY_RECOGNITION TEXT_TRIPLE AUDIO_CLASSIFICATION SPEECH_CONTENT SPEECH_SEGMENTATION DATASET_TABULAR VIDEO_ANNOTATION FREE_FORMAT |
   
#### Workflow数据集标注节点代码样例
主要包含三种场景的用例：
- 场景一：基于用户指定的数据集创建标注任务，并等待用户标注完成。 使用场景：
  - 用户只创建了一个未标注完成的数据集，需要在工作流运行时对数据进行人工标注。
  
  - 可以放在数据集导入节点之后，对导入的新数据进行人工标注。
  
  
  数据准备：提前在[ModelArts管理控制台](https://console.huaweicloud.com/modelarts/)创建一个数据集。
  ```
  from modelarts import workflow as wf
  # 通过LabelingStep给输入的数据集对象创建新的标注任务，并等待用户标注完成
  # 定义输入的数据集对象
  dataset = wf.data.DatasetPlaceholder(name="input_dataset")
  # 定义标注任务的名称参数
  task_name = wf.Placeholder(name="placeholder_name", placeholder_type=wf.PlaceholderType.STR)
  labeling = wf.steps.LabelingStep(
      name="labeling", # 数据集标注节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
      title="数据集标注", # 标题信息，不填默认使用name值
      properties=wf.steps.LabelTaskProperties(
          task_type=wf.data.LabelTaskTypeEnum.IMAGE_CLASSIFICATION,   # 标注任务的类型，以图像分类为例
          task_name=task_name   # 该名称对应的标注任务如果不存在则创建，如果存在则直接使用该任务
      ),
      inputs=wf.steps.LabelingInput(name="input_name", data=dataset), # LabelingStep的输入，数据集对象在运行时配置；data字段也可使用wf.data.Dataset(dataset_name="fake_dataset_name")表示
      outputs=wf.steps.LabelingOutput(name="output_name"), # LabelingStep的输出
  )
  workflow = wf.Workflow(
      name="labeling-step-demo",
      desc="this is a demo workflow",
      steps=[labeling]
  )
  ```
  
- 场景二：基于指定的标注任务进行标注。 使用场景：
  - 用户基于数据集自主创建了一个标注任务，需要在工作流运行时对数据进行人工标注。
  
  - 可以放在数据集导入节点之后，对导入的新数据进行人工标注。
  
  
  数据准备：提前在[ModelArts管理控制台](https://console.huaweicloud.com/modelarts/)，基于使用的数据集创建一个标注任务。
  ```
  from modelarts import workflow as wf
  # 用户输入标注任务，等待用户标注完成
  # 定义数据集的标注任务对象
  label_task = wf.data.LabelTaskPlaceholder(name="label_task_placeholder_name")
  labeling = wf.steps.LabelingStep(
      name="labeling", # 数据集标注节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
      title="数据集标注", # 标题信息，不填默认使用name值
      inputs=wf.steps.LabelingInput(name="input_name", data=label_task), # LabelingStep的输入，标注任务对象在运行时配置；data字段也可使用wf.data.LabelTask(dataset_name="dataset_name", task_name="label_task_name")来表示
      outputs=wf.steps.LabelingOutput(name="output_name"), # LabelingStep的输出
  )
  workflow = wf.Workflow(
      name="labeling-step-demo",
      desc="this is a demo workflow",
      steps=[labeling]
  )
  ```
  
- 场景三：基于数据集创建节点的输出创建标注任务。 使用场景：数据集创建节点的输出作为数据集数据标注节点的输入。
  ```
  from modelarts import workflow as wf
  # 定义数据集输出路径参数
  dataset_output_path = wf.Placeholder(name="dataset_output_path", placeholder_type=wf.PlaceholderType.STR, placeholder_format="obs")
  # 定义数据集名称参数
  dataset_name = wf.Placeholder(name="dataset_name", placeholder_type=wf.PlaceholderType.STR)
  create_dataset = wf.steps.CreateDatasetStep(
      name="create_dataset",# 数据集创建节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
      title="数据集创建", # 标题信息，不填默认使用name值
      inputs=wf.steps.CreateDatasetInput(name="input_name", data=wf.data.OBSPlaceholder(name="obs_placeholder_name", object_type="directory")),# CreateDatasetStep的输入，数据在运行时配置；data字段也可使用wf.data.OBSPath(obs_path="fake_obs_path")对象表示
      outputs=wf.steps.CreateDatasetOutput(name="create_dataset_output", config=wf.data.OBSOutputConfig(obs_path=dataset_output_path)),# CreateDatasetStep的输出
      properties=wf.steps.DatasetProperties(
          dataset_name=dataset_name, # 该名称对应的数据集如果不存在，则创建新的数据集;如果已存在，则直接使用该名称对应的数据集
          data_type=wf.data.DataTypeEnum.IMAGE, # 数据集对应的数据类型, 示例为图像
      )
  )
  # 定义标注任务的名称参数
  task_name = wf.Placeholder(name="placeholder_name", placeholder_type=wf.PlaceholderType.STR)
  labeling = wf.steps.LabelingStep(
      name="labeling", # 数据集标注节点的名称，命名规范(只能包含英文字母、数字、下划线（_）、中划线（-），并且只能以英文字母开头，长度限制为64字符)，一个Workflow里的两个step名称不能重复
      title="数据集标注", # 标题信息，不填默认使用name值
      properties=wf.steps.LabelTaskProperties(
          task_type=wf.data.LabelTaskTypeEnum.IMAGE_CLASSIFICATION,   # 标注任务的类型，以图像分类为例
          task_name=task_name   # 该名称对应的标注任务如果不存在则创建，如果存在则直接使用该任务
      ),
      inputs=wf.steps.LabelingInput(name="input_name", data=create_dataset.outputs["create_dataset_output"].as_input()), # LabelingStep的输入，data数据来源为数据集创建节点的输出
      outputs=wf.steps.LabelingOutput(name="output_name"), # LabelingStep的输出
      depend_steps=create_dataset # 依赖的数据集创建节点对象
  )
  # create_dataset是 wf.steps.CreateDatasetStep的一个实例，create_dataset_output是wf.steps.CreateDatasetOutput的name字段值
  workflow = wf.Workflow(
      name="labeling-step-demo",
      desc="this is a demo workflow",
      steps=[create_dataset, labeling]
  )
  ```