Gerenciar workspaces do Azure Machine Learning usando a CLI do Azure

APLICA-SE A:Extensão do ML da CLI do Azure v2 (atual)

Neste artigo, você aprenderá a criar e gerenciar workspaces do Azure Machine Learning usando a CLI do Azure. A CLI do Azure fornece comandos para gerenciar recursos do Azure e foi criada para ajudar você a trabalhar de maneira rápida com o Azure, com ênfase na automação. A extensão de machine learning para a CLI fornece comandos para trabalhar com recursos do Azure Machine Learning.

Você também pode gerenciar workspaces usando o portal do Azure e o SDK do Python, o Azure PowerShell ou por meio da extensão do VS Code.

Pré-requisitos

• Uma assinatura do Azure. Se você não tiver uma, experimente a versão paga ou gratuita do Azure Machine Learning.

• Para usar os comandos da CLI deste documento em seu ambiente local, você precisará da CLI do Azure.

  Se você usar o Azure Cloud Shell, a CLI será acessada por meio do navegador e residirá na nuvem.

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.

Dica

Uma instância do Azure Application Insights é criada quando você cria o espaço de trabalho. Se quiser, você pode excluir a instância do Application Insights após a criação do cluster. Essa exclusão limita as informações coletadas do espaço de trabalho e pode dificultar a solução de problemas. Se você excluir a instância do Application Insights criada pelo espaço de trabalho, não poderá recriá-la sem excluir e recriar o espaço de trabalho.

Para saber mais sobre como usar essa instância do Application Insights, confira Monitorar e coletar dados de pontos de extremidade de serviço Web do Machine Learning.

Proteger comunicações da CLI

Alguns dos comandos da CLI do Azure se comunicam com o Azure Resource Manager pela Internet. Essa comunicação é protegida usando HTTPS/TLS 1.2.

Com a extensão da CLI v2 ('ml') do Azure Machine Learning, todos os comandos se comunicam com o Azure Resource Manager. Isso inclui dados operacionais, como parâmetros YAML e metadados. Se o workspace do Azure Machine Learning for público (ou seja, não atrás de uma rede virtual), não haverá nenhuma configuração extra necessária. As comunicações são protegidas usando HTTPS/TLS 1.2.

Se o workspace do Azure Machine Learning usar um ponto de extremidade privado e uma rede virtual e você estiver usando a CLI v2, escolha uma das seguintes configurações a ser usada:

• Se você estiver OKcom a comunicação da CLI v2 pela internet pública, use o parâmetro --public-network-access a seguir para o comando az ml workspace update para habilitar o acesso à rede pública. Por exemplo, o comando a seguir atualiza um workspace para acesso à rede pública:

  az ml workspace update --name myworkspace --public-network-access enabled
  

• Se você não estiver OK com a comunicação da CLI v2 pela Internet pública, poderá usar um Link Privado do Azure para aumentar a segurança da comunicação. Use os links a seguir para proteger as comunicações com o Azure Resource Manager usando o Link Privado do Azure.

  1. Proteja seu espaço de trabalho Azure Machine Learning dentro de uma rede virtual usando um ponto de extremidade privado.
  2. Crie um Link Privado para gerenciar recursos do Azure.
  3. Crie um ponto de extremidade privado para o Link Privado criado na etapa anterior.

  Importante

  Para configurar o link privado para Azure Resource Manager, você deve ser o proprietário da assinatura da assinatura do Azure e um proprietário ou colaborador do grupo de gerenciamento raiz. Para obter mais informações, consulte Criar um link privado para gerenciar recursos do Azure.

Para obter mais informações sobre a comunicação CLI v2, confira Instalar e configurar a CLI.

Conectar a CLI à assinatura do Azure

Importante

Se você estiver usando o Azure Cloud Shell, ignore esta seção. O Cloud Shell autentica automaticamente você usando a conta que você faz logon em sua assinatura do Azure.

Há várias maneiras de se autenticar em sua assinatura do Azure por meio da CLI. O mais simples é autenticar-se interativamente usando um navegador. Para se autenticar interativamente, abra uma linha de comando ou terminal e use o seguinte comando:

az login

Se a CLI pode abrir seu navegador padrão, ela irá fazê-lo e carregar uma página de entrada. Caso contrário, você precisará abrir um navegador e seguir as instruções na linha de comando. As instruções envolvem a navegação para https://aka.ms/devicelogin e a inserção de um código de autorização.

Dica

