Instalar e usar a CLI (v1)

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

A CLI do Azure Machine Learning é uma extensão do Azure CLI, uma interface de linha de comando de plataforma cruzada para a plataforma Azure. Essa extensão fornece comandos para trabalhar com o Azure Machine Learning. Ela permite automatizar suas atividades de machine learning. A seguinte lista fornece algumas ações de exemplo que você pode fazer com a extensão CLI:

• Executar experimentos para criar modelos de aprendizado de máquina

• Registrar modelos de aprendizado de máquina para uso do cliente

• Empacote, implante e rastreie o ciclo de vida de seus modelos de aprendizado de máquina

A CLI não é uma substituta do SDK do Azure Machine Learning. Ela é uma ferramenta complementar que é otimizada para lidar com tarefas altamente parametrizadas, que se adaptam bem à automação.

Pré-requisitos

• Para usar a CLI, você deve ter uma assinatura do Azure. Caso não tenha uma assinatura do Azure, crie uma conta gratuita antes de começar. Experimente hoje mesmo a versão gratuita ou paga 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.

Documentos de referência completos

Localize os documentos de referência completos para a extensão azure-cli-ml da CLI do Azure.

Conectar a CLI à assinatura do Azure

Há várias maneiras de se autenticar em sua assinatura do Azure por meio da CLI. O mais básico é 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.

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

Instalar a extensão

Para instalar a extensão da CLI (v1):

az extension add -n azure-cli-ml

Atualizar a extensão

Para atualizar a extensão CLI do Machine Learning, use o seguinte comando:

az extension update -n azure-cli-ml

Remover a extensão

Para remover a extensão CLI, use o seguinte comando:

az extension remove -n azure-cli-ml

Gerenciamento de recursos

Os comandos a seguir demonstram como usar a CLI para gerenciar recursos usados pelo Azure Machine Learning.

• Crie um grupo de recursos se você ainda não tem nenhum:

  az group create -n myresourcegroup -l westus2
  

• Criar um workspace do Azure Machine Learning:

  az ml workspace create -w myworkspace -g myresourcegroup
  

  Para obter mais informações, consulte az ml workspace create.

• Anexe uma configuração de workspace a uma pasta para habilitar a conscientização contextual da CLI.

  az ml folder attach -w myworkspace -g myresourcegroup
  

  Este comando cria um subdiretório .azureml que contém os arquivos de ambiente runconfig e conda de exemplo. Ele também contém um arquivo config.json que é usado para se comunicar com seu workspace do Azure Machine Learning.

  Para obter mais informações, consulte az ml folder attach.

• Anexe um contêiner de Blob do Azure como um armazenamento de dados.

  az ml datastore attach-blob  -n datastorename -a accountname -c containername
  

  Para obter mais informações, consulte az ml datastore attach-blob.

• Carregue arquivos em um armazenamento de dados.

  az ml datastore upload  -n datastorename -p sourcepath
  

  Para obter mais informações, consulte az ml datastore upload.

• Anexe um cluster do AKS como um destino de computação.

  az ml computetarget attach aks -n myaks -i myaksresourceid -g myresourcegroup -w myworkspace
  

  Para obter mais informações, consulte az ml computetarget attach aks

Clusters de cálculo

• Crie um novo cluster de computação gerenciado.

  az ml computetarget create amlcompute -n cpu --min-nodes 1 --max-nodes 1 -s STANDARD_D3_V2
  

• Criar um novo cluster de cálculo gerenciado com identidade gerenciada

  • Identidade gerenciada atribuída pelo usuário

    az ml computetarget create amlcompute --name cpu-cluster --vm-size Standard_NC6 --max-nodes 5 --assign-identity '/subscriptions/<subcription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user_assigned_identity>'
    

  • Identidade gerenciada atribuída pelo sistema

    az ml computetarget create amlcompute --name cpu-cluster --vm-size Standard_NC6 --max-nodes 5 --assign-identity '[system]'
    

• Adicionar uma identidade gerenciada a um cluster de cálculo existente:

  • Identidade gerenciada atribuída pelo usuário

    az ml computetarget amlcompute identity assign --name cpu-cluster '/subscriptions/<subcription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user_assigned_identity>'
    

  • Identidade gerenciada atribuída pelo sistema

    az ml computetarget amlcompute identity assign --name cpu-cluster '[system]'
    

Para obter mais informações, consulte az ml computetarget create amlcompute.

Instância de computação

Gerenciar instâncias de computação. Nos exemplos abaixo, o nome da instância de computação é cpu

