Usare GitHub Actions con Azure Machine Learning

Articolo
10/16/2024

SI APPLICA A:Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)Python SDK azure-ai-ml v2 (corrente)

Iniziare a usare GitHub Actions per eseguire il training di un modello in Azure Machine Learning.

Questo articolo illustra come creare un flusso di lavoro di GitHub Actions che compila e distribuisce un modello di Machine Learning in Azure Machine Learning. Si eseguirà il training di un modello di regressione lineare scikit-learn nel set di dati NYC Taxi.

GitHub Actions usa un file YAML (.yml) del flusso di lavoro /.github/workflows/ nel percorso nel repository. Questa definizione contiene i vari passaggi e i parametri che costituiscono il flusso di lavoro.

Prerequisiti

Prima di seguire la procedura descritta in questo articolo, assicurarsi di disporre dei prerequisiti seguenti:

Un'area di lavoro di Azure Machine Learning. Se non è disponibile, seguire la procedura descritta nell'articolo Avvio rapido: Creare risorse dell'area di lavoro per crearne una.
Per installare l’SDK Python v2, usare il comando seguente:
```
pip install azure-ai-ml azure-identity
```
Per aggiornare un'installazione esistente di SDK alla versione più recente, usare il comando seguente:
```
pip install --upgrade azure-ai-ml azure-identity
```
Per altre informazioni, vedere Installare Python SDK v2 per Azure Machine Learning.

Un account GitHub. Se non è disponibile, iscriversi per riceverne uno gratuito.

Passaggio 1: ottenere il codice

Creare una copia tramite fork del repository seguente in GitHub:

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

Clonare il repository con fork in locale.

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

Passaggio 2: eseguire l'autenticazione con Azure

È necessario prima definire come eseguire l'autenticazione con Azure. È possibile usare un'entità servizio o OpenID Connect.

Generare le credenziali per la distribuzione

Entità servizio
OpenID Connect

Creare un'entità servizio con il comando az ad sp create-for-rbac dell'interfaccia della riga di comando di Azure. Eseguire questo comando con Azure Cloud Shell nel portale di Azure oppure selezionando il pulsante Prova.

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

Il parametro --json-auth è disponibile nelle versioni >dell'interfaccia della riga di comando di Azure = 2.51.0. Versioni precedenti a questo utilizzo --sdk-auth con un avviso di deprecazione.

Nell'esempio precedente sostituire i segnaposto con l'ID sottoscrizione e il nome del gruppo di risorse. L'output è un oggetto JSON con le credenziali di assegnazione di ruolo che forniscono l'accesso all'app del servizio app simile a questo esempio. Copiare l'oggetto JSON per un uso successivo.

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

OpenID Connect è un metodo di autenticazione che utilizza token di breve durata. Configurare OpenID Connect con GitHub Actions è un processo più complesso che offre una maggiore sicurezza.

Se non si dispone di un'applicazione esistente, registrare una nuova applicazione Microsoft Entra e un'entità servizio in grado di accedere alle risorse.
```
az ad app create --display-name myApp
```
Questo comando genererà un oggetto JSON con un appId che corrisponde a client-id. Il objectId è APPLICATION-OBJECT-ID e verrà usato per la creazione di credenziali federate con chiamate API Graph. Salvare il valore da usare come AZURE_CLIENT_ID segreto GitHub in un secondo momento.
Creare un'entità servizio. Sostituire il $appID con il valore appId dall'output JSON. Questo comando genera l'output JSON con una diversa objectId che verrà usata nel passaggio successivo. Il nuovo objectId è assignee-object-id.

Questo comando genera un output JSON con una diversa objectId e verrà usato nel passaggio successivo. Il nuovo objectId è assignee-object-id.

