Usar um modelo do Azure Resource Manager para criar um workspace para o Azure Machine Learning

  • Artigo

Neste artigo, você aprenderá várias maneiras de criar um workspace do Azure Machine Learning usando modelos do Azure Resource Manager. Um modelo do Resource Manager facilita a criação de recursos como uma operação única e coordenada. Um modelo é um documento JSON que define os recursos necessários para uma implantação. Além disso, pode especificar os parâmetros de implantação. Os parâmetros são usados para fornecer valores de entrada ao usar o modelo.

Para saber mais, confira Implantar um aplicativo com o modelo do Gerenciador de Recursos do Azure.

Pré-requisitos

Limitações

  • Ao criar um novo espaço de trabalho, é possível criar automaticamente os serviços necessários para o espaço de trabalho ou usar os serviços existentes. Se você quiser usar os serviços existentes de uma assinatura do Azure diferente do espaço de trabalho, deverá registrar o namespace Azure Machine Learning na assinatura que contém esses serviços. Por exemplo, ao criar um espaço de trabalho na assinatura A que usa uma conta de armazenamento da assinatura B, o namespace do Azure Machine Learning deverá ser registrado na assinatura B antes que você possa usar a conta de armazenamento com o espaço de trabalho.

    O provedor de recursos do Azure Machine Learning é o Microsoft. MachineLearningServices. Para mais informações sobre como verificar se ele está registrado e como registrá-lo, confira o artigo Provedores e tipos de recursos do Azure.

    Importante

    Isso se aplica somente aos recursos fornecidos durante a criação do espaço de trabalho; Contas de Armazenamento do Azure, Registro de Contêiner do Azure, Azure Key Vault e Application Insights.

  • O modelo de exemplo nem sempre pode usar a versão mais recente da API para o Azure Machine Learning. Antes de usar o modelo, recomendamos modificá-lo para usar as versões mais recentes da API. Para obter informações sobre as versões mais recentes da API do Azure Machine Learning, confira API REST do Azure Machine Learning.

    Dica

    Cada serviço do Azure tem um conjunto próprio de versões de API. Para obter informações sobre a API de um serviço específico, verifique as informações de serviço na referência da API REST do Azure.

    Para atualizar a versão da API, localize a entrada "apiVersion": "YYYY-MM-DD" para o tipo de recurso e atualize-a para a versão mais recente. O seguinte exemplo é uma entrada para o Azure Machine Learning:

    "type": "Microsoft.MachineLearningServices/workspaces",
"apiVersion": "2023-10-01",

Vários workspaces na mesma VNet

O modelo não dá suporte a vários workspaces do Azure Machine Learning implantados na mesma VNet. Isso ocorre porque o modelo cria novas zonas DNS durante a implantação.

Se você quiser criar um modelo que implante vários workspaces na mesma VNet, configure isso manualmente (usando o portal do Azure ou a CLI) e, em seguida, use o portal do Azure para gerar um modelo.

Modelo do Resource Manager do espaço de trabalho

O modelo do Azure Resource Manager usado em todo este documento pode ser encontrado no diretório microsoft.machineleaerningservices/machine-learning-workspace-vnet do repositório do GitHub de modelos de início rápido do Azure.

Esse modelo cria os seguintes serviços do Azure:

  • Conta de Armazenamento do Azure
  • Cofre de Chave do Azure
  • Azure Application Insights
  • Registro de Contêiner do Azure
  • Workspace do Azure Machine Learning

O grupo de recursos é o contêiner que retém os serviços. Os diversos serviços são exigidos pelo workspace do Azure Machine Learning.

O modelo de exemplo tem dois parâmetros obrigatórios:

  • O local onde os recursos serão criados.

    O modelo usará a localização selecionada para a maioria dos recursos. A exceção é o serviço do Application Insights que não está disponível em todos os locais de disponibilidade dos outros serviços. Se você selecionar uma localização onde não esteja disponível, o serviço será criado na localização Centro-Sul dos EUA.

  • O workspaceName, que é o nome amigável do workspace do Azure Machine Learning.

    Observação

    O nome do workspace não diferencia maiúsculas de minúsculas.

    Os nomes dos outros serviços são gerados aleatoriamente.

Dica

Embora o modelo associado a este documento crie um Registro de Contêiner do Azure, você também pode criar um workspace sem criar nenhum registro de contêiner. Um registro de contêiner será criado quando você executar uma operação que exija um. Treinar ou implantar um modelo, por exemplo.

