Merge pull request #233449 from lgayhardt/amlregcomp0423

update register component in UI and common errors

Author: v-ccolin

articles/machine-learning/how-to-create-component-pipelines-ui.md

@@ -8,7 +8,7 @@ ms.subservice: core
 ms.author: keli19
 author: likebupt
 ms.reviewer: lagayhar
-ms.date:  05/10/2022
+ms.date:  03/27/2022
 ms.topic: how-to
 ms.custom: devplatv2, designer, event-tier1-build-2022, ignite-2022
 ---
@@ -17,7 +17,7 @@ ms.custom: devplatv2, designer, event-tier1-build-2022, ignite-2022
 
 [!INCLUDE [cli v2](../../includes/machine-learning-cli-v2.md)]
 
-In this article, you'll learn how to create and run [machine learning pipelines](concept-ml-pipelines.md) by using the Azure Machine Learning studio and [Components](concept-component.md). You can create pipelines without using components, but components offer better amount of flexibility and reuse. Azure Machine Learning Pipelines may be defined in YAML and [run from the CLI](how-to-create-component-pipelines-cli.md), [authored in Python](how-to-create-component-pipeline-python.md), or composed in Azure Machine Learning Studio Designer with a drag-and-drop UI. This document focuses on the Azure Machine Learning studio designer UI.
+In this article, you'll learn how to create and run [machine learning pipelines](concept-ml-pipelines.md) by using the Azure Machine Learning studio and [Components](concept-component.md). You can create pipelines without using components, but components offer better amount of flexibility and reuse. Azure Machine Learning Pipelines may be defined in YAML and [run from the CLI](how-to-create-component-pipelines-cli.md), [authored in Python](how-to-create-component-pipeline-python.md), or composed in Azure Machine Learning studio Designer with a drag-and-drop UI. This document focuses on the Azure Machine Learning studio designer UI.
 
 ## Prerequisites
 