• Criar uma nova instância de computação.

  az ml computetarget create computeinstance -n cpu -s "STANDARD_D3_V2" -v
  

  Para obter mais informações, consulte az ml computetarget create computeinstance.

• Parar uma computeinstance.

  az ml computetarget computeinstance stop -n cpu -v
  

  Para obter mais informações, consulte az ml computetarget computeinstance stop.

• Inicie uma computeinstance.

  az ml computetarget computeinstance start -n cpu -v
  

  Para obter mais informações, consulte az ml computetarget computeinstance start.

• Reinicie uma computeinstance.

  az ml computetarget computeinstance restart -n cpu -v
  

  Para obter mais informações, consulte az ml computetarget computeinstance restart.

• Excluir uma computeinstance.

  az ml computetarget delete -n cpu -v
  

  Para obter mais informações, consulte az ml computetarget delete computeinstance.

Executar experimentos

• Comece uma corrida de sua experiência. Ao usar esse comando, especifique o nome do arquivo runconfig (o texto antes de *.runconfig, se você estiver olhando o seu sistema de arquivos) em relação ao parâmetro -c.

  az ml run submit-script -c sklearn -e testexperiment train.py
  

  Dica

  O comando az ml folder attach cria um subdiretório .azureml, que contém dois arquivos de exemplo de runconfig.

  Se você tiver um script Python que cria um objeto de configuração de execução programaticamente, poderá usar RunConfig.save() para salvá-lo como um arquivo runconfig.

  O esquema runconfig completo pode ser encontrado neste arquivo JSON. O esquema está autodocumentando por meio da chave description de cada objeto. Além disso, há enumerações para valores possíveis e um snippet de modelo no final.

  Para obter mais informações, consulte az ml run submit-script.

• Exibir uma lista de experimentos:

  az ml experiment list
  

  Para obter mais informações, consulte az ml experiment list.

Execução de HyperDrive

Você pode usar o HyperDrive com a CLI do Azure para realizar as execuções de ajuste de parâmetro. Primeiro, crie um arquivo de configuração HyperDrive no formato a seguir. Consulte o artigo Ajustar hiperparâmetros para seu modelo para obter detalhes sobre parâmetros de ajuste de hiperparâmetro.

# hdconfig.yml
sampling: 
    type: random # Supported options: Random, Grid, Bayesian
    parameter_space: # specify a name|expression|values tuple for each parameter.
    - name: --penalty # The name of a script parameter to generate values for.
      expression: choice # supported options: choice, randint, uniform, quniform, loguniform, qloguniform, normal, qnormal, lognormal, qlognormal
      values: [0.5, 1, 1.5] # The list of values, the number of values is dependent on the expression specified.
policy: 
    type: BanditPolicy # Supported options: BanditPolicy, MedianStoppingPolicy, TruncationSelectionPolicy, NoTerminationPolicy
    evaluation_interval: 1 # Policy properties are policy specific. See the above link for policy specific parameter details.
    slack_factor: 0.2
primary_metric_name: Accuracy # The metric used when evaluating the policy
primary_metric_goal: Maximize # Maximize|Minimize
max_total_runs: 8 # The maximum number of runs to generate
max_concurrent_runs: 2 # The number of runs that can run concurrently.
max_duration_minutes: 100 # The maximum length of time to run the experiment before cancelling.

Adicione esse arquivo junto com os arquivos de configuração de execução. Em seguida, envie uma execução de HyperDrive usando:

az ml run submit-hyperdrive -e <experiment> -c <runconfig> --hyperdrive-configuration-name <hdconfig> my_train.py

Observe a seção argumentos no runconfig e o espaço de parâmetro na configuração do HyperDrive. Eles contêm os argumentos de linha de comando a serem passados ao script de treinamento. O valor em runconfig permanece o mesmo em cada iteração, enquanto o intervalo na configuração de HyperDrive é iterado. Não especifique o mesmo argumento em ambos os arquivos.

Gerenciamento de conjunto de dados

Os seguintes comandos demonstram como trabalhar com conjuntos de dados no Azure Machine Learning:

• Registrar um conjunto de dados:

  az ml dataset register -f mydataset.json
  

  Para obter informações sobre o formato do arquivo JSON usado para definir o conjunto de dados, use az ml dataset register --show-template.

  Para obter mais informações, consulte az ml dataset register.

• Listar todos os conjuntos de dados em um workspace:

  az ml dataset list
  

  Para obter mais informações, consulte az ml dataset list.