Você também pode fazer referência a uma conta de armazenamento ou registro de contêiner existente no modelo do Azure Resource Manager, em vez de criar um. Ao fazer isso, você deve usar uma identidade gerenciada (versão preliminar) ou habilitar a conta de administrador para o registro de contêiner.

Aviso

Após a criação de um Registro de Contêiner do Azure para um workspace, não o exclua. Fazer isso interromperá o workspace do Azure Machine Learning.

Para obter mais informações sobre modelos, consulte os artigos a seguir:

Implantar modelo

Para implantar seu modelo, você precisa criar um grupo de recursos.

Consulte a seção portal do Azure se preferir usar a interface gráfica do usuário.

az group create --name "examplegroup" --location "eastus"

Depois que o grupo de recursos for criado com êxito, implante o modelo com o seguinte comando:

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" location="eastus"

Por padrão, todos os recursos criados como parte do modelo são novos. No entanto, você também tem a opção de usar os recursos existentes. Ao fornecer parâmetros adicionais ao modelo, você pode usar os recursos existentes. Por exemplo, se você quiser usar uma conta de armazenamento existente, defina o valor de storageAccountOption como existente e forneça o nome da sua conta de armazenamento no parâmetro storageAccountName.

Importante

Caso você deseje usar uma conta de Armazenamento do Microsoft Azure existente, ela não pode ser uma conta Premium (Premium_LRS e Premium_GRS). Ela também não pode ter um namespace hierárquico (usado com o Azure Data Lake Storage Gen2). Não há suporte para o armazenamento Premium nem o namespace hierárquico na conta de armazenamento padrão do espaço de trabalho. Não há suporte para o armazenamento Premium nem para namespaces hierárquicos na conta de armazenamento padrão do espaço de trabalho. Use o armazenamento Premium ou o namespace hierárquico com as contas de armazenamento não padrão.

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="eastus" \
      storageAccountOption="existing" \
      storageAccountName="existingstorageaccountname"

Implantar um espaço de trabalho criptografado

O modelo de exemplo a seguir demonstra como criar um workspace com três configurações:

  • Habilitar configurações de alta confidencialidade para o espaço de trabalho. Isso cria uma nova instância do Azure Cosmos DB.
  • Habilite a criptografia para o espaço de trabalho.
  • Usa um Azure Key Vault existente para recuperar chaves gerenciadas pelo cliente. As chaves gerenciadas pelo cliente são usadas para criar uma nova instância do Azure Cosmos DB para o espaço de trabalho.

Importante

Depois que um workspace tiver sido criado, você não poderá alterar as configurações de dados confidenciais, criptografia, ID do cofre de chaves e identificadores de chave. Para alterar esses valores, você precisa criar um workspace usando os novos valores.

Para obter mais informações, confira Chaves gerenciadas pelo cliente.

Importante

Há alguns requisitos específicos que sua assinatura precisa atender antes de usar este modelo:

  • Você precisa ter um Azure Key Vault existente que contenha uma chave de criptografia.
  • O Azure Key Vault precisa estar na mesma região em que você planeja criar o workspace do Azure Machine Learning.
  • Você deve especificar a ID do Azure Key Vault e o URI da chave de criptografia.

Para obter as etapas de criação do cofre e da chave, consulte Configurar chaves gerenciadas pelo cliente.

Para obter os valores para a cmk_keyvault (ID do Key Vault) e os parâmetros resource_cmk_uri (URI de chave) necessários para este modelo, use as seguintes etapas:

  1. Para obter a ID do Key Vault, use o seguinte comando:

    az keyvault show --name <keyvault-name> --query 'id' --output tsv

    Esse comando retorna um valor semelhante a /subscriptions/{subscription-guid}/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<keyvault-name>.

  2. Para obter o valor do URI para a chave gerenciada pelo cliente, use o seguinte comando:

    az keyvault key show --vault-name <keyvault-name> --name <key-name> --query 'key.kid' --output tsv

Esse comando retorna um valor semelhante a https://mykeyvault.vault.azure.net/keys/mykey/{guid}.

Importante

Depois que um workspace tiver sido criado, você não poderá alterar as configurações de dados confidenciais, criptografia, ID do cofre de chaves e identificadores de chave. Para alterar esses valores, você precisa criar um workspace usando os novos valores.

