Utiliser GitHub Actions avec Azure Machine Learning

S’APPLIQUE À :Extension Azure ML CLI v2 (actuelle)Kit de développement logiciel (SDK) Python azure-ai-ml v2 (préversion)

Prise en main de GitHub Actions pour entraîner un modèle sur Azure Machine Learning.

Cet article va vous apprendre à créer un workflow GitHub Actions, qui génère et déploie un modèle Machine Learning sur Azure Machine Learning. Vous allez entraîner un modèle de régression linéaire scikit-learn sur le jeu de données NYC Taxi.

GitHub Actions utilise un fichier YAML (.yml) de workflow dans le chemin /.github/workflows/ de votre dépôt. Cette définition contient les étapes et les paramètres qui composent le workflow.

Prérequis

Avant de suivre les étapes décrites dans cet article, vérifiez que vous disposez des composants requis suivants :

• Un espace de travail Azure Machine Learning. Si vous n’en avez pas, procédez comme suit dans le Guide de démarrage rapide : Créer des ressources d’espace de travail pour en créer un.

• Pour installer le kit SDK Python v2, utilisez la commande suivante :

  pip install azure-ai-ml azure-identity
  

  Pour mettre à jour une installation existante du Kit de développement logiciel (SDK) vers la version la plus récente, utilisez la commande suivante :

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

  Pour plus d’informations, consultez Installer le kit SDK Python v2 pour Azure Machine Learning.

• Un compte GitHub. Si vous n’en avez pas, inscrivez-vous gratuitement.

Étape 1 : Obtenir le code

Effectuez une duplication (fork) du dépôt suivant sur GitHub :

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

Étape 2 : S’authentifier auprès d’Azure

Vous devez d’abord définir comment vous authentifier auprès d’Azure. Vous pouvez utiliser un principal de service ou OpenID Connect.

Générer les informations d’identification du déploiement

Principal du service

Créez un principal de service à l’aide de la commande az ad sp create-for-rbac dans Azure CLI. Exécutez cette commande en utilisant Azure Cloud Shell dans le portail Azure ou en sélectionnant le bouton Essayer.

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

Le paramètre --json-auth est disponible dans les versions d’Azure CLI >= 2.51.0. Les versions antérieures à celle-ci utilisent --sdk-auth avec un avertissement de dépréciation.

Dans l’exemple ci-dessus, remplacez les espaces réservés par votre ID d’abonnement, le nom de votre groupe de ressources et le nom de votre application. La sortie correspond à un objet JSON avec les informations d’identification de l’attribution de rôle qui fournit l’accès à votre application App Service, similaire à ce qui suit. Copiez cet objet JSON pour une version ultérieure.

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

OpenID Connect

OpenID Connect est une méthode d’authentification qui utilise des jetons de courte durée. La configuration d’OpenID Connect avec GitHub Actions est un processus plus complexe qui offre une sécurité renforcée.

1. Si vous n’avez pas d’application existante, inscrivez une nouvelle application Microsoft Entra et un principal de service pouvant accéder aux ressources.

   az ad app create --display-name myApp
   

   Cette commande affiche une sortie JSON avec un appId qui est votre client-id. Le objectId est APPLICATION-OBJECT-ID et il sera utilisé pour créer des informations d’identification fédérées avec des appels d’API Graph. Enregistrez la valeur à utiliser comme secret GitHub AZURE_CLIENT_ID ultérieurement.

2. Créer un principal de service. Remplacez le $appID par l’appID de votre sortie JSON. Cette commande génère une sortie JSON avec un objectId différent qui sera utilisée à l’étape suivante. Le nouveau objectId est le assignee-object-id.

   Cette commande génère une sortie JSON avec un objectId différent, qui sera utilisée à l’étape suivante. Le nouveau objectId est le assignee-object-id.

   copiez le appOwnerTenantId à utiliser comme secret GitHub pour AZURE_TENANT_ID ultérieurement.

    az ad sp create --id $appId
   