• Obter detalhes de um conjunto de dados:

  az ml dataset show -n dataset-name
  

  Para obter mais informações, consulte az ml dataset show.

• Cancelar o registro de um conjunto de dados:

  az ml dataset unregister -n dataset-name
  

  Para obter mais informações, consulte az ml dataset unregister.

Gerenciamento de ambiente

Os seguintes comandos demonstram como criar, registrar e listar ambientes do Azure Machine Learning para seu workspace:

• Criar arquivos scaffolding para um ambiente:

  az ml environment scaffold -n myenv -d myenvdirectory
  

  Para obter mais informações, consulte az ml environment scaffold.

• Registrar um ambiente:

  az ml environment register -d myenvdirectory
  

  Para obter mais informações, consulte az ml environment register.

• Listar ambientes registrados:

  az ml environment list
  

  Para obter mais informações, consulte az ml environment list.

• Baixar um ambiente registrado:

  az ml environment download -n myenv -d downloaddirectory
  

  Para obter mais informações, consulte az ml environment download.

Esquema de configuração de ambiente

Se você usou o comando az ml environment scaffold, ele gera um arquivo azureml_environment.json de modelo que pode ser modificado e usado para criar configurações de ambiente personalizadas com a CLI. O objeto de nível superior é mapeado de modo flexível para a classe Environment no SDK do Python.

{
    "name": "testenv",
    "version": null,
    "environmentVariables": {
        "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
    },
    "python": {
        "userManagedDependencies": false,
        "interpreterPath": "python",
        "condaDependenciesFile": null,
        "baseCondaEnvironment": null
    },
    "docker": {
        "enabled": false,
        "baseImage": "mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210615.v1",
        "baseDockerfile": null,
        "sharedVolumes": true,
        "shmSize": "2g",
        "arguments": [],
        "baseImageRegistry": {
            "address": null,
            "username": null,
            "password": null
        }
    },
    "spark": {
        "repositories": [],
        "packages": [],
        "precachePackages": true
    },
    "databricks": {
        "mavenLibraries": [],
        "pypiLibraries": [],
        "rcranLibraries": [],
        "jarLibraries": [],
        "eggLibraries": []
    },
    "inferencingStackVersion": null
}

A tabela a seguir detalha cada campo de nível superior no arquivo JSON, bem como o tipo e uma descrição. Se um tipo de objeto estiver vinculado a uma classe do SDK do Python, haverá uma correspondência de 1:1 flexível entre cada campo JSON e o nome da variável pública na classe Python. Em alguns casos, o campo pode ser mapeado para um argumento de construtor em vez de uma variável de classe. Por exemplo, o campo environmentVariables é mapeado para a variável environment_variables na classe Environment.

Gerenciamento de pipeline do ML

Os seguintes comandos demonstram como trabalhar com pipelines de machine learning:

• Criar um pipeline de machine learning:

  az ml pipeline create -n mypipeline -y mypipeline.yml
  

  Para obter mais informações, consulte az ml pipeline create.

  Para obter mais informações sobre o arquivo YAML do pipeline, consulte Definir pipelines de machine learning no YAML.

• Executar um pipeline:

  az ml run submit-pipeline -n myexperiment -y mypipeline.yml
  

  Para obter mais informações, consulte az ml run submit-pipeline.

  Para obter mais informações sobre o arquivo YAML do pipeline, consulte Definir pipelines de machine learning no YAML.

• Agendar um pipeline:

  az ml pipeline create-schedule -n myschedule -e myexperiment -i mypipelineid -y myschedule.yml
  

  Para obter mais informações, consulte az ml pipeline create-schedule.

Registro de modelo, criação de perfil, implantação

Os comandos a seguir demonstram como registrar um modelo treinado e implantá-lo como um serviço de produção:

• Registre um modelo com o Azure Machine Learning:

  az ml model register -n mymodel -p sklearn_regression_model.pkl
  

  Para obter mais informações, consulte az ml model register.

• OPCIONAL Analise seu modelo para obter valores de CPU e memória ideais para implantação.

  az ml model profile -n myprofile -m mymodel:1 --ic inferenceconfig.json -d "{\"data\": [[1,2,3,4,5,6,7,8,9,10],[10,9,8,7,6,5,4,3,2,1]]}" -t myprofileresult.json
  

  Para obter mais informações, consulte az ml model profile.

