Gerenciar workspaces do Azure Machine Learning usando a extensão da CLI do Azure v1

Artigo
09/03/2024

APLICA-SE A: Extensão de ML da CLI do Azure v1

Importante

Alguns comandos da CLI do Azure neste artigo usam a extensão azure-cli-ml ou v1 do Azure Machine Learning. O suporte à extensão v1 terminará em 30 de setembro de 2025. Você poderá instalar e usar a extensão v1 até essa data.

Recomendamos que você faça a transição para a extensão ml ou v2, antes de 30 de setembro de 2025. Para obter mais informações sobre a extensão v2, confira Extensão da CLI do Azure ML e SDK do Python v2.

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 aprendizado de máquina para a CLI fornece comandos para trabalhar com recursos do Azure Machine Learning.

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 workspace, é possível criar automaticamente os serviços necessários para o workspace 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, se criar um workspace na assinatura A que utiliza uma conta de armazenamento na assinatura B, o namespace do Azure Machine Learning deve ser registrado na assinatura B antes que o workspace possa usar a conta de armazenamento.

O provedor de recursos do Azure Machine Learning é o Microsoft. MachineLearningServices. Para obter informações sobre como ver se isso já está registrado ou em processo de registro, confira Provedores e tipos de recursos do Azure.

Importante

Essas informações se aplicam somente aos recursos fornecidos durante a criação do workspace: contas de Armazenamento do Microsoft 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 workspace e pode dificultar a solução de problemas. Se você excluir a instância do Application Insights criada pelo workspace, a única maneira de recriá-la é excluindo e recriando o workspace.

Para obter mais informações sobre como usar a instância do Application Insights, veja 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 v1 ( azure-cli-ml ) do Azure Machine Learning, somente alguns dos comandos se comunicam com o Azure Resource Manager. Especificamente, comandos que criam, atualizam, excluem, listam ou mostram recursos do Azure. Operações como enviar um trabalho de treinamento se comunicam diretamente com o espaço de trabalho do Azure Machine Learning. Se o espaço de trabalho estiver protegido com um ponto de extremidade privado, isso será suficiente para proteger os comandos fornecidos pela azure-cli-ml extensão.

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ê 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 as informações de assinatura na página de visão geral do seu workspace no portal do Azure.

Para selecionar outra assinatura para usar nos comandos da CLI do Azure, execute o comando az account set -s <subscription> e especifique o nome ou ID da assinatura para a qual 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
Trazer recursos existentes

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

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

Para criar um workspace que usa os recursos existentes, você precisará fornecer a ID de cada recurso. Você pode obter essa ID na guia "propriedades" em cada recurso por meio do 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"

A ID do recurso retornada tem o seguinte formato: "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/<provider>/<subresource>/<resource-name>".

Depois que você tiver as IDs para os recursos que deseja usar com o workspace, use o comando az workspace create -w <workspace-name> -g <resource-group-name> base e adicione os parâmetros e as IDs para os recursos existentes. Por exemplo, o seguinte comando cria um workspace que usa um registro de contêiner existente:

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --container-registry "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerRegistry/registries/<acr-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.

Caso queira restringir o acesso ao seu workspace a uma rede virtual, use os seguintes parâmetros como parte do comando az ml workspace create ou use os comandos az ml workspace private-endpoint.

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --pe-name "<pe name>"
                       --pe-auto-approval "<pe-autoapproval>"
                       --pe-resource-group "<pe name>"
                       --pe-vnet-name "<pe name>"
                       --pe-subnet-name "<pe name>"

--pe-name: o nome do ponto de extremidade privado que é criado.
--pe-auto-approval: indica se as conexões de ponto de extremidade privado com o espaço de trabalho devem ser aprovadas automaticamente.
--pe-resource-group: o grupo de recursos no qual o ponto de extremidade privado deve ser criado. Precisa ser o mesmo grupo que contém a rede virtual.
--pe-vnet-name: a rede virtual existente na qual o ponto de extremidade privado deve ser criado.
--pe-subnet-name: o nome da sub-rede na qual o ponto de extremidade privado deve ser criado. O valor padrão é default.

Para obter mais informações sobre como usar esses comandos, confira as Páginas de referência da CLI.

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 --cmk-keyvault para especificar o Azure Key Vault que contém a chave e --resource-cmk-uri para especificar a ID do recurso e URI da chave no cofre.

Para limitar os dados que a Microsoft coleta em seu workspace, você poderá especificar adicionalmente o parâmetro --hbi-workspace.

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --cmk-keyvault "<cmk keyvault name>"
                       --resource-cmk-uri "<resource cmk uri>"
                       --hbi-workspace

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. Para obter mais informações sobre como monitorar esses itens, confira a seção Monitoramento e log do artigo sobre arquitetura e conceitos.

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 -w <workspace-name> -g <resource-group-name>

Atualizar um workspace

Para atualizar um workspace, use o seguinte comando:

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

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 -w <workspace-name> -g <resource-group-name>

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

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 -w <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>

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

Depois que um Registro de Contêiner do Azure for criado 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 (v1).

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.

Compartilhar via

Gerenciar workspaces do Azure Machine Learning usando a extensão da CLI do Azure v1

Pré-requisitos

Limitações

Proteger comunicações da CLI

Conectar a CLI à assinatura do Azure

Criar um grupo de recursos

Criar um workspace

Configurações avançadas

Configurar o workspace para conectividade de rede privada

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

Usar a CLI para gerenciar workspaces

Obter informações do workspace

Atualizar um workspace

Sincronizar chaves para recursos dependentes

Excluir um workspace

Solução de problemas

Erros do provedor de recursos

Como mover o workspace

Como excluir o Registro de Contêiner do Azure

Próximas etapas

Comentários

Recursos adicionais