3. Créez une attribution de rôle par abonnement et objet. Par défaut, l’attribution de rôle est liée à votre abonnement par défaut. Remplacez $subscriptionId par votre ID d’abonnement, $resourceGroupName par le nom de votre groupe de ressources et $assigneeObjectId par le assignee-object-id généré (l’identifiant de l’objet du principal de service nouvellement créé).

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

4. Exécutez la commande suivante pour créer des informations d’identification d’identité fédérée pour votre application Microsoft Entra.

   • Remplacez APPLICATION-OBJECT-ID par l’objectId (généré lors de la création de l’application) pour votre application Microsoft Entra.
   • Définissez une valeur pour CREDENTIAL-NAME que vous référencerez ultérieurement.
   • Définissez subject. Cette valeur est définie par GitHub en fonction de votre workflow :
     • Travaux dans votre environnement GitHub Actions : repo:< Organization/Repository >:environment:< Name >
     • Pour les tâches non liées à un environnement, incluez le chemin de référence (ref path) de la branche/étiquette en fonction du chemin de référence utilisé pour déclencher le workflow : repo:< Organization/Repository >:ref:< ref path>. Par exemple, repo:n-username/ node_express:ref:refs/heads/my-branch ou repo:n-username/ node_express:ref:refs/tags/my-tag.
     • Pour les workflows déclenchés par un événement de demande de tirage (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"
       ]
   }
   

Créer des secrets

Principal du service

1. Dans GitHub, accédez à votre dépôt.

2. Sélectionnez Paramètres dans le volet de navigation.

3. Sélectionnez Sécurité > Secrets et variables > Actions.

   

4. Sélectionnez New repository secret (Nouveau secret de dépôt).

5. Collez l’intégralité de la sortie JSON de la commande Azure CLI dans le champ de valeur du secret. Nommez le secret AZURE_CREDENTIALS.

6. Sélectionnez Ajouter un secret.

OpenID Connect

Vous devez fournir l’ID de client, l’ID de locataire et l’ID d’abonnement de votre application à l’action de connexion. Vous pouvez fournir ces valeurs directement dans le workflow ou les stocker dans des secrets GitHub et les référencer dans votre workflow. L’enregistrement des valeurs en tant que secrets GitHub est l’option la plus sécurisée.

1. Dans GitHub, accédez à votre dépôt.

2. Sélectionnez Sécurité > Secrets et variables > Actions.

   

3. Sélectionnez New repository secret (Nouveau secret de dépôt).

4. Créez des secrets pour AZURE_CLIENT_ID, AZURE_TENANT_ID et AZURE_SUBSCRIPTION_ID. Utilisez ces valeurs à partir de votre application Microsoft Entra pour vos secrets GitHub :

   Secret GitHub	Application Microsoft Entra
   AZURE_CLIENT_ID	ID d’application (client)
   AZURE_TENANT_ID	ID de l’annuaire (locataire)
   AZURE_SUBSCRIPTION_ID	Identifiant d’abonnement

5. Enregistrez chaque secret en sélectionnant Ajouter un secret.

Étape 3 : Mettre à jour setup.sh pour vous connecter à votre espace de travail Azure Machine Learning

Vous devez mettre à jour les variables du fichier d’installation CLI pour qu’elles correspondent à votre espace de travail.

1. Dans votre dépôt cloné, accédez à azureml-examples/cli/.

2. Modifiez setup.sh et mettez à jour ces variables dans le fichier.

   Variable	Description
   GROUP	nom du groupe de ressources
   LOCATION	Lieu de votre espace de travail (exemple : eastus2)
   ESPACE DE TRAVAIL	Nom de l’espace de travail Azure Machine Learning

Étape 4 : Mettre à jour pipeline.yml avec le nom de votre cluster de calcul

Vous allez utiliser un fichier pipeline.yml pour déployer votre pipeline Azure Machine Learning. Il s’agit d’un pipeline Machine Learning et non d’un pipeline DevOps. Vous devez uniquement effectuer cette mise à jour si vous utilisez un autre nom que cpu-cluster pour le nom de votre cluster de calcul.