• Implantar seu modelo no AKS

  az ml model deploy -n myservice -m mymodel:1 --ic inferenceconfig.json --dc deploymentconfig.json --ct akscomputetarget
  

  Para obter mais informações sobre o esquema do arquivo de configuração de inferência, consulte Esquema de configuração de inferência.

  Para obter mais informações sobre o esquema do arquivo de configuração de implantação, consulte Esquema de configuração de implantação.

  Para obter mais informações, consulte az ml model deploy.

Esquema de configuração de inferência

As entradas no documento inferenceconfig.json são mapeadas para os parâmetros da classe InferenceConfig. A seguinte tabela descreve o mapeamento entre as entidades no documento JSON e os parâmetros do método:

É possível incluir especificações completas de um ambiente do Azure Machine Learning no arquivo de configuração da inferência. Se esse ambiente não existir no seu workspace, o Azure Machine Learning o criará. Caso contrário, se necessário, o Azure Machine Learning atualizará o ambiente. Este JSON é um exemplo:

{
    "entryScript": "score.py",
    "environment": {
        "docker": {
            "arguments": [],
            "baseDockerfile": null,
            "baseImage": "mcr.microsoft.com/azureml/intelmpi2018.3-ubuntu18.04",
            "enabled": false,
            "sharedVolumes": true,
            "shmSize": null
        },
        "environmentVariables": {
            "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
        },
        "name": "my-deploy-env",
        "python": {
            "baseCondaEnvironment": null,
            "condaDependencies": {
                "channels": [
                    "conda-forge"
                ],
                "dependencies": [
                    "python=3.7",
                    {
                        "pip": [
                            "azureml-defaults",
                            "azureml-telemetry",
                            "scikit-learn==0.22.1",
                            "inference-schema[numpy-support]"
                        ]
                    }
                ],
                "name": "project_environment"
            },
            "condaDependenciesFile": null,
            "interpreterPath": "python",
            "userManagedDependencies": false
        },
        "version": "1"
    }
}

Também é possível usar um ambiente existente do Azure Machine Learning em parâmetros separados da CLI e remover a chave do "ambiente" do arquivo de configuração da inferência. Use -e para o nome do ambiente e --ev para a versão do ambiente. Se você não especificar --ev, a versão mais recente será usada. Veja um exemplo de arquivo de configuração de inferência:

{
    "entryScript": "score.py",
    "sourceDirectory": null
}

O comando a seguir demonstra como implantar um modelo usando o arquivo de configuração de inferência anterior, chamado myInferenceConfig.json.

Ele também usa a versão mais recente de um ambiente existente do Azure Machine Learning, chamado AzureML-Minimal.

az ml model deploy -m mymodel:1 --ic myInferenceConfig.json -e AzureML-Minimal --dc deploymentconfig.json

Esquema de configuração de implantação

Esquema de configuração de implantação local

As entradas no documento deploymentconfig.json são mapeadas para os parâmetros de LocalWebservice.deploy_configuration. A seguinte tabela descreve o mapeamento entre as entidades no documento JSON e os parâmetros do método:

O seguinte JSON é um exemplo de configuração de implantação a ser usada com a CLI:

{
    "computeType": "local",
    "port": 32267
}

Salve esse JSON como um arquivo chamado deploymentconfig.json.

Esquema de configuração de implantação da Instância de Contêiner do Azure

As entradas no documento deploymentconfig.json são mapeadas para os parâmetros de AciWebservice.deploy_configuration. A seguinte tabela descreve o mapeamento entre as entidades no documento JSON e os parâmetros do método:

O seguinte JSON é um exemplo de configuração de implantação a ser usada com a CLI:

{
    "computeType": "aci",
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    },
    "authEnabled": true,
    "sslEnabled": false,
    "appInsightsEnabled": false
}

Esquema de configuração de implantação do Serviço de Kubernetes do Azure

As entradas no documento deploymentconfig.json são mapeadas para os parâmetros de AksWebservice.deploy_configuration. A seguinte tabela descreve o mapeamento entre as entidades no documento JSON e os parâmetros do método:

O seguinte JSON é um exemplo de configuração de implantação a ser usada com a CLI:

{
    "computeType": "aks",
    "autoScaler":
    {
        "autoscaleEnabled": true,
        "minReplicas": 1,
        "maxReplicas": 3,
        "refreshPeriodInSeconds": 1,
        "targetUtilization": 70
    },
    "dataCollection":
    {
        "storageEnabled": true
    },
    "authEnabled": true,
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    }
}

Próximas etapas

• Referência de comando para a extensão CLI do Machine Learning.

• Treinar e implantar modelos de machine learning usando o Azure Pipelines