Depois de entrar, você deve ver uma lista de assinaturas associadas à sua conta do Azure. A informação de assinatura com isDefault: true é a assinatura ativada no momento para os comandos da CLI do Azure. Essa assinatura precisa ser a mesma que contém o seu workspace do Azure Machine Learning. Você pode encontrar a ID da assinatura no portal do Azure visitando a página de visão geral do seu workspace.

Para selecionar outra assinatura, use o comando az account set -s <subscription name or ID> e especifique o nome ou a ID da assinatura para a qual deseja alternar. Para obter mais informações sobre a seleção da assinatura, confira Usar várias assinaturas do Azure.

Para outros métodos de autenticação, confira Entrar com a CLI do Azure.

Criar um grupo de recursos

O workspace do Azure Machine Learning precisa ser criado dentro de um grupo de recursos. É possível usar um grupo de recursos existente ou criar um novo. Para criar um grupo de recursos, use o comando a seguir. Substitua <resource-group-name> pelo nome a ser usado para esse grupo de recursos. Substitua <location> pela região do Azure a ser usada para este grupo de recursos:

Observação

Você deve selecionar uma região na qual o Azure Machine Learning está disponível. Para obter informações, veja Produtos disponíveis por região.

az group create --name <resource-group-name> --location <location>

A resposta desse comando é semelhante ao JSON a seguir. Você pode usar os valores de saída para localizar os recursos criados ou analisar como entrada para as etapas subsequentes da CLI para automação.

{
  "id": "/subscriptions/<subscription-GUID>/resourceGroups/<resourcegroupname>",
  "location": "<location>",
  "managedBy": null,
  "name": "<resource-group-name>",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": null
}

Para obter mais informações sobre como trabalhar com grupos de recursos, confira az group.

Criar um workspace

Quando você implanta um workspace do Azure Machine Learning, vários outros serviços são necessários como recursos associados dependentes. Quando você usa a CLI para criar o workspace, a CLI pode criar recursos associados em seu nome ou você pode anexar recursos existentes.

Importante

Ao anexar sua conta de armazenamento, verifique se ela atende aos seguintes critérios:

• A conta de armazenamento não é uma conta Premium (Premium_LRS e Premium_GRS)
• As funcionalidades de Blob do Azure e Arquivo do Azure estão habilitadas
• O Namespace Hierárquico (ADLS Gen 2) está desabilitado. Esses requisitos destinam-se apenas à conta de armazenamento padrão usada pelo workspace.

Quando anexar o registro de contêiner do Azure, você precisará ter a conta do administrador habilitada para ser usada com um workspace do Azure Machine Learning.

Criar com novos recursos

Para criar um workspace no qual os serviços são criados automaticamente, use o seguinte comando:

az ml workspace create -n <workspace-name> -g <resource-group-name>

Trazer recursos existentes

Para criar um novo workspace ao trazer recursos associados existentes usando a CLI, primeiro você terá que definir como seu workspace deve ser configurado em um arquivo de configuração.

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-basicex-prod
location: eastus
display_name: Bring your own dependent resources-example
description: This configuration specifies a workspace configuration with existing dependent resources
storage_account: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Storage/storageAccounts/<STORAGE_ACCOUNT>
container_registry: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerRegistry/registries/<CONTAINER_REGISTRY>
key_vault: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT>
application_insights: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.insights/components/<APP_INSIGHTS>
tags:
  purpose: demonstration

Você pode referenciar esse arquivo de configuração como parte do comando da CLI de criação do workspace.

az ml workspace create -g <resource-group-name> --file workspace.yml

Se anexar recursos existentes, você precisará fornecer a ID dos recursos. Você pode obter essa ID na guia "propriedades" em cada recurso no Portal do Azure ou executando os comandos a seguir usando a CLI do Azure.

• Conta do Armazenamento do Azure: az storage account show --name <storage-account-name> --query "id"
• Application Insights do Azure:az monitor app-insights component show --app <application-insight-name> -g <resource-group-name> --query "id"
• Azure Key Vault: az keyvault show --name <key-vault-name> --query "ID"
• Registro de Contêiner do Azure: az acr show --name <acr-name> -g <resource-group-name> --query "id"

O valor da ID do Recurso é semelhante ao seguinte texto: "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/<provider>/<subresource>/<resource-name>".

Importante

Ao anexar recursos existentes, você não precisará especificar todos. Você pode especificar um ou mais. Por exemplo, especifique uma conta de armazenamento existente e o workspace criará os outros recursos.

