你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

跨工作区与注册表共享数据（预览版）

使用 Azure 机器学习注册表可以跨组织中的工作区进行协作。 使用注册表可以共享模型、组件、环境和数据。 使用注册表共享数据目前是一项预览版功能。 在本文中，学习如何：

• 在注册表中创建数据资产。
• 将现有数据资产从工作区共享到注册表
• 使用注册表中的数据资产作为工作区中模型训练作业的输入。

重要

此功能目前处于公开预览状态。 此预览版在提供时没有附带服务级别协议，我们不建议将其用于生产工作负荷。 某些功能可能不受支持或者受限。

有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

使用 Azure 机器学习注册表共享数据可以解决的关键场景

你可能希望在一个中央位置跨多个团队、项目或工作区共享数据。 此类数据没有敏感的访问控制，可以在组织中广泛使用。

示例包括：

• 团队想要共享经过预处理并准备在试验中使用的公共数据集。
• 你的组织已从外部供应商处获取了项目的特定数据集，并希望将其提供给处理项目的所有团队。
• 团队希望在不同区域的工作区之间共享数据资产。

在这些场景中，可以在注册表中创建数据资产，或将现有数据资产从工作区共享到注册表。 然后，可以在多个工作区中使用此数据资产。

使用 Azure 机器学习注册表共享数据无法解决的场景

• 共享需要精细访问控制的敏感数据。 不能在注册表中创建与一小部分用户/工作区共享的数据资产，而让组织中许多其他用户访问注册表。

• 共享现有存储中可用的数据，这些数据严禁复制，或者由于太大或成本太高而无法复制。 每当在注册表中创建数据资产时，都会将数据的副本引入注册表存储中，以便可以进行复制。

Azure 机器学习注册表支持的数据资产类型

提示

在决定是否要将 uri_file、uri_folder 或 mltable 用于你的场景时，请查看以下规范场景。

可以创建三种数据资产类型：

类型	V2 API	规范场景
文件：引用单个文件	uri_file	读/写单个文件 - 文件可以采用任何格式。
文件夹：引用单个文件夹	uri_folder	必须将 parquet/CSV 文件的目录读取/写入到 Pandas/Spark 中。 使用目录中的图像、文本、音频、视频文件进行深度学习。
表：引用数据表	mltable	架构很复杂，可能会频繁更改，或者需要大型表格数据的一部分。

Azure 机器学习注册表支持的路径

创建数据资产时，必须指定指向数据位置的 path 参数。 目前仅支持指向本地计算机上位置的路径。

提示

“Local”是指正在使用的计算机的本地存储。 例如，如果你使用的是笔记本电脑，则为本地驱动器。 如果你使用的是 Azure 机器学习计算实例，则为计算实例的“本地”驱动器。

先决条件

在按照本文中的步骤操作之前，请确保满足以下先决条件：

• 熟悉 Azure 机器学习注册表 和 Azure 机器学习中的数据概念。

• 用于共享数据的 Azure 机器学习注册表。 若要创建注册表，请参阅了解如何创建注册表。

• Azure 机器学习工作区。 如果没有，请按照快速入门：创建工作区资源一文中的步骤创建一个。

  重要

  要在其中创建工作区的 Azure 区域（位置）必须在 Azure 机器学习注册表支持的区域列表中。

• 按照如何共享模型、组件和环境一文创建的环境和组件。

• Azure CLI 和 ml 扩展或 Azure 机器学习 Python SDK v2：

  Azure CLI

  若要安装 Azure CLI 和扩展，请参阅安装、设置和使用 CLI (v2)。

  重要

  • 本文中的 CLI 示例假定你使用的是 Bash（或兼容的）shell。 例如，从 Linux 系统或者适用于 Linux 的 Windows 子系统。

  • 这些示例还假设你已配置 Azure CLI 的默认设置，因此不需要为订阅、工作区、资源组或位置指定参数。 若要配置默认设置，请使用以下命令。 将以下参数替换为你的配置值：

    • 将 <subscription> 替换为你的 Azure 订阅 ID。
    • 将 <workspace> 替换为 Azure 机器学习工作区名称。
    • 将 <resource-group> 替换为包含你的工作区的 Azure 资源组。
    • 将 <location> 替换为包含你的工作区的 Azure 区域。

    az account set --subscription <subscription>
    az configure --defaults workspace=<workspace> group=<resource-group> location=<location>
    

    可以使用 az configure -l 命令查看当前的默认值。

  Python SDK

  若要安装 Python SDK v2，请使用以下命令：

  pip install --pre --upgrade azure-ai-ml azure-identity
  

