Merge pull request #705 from GitHubber17/310675-c

Freshness: 310675 Azure Machine Learning

Author: v-shils

articles/machine-learning/v1/how-to-train-with-custom-image.md

@@ -1,46 +1,51 @@
 ---
 title: Train a model by using a custom Docker image
 titleSuffix: Azure Machine Learning
-description: Learn how to use your own Docker images, or curated ones from Microsoft, to train models in Azure Machine Learning.
+description: Learn how to use your own Docker images, or curated images from Microsoft, to train models in Azure Machine Learning.
 services: machine-learning
 ms.service: azure-machine-learning
 ms.subservice: core
 ms.author: ssalgado
 author: saachigopal
 ms.reviewer: ssalgado
-ms.date: 11/14/2023
+ms.date: 10/08/2024
 ms.topic: how-to
 ms.custom: UpdateFrequency5, sdkv1
+
+#Customer intent: As a data scientist professional, I want to use Docker or other curated images in Azure Machine Learning, so I can train models.
 ---
 
 # Train a model by using a custom Docker image
 
 [!INCLUDE [sdk v1](../includes/machine-learning-sdk-v1.md)]
 
-In this article, learn how to use a custom Docker image when you're training models with Azure Machine Learning. You'll use the example scripts in this article to classify pet images by creating a convolutional neural network. 
+This article describes how to use a custom Docker image to train models with Azure Machine Learning. Example scripts show how to classify images by creating a convolutional neural network. 
 