@@ -34,8 +34,6 @@ In this article, you'll learn how to create and run [machine learning pipelines]
     cd azureml-examples/cli/jobs/pipelines-with-components/
     ```
 
-## Register component in your workspace
-
 >[!Note]
 > Designer supports two type of components, classic prebuilt components and custom components. These two types of components are not compatible.  
 >
@@ -44,23 +42,34 @@ In this article, you'll learn how to create and run [machine learning pipelines]
 >
 >Custom components allow you to provide your own code as a component. It supports sharing across workspaces and seamless authoring across Studio, CLI, and SDK interfaces.
 >
->This article applies to custom components. 
+>This article applies to **custom components**.
+
+## Register component in your workspace
 
-To build pipeline using components in UI, you need to register components to your workspace first. You can use CLI or SDK to register components to your workspace, so that you can share and reuse the component within the workspace. Registered components support automatic versioning so you can update the component but assure that pipelines that require an older version will continue to work.  
+To build pipeline using components in UI, you need to register components to your workspace first. You can use UI, CLI or SDK to register components to your workspace, so that you can share and reuse the component within the workspace. Registered components support automatic versioning so you can update the component but assure that pipelines that require an older version will continue to work.  
 
-In the example below take using CLI for example. If you want to learn more about how to build a component, see [Create and run pipelines using components with  CLI](how-to-create-component-pipelines-cli.md).
+The example below uses UI to register components, and the [component source files](https://github.com/Azure/azureml-examples/tree/main/cli/jobs/pipelines-with-components/basics/1b_e2e_registered_components)  are in the `cli/jobs/pipelines-with-components/basics/1b_e2e_registered_components` directory of the [`azureml-examples` repository](https://github.com/Azure/azureml-examples). You need to clone the repo to local first.
 
-1. From the `cli/jobs/pipelines-with-components/basics` directory of the [`azureml-examples` repository](https://github.com/Azure/azureml-examples), navigate to the `1b_e2e_registered_components` subdirectory.
+1. In your Azure Machine Learning workspace, navigate to **Components** page and select **New Component**.
 
-1. Register the components to Azure Machine Learning workspace using following commands. Learn more about [ML components](concept-component.md).
+:::image type="content" source="./media/how-to-create-component-pipelines-ui/register-component-entry-button.png" alt-text="Screenshot showing register entry button in component page." lightbox ="./media/how-to-create-component-pipelines-ui/register-component-entry-button.png":::
 
-    ```CLI
-    az ml component create --file train.yml
-    az ml component create --file score.yml
-    az ml component create --file eval.yml
-    ```
+1. This example will use `train.yml` [in the directory](https://github.com/Azure/azureml-examples/tree/main/cli/jobs/pipelines-with-components/basics/1b_e2e_registered_components). The YAML file defines the name, type, interface including inputs and outputs, code, environment and command of this component. The code of this component `train.py` is under `./train_src` folder, which describes the execution logic of this component. To learn more about the component schema, see the [command component YAML schema reference](reference-yaml-component-command.md).
+
+>[!Note]
+> When register components in UI, `code` defined in the component YAML file can only point to the current folder where YAML file locates or the subfolders, which means you cannot specify `../` for `code` as UI cannot recognize the parent directory.
+> `additional_includes` can only point to the current or sub folder.
+
+
+1. Select Upload from **Folder**, and select the `1b_e2e_registered_components` folder to upload. Select `train.yml` from the drop down list below.
+
+:::image type="content" source="./media/how-to-create-component-pipelines-ui/upload-from-local-folder.png" alt-text="Screenshot showing upload from local folder." lightbox ="./media/how-to-create-component-pipelines-ui/upload-from-local-folder.png":::
+
+1. Select **Next** in the bottom, and you can confirm the details of this component. Once you've confirmed, select **Create** to finish the registration process.
+
+1. Repeat the steps above to register Score and Eval component using `score.yml` and `eval.yml` as well.
 
-1. After register component successfully, you can see your component in the studio UI.
+1. After registering the three components successfully, you can see your components in the studio UI.
 
 :::image type="content" source="./media/how-to-create-component-pipelines-ui/component-page.png" alt-text="Screenshot showing registered component in component page." lightbox ="./media/how-to-create-component-pipelines-ui/component-page.png":::
 
@@ -104,7 +113,7 @@ In the example below take using CLI for example. If you want to learn more about
 
 1. Select submit, and fill in the required information for your pipeline job.
 
-    :::image type="content" source="./media/how-to-create-component-pipelines-ui/submit-pipeline.png" alt-text="Screenshot of set up pipeline job with submit highlighted." lightbox ="./media/how-to-create-component-pipelines-ui/submit-pipeline.png":::
+    :::image type="content" source="./media/how-to-create-component-pipelines-ui/submit-pipeline.png" alt-text="Screenshot of setup pipeline job with submit highlighted." lightbox ="./media/how-to-create-component-pipelines-ui/submit-pipeline.png":::
 
 1. After submit successfully, you'll see a job detail page link in the left page. Select **Job detail** to go to pipeline job detail page for checking status and debugging.
 

articles/machine-learning/media/how-to-create-component-pipelines-ui/register-component-entry-button.png

@@ -37,7 +37,7 @@ The source JSON schema can be found at https://azuremlschemas.azureedge.net/late
 | `is_deterministic` | boolean |This option determines if the component will produce the same output for the same input data. You should usually set this to `false` for components that load data from external sources, such as importing data from a URL. This is because the data at the URL might change over time. | | `true` |
 | `command` | string | **Required.** The command to execute. | | |
 | `code` | string | Local path to the source code directory to be uploaded and used for the component. | | |
-| `environment` | string or object | **Required.** The environment to use for the component. This value can be either a reference to an existing versioned environment in the workspace or an inline environment specification. <br><br> To reference an existing environment, use the `azureml:<environment-name>:<environment-version>` syntax. <br><br> To define an environment inline, follow the [Environment schema](reference-yaml-environment.md#yaml-syntax). Exclude the `name` and `version` properties as they are not supported for inline environments. | | |
+| `environment` | string or object | **Required.** The environment to use for the component. This value can be either a reference to an existing versioned environment in the workspace or an inline environment specification. <br><br> To reference an existing environment, use the `azureml:<environment-name>:<environment-version>` syntax. <br><br> To define an environment inline, follow the [Environment schema](reference-yaml-environment.md#yaml-syntax). Exclude the `name` and `version` properties as they aren't supported for inline environments. | | |
 | `distribution` | object | The distribution configuration for distributed training scenarios. One of [MpiConfiguration](#mpiconfiguration), [PyTorchConfiguration](#pytorchconfiguration), or [TensorFlowConfiguration](#tensorflowconfiguration). | | |
 | `resources.instance_count` | integer | The number of nodes to use for the job. | | `1` |
 | `inputs` | object | Dictionary of component inputs. The key is a name for the input within the context of the component and the value is the component input definition. <br><br> Inputs can be referenced in the `command` using the `${{ inputs.<input_name> }}` expression. | | |
@@ -108,7 +108,7 @@ Examples are available in the [examples GitHub repository](https://github.com/Az
 
 ### Define optional inputs in command line
 When the input is set as `optional = true`, you need use `$[[]]` to embrace the command line with inputs. For example `$[[--input1 ${{inputs.input1}}]`. The command line at runtime may have different inputs.
-- If  you are using only specify the required `training_data` and `model_output` parameters, the command line will look like:
+- If  you're using only specify the required `training_data` and `model_output` parameters, the command line will look like:
 
 ```azurecli
 python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path
@@ -121,6 +121,15 @@ If no value is specified at runtime, `learning_rate` and `learning_rate_schedule
 python train.py --training_data some_input_path --max_epocs 10 --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path
 ```
 
+## Common errors and recommendation
+
+Following are some common errors and corresponding recommended suggestions when you define a component.
+
+| Key | Errors | Recommendation | 
+| --- | ---- | ----------- |
+|command|1. Only optional inputs can be in `$[[]]`<br> 2. Using `\` to make a new line isn't supported in command.<br>3. Inputs or outputs aren't found.|1. Check that all the inputs or outputs used in command are already defined in the `inputs` and `outputs` sections, and use the correct format for optional inputs `$[[]]` or required ones `${{}}`.<br>2. Don't use `\` to make a new line.|
+|environment|1. No definition exists for environment `{envName}` version `{envVersion}`. <br>2. No environment exists for name `{envName}`, version `{envVersion}`.<br>3. Couldn't find asset with ID `{envAssetId}`. |1. Make sure the environment name and version you refer in the component definition exists. <br>2. You need to specify the version if you refer to a registered environment.|
+|inputs/outputs|1. Inputs/outputs names conflict with system reserved parameters.<br>2. Duplicated names of inputs or outputs.|1. Don't use any of these reserved parameters as your inputs/outputs name: `path`, `ld_library_path`, `user`, `logname`, `home`, `pwd`, `shell`.<br>2. Make sure names of inputs and outputs aren't duplicated.|
 
 ## Next steps