Uso de Acciones de GitHub con Azure Machine Learning

SE APLICA A:Extensión ML de la CLI de Azure v2 (actual)SDK de Python azure-ai-ml v2 (actual)

Introducción a Acciones de GitHub para entrenar un modelo en Azure Machine Learning.

En este artículo se explica cómo crear un flujo de trabajo de Acciones de GitHub que compila e implementa un modelo de Machine Learning en Azure Machine Learning. Entrenará un modelo de regresión lineal scikit-learn en el conjunto de datos nyc Taxi.

Defina un flujo de trabajo de Acciones de GitHub en un archivo YAML (.yml) en la ruta de acceso /.github/workflows/ del repositorio. En esta definición se incluyen los diversos pasos y parámetros que componen el flujo de trabajo.

Prerrequisitos

Antes de seguir los pasos de este artículo, asegúrese de que tiene los siguientes requisitos previos:

• Un área de trabajo de Azure Machine Learning. Si no tiene uno, siga los pasos descritos en el artículo Inicio rápido: Creación de recursos del área de trabajo para crear uno.

• Para instalar el SDK de Python v2, use el siguiente comando:

  pip install azure-ai-ml azure-identity
  

  Para actualizar una instalación existente del SDK a la versión más reciente, use el siguiente comando:

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

  Para más información, consulte Instalación del SDK v2 de Python para Azure Machine Learning.

• Una cuenta de GitHub. Si no tiene ninguna, regístrese para obtener una gratuita.

Paso 1: Obtención del código

Bifurque el repositorio siguiente en GitHub:

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

Clone el repositorio bifurcado localmente.

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

Paso 2: Autenticación con Azure

Primero deberá definir cómo autenticarse con Azure. Puede usar una entidad de servicio o OpenID Connect.

Genere las credenciales de implementación.

Entidad de servicio

Cree una entidad de servicio mediante el comando az ad sp create-for-rbac de la CLI de Azure. Puede ejecutar este comando mediante Azure Cloud Shell en Azure Portal o haciendo clic en el botón Probar.

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

El parámetro --json-auth está disponible en las versiones de la CLI de Azure >= 2.51.0. Las versiones anteriores a esta usan --sdk-auth con una advertencia de desuso.

En este ejemplo, reemplace los marcadores de posición por su identificador de suscripción, el nombre del grupo de recursos y el nombre de la aplicación. La salida es un objeto JSON con las credenciales de asignación de roles que proporcionan acceso a la aplicación App Service similar al siguiente. Copie este objeto JSON para más adelante.

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

OpenID Connect

Open ID Connect es un método de autenticación que usa tokens de corta duración. La configuración de OpenID Connect con Acciones de GitHub es un proceso más complejo que ofrece seguridad reforzada.

1. Si no tiene una aplicación existente, registre una nueva aplicación de Microsoft Entra y una entidad de servicio que puedan acceder a los recursos.

   az ad app create --display-name myApp
   

   Este comando genera un JSON de salida con un appId que es su client-id. La objectId es APPLICATION-OBJECT-ID y se usará para crear credenciales federadas con llamadas a la Graph API. Guarde el valor que se usará como secreto de GitHub de AZURE_CLIENT_ID más adelante.

2. Crear una entidad de servicio. Reemplace $appID por el valor de appId de la salida de JSON. Este comando genera una salida de JSON con un objectId diferente y se usará en el siguiente paso. El nuevo objectId es assignee-object-id.

   Este comando genera una salida de JSON con un objectId diferente y se usará en el siguiente paso. El nuevo objectId es assignee-object-id.

   Copie el appOwnerTenantId para usarlo como secreto de GitHub para AZURE_TENANT_ID más adelante.

    az ad sp create --id $appId
   

3. Cree una asignación de roles por suscripción y objeto. De forma predeterminada, la asignación de roles se vinculará a la suscripción predeterminada. Reemplace $subscriptionId por el ID de suscripción, $resourceGroupName por el nombre del grupo de recursos y $assigneeObjectId por el valor de assignee-object-id generado (el id. de objeto de la entidad de servicio recién creada).

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