Para habilitar o uso de chaves gerenciadas pelo cliente, defina os seguintes parâmetros ao implantar o modelo:

  • encryption_status como Habilitado.
  • cmk_keyvault como o valor cmk_keyvault obtido nas etapas anteriores.
  • resource_cmk_uri como o valor resource_cmk_uri obtido nas etapas anteriores.
az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="eastus" \
      encryption_status="Enabled" \
      cmk_keyvault="/subscriptions/{subscription-guid}/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<keyvault-name>" \
      resource_cmk_uri="https://mykeyvault.vault.azure.net/keys/mykey/{guid}" \

Ao usar uma chave gerenciada pelo cliente, o Azure Machine Learning cria um grupo de recursos secundário que contém a instância do Azure Cosmos DB. Para obter mais informações, consulte criptografia em repouso no Azure Cosmos DB.

Uma configuração adicional que você pode fornecer para seus dados é definir o parâmetro confidential_data como true. Este exemplo faz o seguinte:

  • Inicia a criptografia do disco de rascunho local para os cluster de cálculo do Azure Machine Learning, contanto que você não tenha criado nenhum cluster anterior em sua assinatura. Se você tiver criado anteriormente um cluster na assinatura, abra um tíquete de suporte para que a criptografia do disco de rascunho esteja habilitada para seus clusters de cálculo.

  • Limpa o disco temporário local entre os trabalhos.

  • Transmite com segurança as credenciais da sua conta de armazenamento, o registro de contêiner e a conta SSH da camada de execução para seus clusters de cálculo usando seu cofre de chaves.

  • Habilita a filtragem de IP para garantir que os pools de lote subjacentes não possam ser chamados por nenhum serviço externo que não seja o AzureMachineLearningService.

    Importante

    Depois que um workspace tiver sido criado, você não poderá alterar as configurações de dados confidenciais, criptografia, ID do cofre de chaves e identificadores de chave. Para alterar esses valores, você precisa criar um workspace usando os novos valores.

    Para obter mais informações, consulte criptografia em repouso.

Implantar espaço de trabalho por trás de uma rede virtual

Ao definir o valor do parâmetro vnetOption como new ou existing, você poderá criar os recursos usados por um espaço de trabalho por trás de uma rede virtual.

Importante

Para o registro de contêiner, somente o SKU 'Premium' tem suporte.

Importante

Application Insights não oferece suporte à implantação por trás de uma rede virtual.

Implantar apenas espaço de trabalho por trás do ponto de extremidade privado

Se os recursos associados não estiverem atrás de uma rede virtual, você poderá definir o parâmetro privateEndpointType como AutoAproval ou ManualApproval para implantar o espaço de trabalho por trás de um ponto de extremidade privado. Isso pode ser feito para espaços de trabalho novos e existentes. Ao atualizar um espaço de trabalho existente, preencha os parâmetros do modelo com as informações do espaço de trabalho existente.

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="eastus" \
      privateEndpointType="AutoApproval"

Usar uma nova rede virtual

Para implantar um recurso por trás de uma nova rede virtual, defina vnetOption como novo junto com as configurações de rede virtual para o respectivo recurso. A implantação abaixo mostra como implantar um espaço de trabalho com o recurso de conta de armazenamento por trás de uma nova rede virtual.

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="eastus" \
      vnetOption="new" \
      vnetName="examplevnet" \
      storageAccountBehindVNet="true"
      privateEndpointType="AutoApproval"

Como alternativa, você pode implantar vários ou todos os recursos dependentes por trás de uma rede virtual.

az deployment group create \
    --name "exampledeployment" \
    --resource-group "examplegroup" \
    --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
    --parameters workspaceName="exampleworkspace" \
      location="eastus" \
      vnetOption="new" \
      vnetName="examplevnet" \
      storageAccountBehindVNet="true" \
      keyVaultBehindVNet="true" \
      containerRegistryBehindVNet="true" \
      containerRegistryOption="new" \
      containerRegistrySku="Premium"
      privateEndpointType="AutoApproval"

Usar uma rede virtual e recursos existentes

Para implantar um espaço de trabalho com recursos associados existentes, você precisa definir o parâmetro vnetOption como existente junto com os parâmetros de sub-rede. No entanto, você precisa criar pontos de extremidade de serviço na rede virtual para cada um dos recursos antes da implantação. Assim como ocorre com novas implantações de rede virtual, você pode ter um ou todos os seus recursos por trás de uma rede virtual.