克隆示例存储库

本文中的代码示例基于示例存储库中的 nyc_taxi_data_regression 示例。 若要在开发环境中使用这些文件，请使用以下命令克隆存储库并将目录更改为示例：

git clone https://github.com/Azure/azureml-examples
cd azureml-examples

Azure CLI

对于 CLI 示例，请将目录更改为示例存储库的本地克隆中的 cli/jobs/pipelines-with-components/nyc_taxi_data_regression。

cd cli/jobs/pipelines-with-components/nyc_taxi_data_regression

Python SDK

对于 Python SDK 示例，请使用示例存储库中的 nyc_taxi_data_regression 示例。 示例笔记本位于 sdk/python/assets/assets-in-registry 目录中。 用于训练和推理的组件的所有示例 YAML 文件模型训练代码和示例数据位于 cli/jobs/pipelines-with-components/nyc_taxi_data_regression 中。 如果你想要逐步运行笔记本以试用本文档中的代码，请切换到 sdk/resources/registry 目录并打开笔记本。

创建 SDK 连接

提示

仅当使用 Python SDK 时才需要执行此步骤。

创建与 Azure 机器学习工作区和注册表的客户端连接。 在以下示例中，将 <...> 占位符值替换为适合你的配置的值。 例如，Azure 订阅 ID、工作区名称、注册表名称等：

ml_client_workspace = MLClient( credential=credential,
    subscription_id = "<workspace-subscription>",
    resource_group_name = "<workspace-resource-group",
    workspace_name = "<workspace-name>")
print(ml_client_workspace)

ml_client_registry = MLClient(credential=credential,
                        registry_name="<REGISTRY_NAME>",
                        registry_location="<REGISTRY_REGION>")
print(ml_client_registry)

在注册表中创建数据

在此步骤中创建的数据资产将在本文后面提交训练作业时使用。

Azure CLI

提示

CLI 命令 az ml data create 还可用于在工作区或注册表中创建数据。 结合 --workspace-name 命令运行该命令会在工作区中创建数据，而结合 --registry-name 运行该命令会在注册表中创建数据。

数据源位于之前克隆的示例存储库中。 在本地克隆下，转到以下目录路径：cli/jobs/pipelines-with-components/nyc_taxi_data_regression。 在此目录中，创建一个名为 data-registry.yml 的 YAML 文件，并使用以下 YAML 作为文件的内容：

$schema: https://azuremlschemas.azureedge.net/latest/data.schema.json
name: transformed-nyc-taxt-data
description: Transformed NYC Taxi data created from local folder.
version: 1
type: uri_folder
path: data_transformed/

值 path 指向 data_transformed 子目录，该子目录包含使用注册表共享的数据。

若要在注册表中创建数据，请使用 az ml data create。 在以下示例中，将 <registry-name> 替换为注册表的名称。

az ml data create --file data-registry.yml --registry-name <registry-name>

如果出现错误，指出注册表中已存在具有此名称和版本的数据，你可以编辑 data-registry.yml 中的 version 字段，或者在 CLI 中指定不同的版本以便替代 data-registry.yml 中的版本值。

# use shell epoch time as the version
version=$(date +%s)
az ml data create --file data-registry.yml --registry-name <registry-name> --set version=$version

提示

如果命令 version=$(date +%s) 未在环境中设置 $version 变量，请将 $version 替换为一个随机数。

从 az ml data create 命令的输出中保存数据的 name 和 version，并将它们与 az ml data show 命令一起使用以查看资产的详细信息。