1. Dans votre dépôt cloné, accédez à azureml-examples/cli/jobs/pipelines/nyc-taxi/pipeline.yml.
2. Chaque fois que vous voyez compute: azureml:cpu-cluster, mettez à jour la valeur de cpu-cluster avec le nom de votre cluster de calcul. Par exemple, si votre cluster se nomme my-cluster, la nouvelle valeur est azureml:my-cluster. Il existe cinq mises à jour.

Étape 5 : Exécuter votre workflow GitHub Actions

Votre workflow s’authentifie auprès d’Azure, configure l’interface CLI Azure Machine Learning, puis utilise l’interface CLI pour entraîner un modèle dans Azure Machine Learning.

Principal du service

Votre fichier de workflow est composé d’une section comprenant un déclencheur et d’une section comprenant des travaux :

• Un déclencheur démarre le workflow dans la section on. Le workflow s’exécute par défaut selon une planification Cron et quand une demande de tirage (pull request) est effectuée à partir des branches et des chemins correspondants. Découvrez plus en détail les événements qui déclenchent des workflows.
• Dans la section des travaux du workflow, vous extrayez le code et vous vous connectez à Azure avec votre secret de principal de service.
• La section des travaux comprend également une action d’installation qui installe et configure l’interface CLI Machine Learning (v2). Une fois l’interface CLI installée, l’action d’exécution des travaux exécute votre fichier pipeline.yml Azure Machine Learning pour entraîner un modèle avec les données de NYC Taxi.

Activer votre workflow

1. Dans votre dépôt cloné, ouvrez .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml et vérifiez que votre workflow ressemble à ceci.

   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. Sélectionnez Afficher les exécutions.

3. Activez les workflows en sélectionnant I understand my workflows, go ahead and enable them (Je comprends mes workflows. Continuer l’opération et activer les workflows).

4. Sélectionnez le workflow cli-jobs-pipelines-nyc-taxi-pipeline, puis choisissez Activer le workflow.

5. Sélectionnez Exécuter le workflow, puis choisissez l’option Exécuter le workflow.

OpenID Connect

Votre fichier de workflow est composé d’une section comprenant un déclencheur et d’une section comprenant des travaux :

• Un déclencheur démarre le workflow dans la section on. Le workflow s’exécute par défaut selon une planification Cron et quand une demande de tirage (pull request) est effectuée à partir des branches et des chemins correspondants. Découvrez plus en détail les événements qui déclenchent des workflows.
• Dans la section des travaux du workflow, vous extrayez le code et vous vous connectez à Azure avec l’action de connexion à Azure en utilisant OpenID Connect.
• La section des travaux comprend également une action d’installation qui installe et configure l’interface CLI Machine Learning (v2). Une fois l’interface CLI installée, l’action d’exécution des travaux exécute votre fichier pipeline.yml Azure Machine Learning pour entraîner un modèle avec les données de NYC Taxi.

Activer votre workflow

1. Dans votre dépôt cloné, ouvrez .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml et vérifiez que votre workflow ressemble à ceci.

   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. Sélectionnez Afficher les exécutions.

3. Activez les workflows en sélectionnant I understand my workflows, go ahead and enable them (Je comprends mes workflows. Continuer l’opération et activer les workflows).

4. Sélectionnez le workflow cli-jobs-pipelines-nyc-taxi-pipeline, puis choisissez Activer le workflow.

   

5. Sélectionnez Exécuter le workflow, puis choisissez l’option Exécuter le workflow.

   

Étape 6 : Vérifier l’exécution de workflow

1. Ouvrez l’exécution de workflow qui s’est achevée, puis vérifiez que le travail de build s’est correctement exécuté. Vous voyez une coche verte en regard du travail.

2. Ouvrez Azure Machine Learning Studio, et accédez à nyc-taxi-pipeline-example. Vérifiez que chaque partie de votre travail (préparation, transformation, entraînement, prédiction, scoring) s’est effectuée, et que vous voyez une coche verte.

   

Nettoyer les ressources

Lorsque votre groupe de ressource et référentiel ne sont plus nécessaires, nettoyez les ressources que vous avez déployées en supprimant le groupe de ressources et votre référentiel GitHub.

Étapes suivantes

Créer des pipelines ML de production avec le kit SDK Python