Merge pull request #824 from MicrosoftDocs/main

10/15/2024 AM Publish

Author: Taojunshen

articles/machine-learning/how-to-migrate-from-v1.md

@@ -8,10 +8,11 @@ ms.subservice: core
 ms.topic: how-to
 author: sdgilley
 ms.author: sgilley
-ms.date: 02/22/2024
-ms.reviewer: balapv
+ms.date: 10/14/2024
+ms.reviewer: paulsh
 ms.custom: devplatv2, devx-track-python
 monikerRange: 'azureml-api-2 || azureml-api-1'
+#customer intent: As a developer, I want to understand the differences between v1 and v2 of Azure Machine Learning REST APIs, CLI extension, and Python SDK, to decide which I should use.
 ---
 
 # Upgrade to v2
@@ -36,7 +37,7 @@ A new v2 project can reuse existing v1 resources like workspaces and compute and
 
 Some feature gaps in v2 include:
 
-- Spark support in jobs - this is currently in preview in v2.
+- Spark support in jobs -  currently in preview in v2.
 - Publishing jobs (pipelines in v1) as endpoints. You can however, schedule pipelines without publishing.
 - Support for SQL/database datastores.
 - Ability to use classic prebuilt components in the designer with v2.
@@ -100,13 +101,13 @@ For a comparison of SDK v1 and v2 code, see [Workspace management in SDK v1 and
 
 ### Datastore
 
-Object storage datastore types created with v1 are fully available for use in v2. Database datastores are not supported; export to object storage (usually Azure Blob) is the recommended migration path.
+Object storage datastore types created with v1 are fully available for use in v2. Database datastores aren't supported; export to object storage (usually Azure Blob) is the recommended migration path.
 
 For a comparison of SDK v1 and v2 code, see [Datastore management in SDK v1 and SDK v2](migrate-to-v2-resource-datastore.md).
 
 ### Data (datasets in v1)
 
-Datasets are renamed to data assets. *Backwards compatibility* is provided, which means you can use V1 Datasets in V2. When you consume a V1 Dataset in a V2 job you will notice they are automatically mapped into V2 types as follows:
+Datasets are renamed to data assets. *Backwards compatibility* is provided, which means you can use V1 Datasets in V2. When you consume a V1 Dataset in a V2 job, you'll notice they're automatically mapped into V2 types as follows:
 
 * V1 FileDataset = V2 Folder (`uri_folder`)
 * V1 TabularDataset = V2 Table (`mltable`)
@@ -126,7 +127,7 @@ For a comparison of SDK v1 and v2 code, see [Compute management in SDK v1 and SD
 
 ### Jobs (experiments, runs, pipelines in v1)
 
-In v2, "experiments", "runs", and "pipelines" are consolidated into jobs. A job has a type. Most jobs are `command` jobs that run a command, like `python main.py`. What runs in a job is agnostic to any programming language, so you can run `bash` scripts, invoke `python` interpreters, run a bunch of `curl` commands, or anything else. Another common type of job is `pipeline`, which defines child jobs that may have input/output relationships, forming a directed acyclic graph (DAG).
+In v2, "experiments," "runs," and "pipelines" are consolidated into jobs. A job has a type. Most jobs are `command` jobs that run a command, like `python main.py`. What runs in a job is agnostic to any programming language, so you can run `bash` scripts, invoke `python` interpreters, run a bunch of `curl` commands, or anything else. Another common type of job is `pipeline`, which defines child jobs that might have input/output relationships, forming a directed acyclic graph (DAG).
 
 For a comparison of SDK v1 and v2 code, see 
 * [Run a script](migrate-to-v2-command-job.md)
@@ -140,9 +141,9 @@ For a comparison of SDK v1 and v2 code, see
 
 You can use designer to build pipelines using your own v2 custom components and the new prebuilt components from registry. In this situation, you can use v1 or v2 data assets in your pipeline. 
 
-You can continue to use designer to build pipelines using classic prebuilt components and v1 dataset types (tabular, file). You cannot use existing designer classic prebuilt components with v2 data asset.
+You can continue to use designer to build pipelines using classic prebuilt components and v1 dataset types (tabular, file). You can't use existing designer classic prebuilt components with v2 data asset.
 
-You cannot build a pipeline using both existing designer classic prebuilt components and v2 custom components.
+You can't build a pipeline using both existing designer classic prebuilt components and v2 custom components.
 
 
 ### Model
@@ -153,7 +154,7 @@ For a comparison of SDK v1 and v2 code, see [Model management in SDK v1 and SDK
 
 ### Endpoint and deployment (endpoint and web service in v1)
 
-With SDK/CLI v1, you can deploy models on ACI or AKS as web services. Your existing v1 model deployments and web services will continue to function as they are, but Using SDK/CLI v1 to deploy models on ACI or AKS as web services is now considered as **legacy**. For new model deployments, we recommend upgrading to v2. In v2, we offer [managed endpoints or Kubernetes endpoints](./concept-endpoints.md?view=azureml-api-2&preserve-view=true). The following table guides our recommendation:
+With SDK/CLI v1, you can deploy models on ACI or AKS as web services. Your existing v1 model deployments and web services continue to function as they are, but Using SDK/CLI v1 to deploy models on ACI or AKS as web services is now considered as **legacy**. For new model deployments, we recommend upgrading to v2. In v2, we offer [managed endpoints or Kubernetes endpoints](./concept-endpoints.md?view=azureml-api-2&preserve-view=true). The following table guides our recommendation:
 
 |Endpoint type in v2|Upgrade from|Notes|
 |-|-|-|
@@ -172,7 +173,7 @@ Environments created from v1 can be used in v2. In v2, environments have new fea
 
 ## Managing secrets
 
-The management of Key Vault secrets differs significantly in V2 compared to V1. The V1 set_secret and get_secret SDK methods are not available in V2. Instead, direct access using Key Vault client libraries should be used. When accessing secrets from a training script, you can use either the managed identity of the compute or your identity.
+The management of Key Vault secrets differs significantly in V2 compared to V1. The V1 set_secret and get_secret SDK methods aren't available in V2. Instead, direct access using Key Vault client libraries should be used. When accessing secrets from a training script, you can use either the managed identity of the compute or your identity.
 
 For details about Key Vault, see [Use authentication credential secrets in Azure Machine Learning training jobs](how-to-use-secrets-in-runs.md?view=azureml-api-2&preserve-view=true).
 
@@ -184,11 +185,11 @@ There are a few scenarios that are common across the machine learning lifecycle
 
 Azure recommends Azure Resource Manager templates (often via Bicep for ease of use) to create resources. The same is a good approach for creating Azure Machine Learning resources as well.
 
-If your team is only using Azure Machine Learning, you may consider provisioning the workspace and any other resources via YAML  files and CLI instead.
+If your team is only using Azure Machine Learning, you might consider provisioning the workspace and any other resources via YAML  files and CLI instead.
 
 ### Prototyping models
 
-We recommend v2 for prototyping models. You may consider using the CLI for an interactive use of Azure Machine Learning, while your model training code is Python or any other programming language. Alternatively, you may adopt a full-stack approach with Python solely using the Azure Machine Learning SDK or a mixed approach with the Azure Machine Learning Python SDK and YAML files.
+We recommend v2 for prototyping models. You might consider using the CLI for an interactive use of Azure Machine Learning, while your model training code is Python or any other programming language. Alternatively, you might adopt a full-stack approach with Python solely using the Azure Machine Learning SDK or a mixed approach with the Azure Machine Learning Python SDK and YAML files.
 
 ### Production model training
 
@@ -210,30 +211,28 @@ The solution accelerator for MLOps with v2 is being developed at https://github.
 
 ### A note on GitOps with v2
 
-A key paradigm with v2 is serializing machine learning entities as YAML files for source control with `git`, enabling better GitOps approaches than were possible with v1. For instance, you could enforce policy by which only a service principal used in CI/CD pipelines can create/update/delete some or all entities, ensuring changes go through a governed process like pull requests with required reviewers. Since the files in source control are YAML, they're easy to diff and track changes over time. You and your team may consider shifting to this paradigm as you upgrade to v2.
+A key paradigm with v2 is serializing machine learning entities as YAML files for source control with `git`, enabling better GitOps approaches than were possible with v1. For instance, you could enforce policy by which only a service principal used in CI/CD pipelines can create/update/delete some or all entities, ensuring changes go through a governed process like pull requests with required reviewers. Since the files in source control are YAML, they're easy to diff and track changes over time. You and your team might consider shifting to this paradigm as you upgrade to v2.
 
-You can obtain a YAML representation of any entity with the CLI via `az ml <entity> show --output yaml`. Note that this output will have system-generated properties, which can be ignored or deleted.
+You can obtain a YAML representation of any entity with the CLI via `az ml <entity> show --output yaml`. This output has system-generated properties, which can be ignored or deleted.
 
 ## Should I upgrade existing v1 code to v2
 
-You can reuse your existing v1 assets in your v2 workflows. For instance a model created in v1 can be used to perform Managed Inferencing in v2.
+You can reuse your existing v1 assets in your v2 workflows. For instance, a model created in v1 can be used to perform Managed Inferencing in v2.
 
-Optionally, if you want to upgrade specific parts of your existing v1 code to v2, please refer to the comparison links provided in this document.
+Optionally, if you want to upgrade specific parts of your existing v1 code to v2, refer to the comparison links provided in this document.
 
 ## Can I use v1 and v2 together?
 
-v1 and v2 can co-exist in a workspace. You can reuse your existing assets in your v2 workflows. For instance a model created in v1 can be used to perform Managed Inferencing in v2. Resources like workspace, compute, and datastore work across v1 and v2, with exceptions. A user can call the v1 Python SDK to change a workspace's description, then using the v2 CLI extension change it again. Jobs (experiments/runs/pipelines in v1) can be submitted to the same workspace from the v1 or v2 Python SDK. A workspace can have both v1 and v2 model deployment endpoints. 
+v1 and v2 can coexist in a workspace. You can reuse your existing assets in your v2 workflows. For instance, a model created in v1 can be used to perform Managed Inferencing in v2. Resources like workspace, compute, and datastore work across v1 and v2, with exceptions. A user can call the v1 Python SDK to change a workspace's description, then using the v2 CLI extension change it again. Jobs (experiments/runs/pipelines in v1) can be submitted to the same workspace from the v1 or v2 Python SDK. A workspace can have both v1 and v2 model deployment endpoints. 
 
 ### Using v1 and v2 code together
 
-We do not recommend using the v1 and v2 SDKs together in the same code. It is technically possible to use v1 and v2 in the same code because they use different Azure namespaces. However, there are many classes with the same name across these namespaces (like Workspace, Model) which can cause confusion and make code readability and debuggability challenging. 
+We don't recommend using the v1 and v2 SDKs together in the same code. It's technically possible to use v1 and v2 in the same code because they use different Azure namespaces. However, there are many classes with the same name across these namespaces (like Workspace, Model) which can cause confusion and make code readability and debuggability challenging. 
 
 > [!IMPORTANT]
 > If your workspace uses a private endpoint, it will automatically have the `v1_legacy_mode` flag enabled, preventing usage of v2 APIs. See [how to configure network isolation with v2](how-to-configure-network-isolation-with-v2.md?view=azureml-api-2&preserve-view=true) for details.
 
-
-
-## Next steps
+## Related content
 
 - [Get started with the CLI (v2)](how-to-configure-cli.md?view=azureml-api-2&preserve-view=true)
 - [Get started with the Python SDK (v2)](https://aka.ms/sdk-v2-install)