az ml data show --name transformed-nyc-taxt-data --version 1 --registry-name <registry-name>

提示

如果你使用了不同的数据名称或版本，请相应地替换 --name 和 --version 参数。

还可以使用 az ml data list --registry-name <registry-name> 列出注册表中的所有数据资产。

Python SDK

提示

MLClient.environmentsdata.create_or_update() 还可用于在工作区或注册表中创建数据，具体取决于该命令初始化了哪个目标。 由于你要在本文档中同时处理工作区和注册表，因此已初始化 ml_client_workspace 和 ml_client_registry 以分别处理工作区和注册表。

源数据目录 data_transformed 在 cli/jobs/pipelines-with-components/nyc_taxi_data_regression/ 中提供。 初始化数据对象并创建数据。

my_path = "./data_transformed/"
my_data = Data(path=my_path,
               type=AssetTypes.URI_FOLDER,
               description="Transformed NYC Taxi data created from local folder.",
               name="transformed-nyc-taxt-data",
               version='1')
ml_client_registry.data.create_or_update(my_data)

提示

如果有错误指出注册表中已存在具有此名称和版本的数据，请为 version 参数指定不同的版本。

记下输出中数据的 name 和 version，并将其传递给 ml_client_registry.data.get() 方法以从注册表中提取数据。

还可以使用 ml_client_registry.data.list() 列出注册表中的所有数据资产。

在注册表中创建环境和组件

若要在注册表中创建环境和组件，请按照如何共享模型、组件和环境一文中的步骤操作。 创建的环境和组件将在下一部分中的训练作业中使用。

提示

可以使用工作区中的环境和组件，而不是使用注册表中的环境和组件。

使用注册表中的组件在工作区中运行管道作业

在运行使用注册表中的组件和数据的管道作业时，计算资源位于工作区本地。 在以下示例中，作业使用 Scikit Learn 训练组件和在前面部分创建的数据资产来训练模型。

注意

一个要点是此管道将在工作区中使用不在特定工作区中的训练数据运行。 该数据位于可与组织中的任何工作区一起使用的注册表中。 你可以在你有权访问的任何工作区中运行此训练作业，而不必在该工作区中提供训练数据。

Azure CLI

验证文件是否位于 cli/jobs/pipelines-with-components/nyc_taxi_data_regression 目录中。 编辑 single-job-pipeline.yml 文件 train_job 部分下的 component 部分以引用训练组件，编辑 training_data 部分下的 path 以引用在前面部分中创建的数据资产。 以下示例显示了 single-job-pipeline.yml 编辑后的外观。 将 <registry_name> 替换为注册表的名称：

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
display_name: nyc_taxi_data_regression_single_job
description: Single job pipeline to train regression model based on nyc taxi dataset

jobs:
  train_job:
    type: command
    component: azureml://registries/<registry-name>/component/train_linear_regression_model/versions/1
    compute: azureml:cpu-cluster
    inputs:
      training_data: 
        type: uri_folder
        path: azureml://registries/<registry-name>/data/transformed-nyc-taxt-data/versions/1
    outputs:
      model_output: 
        type: mlflow_model
      test_data: 

警告

• 在运行管道作业之前，请确认要在其中运行该作业的工作区位于创建数据的注册表所支持的 Azure 区域中。
• 确认该工作区包含名为 cpu-cluster 的计算群集，或使用你的计算名称编辑 jobs.train_job.compute 下的 compute 字段。

使用 az ml job create 命令运行管道作业。

az ml job create --file single-job-pipeline.yml 

提示

如果你尚未按照先决条件部分中所述配置默认工作区和资源组，则需要指定 --workspace-name 和 --resource-group 参数，这样才能正常运行 az ml job create。

有关运行作业的详细信息，请参阅以下文章：

• 运行作业 (CLI)
• 使用组件的管道作业 (CLI)

Python SDK

# get the data asset
data_asset_from_registry = ml_client_registry.data.get(name="transformed-nyc-taxt-data", version="1")

@pipeline()
def pipeline_with_registered_components(
    training_data
):
    train_job = train_component_from_registry(
        training_data=training_data,
    )