Importante

A sub-rede deve ter um ponto de extremidade de serviço Microsoft.Storage

Importante

As sub-redes não permitem a criação de pontos de extremidade privados. Desabilite o ponto de extremidade privado para habilitar a sub-rede.

  1. Habilite os pontos de extremidade de serviço para os recursos.

    az network vnet subnet update --resource-group "examplegroup" --vnet-name "examplevnet" --name "examplesubnet" --service-endpoints "Microsoft.Storage"
az network vnet subnet update --resource-group "examplegroup" --vnet-name "examplevnet" --name "examplesubnet" --service-endpoints "Microsoft.KeyVault"
az network vnet subnet update --resource-group "examplegroup" --vnet-name "examplevnet" --name "examplesubnet" --service-endpoints "Microsoft.ContainerRegistry"

  2. Implantar o espaço de trabalho

    az deployment group create \
--name "exampledeployment" \
--resource-group "examplegroup" \
--template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.machinelearningservices/machine-learning-workspace-vnet/azuredeploy.json" \
--parameters workspaceName="exampleworkspace" \
  location="eastus" \
  vnetOption="existing" \
  vnetName="examplevnet" \
  vnetResourceGroupName="examplegroup" \
  storageAccountBehindVNet="true" \
  keyVaultBehindVNet="true" \
  containerRegistryBehindVNet="true" \
  containerRegistryOption="new" \
  containerRegistrySku="Premium" \
  subnetName="examplesubnet" \
  subnetOption="existing"
  privateEndpointType="AutoApproval"

Use o Portal do Azure

  1. Siga as etapas em Implantar recursos do modelo personalizado. Ao chegar na tela Selecionar um modelo, escolha a entrada inícios rápidos. Quando for exibido, selecione o link "Clique aqui para abrir o repositório de modelos". Esse link leva você ao diretório quickstarts no repositório de modelos de início rápido do Azure.

  2. Na lista de modelos de início rápido, selecione microsoft.machinelearningservices. Finalmente, selecione Deploy to Azure.

  3. Quando o modelo aparecer, forneça as seguintes informações necessárias e quaisquer outros parâmetros, dependendo do cenário de implantação.

    • Assinatura: Selecione a assinatura do Azure a ser usada para esses recursos.
    • Grupo de recursos: Selecione ou crie um grupo de recursos para conter os serviços.
    • Região: selecione a região do Azure onde os recursos serão criados.
    • Nome do workspace: O nome a ser usado para o workspace do Azure Machine Learning que será criado. O nome do workspace deverá ter entre 3 e 33 caracteres. E o nome poderá conter apenas caracteres alfanuméricos e '-'.
    • Localização: Selecione a localização onde os recursos serão criados.

  4. Selecione Examinar + criar.

  5. Na tela Revisar + criar, concorde com os termos e condições listados e selecione Criar.

Para obter mais informações, consulte Implantar recursos de modelo personalizado.

Solução de problemas

Erros do provedor de recursos

Ao criar um workspace do Azure Machine Learning ou um recurso usado pelo workspace, você pode receber um erro semelhante às seguintes mensagens:

  • No registered resource provider found for location {location}
  • The subscription is not registered to use namespace {resource-provider-namespace}

A maioria dos provedores de recursos é automaticamente registrada, mas não todos. Se você receber essa mensagem, será necessário registrar o provedor mencionado.

A seguinte tabela contém uma lista dos provedores de recursos exigidos pelo Azure Machine Learning:

Provedor de recursos Por que ele é necessário
Microsoft.MachineLearningServices Criar o Workspace do Azure Machine Learning.
Microsoft.Storage A conta de Armazenamento do Azure é usada como o armazenamento padrão do workspace.
Microsoft.ContainerRegistry O Registro de Contêiner do Azure é usado pelo workspace para criar imagens do Docker.
Microsoft.KeyVault O Azure Key Vault é usado pelo workspace para armazenar segredos.
Microsoft.Notebooks Notebooks integrados na instância de computação do Azure Machine Learning.
Microsoft.ContainerService Se você planeja implantar modelos treinados nos Serviços de Kubernetes do Azure.

Se você planeja usar uma chave gerenciada pelo cliente com o Azure Machine Learning, registre os seguintes provedores de serviços:

Provedor de recursos Por que ele é necessário
Microsoft.DocumentDB Instância do Azure CosmosDB que registra metadados do workspace.
Microsoft.Search O Azure Search oferece funcionalidades de indexação para o workspace.