4. Ejecute el siguiente comando para crear una credencial de identidad federada para la aplicación de Microsoft Entra.

   • Reemplace APPLICATION-OBJECT-ID por el objectId (generado al crear la aplicación) de la aplicación de Microsoft Entra.
   • Establezca un valor para CREDENTIAL-NAME al que haga referencia más adelante.
   • Establezca subject. Este valor lo define GitHub en función del flujo de trabajo:
     • Trabajos en el entorno de Acciones de GitHub: repo:< Organization/Repository >:environment:< Name >
     • En el caso de los trabajos no vinculados a un entorno, incluya la ruta de acceso de referencia para una rama o etiqueta en función de la ruta de acceso de referencia usada para desencadenar el flujo de trabajo: repo:< Organization/Repository >:ref:< ref path>. Por ejemplo, repo:n-username/ node_express:ref:refs/heads/my-branch o repo:n-username/ node_express:ref:refs/tags/my-tag.
     • En el caso de los flujos de trabajo desencadenados por un evento de solicitud de incorporación de cambios: 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"
       ]
   }
   

Crear secretos

Entidad de servicio

1. En GitHub, vaya al repositorio.

2. Vaya a Configuración en el menú de navegación.

3. Seleccione Seguridad > Secretos y variables > Acciones.

   

4. Seleccione New repository secret (Nuevo secreto del repositorio).

5. Pegue la salida JSON completa del comando de la CLI de Azure en el campo de valor del secreto. Asigne al secreto el nombre AZURE_CREDENTIALS.

6. Seleccione Add secret (Agregar secreto).

OpenID Connect

Debe especificar el identificador de cliente, el identificador de inquilino y el identificador de suscripción en la acción de inicio de sesión. Estos valores se pueden proporcionar directamente en el flujo de trabajo o se pueden almacenar en secretos de GitHub y se puede hacer referencia a ellos en el flujo de trabajo. Guardar los valores como secretos de GitHub es la opción más segura.

1. En GitHub, vaya al repositorio.

2. Seleccione Seguridad > Secretos y variables > Acciones.

   

3. Seleccione New repository secret (Nuevo secreto del repositorio).

4. Cree secretos para AZURE_CLIENT_ID, AZURE_TENANT_ID y AZURE_SUBSCRIPTION_ID. Use estos valores de la aplicación de Microsoft Entra para los secretos de GitHub:

   Secreto de GitHub	Aplicación de Microsoft Entra
   AZURE_CLIENT_ID	Id. de aplicación (cliente)
   AZURE_TENANT_ID	Id. de directorio (inquilino)
   AZURE_SUBSCRIPTION_ID	Id. de suscripción

5. Guarde todos los secretos, para lo que debe seleccionar Add secret (Agregar secreto).

Paso 3: Actualización setup.sh para conectarse al área de trabajo de Azure Machine Learning

Deberá actualizar las variables del archivo de instalación de la CLI para que coincidan con el área de trabajo.

1. En el repositorio bifurcada, vaya a azureml-examples/cli/.

2. Edite setup.sh y actualice estas variables en el archivo.

   Variable	Descripción
   GROUP	nombre del grupo de recursos.
   LOCATION	Ubicación del área de trabajo (ejemplo: eastus2)
   ÁREA DE TRABAJO	Nombre del área de trabajo de Azure Machine Learning

Paso 4: Actualización pipeline.yml con el nombre del clúster de proceso

Usará un pipeline.yml archivo para implementar la canalización de Azure Machine Learning. Se trata de una canalización de aprendizaje automático y no una canalización de DevOps. Solo tiene que realizar esta actualización si usa un nombre distinto cpu-cluster del nombre del clúster del equipo.

1. En el repositorio bifurcada, vaya a azureml-examples/cli/jobs/pipelines/nyc-taxi/pipeline.yml.
2. Cada vez que vea compute: azureml:cpu-cluster, actualice el valor de con el nombre del clúster de cpu-cluster proceso. Por ejemplo, si su grupo se denominamy-cluster, su nuevo valor sería azureml:my-cluster. Hay cinco actualizaciones.