A saída do comando de criação do workspace é semelhante ao documento JSON a seguir. Você pode usar os valores de saída para localizar os recursos criados ou analisar como entrada para as etapas subsequentes da CLI.

{
  "applicationInsights": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.insights/components/<application-insight-name>",
  "containerRegistry": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.containerregistry/registries/<acr-name>",
  "creationTime": "2019-08-30T20:24:19.6984254+00:00",
  "description": "",
  "friendlyName": "<workspace-name>",
  "id": "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>",
  "identityPrincipalId": "<GUID>",
  "identityTenantId": "<GUID>",
  "identityType": "SystemAssigned",
  "keyVault": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.keyvault/vaults/<key-vault-name>",
  "location": "<location>",
  "name": "<workspace-name>",
  "resourceGroup": "<resource-group-name>",
  "storageAccount": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.storage/storageaccounts/<storage-account-name>",
  "type": "Microsoft.MachineLearningServices/workspaces",
  "workspaceid": "<GUID>"
}

Configurações avançadas

Configurar o workspace para conectividade de rede privada

Dependendo do caso de uso e dos requisitos organizacionais, você pode optar por configurar o Azure Machine Learning usando a conectividade de rede privada. Você pode usar a CLI do Azure para implantar um workspace e um ponto de extremidade de link privado para o recurso de workspace. Para obter mais informações sobre como usar um ponto de extremidade privado e uma VNet (rede virtual) com seu workspace, confira Visão geral do isolamento e da privacidade da rede virtual. Para configurações de recursos complexas, confira também as opções de implantação baseadas em modelo, incluindo Azure Resource Manager.

Ao usar o link privado, seu workspace não pode usar o Registro de Contêiner do Azure para compilar imagens docker. Portanto, você deve definir a propriedade image_build_compute como um nome de cluster de computação de CPU a ser usado para a criação de ambiente de imagem do Docker. Você também pode especificar se o workspace de link privado deve ser acessível pela Internet usando a propriedade public_network_access privada.

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-privatelink-prod
location: eastus
display_name: Private Link endpoint workspace-example
description: When using private link, you must set the image_build_compute property to a cluster name to use for Docker image environment building. You can also specify whether the workspace should be accessible over the internet.
image_build_compute: cpu-compute
public_network_access: Disabled
tags:
  purpose: demonstration

az ml workspace create -g <resource-group-name> --file privatelink.yml

Depois de criar o workspace, use os comandos da CLI de rede do Azure para criar um ponto de extremidade de link privado para o workspace.

az network private-endpoint create \
    --name <private-endpoint-name> \
    --vnet-name <vnet-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id "/subscriptions/<subscription>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>" \
    --group-id amlworkspace \
    --connection-name workspace -l <location>

Para criar as entradas da zona DNS privada para o workspace, use os seguintes comandos:

# Add privatelink.api.azureml.ms
az network private-dns zone create \
    -g <resource-group-name> \
    --name 'privatelink.api.azureml.ms'

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name 'privatelink.api.azureml.ms' \
    --name <link-name> \
    --virtual-network <vnet-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group create \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name myzonegroup \
    --private-dns-zone 'privatelink.api.azureml.ms' \
    --zone-name 'privatelink.api.azureml.ms'

# Add privatelink.notebooks.azure.net
az network private-dns zone create \
    -g <resource-group-name> \
    --name 'privatelink.notebooks.azure.net'

az network private-dns link vnet create \
    -g <resource-group-name> \
    --zone-name 'privatelink.notebooks.azure.net' \
    --name <link-name> \
    --virtual-network <vnet-name> \
    --registration-enabled false

az network private-endpoint dns-zone-group add \
    -g <resource-group-name> \
    --endpoint-name <private-endpoint-name> \
    --name myzonegroup \
    --private-dns-zone 'privatelink.notebooks.azure.net' \
    --zone-name 'privatelink.notebooks.azure.net'

Chave gerenciada pelo cliente e workspace de alto impacto nos negócios

Por padrão, os metadados do workspace são armazenados em uma instância do Azure Cosmos DB mantida pela Microsoft. Os dados são criptografados com chaves gerenciadas pela Microsoft. Em vez de usar a chave gerenciada pela Microsoft, você também pode fornecer uma chave própria. Isso cria um conjunto extra de recursos em sua assinatura do Azure para armazenar dados.

Para saber mais sobre os recursos criados quando você traz sua chave para criptografia, confira Criptografia de dado com o Azure Machine Learning.

Use o parâmetro customer_managed_key e contendo os parâmetros key_vault e key_uri para especificar a ID do recurso e a URI da chave no cofre.