Se você planeja usar uma rede virtual gerenciada com o Azure Machine Learning, registre o provedor de recursos Microsoft.Network. Esse provedor de recursos é usado pelo workspace ao criar pontos de extremidade privados para a rede virtual gerenciada.

Para obter informações sobre o registro de provedores de recursos, confira Resolver erros de registro de provedor de recursos.

Política de acesso do Azure Key Vault e modelos do Azure Resource Manager

Quando você usa um modelo de Azure Resource Manager para criar o workspace e os recursos associados (incluindo o Azure Key Vault), várias vezes. Por exemplo, usando o modelo várias vezes com os mesmos parâmetros como parte de um pipeline de implantação e integração contínuas.

A maioria das operações de criação de recursos por meio de modelos é idempotente, mas o Key Vault limpa as políticas de acesso toda vez que o modelo é usado. Limpar as políticas de acesso interrompe o acesso ao Key Vault para qualquer workspace existente que o esteja usando. Por exemplo, as ações de parar/criar funcionalidades de VM do Azure Notebooks podem falhar.

Para evitar esse problema, recomendamos uma das seguintes abordagens:

  • Não implante o modelo mais de uma vez para os mesmos parâmetros. Ou exclua os recursos existentes antes de usar o modelo para recriá-los.

  • Examine as políticas de acesso do Key Vault e use essas políticas para definir a propriedade accessPolicies do modelo. Para exibir as políticas de acesso, use o seguinte comando da CLI do Azure:

    az keyvault show --name mykeyvault --resource-group myresourcegroup --query properties.accessPolicies

    Para obter mais informações sobre como usar a seção accessPolicies do modelo, consulte a referência de objeto AccessPolicyEntry.

  • Verifique se o recurso do Key Vault já existe. Se existir, não o recrie por meio do modelo. Por exemplo, para usar o Key Vault existente em vez de criar outro, faça as seguintes alterações no modelo:

    • Adicione um parâmetro que aceita a ID de um recurso do Key Vault existente:

      "keyVaultId":{
  "type": "string",
  "metadata": {
    "description": "Specify the existing Key Vault ID."
  }
}

    • Remova a seção que cria um recurso do Key Vault:

      {
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2018-02-14",
  "name": "[variables('keyVaultName')]",
  "location": "[parameters('location')]",
  "properties": {
    "tenantId": "[variables('tenantId')]",
    "sku": {
      "name": "standard",
      "family": "A"
    },
    "accessPolicies": [
    ]
  }
},

    • Remova linha "[resourceId('Microsoft.KeyVault/vaults', variables('keyVaultName'))]", da seção dependsOn do workspace. Além disso altere a entrada keyVault na seção properties do workspace para referenciar o parâmetro keyVaultId:

      {
  "type": "Microsoft.MachineLearningServices/workspaces",
  "apiVersion": "2019-11-01",
  "name": "[parameters('workspaceName')]",
  "location": "[parameters('location')]",
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Insights/components', variables('applicationInsightsName'))]"
  ],
  "identity": {
    "type": "systemAssigned"
  },
  "sku": {
    "tier": "[parameters('sku')]",
    "name": "[parameters('sku')]"
  },
  "properties": {
    "friendlyName": "[parameters('workspaceName')]",
    "keyVault": "[parameters('keyVaultId')]",
    "applicationInsights": "[resourceId('Microsoft.Insights/components',variables('applicationInsightsName'))]",
    "storageAccount": "[resourceId('Microsoft.Storage/storageAccounts/',variables('storageAccountName'))]"
  }
}

    Após essas alterações, você pode especificar a ID do recurso do Key Vault existente ao executar o modelo. Em seguida, o modelo reutilizará o Key Vault definindo a propriedade keyVault do workspace como a ID desse Key Vault.

    Para obter a ID do Key Vault, você pode fazer referência à saída do trabalho do modelo original ou usar a CLI do Azure. O seguinte comando é um exemplo de como usar a CLI do Azure para obter a ID de recurso do Key Vault:

    az keyvault show --name mykeyvault --resource-group myresourcegroup --query id

    Esse comando retorna um valor semelhante ao texto a seguir:

    /subscriptions/{subscription-guid}/resourceGroups/myresourcegroup/providers/Microsoft.KeyVault/vaults/mykeyvault

Próximas etapas