Paso 5: Ejecución del flujo de trabajo de Acciones de GitHub

El flujo de trabajo se autentica con Azure, configura la CLI de Azure Machine Learning y usa la CLI para entrenar un modelo en Azure Machine Learning.

Entidad de servicio

El archivo de flujo de trabajo se compone de una sección de desencadenador y trabajos:

• Un desencadenador inicia el flujo de trabajo en la sección on. El flujo de trabajo se ejecuta de forma predeterminada en una programación cron y cuando se realiza una solicitud de incorporación de cambios a partir de ramas y rutas de acceso coincidentes. Obtenga más información sobre los eventos que desencadenan flujos de trabajo.
• En la sección de trabajos del flujo de trabajo, el código de desprotección y el inicio de sesión en Azure con el secreto de la entidad de servicio.
• La sección trabajos también incluye una acción de instalación que instala y configura la CLI de Machine Learning (v2). Una vez instalada la CLI, la acción ejecutar trabajo ejecuta el archivo de Azure Machine Learning pipeline.yml para entrenar un modelo con datos de taxis de Nueva York.

Habilitación del flujo de trabajo

1. En el repositorio bifurcada, abra .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml y compruebe que el flujo de trabajo tiene este aspecto.

   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. Seleccione Ver ejecuciones.

3. Habilite los flujos de trabajo seleccionando Entiendo mis flujos de trabajo, continúe y habilítelos.

4. Seleccione el flujo de trabajo cli-jobs-pipelines-nyc-taxi-pipeline y elija Habilitar flujo de trabajo.

5. Seleccione Ejecutar flujo de trabajo y elija la opción Ejecutar flujo de trabajo ahora.

OpenID Connect

El archivo de flujo de trabajo se compone de una sección de desencadenador y trabajos:

• Un desencadenador inicia el flujo de trabajo en la sección on. El flujo de trabajo se ejecuta de forma predeterminada en una programación cron y cuando se realiza una solicitud de incorporación de cambios a partir de ramas y rutas de acceso coincidentes. Obtenga más información sobre los eventos que desencadenan flujos de trabajo.
• En la sección trabajos del flujo de trabajo, el código de desprotegerá e inicia sesión en Azure con la acción de inicio de sesión de Azure mediante OpenID Connect.
• La sección trabajos también incluye una acción de instalación que instala y configura la CLI de Machine Learning (v2). Una vez instalada la CLI, la acción ejecutar trabajo ejecuta el archivo de Azure Machine Learning pipeline.yml para entrenar un modelo con datos de taxis de Nueva York.

Habilitación del flujo de trabajo

1. En el repositorio bifurcada, abra .github/workflows/cli-jobs-pipelines-nyc-taxi-pipeline.yml y compruebe que el flujo de trabajo tiene este aspecto.

   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. Seleccione Ver ejecuciones.

3. Habilite los flujos de trabajo seleccionando Entiendo mis flujos de trabajo, continúe y habilítelos.

4. Seleccione el flujo de trabajo cli-jobs-pipelines-nyc-taxi-pipeline y elija Habilitar flujo de trabajo.

   

5. Seleccione Ejecutar flujo de trabajo y elija la opción Ejecutar flujo de trabajo ahora.

   

Paso 6: Comprobación de la ejecución del flujo de trabajo

1. Abra la ejecución del flujo de trabajo completado y compruebe que el trabajo de compilación se ejecutó correctamente. Verá una marca de verificación verde junto al trabajo.

2. Abra Estudio de Azure Machine Learning y vaya al nyc-taxi-pipeline-example. Compruebe que se ha completado cada parte del trabajo (preparación, transformación, entrenamiento, predicción, puntuación) y que ve una marca de verificación verde.

   

Limpieza de recursos

Cuando el repositorio y el grupo de recursos ya no sean necesarios, limpie los recursos que implementó eliminando el grupo de recursos y el repositorio de GitHub.

Pasos siguientes

Creación de canalizaciones de MACHINE de producción con el SDK de Python