Para limitar os dados que a Microsoft coleta em seu workspace, você poderá especificar adicionalmente a propriedade hbi_workspace.

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-cmkexample-prod
location: eastus
display_name: Customer managed key encryption-example
description: This configurations shows how to create a workspace that uses customer-managed keys for encryption.
customer_managed_key: 
  key_vault: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT>
  key_uri: https://<KEY_VAULT>.vault.azure.net/keys/<KEY_NAME>/<KEY_VERSION>
tags:
  purpose: demonstration

Você pode referenciar esse arquivo de configuração como parte do comando da CLI de criação do workspace.

az ml workspace create -g <resource-group-name> --file cmk.yml

Observação

Autorize o aplicativo Machine Learning (em Gerenciamento de Identidades e Acesso) com permissões de colaborador na sua assinatura para gerenciar os recursos adicionais de criptografia de dados.

Observação

O Azure Cosmos DB não é usado para armazenar informações como desempenho do modelo, informações registradas por experimentos ou informações registradas das suas implantações de modelo.

Importante

A seleção de alto impacto nos negócios só pode ser feita durante a criação de um workspace. Não é possível alterar essa configuração após a criação do workspace.

Para obter mais informações sobre as chaves gerenciadas pelo cliente e o workspace de alto impacto nos negócios, confira Segurança empresarial do Azure Machine Learning.

Usar a CLI para gerenciar workspaces

Obter informações do workspace

Para obter informações sobre um workspace, use o seguinte comando:

az ml workspace show -n <workspace-name> -g <resource-group-name>

Para obter mais informações, confira a documentação de az ml workspace show.

Atualizar um workspace

Para atualizar um workspace, use o seguinte comando:

az ml workspace update -n <workspace-name> -g <resource-group-name>

Para obter mais informações, confira a documentação de az ml workspace update.

Sincronizar chaves para recursos dependentes

Se você alterar as chaves de acesso de um dos recursos usados pelo workspace, levará cerca de uma hora para que o workspace seja sincronizado com a nova chave. Para forçar o workspace a sincronizar as novas chaves imediatamente, use o seguinte comando:

az ml workspace sync-keys -n <workspace-name> -g <resource-group-name>

Para obter mais informações, confira Regenerar chaves de acesso de armazenamento.

Para saber mais sobre o comando sync-keys, confira az ml workspace sync-keys.

Excluir um workspace

Aviso

Se a exclusão reversível estiver habilitada para o workspace, ele pode ser recuperado após a exclusão. Se a exclusão reversível não estiver habilitada ou se você selecionar a opção para excluir o workspace permanentemente, ele não poderá ser recuperado. Para mais informações, consulte Recuperar um workspace excluído.

Para excluir um workspace depois que ele não for mais necessário, use o seguinte comando:

az ml workspace delete -n <workspace-name> -g <resource-group-name>

Importante

A exclusão de um workspace não exclui o Application Insights, a conta de armazenamento, o cofre de chaves nem o registro de contêiner usado pelo workspace.

Exclua também o grupo de recursos, o que exclui o workspace e todos os outros recursos do Azure no grupo de recursos. Para excluir o grupo de recursos, use o seguinte comando:

az group delete -g <resource-group-name>

Para obter mais informações, confira a documentação de az ml workspace delete.

Dica

O comportamento padrão do Azure Machine Learning é excluir temporariamente o workspace. Isso significa que o workspace não é excluído imediatamente, mas está programado para exclusão. Para mais informações, confira Exclusão temporária.

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.

Como mover o workspace

Aviso

Não há suporte para a movimentação do workspace do Azure Machine Learning para outra assinatura nem para a movimentação da assinatura proprietária para um novo locatário. Se você fizer isso, poderá causar erros.

Como excluir o Registro de Contêiner do Azure

O workspace do Azure Machine Learning usa o ACR (Registro de Contêiner do Azure) para algumas operações. Ele criará automaticamente uma instância do ACR quando precisar de uma pela primeira vez.

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.

Próximas etapas

Para obter mais informações sobre a extensão da CLI do Azure para machine learning, confira a documentação de az ml.

Para verificar se há problemas com seu espaço de trabalho, confira Como usar o diagnóstico de espaço de trabalho.

Para saber como mover um workspace para uma nova assinatura do Azure, confira Como mover um workspace.

Para obter informações sobre como manter o Azure Machine Learning atualizado com as últimas atualizações de segurança, confira Gerenciamento de vulnerabilidades.