Usar GitHub Actions com o Azure Machine Learning

APLICA-SE A:Extensão de ML da CLI do Azure v2 (atual)SDK do Python azure-ai-ml v2 (atual)

Comece a usar o GitHub Actions para treinar um modelo no Azure Machine Learning.

Este artigo ensinará como criar um fluxo de trabalho do GitHub Actions que cria e implanta um modelo de machine learning no Azure Machine Learning. Você treinará um modelo de regressão linear scikit-learn no conjunto de dados de táxi de NOVA YORK.

O GitHub Actions usa um arquivo YAML (.yml) de fluxo de trabalho no caminho /.github/workflows/ do seu repositório. Essa definição contém as várias etapas e os parâmetros que compõem o fluxo de trabalho.

Pré-requisitos

Antes de seguir as etapas neste artigo, verifique se você tem os seguintes pré-requisitos:

• Um Workspace do Azure Machine Learning. Se você não tiver um, use as etapas do artigo Início Rápido: criar recursos de workspace para criar.

• Para instalar o SDK do Python v2, use o seguinte comando:

  pip install azure-ai-ml azure-identity
  

  Para atualizar uma instalação do SDK existente para a versão mais recente, use o seguinte comando:

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

  Para saber mais, confira Instalar o SDK do Python v2 para Azure Machine Learning.

• Uma conta do GitHub. Caso ainda não tenha uma, inscreva-se gratuitamente.

Etapa 1: obter o código

Bifurque o seguinte repositório no GitHub:

https://github.com/azure/azureml-examples

Clone seu repositório bifurcado localmente.

git clone https://github.com/YOUR-USERNAME/azureml-examples

Etapa 2: Autenticar com o Azure

Primeiro, você precisará definir como autenticar com o Azure. Você pode usar uma entidade de serviço ou o OpenID Connect.

Gerar as credenciais de implantação

Entidade de serviço

Crie uma entidade de serviço com o comando az ad sp create-for-rbac na CLI do Azure. Execute esse comando com o Azure Cloud Shell no portal do Azure ou selecionando o botão Experimentar.

az ad sp create-for-rbac --name "myML" --role contributor \
                            --scopes /subscriptions/<subscription-id>/resourceGroups/<group-name> \
                            --json-auth

O parâmetro --json-auth está disponível nas versões da CLI do Azure >= 2.51.0. Versões anteriores a essa usam --sdk-auth com um aviso de substituição.

No exemplo acima, substitua os espaços reservados pela ID da assinatura, nome do grupo de recursos e nome do aplicativo. A saída é um objeto JSON com as credenciais de atribuição de função que fornecem acesso ao aplicativo do Serviço de Aplicativo semelhante ao mostrado abaixo. Copie esse objeto JSON para uso posterior.

  {
    "clientId": "<GUID>",
    "clientSecret": "<GUID>",
    "subscriptionId": "<GUID>",
    "tenantId": "<GUID>",
    (...)
  }

OpenID Connect

O OpenID Connect é um método de autenticação que usa tokens de curta duração. A configuração do OpenID Connect com o GitHub Actions é um processo mais complexo que oferece segurança aprimorada.

1. Se você não tiver um aplicativo atual, registre um novo aplicativo do Microsoft Entra e uma entidade de serviço que possa acessar recursos.

   az ad app create --display-name myApp
   

   Esse comando produzirá um JSON com um appId que consiste em seu client-id. objectId é referente a APPLICATION-OBJECT-ID e será usado para criar credenciais federadas com as chamadas à API do Graph. Salve o valor para usar mais tarde como o segredo AZURE_CLIENT_ID do GitHub.

2. Crie uma entidade de serviço. Substitua $appID pelo AppID de sua saída JSON. Esse comando gera uma saída JSON com um objectId diferente que será usado na próxima etapa. O novo objectId é o assignee-object-id.

   Esse comando gera uma saída JSON com um objectId diferente e será usado na próxima etapa. O novo objectId é o assignee-object-id.

   Copie o appOwnerTenantId para usar mais tarde como um segredo do GitHub para AZURE_TENANT_ID.

    az ad sp create --id $appId
   

3. Crie uma atribuição de função por assinatura e objeto. Por padrão, a atribuição de função será vinculada à sua assinatura padrão. Substitua $subscriptionId pela ID da sua assinatura, $resourceGroupName pelo nome do seu grupo de recursos e $assigneeObjectId pela assignee-object-id gerada (a ID do objeto da entidade de serviço recém-criada).

   az role assignment create --role contributor --subscription $subscriptionId --assignee-object-id  $assigneeObjectId --assignee-principal-type ServicePrincipal --scope /subscriptions/$subscriptionId/resourceGroups/$resourceGroupName
   