Copiare appOwnerTenantId da usare come segreto GitHub per AZURE_TENANT_ID in un secondo momento.
```
 az ad sp create --id $appId
```
Creare una nuova assegnazione di ruolo per sottoscrizione e oggetto. Per impostazione predefinita, l'assegnazione di ruolo verrà associata alla sottoscrizione predefinita. Sostituire $subscriptionId con l'ID sottoscrizione, $resourceGroupName con il nome del gruppo di risorse e $assigneeObjectId con il assignee-object-id generato (l'ID oggetto dell'entità servizio appena creato).
```
az role assignment create --role contributor --subscription $subscriptionId --assignee-object-id  $assigneeObjectId --assignee-principal-type ServicePrincipal --scope /subscriptions/$subscriptionId/resourceGroups/$resourceGroupName
```
Eseguire il comando seguente per creare una nuova credenziale di identità federata per l'applicazione Microsoft Entra.
- Sostituire APPLICATION-OBJECT-ID con il objectId (generato durante la creazione dell'app) per l'applicazione Microsoft Entra.
- Impostare un valore per CREDENTIAL-NAME a cui fare riferimento in seguito.
- Impostare subject. Il valore di questo valore è definito da GitHub a seconda del flusso di lavoro:
  - Processi nell'ambiente GitHub Actions: repo:< Organization/Repository >:environment:< Name >
  - Per i processi non associati a un ambiente, includere il percorso di riferimento per branch/tag in base al percorso di riferimento usato per attivare il flusso di lavoro: repo:< Organization/Repository >:ref:< ref path>. Ad esempio, repo:n-username/ node_express:ref:refs/heads/my-branch o repo:n-username/ node_express:ref:refs/tags/my-tag.
  - Per i flussi di lavoro attivati da un evento di richiesta 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"
    ]
}
```

In GitHub, andare al proprio repository.
Passare a Impostazioni nel menu di spostamento.
Selezionare Sicurezza > Segreti e variabili > Azioni.
Selezionare Nuovo segreto repository.
Incollare l'intero output JSON del comando dell'interfaccia della riga di comando di Azure nel campo del valore del segreto. Assegnare al segreto il nome AZURE_CREDENTIALS.
Selezionare Aggiungi segreto.

È necessario specificare l'ID client, l'ID tenant el'ID sottoscrizione dell'applicazione all'azione di accesso. Questi valori possono essere forniti direttamente nel flusso di lavoro oppure possono essere archiviati nei segreti gitHub e riportati nel flusso di lavoro. Salvare i valori come segreti GitHub è l'opzione più sicura.

In GitHub, andare al proprio repository.
Selezionare Sicurezza > Segreti e variabili > Azioni.
Selezionare Nuovo segreto repository.
Creare segreti per AZURE_CLIENT_ID, AZURE_TENANT_IDe AZURE_SUBSCRIPTION_ID. Usare questi valori dell'applicazione Microsoft Entra per i segreti di GitHub:

Segreto GitHub Applicazione Microsoft Entra

AZURE_CLIENT_ID ID applicazione (client)

AZURE_TENANT_ID ID della directory (tenant)

AZURE_SUBSCRIPTION_ID ID sottoscrizione
Salvare ogni segreto selezionando Aggiungi segreto.

Segreto GitHub	Applicazione Microsoft Entra
AZURE_CLIENT_ID	ID applicazione (client)
AZURE_TENANT_ID	ID della directory (tenant)
AZURE_SUBSCRIPTION_ID	ID sottoscrizione

Passaggio 3: aggiornare `setup.sh` per connettersi all'area di lavoro di Azure Machine Learning

Sarà necessario aggiornare le variabili del file di installazione dell'interfaccia della riga di comando in modo che corrispondano all'area di lavoro.

Nel repository con fork andare a azureml-examples/cli/.
Modificare setup.sh e aggiornare queste variabili nel file.

Variabile Descrizione

GROUP nome del gruppo di risorse

LOCATION Posizione dell'area di lavoro (ad esempio: eastus2)

AREA DI LAVORO Nome dell'area di lavoro di Azure Machine Learning

Variabile	Descrizione
GROUP	nome del gruppo di risorse
LOCATION	Posizione dell'area di lavoro (ad esempio: `eastus2`)
AREA DI LAVORO	Nome dell'area di lavoro di Azure Machine Learning

Passaggio 4: aggiornare `pipeline.yml` con il nome del cluster di elaborazione

Si userà un file pipeline.yml per distribuire la pipeline di Azure Machine Learning. Si tratta di una pipeline di Machine Learning e non di una pipeline DevOps. È necessario eseguire questo aggiornamento solo se si usa un nome diverso da cpu-cluster per il nome del cluster del computer.

Nel repository con fork andare a azureml-examples/cli/jobs/pipelines/nyc-taxi/pipeline.yml.
Ogni volta che viene visualizzato compute: azureml:cpu-cluster, aggiornare il valore di cpu-cluster con il nome del cluster di elaborazione. Ad esempio, se il cluster è denominato my-cluster, il nuovo valore sarà azureml:my-cluster. Sono disponibili cinque aggiornamenti.

Passaggio 5: eseguire il flusso di lavoro di GitHub Actions

Il flusso di lavoro esegue l'autenticazione con Azure, configura l'interfaccia della riga di comando di Azure Machine Learning e usa l'interfaccia della riga di comando per eseguire il training di un modello in Azure Machine Learning.

Entità servizio
OpenID Connect

Il file del flusso di lavoro è costituito da una sezione trigger e processi:

Un trigger avvia il flusso di lavoro nella sezione on. Il flusso di lavoro viene eseguito per impostazione predefinita in base a una pianificazione cronologica e quando viene effettuata una richiesta pull da rami e percorsi corrispondenti. Altre informazioni sugli eventi che attivano i flussi di lavoro.
Nella sezione dei processi del flusso di lavoro si estrae il codice e si accede ad Azure con il segreto dell'entità servizio.
La sezione processi include anche un'azione di installazione che installa e configura l'interfaccia della riga di comando di Machine Learning (v2). Dopo aver installato l'interfaccia della riga di comando, l'azione di esecuzione del processo esegue il file di Azure Machine Learning pipeline.yml per eseguire il training di un modello con i dati dei taxi di New York.

Abilitare il flusso di lavoro

Nel repository con fork aprire .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml e verificare che il flusso di lavoro sia simile al seguente.

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

Selezionare Visualizza esecuzioni.
Abilitare i flussi di lavoro selezionando Comprendo i flussi di lavoro, procedere e abilitarli.
Selezionare il flusso di lavoro cli-jobs-pipelines-nyc-taxi-pipelinee scegliere Abilita flusso di lavoro.
Selezionare Esegui flusso di lavoro e scegliere l'opzione per eseguire flusso di lavoro ora.

Il file del flusso di lavoro è costituito da una sezione trigger e processi:

Un trigger avvia il flusso di lavoro nella sezione on. Il flusso di lavoro viene eseguito per impostazione predefinita in base a una pianificazione cronologica e quando viene effettuata una richiesta pull da rami e percorsi corrispondenti. Altre informazioni sugli eventi che attivano i flussi di lavoro.
Nella sezione dei processi del flusso di lavoro si estrae il codice e si accede ad Azure con l'azione di accesso di Azure usando OpenID Connect.
La sezione processi include anche un'azione di installazione che installa e configura l'interfaccia della riga di comando di Machine Learning (v2). Dopo aver installato l'interfaccia della riga di comando, l'azione di esecuzione del processo esegue il file di Azure Machine Learning pipeline.yml per eseguire il training di un modello con i dati dei taxi di New York.

Abilitare il flusso di lavoro

Nel repository con fork aprire .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml e verificare che il flusso di lavoro sia simile al seguente.

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

Selezionare Visualizza esecuzioni.
Abilitare i flussi di lavoro selezionando Comprendo i flussi di lavoro, procedere e abilitarli.
Selezionare il flusso di lavoro cli-jobs-pipelines-nyc-taxi-pipelinee scegliere Abilita flusso di lavoro.
Selezionare Esegui flusso di lavoro e scegliere l'opzione per eseguire flusso di lavoro ora.

Passaggio 6: verificare l'esecuzione del flusso di lavoro

Aprire l'esecuzione del flusso di lavoro completata e verificare che il processo di compilazione sia stato eseguito correttamente. Accanto al processo verrà visualizzato un segno di spunta verde.
Aprire lo studio di Azure Machine Learning e passare a nyc-taxi-pipeline-example. Verificare che ogni parte del processo (preparazione, trasformazione, training, stima, punteggio) sia stata completata e che venga visualizzato un segno di spunta verde.

Pulire le risorse

Quando il gruppo di risorse e il repository non sono più necessari, pulire le risorse distribuite eliminando il gruppo di risorse e il repository GitHub.

Passaggi successivi

Creare pipeline di Machine Learning di produzione con l'SDK di Python

Condividi tramite

Usare GitHub Actions con Azure Machine Learning

Prerequisiti

Passaggio 1: ottenere il codice

Passaggio 2: eseguire l'autenticazione con Azure

Generare le credenziali per la distribuzione

Creare segreti

Passaggio 3: aggiornare `setup.sh` per connettersi all'area di lavoro di Azure Machine Learning

Passaggio 4: aggiornare `pipeline.yml` con il nome del cluster di elaborazione

Passaggio 5: eseguire il flusso di lavoro di GitHub Actions

Abilitare il flusso di lavoro

Abilitare il flusso di lavoro

Passaggio 6: verificare l'esecuzione del flusso di lavoro

Pulire le risorse

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Usare GitHub Actions con Azure Machine Learning

Prerequisiti

Passaggio 1: ottenere il codice

Passaggio 2: eseguire l'autenticazione con Azure

Generare le credenziali per la distribuzione

Creare segreti

Passaggio 3: aggiornare setup.sh per connettersi all'area di lavoro di Azure Machine Learning

Passaggio 4: aggiornare pipeline.yml con il nome del cluster di elaborazione

Passaggio 5: eseguire il flusso di lavoro di GitHub Actions

Abilitare il flusso di lavoro

Passaggio 6: verificare l'esecuzione del flusso di lavoro

Pulire le risorse

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Passaggio 3: aggiornare `setup.sh` per connettersi all'area di lavoro di Azure Machine Learning

Passaggio 4: aggiornare `pipeline.yml` con il nome del cluster di elaborazione