-Azure Machine Learning provides a default Docker base image. You can also use Azure Machine Learning environments to specify a different base image, such as one of the maintained [Azure Machine Learning base images](https://github.com/Azure/AzureML-Containers) or your own [custom image](../how-to-deploy-custom-container.md). Custom base images allow you to closely manage your dependencies and maintain tighter control over component versions when running training jobs.
+Azure Machine Learning provides a default Docker base image. You can also use Azure Machine Learning environments to specify a different base image, such as a maintained [Azure Machine Learning base image](https://github.com/Azure/AzureML-Containers) or your own [custom image](../how-to-deploy-custom-container.md). Custom base images allow you to closely manage your dependencies and maintain tighter control over component versions when you run training jobs.
 
 ## Prerequisites
 
-Run the code on either of these environments:
+To run the example code, your configuration must include one of the following environments:
+
+- Azure Machine Learning compute instance with a dedicated notebook server preloaded with the Machine Learning SDK and Samples repository.
+
+   This configuration requires no downloads or other installation. To prepare this environment, see [Create resources to get started](../quickstart-create-resources.md).
+
+- Jupyter Notebook server. The following resources provide instructions to help you prepare this environment:
 
-* Azure Machine Learning compute instance (no downloads or installation necessary):
-  * Complete the [Create resources to get started](../quickstart-create-resources.md) tutorial to create a dedicated notebook server preloaded with the SDK and the sample repository.
-* Your own Jupyter Notebook server:
-  * Create a [workspace configuration file](../how-to-configure-environment.md#local-and-dsvm-only-create-a-workspace-configuration-file).
-  * Install the [Azure Machine Learning SDK](/python/api/overview/azure/ml/install). 
-  * Create an [Azure container registry](/azure/container-registry/) or other Docker registry that's available on the internet.
+   - Create a [workspace configuration file](../how-to-configure-environment.md#local-and-dsvm-only-create-a-workspace-configuration-file).
+   - Install the [Azure Machine Learning SDK](/python/api/overview/azure/ml/install).
+   - Create an [Azure container registry](/azure/container-registry/) or other Docker registry available on the internet.
 
 ## Set up a training experiment
 
-In this section, you set up your training experiment by initializing a workspace, defining your environment, and configuring a compute target.
+The first task is to set up your training experiment by initializing a Machine Learning workspace, defining your environment, and configuring a compute target.
 
 ### Initialize a workspace
 
-The [Azure Machine Learning workspace](../concept-workspace.md) is the top-level resource for the service. It gives you a centralized place to work with all the artifacts that you create. In the Python SDK, you can access the workspace artifacts by creating a [`Workspace`](/python/api/azureml-core/azureml.core.workspace.workspace) object.
+The [Azure Machine Learning workspace](../concept-workspace.md) is the top-level resource for the service. It gives you a centralized place to work with all the artifacts you create. In the Python SDK, you can access the workspace artifacts by creating a [`Workspace`](/python/api/azureml-core/azureml.core.workspace.workspace) object.
 
-Create a `Workspace` object from the config.json file that you created as a [prerequisite](#prerequisites).
+As needed, create a `Workspace` object from the config.json file that you created as a [prerequisite](#prerequisites).
 
 ```Python
 from azureml.core import Workspace
@@ -60,7 +65,7 @@ fastai_env = Environment("fastai2")
 
 The specified base image in the following code supports the fast.ai library, which allows for distributed deep-learning capabilities. For more information, see the [fast.ai Docker Hub repository](https://hub.docker.com/u/fastdotai). 
 
-When you're using your custom Docker image, you might already have your Python environment properly set up. In that case, set the `user_managed_dependencies` flag to `True` to use your custom image's built-in Python environment. By default, Azure Machine Learning builds a Conda environment with dependencies that you specified. The service runs the script in that environment instead of using any Python libraries that you installed on the base image.
+When you use your custom Docker image, you might already have your Python environment properly set up. In that case, set the `user_managed_dependencies` flag to `True` to use your custom image's built-in Python environment. By default, Azure Machine Learning builds a Conda environment with dependencies that you specified. The service runs the script in that environment instead of using any Python libraries that you installed on the base image.
 
 ```python
 fastai_env.docker.base_image = "fastdotai/fastai2:latest"
@@ -72,7 +77,7 @@ fastai_env.python.user_managed_dependencies = True
 To use an image from a private container registry that isn't in your workspace, use `docker.base_image_registry` to specify the address of the repository and a username and password:
 
 ```python
-# Set the container registry information.
+# Set the container registry information
 fastai_env.docker.base_image_registry.address = "myregistry.azurecr.io"
 fastai_env.docker.base_image_registry.username = "username"
 fastai_env.docker.base_image_registry.password = "password"
@@ -83,27 +88,27 @@ fastai_env.docker.base_image_registry.password = "password"
 It's also possible to use a custom Dockerfile. Use this approach if you need to install non-Python packages as dependencies. Remember to set the base image to `None`.
 
 ```python 
-# Specify Docker steps as a string. 
+# Specify Docker steps as a string
 dockerfile = r"""
 FROM mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210615.v1
 RUN echo "Hello from custom container!"
 """
 
-# Set the base image to None, because the image is defined by Dockerfile.
+# Set the base image to None, because the image is defined by Dockerfile
 fastai_env.docker.base_image = None
 fastai_env.docker.base_dockerfile = dockerfile
 
-# Alternatively, load the string from a file.
+# Alternatively, load the string from a file
 fastai_env.docker.base_image = None
 fastai_env.docker.base_dockerfile = "./Dockerfile"
 ```
 
->[!IMPORTANT]
+> [!IMPORTANT]
 > Azure Machine Learning only supports Docker images that provide the following software:
-> * Ubuntu 18.04 or greater.
-> * Conda 4.7.# or greater.
-> * Python 3.7+.
-> * A POSIX compliant shell available at /bin/sh is required in any container image used for training. 
+> * Ubuntu 18.04 or greater
+> * Conda 4.7.# or greater
+> * Python 3.7+
+> * A POSIX compliant shell available at /bin/sh is required in any container image used for training
 
 For more information about creating and managing Azure Machine Learning environments, see [Create and use software environments](../how-to-use-environments.md). 
 
@@ -119,7 +124,7 @@ As with other Azure services, there are limits on certain resources (for example
 from azureml.core.compute import ComputeTarget, AmlCompute
 from azureml.core.compute_target import ComputeTargetException
 
-# Choose a name for your cluster.
+# Choose a name for your cluster
 cluster_name = "gpu-cluster"
 
 try:
@@ -130,19 +135,17 @@ except ComputeTargetException:
     compute_config = AmlCompute.provisioning_configuration(vm_size='STANDARD_NC6',
                                                            max_nodes=4)
 
-    # Create the cluster.
+    # Create the cluster
     compute_target = ComputeTarget.create(ws, cluster_name, compute_config)
 
     compute_target.wait_for_completion(show_output=True)
 
-# Use get_status() to get a detailed status for the current AmlCompute.
+# Use get_status() to get a detailed status for the current AmlCompute
 print(compute_target.get_status().serialize())
 ```
 
-
->[!IMPORTANT]
->Use CPU SKUs for any image build on compute. 
-
+> [!IMPORTANT]
+> Use CPU SKUs for any image build on compute. 
 
 ## Configure your training job
 
@@ -173,7 +176,7 @@ run.wait_for_completion(show_output=True)
 > [!WARNING]
 > Azure Machine Learning runs training scripts by copying the entire source directory. If you have sensitive data that you don't want to upload, use an [.ignore file](../concept-train-machine-learning-model.md#understand-what-happens-when-you-submit-a-training-job) or don't include it in the source directory. Instead, access your data by using a [datastore](/python/api/azureml-core/azureml.data).
 
-## Next steps
-In this article, you trained a model by using a custom Docker image. See these other articles to learn more about Azure Machine Learning:
-* [Track run metrics](../how-to-log-view-metrics.md) during training.
-* [Deploy a model](../how-to-deploy-custom-container.md) by using a custom Docker image.
+## Related content
+
+* [Track run metrics](../how-to-log-view-metrics.md)
+* [Deploy a model by using a custom Docker image](../how-to-deploy-custom-container.md)