4. Execute o comando a seguir a fim de criar uma credencial de identidade federada para o aplicativo do Microsoft Entra.

   • Substitua APPLICATION-OBJECT-ID pela objectId (gerada ao criar o aplicativo) do aplicativo do Microsoft Entra.
   • Defina um valor de CREDENTIAL-NAME para referência posterior.
   • Defina o subject. O valor disso é definido pelo GitHub dependendo do seu fluxo de trabalho:
     • Trabalhos em seu ambiente do GitHub Actions: repo:< Organization/Repository >:environment:< Name >
     • Para trabalhos não vinculados a um ambiente, inclua o caminho de referência para ramificação/marca com base no caminho de referência usado para disparar o fluxo de trabalho: repo:< Organization/Repository >:ref:< ref path>. Por exemplo, repo:n-username/ node_express:ref:refs/heads/my-branch ou repo:n-username/ node_express:ref:refs/tags/my-tag.
     • Para fluxos de trabalho disparados por um evento de solicitação de pull: repo:< Organization/Repository >:pull_request.

   az ad app federated-credential create --id <APPLICATION-OBJECT-ID> --parameters credential.json
   ("credential.json" contains the following content)
   {
       "name": "<CREDENTIAL-NAME>",
       "issuer": "https://token.actions.githubusercontent.com",
       "subject": "repo:octo-org/octo-repo:environment:Production",
       "description": "Testing",
       "audiences": [
           "api://AzureADTokenExchange"
       ]
   }
   

Criar segredos

Entidade de serviço

1. No GitHub, acesse seu repositório.

2. Acesse Configurações no menu de navegação.

3. Selecione Segurança > Segredos e variáveis > Ações.

   

4. Selecione Novo segredo de repositório.

5. Cole toda a saída JSON do comando da CLI do Azure no campo valor do segredo. Dê ao segredo o nome AZURE_CREDENTIALS.

6. Selecione Adicionar segredo.

OpenID Connect

Você precisa fornecer a ID do cliente, a ID do locatário e a ID da assinatura do seu aplicativo para a ação de logon. Esses valores podem ser fornecidos diretamente no fluxo de trabalho ou podem ser armazenados em segredos do GitHub e referenciados em seu fluxo de trabalho. Salvar os valores como segredos do GitHub é a opção mais segura.

1. No GitHub, acesse seu repositório.

2. Selecione Segurança > Segredos e variáveis > Ações.

   

3. Selecione Novo segredo de repositório.

4. Crie segredos para AZURE_CLIENT_ID, AZURE_TENANT_ID e AZURE_SUBSCRIPTION_ID. Use esses valores do aplicativo Microsoft Entra para seus segredos do GitHub:

   Segredo do GitHub	Aplicativo do Microsoft Entra
   AZURE_CLIENT_ID	ID do aplicativo (cliente)
   AZURE_TENANT_ID	ID do diretório (locatário)
   AZURE_SUBSCRIPTION_ID	ID da assinatura

5. Salve cada segredo selecionando Adicionar segredo.

Etapa 3: atualizar setup.sh para se conectar ao seu workspace do Azure Machine Learning

Será necessário atualizar as variáveis do arquivo de configuração da CLI para corresponder ao seu workspace.

1. No repositório clonado, acesse azureml-examples/cli/.

2. Edite setup.sh e atualize essas variáveis no arquivo.

   Variável	Descrição
   GROUP	nome do grupo de recursos
   LOCALIZAÇÃO	Local do seu workspace (exemplo: eastus2)
   WORKSPACE	Nome do workspace do Azure Machine Learning

Etapa 4: atualizar pipeline.yml com o nome do seu cluster de cálculo

Você usará um arquivo pipeline.yml para implantar seu pipeline do Azure Machine Learning. Trata-se de um pipeline de machine learning e não de DevOps. Você só precisará fazer essa atualização se estiver usando um nome diferente de cpu-cluster para o cluster de cálculo.

1. No repositório clonado, acesse azureml-examples/cli/jobs/pipelines/nyc-taxi/pipeline.yml.
2. Sempre que vir compute: azureml:cpu-cluster, atualize o valor de cpu-cluster com o nome do cluster de cálculo. Por exemplo, se o cluster for chamado de my-cluster, o novo valor será azureml:my-cluster. Há cinco atualizações.

Etapa 5: executar seu fluxo de trabalho do GitHub Actions

Seu fluxo de trabalho é autenticado com o Azure, configura a CLI do Azure Machine Learning e usa ela para treinar um modelo no Azure Machine Learning.

Entidade de serviço

O arquivo de fluxo de trabalho é composto por uma seção de gatilho e trabalhos:

• Um gatilho inicia o fluxo de trabalho na seção on. O fluxo de trabalho é executado por padrão em um agendamento cron e quando uma solicitação de pull é feita por meio de branches e caminhos correspondentes. Saiba mais sobre eventos que disparam fluxos de trabalho.
• Na seção de trabalhos do fluxo de trabalho, você faz check-out de código e faz logon no Azure com o segredo da entidade de serviço.
• A seção de trabalhos também inclui uma ação de instalação que instala e configura a CLI do Machine Learning (v2). Depois que a CLI é instalada, a ação executar trabalho executa o arquivo pipeline.yml do Azure Machine Learning para treinar um modelo com os dados de táxi de NOVA YORK.

Habilitar seu fluxo de trabalho

1. No repositório clonado, abra .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml e verifique se o fluxo de trabalho tem esta aparência.

   name: cli-jobs-pipelines-nyc-taxi-pipeline
   on:
     workflow_dispatch:
     schedule:
       - cron: "0 0/4 * * *"
     pull_request:
       branches:
         - main
         - sdk-preview
       paths:
         - cli/jobs/pipelines/nyc-taxi/**
         - .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml
         - cli/run-pipeline-jobs.sh
         - cli/setup.sh
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
       - name: check out repo
         uses: actions/checkout@v2
       - name: azure login
         uses: azure/login@v1
         with:
           creds: ${{secrets.AZURE_CREDENTIALS}}
       - name: setup
         run: bash setup.sh
         working-directory: cli
         continue-on-error: true
       - name: run job
         run: bash -x ../../../run-job.sh pipeline.yml
         working-directory: cli/jobs/pipelines/nyc-taxi
   

2. Selecione Exibir execuções.

3. Habilite os fluxos de trabalho selecionando Eu entendo meus fluxos de trabalho, prossiga e habilite-os.

4. Selecione o fluxo de trabalho cli-jobs-pipelines-nyc-taxi-pipeline e escolha Habilitar fluxo de trabalho.

5. Selecione Executar fluxo de trabalho e escolha a opção Executar fluxo de trabalho agora.

OpenID Connect

O arquivo de fluxo de trabalho é composto por uma seção de gatilho e trabalhos:

• Um gatilho inicia o fluxo de trabalho na seção on. O fluxo de trabalho é executado por padrão em um agendamento cron e quando uma solicitação de pull é feita por meio de branches e caminhos correspondentes. Saiba mais sobre eventos que disparam fluxos de trabalho.
• Na seção de trabalhos do fluxo de trabalho, você faz check-out de código e faz logon no Azure com a ação de logon do Azure usando o OpenID Connect.
• A seção de trabalhos também inclui uma ação de instalação que instala e configura a CLI do Machine Learning (v2). Depois que a CLI é instalada, a ação executar trabalho executa o arquivo pipeline.yml do Azure Machine Learning para treinar um modelo com os dados de táxi de NOVA YORK.

Habilitar seu fluxo de trabalho

1. No repositório clonado, abra .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml e verifique se o fluxo de trabalho tem esta aparência.

   name: cli-jobs-pipelines-nyc-taxi-pipeline
   on:
     workflow_dispatch:
     schedule:
       - cron: "0 0/4 * * *"
     pull_request:
       branches:
         - main
         - sdk-preview
       paths:
         - cli/jobs/pipelines/nyc-taxi/**
         - .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml
         - cli/run-pipeline-jobs.sh
         - cli/setup.sh
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
       - name: check out repo
         uses: actions/checkout@v2
       - name: azure login
         uses: azure/login@v1
         with:
             client-id: ${{ secrets.AZURE_CLIENT_ID }}
             tenant-id: ${{ secrets.AZURE_TENANT_ID }}
             subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       - name: setup
         run: bash setup.sh
         working-directory: cli
         continue-on-error: true
       - name: run job
         run: bash -x ../../../run-job.sh pipeline.yml
         working-directory: cli/jobs/pipelines/nyc-taxi
   

2. Selecione Exibir execuções.

3. Habilite os fluxos de trabalho selecionando Eu entendo meus fluxos de trabalho, prossiga e habilite-os.

4. Selecione o fluxo de trabalho cli-jobs-pipelines-nyc-taxi-pipeline e escolha Habilitar fluxo de trabalho.

   

5. Selecione Executar fluxo de trabalho e escolha a opção Executar fluxo de trabalho agora.

   

Etapa 6: verificar a execução do seu fluxo de trabalho

1. Abra a execução concluída do seu fluxo de trabalho e verifique se o trabalho de build foi executado com êxito. Você verá uma marca de verificação verde ao lado do trabalho.

2. Abra o Estúdio do Azure Machine Learning e navegue até o nyc-taxi-pipeline-example. Verifique se cada parte do trabalho (preparação, transformação, treinamento, previsão, pontuação) foi concluída e se há uma marca de verificação verde.

   

Limpar os recursos

Quando seu grupo de recursos e repositório não forem mais necessários, limpe os recursos implantados excluindo o grupo de recursos e o repositório GitHub.

Próximas etapas

Criar pipelines de ML de produção com o SDK do Python