pipeline_job = pipeline_with_registered_components(
    training_data=Input(type="uri_folder", path=data_asset_from_registry.id"),
)
pipeline_job.settings.default_compute = "cpu-cluster"
print(pipeline_job)

警告

• 在运行管道作业之前，请确认要在其中运行此作业的工作区位于创建组件的注册表所支持的 Azure 位置。
• 确认该工作区包含名为 cpu-cluster 的计算群集或使用 pipeline_job.settings.default_compute=<compute-cluster-name> 更新它。

运行管道作业并等待该作业完成。

pipeline_job = ml_client_workspace.jobs.create_or_update(
    pipeline_job, experiment_name="sdk_job_data_from_registry" ,  skip_validation=True
)
ml_client_workspace.jobs.stream(pipeline_job.name)
pipeline_job=ml_client_workspace.jobs.get(pipeline_job.name)
pipeline_job

提示

请注意，你正在使用 ml_client_workspace 运行管道作业，而环境和组件是使用 ml_client_registry 创建的。

由于训练作业中使用的组件是通过注册表共享的，因此你可以将作业提交到你在组织中有权访问的任何工作区，甚至提交到不同的订阅。 例如，如果你有 dev-workspace、test-workspace 和 prod-workspace，可以连接到这些工作区并重新提交作业。

有关运行作业的详细信息，请参阅以下文章：

• 运行作业 (SDK)
• 使用组件的管道作业 (SDK)

将数据从工作区共享到注册表

以下步骤演示如何将现有数据资产从工作区共享到注册表。

Azure CLI

首先，在工作区中创建数据资产。 确保你位于 cli/assets/data 目录中。 此目录中的 local-folder.yml 用于在工作区中创建数据资产。 此文件中指定的数据在 cli/assets/data/sample-data 目录中提供。 以下 YAML 是 local-folder.yml 文件的内容：

$schema: https://azuremlschemas.azureedge.net/latest/data.schema.json
name: local-folder-example-titanic
description: Dataset created from local folder.
type: uri_folder
path: sample-data/

若要在工作区中创建数据资产，请使用以下命令：

az ml data create -f local-folder.yml

有关在工作区中创建数据资产的详细信息，请参阅如何创建数据资产。

在工作区中创建的数据资产可以共享到注册表。 从注册表中，可以将数据资产用于多个工作区。 请注意，我们将在 share 函数中传递 --share_with_name 和 --share_with_version 参数。 这些参数是可选参数，如果不传递这些参数，数据将以与工作区中相同的名称和版本共享。

以下示例演示如何使用 share 命令共享数据资产。 将 <registry-name> 替换为数据将共享到的注册表的名称。

az ml data share --name local-folder-example-titanic --version <version-in-workspace> --share-with-name <name-in-registry> --share-with-version <version-in-registry> --registry-name <registry-name>

Python SDK

首先，在工作区中创建数据资产。 确保你位于 sdk/assets/data 目录中。 数据在 sdk/assets/data/sample-data 提供。

my_path = "./sample-data/"
my_data = Data(path=my_path,
               type=AssetTypes.URI_FOLDER,
               description="",
               name="titanic-dataset",
               version='1')
ml_client_workspace.data.create_or_update(my_data)

有关在工作区中创建数据资产的详细信息，请参阅如何创建数据资产。

在工作区中创建的数据资产可以共享到注册表，并且可以从该处用于多个工作区。 在将数据从工作区共享到注册表时，还可以更改其名称和版本。

请注意，我们将在 share 函数中传递 share_with_name 和 share_with_version 参数。 这些参数是可选参数，如果不传递这些参数，数据将以与工作区中相同的名称和版本共享。

# Sharing data from workspace to registry
ml_client_workspace.data.share(
    name="titanic-dataset",
    version="1",
    registry_name="<REGISTRY_NAME>",
    share_with_name=<name-in-registry>,
    share_with_version=<version-in-registry>,
)

后续步骤

• 如何创建和管理注册表
• 如何管理环境
• 如何训练模型
• 如何使用组件创建管道