Merge pull request #266861 from sdgilley/sdg-freshness

freshness update set-up-training-targets

Author: prmerger-automator[bot]

articles/machine-learning/v1/how-to-set-up-training-targets.md

@@ -8,7 +8,7 @@ ms.author: sgilley
 ms.reviewer: sgilley
 ms.service: machine-learning
 ms.subservice: training
-ms.date: 10/21/2021
+ms.date: 02/21/2024
 ms.topic: how-to
 ms.custom: UpdateFrequency5,sdkv1
 ---
@@ -17,23 +17,24 @@ ms.custom: UpdateFrequency5,sdkv1
 
 [!INCLUDE [sdk v1](../includes/machine-learning-sdk-v1.md)]
 
-In this article, you learn how to configure and submit Azure Machine Learning jobs to train your models. Snippets of code explain the key parts of configuration and submission of a training script.  Then use one of the [example notebooks](#notebook-examples) to find the full end-to-end working examples.
+In this article, you learn how to configure and submit Azure Machine Learning jobs to train your models. Snippets of code explain the key parts of configuration and submission of a training script. Then use one of the [example notebooks](#notebook-examples) to find the full end-to-end working examples.
 
 When training, it is common to start on your local computer, and then later scale out to a cloud-based cluster. With Azure Machine Learning, you can run your script on various compute targets without having to change your training script.
 
-All you need to do is define the environment for each compute target within a **script job configuration**.  Then, when you want to run your training experiment on a different compute target, specify the job configuration for that compute.
+All you need to do is define the environment for each compute target within a **script job configuration**. Then, when you want to run your training experiment on a different compute target, specify the job configuration for that compute.
 
 ## Prerequisites
 
 * If you don't have an Azure subscription, create a free account before you begin. Try the [free or paid version of Azure Machine Learning](https://azure.microsoft.com/free/) today
-* The [Azure Machine Learning SDK for Python](/python/api/overview/azure/ml/install) (>= 1.13.0)
+* The [Azure Machine Learning SDK for Python (v1)](/python/api/overview/azure/ml/install) (>= 1.13.0)
 * An [Azure Machine Learning workspace](../how-to-manage-workspace.md), `ws`
-* A compute target, `my_compute_target`.  [Create a compute target](../how-to-create-attach-compute-studio.md) 
+* A compute target, `my_compute_target`. [Create a compute target](../how-to-create-attach-compute-studio.md) 
 
 ## What's a script run configuration?
+
 A [ScriptRunConfig](/python/api/azureml-core/azureml.core.scriptrunconfig) is used to configure the information necessary for submitting a training job as part of an experiment.
 
-You submit your training experiment with a ScriptRunConfig object.  This object includes the:
+You submit your training experiment with a ScriptRunConfig object. This object includes the:
 
 * **source_directory**: The source directory that contains your training script
 * **script**: The training script to run
@@ -46,7 +47,7 @@ You submit your training experiment with a ScriptRunConfig object.  This object
 The code pattern to submit a training job is the same for all types of compute targets:
 
 1. Create an experiment to run
-1. Create an environment where the script will run
+1. Create an environment where the script runs
 1. Create a ScriptRunConfig, which specifies the compute target and environment
 1. Submit the job
 1. Wait for the job to complete
@@ -60,6 +61,8 @@ Or you can:
 
 Create an [experiment](concept-azure-machine-learning-architecture.md#experiments) in your workspace. An experiment is a light-weight container that helps to organize job submissions and keep track of code.
 
+[!INCLUDE [sdk v1](../includes/machine-learning-sdk-v1.md)]
+
 ```python
 from azureml.core import Experiment
 
@@ -80,10 +83,12 @@ The example code in this article assumes that you have already created a compute
 ## Create an environment
 Azure Machine Learning [environments](../concept-environments.md) are an encapsulation of the environment where your machine learning training happens. They specify the Python packages, Docker image, environment variables, and software settings around your training and scoring scripts. They also specify runtimes (Python, Spark, or Docker).
 
-You can either define your own environment, or use an Azure Machine Learning curated environment. [Curated environments](../how-to-use-environments.md#use-a-curated-environment) are predefined environments that are available in your workspace by default. These environments are backed by cached Docker images which reduce the job preparation cost. See [Azure Machine Learning Curated Environments](../resource-curated-environments.md) for the full list of available curated environments.
+You can either define your own environment, or use an Azure Machine Learning curated environment. [Curated environments](../how-to-use-environments.md#use-a-curated-environment) are predefined environments that are available in your workspace by default. These environments are backed by cached Docker images, which reduce the job preparation cost. See [Azure Machine Learning Curated Environments](../resource-curated-environments.md) for the full list of available curated environments.
 
 For a remote compute target, you can use one of these popular curated environments to start with:
 
+[!INCLUDE [sdk v1](../includes/machine-learning-sdk-v1.md)]
+
 ```python
 from azureml.core import Workspace, Environment
 
@@ -95,7 +100,9 @@ For more information and details about environments, see [Create & use software
 
 ### Local compute target
 
-If your compute target is your **local machine**, you are responsible for ensuring that all the necessary packages are available in the Python environment where the script runs.  Use `python.user_managed_dependencies` to use your current Python environment (or the Python on the path you specify).
+If your compute target is your **local machine**, you're responsible for ensuring that all the necessary packages are available in the Python environment where the script runs. Use `python.user_managed_dependencies` to use your current Python environment (or the Python on the path you specify).
+
+[!INCLUDE [sdk v1](../includes/machine-learning-sdk-v1.md)]
 
 ```python
 from azureml.core import Environment
@@ -109,7 +116,9 @@ myenv.python.user_managed_dependencies = True
 
 ## Create the script job configuration
 
-Now that you have a compute target (`my_compute_target`, see [Prerequisites](#prerequisites) and environment (`myenv`, see [Create an environment](#create-an-environment)), create a script job configuration that runs your training script (`train.py`) located in your `project_folder` directory:
+Now that you have a compute target (`my_compute_target`, see [Prerequisites,](#prerequisites) and environment (`myenv`, see [Create an environment](#create-an-environment)), create a script job configuration that runs your training script (`train.py`) located in your `project_folder` directory:
+
+[!INCLUDE [sdk v1](../includes/machine-learning-sdk-v1.md)]
 
 ```python
 from azureml.core import ScriptRunConfig
@@ -119,33 +128,33 @@ src = ScriptRunConfig(source_directory=project_folder,
                       compute_target=my_compute_target,
                       environment=myenv)
 
-# Set compute target
-# Skip this if you are running on your local computer
-script_run_config.run_config.target = my_compute_target
 ```
 
-If you do not specify an environment, a default environment will be created for you.
+If you don't specify an environment, a default environment will be created for you.
 
-If you have command-line arguments you want to pass to your training script, you can specify them via the **`arguments`** parameter of the ScriptRunConfig constructor, e.g. `arguments=['--arg1', arg1_val, '--arg2', arg2_val]`.
+If you have command-line arguments you want to pass to your training script, you can specify them via the **`arguments`** parameter of the ScriptRunConfig constructor, for example, `arguments=['--arg1', arg1_val, '--arg2', arg2_val]`.
 
-If you want to override the default maximum time allowed for the job, you can do so via the **`max_run_duration_seconds`** parameter. The system will attempt to automatically cancel the job if it takes longer than this value.
+If you want to override the default maximum time allowed for the job, you can do so via the **`max_run_duration_seconds`** parameter. The system attempts to automatically cancel the job if it takes longer than this value.
 
 ### Specify a distributed job configuration
+
 If you want to run a [distributed training](../how-to-train-distributed-gpu.md) job, provide the distributed job-specific config to the **`distributed_job_config`** parameter. Supported config types include [MpiConfiguration](/python/api/azureml-core/azureml.core.runconfig.mpiconfiguration), [TensorflowConfiguration](/python/api/azureml-core/azureml.core.runconfig.tensorflowconfiguration), and [PyTorchConfiguration](/python/api/azureml-core/azureml.core.runconfig.pytorchconfiguration). 
 
-For more information and examples on running distributed Horovod, TensorFlow and PyTorch jobs, see:
+For more information and examples on running distributed Horovod, TensorFlow, and PyTorch jobs, see:
 
 * [Distributed training of deep learning models on Azure](/azure/architecture/reference-architectures/ai/training-deep-learning)
 
 ## Submit the experiment
 
+[!INCLUDE [sdk v1](../includes/machine-learning-sdk-v1.md)]
+
 ```python
 run = experiment.submit(config=src)
 run.wait_for_completion(show_output=True)
 ```
 
 > [!IMPORTANT]
-> When you submit the training job, a snapshot of the directory that contains your training scripts is created and sent to the compute target. It is also stored as part of the experiment in your workspace. If you change files and submit the job again, only the changed files will be uploaded.
+> When you submit the training job, a snapshot of the directory that contains your training scripts will be created and sent to the compute target. It is also stored as part of the experiment in your workspace. If you change files and submit the job again, only the changed files will be uploaded.
 >
 > [!INCLUDE [amlinclude-info](../includes/machine-learning-amlignore-gitignore.md)]
 > 
@@ -157,7 +166,7 @@ run.wait_for_completion(show_output=True)
 >
 > To create artifacts during training (such as model files, checkpoints, data files, or plotted images) write these to the `./outputs` folder.
 >
-> Similarly, you can write any logs from your training job to the `./logs` folder. To utilize Azure Machine Learning's [TensorBoard integration](https://github.com/Azure/MachineLearningNotebooks/blob/master/how-to-use-azureml/track-and-monitor-experiments/tensorboard/export-run-history-to-tensorboard/export-run-history-to-tensorboard.ipynb) make sure you write your TensorBoard logs to this folder. While your job is in progress, you will be able to launch TensorBoard and stream these logs.  Later, you will also be able to restore the logs from any of your previous jobs.
+> Similarly, you can write any logs from your training job to the `./logs` folder. To utilize Azure Machine Learning's [TensorBoard integration](https://github.com/Azure/MachineLearningNotebooks/blob/master/how-to-use-azureml/track-and-monitor-experiments/tensorboard/export-run-history-to-tensorboard/export-run-history-to-tensorboard.ipynb) make sure you write your TensorBoard logs to this folder. While your job is in progress, you will be able to launch TensorBoard and stream these logs. Later, you will also be able to restore the logs from any of your previous jobs.
 >
 > For example, to download a file written to the *outputs* folder to your local machine after your remote training job: 
 > `run.download_file(name='outputs/my_output_file', output_file_path='my_destination_path')`
@@ -177,25 +186,25 @@ See these notebooks for examples of configuring jobs for various training scenar
 
 ## Troubleshooting
 
-* **AttributeError: 'RoundTripLoader' object has no attribute 'comment_handling'**: This error comes from the new version (v0.17.5) of `ruamel-yaml`, an `azureml-core` dependency, that introduces a breaking change to `azureml-core`. In order to fix this error, please uninstall `ruamel-yaml` by running `pip uninstall ruamel-yaml` and installing a different version of `ruamel-yaml`; the supported versions are v0.15.35 to v0.17.4 (inclusive). You can do this by running `pip install "ruamel-yaml>=0.15.35,<0.17.5"`.
+* **AttributeError: 'RoundTripLoader' object has no attribute 'comment_handling'**: This error comes from the new version (v0.17.5) of `ruamel-yaml`, an `azureml-core` dependency, that introduces a breaking change to `azureml-core`. In order to fix this error, uninstall `ruamel-yaml` by running `pip uninstall ruamel-yaml` and installing a different version of `ruamel-yaml`; the supported versions are v0.15.35 to v0.17.4 (inclusive). You can do this by running `pip install "ruamel-yaml>=0.15.35,<0.17.5"`.
 
 
 * **Job fails with `jwt.exceptions.DecodeError`**: Exact error message: `jwt.exceptions.DecodeError: It is required that you pass in a value for the "algorithms" argument when calling decode()`. 
 
     Consider upgrading to the latest version of azureml-core: `pip install -U azureml-core`.
 
-    If you are running into this issue for local jobs, check the version of PyJWT installed in your environment where you are starting jobs. The supported versions of PyJWT are < 2.0.0. Uninstall PyJWT from the environment if the version is >= 2.0.0. You may check the version of PyJWT, uninstall and install the right version as follows:
+    If . you're running into this issue for local jobs, check the version of PyJWT installed in your environment where . you're starting jobs. The supported versions of PyJWT are < 2.0.0. Uninstall PyJWT from the environment if the version is >= 2.0.0. You may check the version of PyJWT, uninstall, and install the right version as follows:
     1. Start a command shell, activate conda environment where azureml-core is installed.
     2. Enter `pip freeze` and look for `PyJWT`, if found, the version listed should be < 2.0.0
     3. If the listed version is not a supported version, `pip uninstall PyJWT` in the command shell and enter y for confirmation.
     4. Install using `pip install 'PyJWT<2.0.0'`
 
-    If you are submitting a user-created environment with your job, consider using the latest version of azureml-core in that environment. Versions >= 1.18.0 of azureml-core already pin PyJWT < 2.0.0. If you need to use a version of azureml-core < 1.18.0 in the environment you submit, make sure to specify PyJWT < 2.0.0 in your pip dependencies.
+    If . you're submitting a user-created environment with your job, consider using the latest version of azureml-core in that environment. Versions >= 1.18.0 of azureml-core already pin PyJWT < 2.0.0. If you need to use a version of azureml-core < 1.18.0 in the environment you submit, make sure to specify PyJWT < 2.0.0 in your pip dependencies.
 
 
- * **ModuleErrors (No module named)**:  If you are running into ModuleErrors while submitting experiments in Azure Machine Learning, the training script is expecting a package to be installed but it isn't added. Once you provide the package name, Azure Machine Learning installs the package in the environment used for your training job.
+ * **ModuleErrors (No module named)**:  If . you're running into ModuleErrors while submitting experiments in Azure Machine Learning, the training script is expecting a package to be installed but it isn't added. Once you provide the package name, Azure Machine Learning installs the package in the environment used for your training job.
 
-    If you are using Estimators to submit experiments, you can specify a package name via `pip_packages` or `conda_packages` parameter in the estimator based on from which source you want to install the package. You can also specify a yml file with all your dependencies using `conda_dependencies_file`or list all your pip requirements in a txt file using `pip_requirements_file` parameter. If you have your own Azure Machine Learning Environment object that you want to override the default image used by the estimator, you can specify that environment via the `environment` parameter of the estimator constructor.
+    If . you're using Estimators to submit experiments, you can specify a package name via `pip_packages` or `conda_packages` parameter in the estimator based on from which source you want to install the package. You can also specify a yml file with all your dependencies using `conda_dependencies_file`or list all your pip requirements in a txt file using `pip_requirements_file` parameter. If you have your own Azure Machine Learning Environment object that you want to override the default image used by the estimator, you can specify that environment via the `environment` parameter of the estimator constructor.
 
     Azure Machine Learning maintained docker images and their contents can be seen in [Azure Machine Learning Containers](https://github.com/Azure/AzureML-Containers).
     Framework-specific dependencies  are listed in the respective framework documentation: