Usar ações do GitHub com o Azure Machine Learning

APLICA-SE A:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

Comece pelo GitHub Actions para preparar um modelo no Azure Machine Learning.

Este artigo ensinará como criar um fluxo de trabalho de Ações do GitHub que cria e implanta um modelo de aprendizado de máquina no Azure Machine Learning. Você treinará um modelo de regressão linear scikit-learn no conjunto de dados do NYC Taxi.

O GitHub Actions usa um arquivo YAML (.yml) de fluxo de trabalho no caminho do /.github/workflows/ repositório. Esta definição contém as várias etapas e 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:

• Uma área de trabalho do Azure Machine Learning. Se você não tiver um, use as etapas no artigo Guia de início rápido: criar recursos do espaço de trabalho para criar um.

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

  pip install azure-ai-ml azure-identity
  

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

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

  Para obter mais informações, consulte Instalar o Python SDK v2 para Azure Machine Learning.

• Uma conta GitHub. Se não tiver uma, inscreva-se gratuitamente.

Passo 1: Obter o código

Fork o seguinte repo no GitHub:

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

Etapa 2: Autenticar com o Azure

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

Gerar credenciais de implantação

Principal de serviço

Crie uma entidade de serviço com o comando az ad sp create-for-rbac na CLI do Azure. Execute este 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 este uso --sdk-auth com um aviso de descontinuaçã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 seu aplicativo do Serviço de Aplicativo semelhante ao abaixo. Copie este objeto JSON para mais tarde.

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

OpenID Connect

OpenID Connect é um método de autenticação que usa tokens de curta duração. Configurar o OpenID Connect com o GitHub Actions é um processo mais complexo que oferece segurança reforçada.

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

   az ad app create --display-name myApp
   

   Este comando produzirá JSON com um appId que é o seu client-id. O objectId é APPLICATION-OBJECT-ID e será usado para criar credenciais federadas com chamadas de API do Graph. Salve o valor para usar como o segredo do AZURE_CLIENT_ID GitHub mais tarde.

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

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

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

    az ad sp create --id $appId
   

3. Crie uma nova 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 assinatura, $resourceGroupName pelo nome do grupo de recursos e $assigneeObjectId pelo gerado assignee-object-id (a ID do objeto principal 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 seguinte comando para criar uma nova credencial de identidade federada para seu aplicativo Microsoft Entra.

   • Substitua APPLICATION-OBJECT-ID pelo objectId (gerado durante a criação do aplicativo) para seu aplicativo Microsoft Entra.
   • Defina um valor para CREDENTIAL-NAME referenciar mais tarde.
   • Defina o subjectarquivo . O valor disso é definido pelo GitHub dependendo do seu fluxo de trabalho:
     • Trabalhos em seu ambiente de ações do GitHub: repo:< Organization/Repository >:environment:< Name >
     • Para Trabalhos não vinculados a um ambiente, inclua o caminho ref para ramificação/tag com base no caminho ref usado para acionar 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 acionados por um evento pull request: 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

Principal de serviço

1. No GitHub, vá para o seu repositório.

2. Vá para Configurações no menu de navegação.

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

   

4. Selecione Novo segredo do repositório.

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

6. Selecione Add secret (Adicionar segredo).

OpenID Connect

Você precisa fornecer a ID do cliente, a ID do locatário e a ID da assinatura do aplicativo para a ação de login. 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, vá para o seu repositório.

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

   

3. Selecione Novo segredo do repositório.

4. Crie segredos para AZURE_CLIENT_ID, AZURE_TENANT_IDe AZURE_SUBSCRIPTION_ID. Use estes valores do seu aplicativo Microsoft Entra para seus segredos do GitHub:

   Segredo do GitHub	Aplicação Microsoft Entra
   AZURE_CLIENT_ID	ID da aplicação (cliente)
   AZURE_TENANT_ID	ID do Diretório (inquilino)
   AZURE_SUBSCRIPTION_ID	ID de Subscrição

5. Salve cada segredo selecionando Adicionar segredo.

Etapa 3: Atualizar setup.sh para se conectar ao seu espaço de trabalho do Azure Machine Learning

Você precisará atualizar as variáveis do arquivo de configuração da CLI para corresponder ao seu espaço de trabalho.

1. No repositório clonado, vá para azureml-examples/cli/.

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

   Variável	Description
   GRUPO	Nome do grupo de recursos
   LOCALIZAÇÃO	Localização do espaço de trabalho (exemplo: eastus2)
   ÁREA DE TRABALHO	Nome do espaço de trabalho do Azure Machine Learning

Etapa 4: Atualizar pipeline.yml com o nome do cluster de computação

Você usará um pipeline.yml arquivo para implantar seu pipeline do Azure Machine Learning. Este é um pipeline de aprendizado de máquina e não um pipeline de DevOps. Você só precisará fazer essa atualização se estiver usando um nome diferente do nome do cpu-cluster cluster do computador.

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

Etapa 5: Executar o fluxo de trabalho de Ações do GitHub

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

Principal de serviço

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

• Um gatilho on inicia o fluxo de trabalho na seção. O fluxo de trabalho é executado por padrão em uma agenda cron e quando uma solicitação pull é feita a partir de ramificações e caminhos correspondentes. Saiba mais sobre eventos que acionam fluxos de trabalho.
• Na seção de trabalhos do fluxo de trabalho, você faz checkout do código e faz logon no Azure com seu segredo da entidade de serviço.
• A seção de trabalhos também inclui uma ação de configuração que instala e configura a CLI do Machine Learning (v2). Depois que a CLI for instalada, a ação de tarefa de execução executará seu arquivo do Azure Machine Learning pipeline.yml para treinar um modelo com dados de táxi de Nova York.

Habilite 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 fluxos de trabalho selecionando Eu entendo meus fluxos de trabalho, vá em frente e habilite-os.

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

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

OpenID Connect

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

• Um gatilho on inicia o fluxo de trabalho na seção. O fluxo de trabalho é executado por padrão em uma agenda cron e quando uma solicitação pull é feita a partir de ramificações e caminhos correspondentes. Saiba mais sobre eventos que acionam fluxos de trabalho.
• Na seção de trabalhos do fluxo de trabalho, você faz checkout do 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 configuração que instala e configura a CLI do Machine Learning (v2). Depois que a CLI for instalada, a ação de tarefa de execução executará seu arquivo do Azure Machine Learning pipeline.yml para treinar um modelo com dados de táxi de Nova York.

Habilite 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 fluxos de trabalho selecionando Eu entendo meus fluxos de trabalho, vá em frente e habilite-os.

4. Selecione o fluxo de trabalho cli-jobs-pipelines-nyc-taxi-pipeline e escolha Ativar 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 fluxo de trabalho

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

2. Abra o estúdio de Aprendizado de Máquina do Azure e navegue até o exemplo nyc-taxi-pipeline. Verifique se cada parte do seu trabalho (preparar, transformar, treinar, prever, pontuar) foi concluída e se você vê uma marca de seleção verde.

   

Clean up resources (Limpar recursos)

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

Próximos passos

Crie pipelines de ML de produção com o Python SDK