Configurar explicaciones basadas en características

Para usar Vertex Explainable AI con un modelo entrenado de forma personalizada, debes configurar determinadas opciones al crear el recurso Model del que quieras solicitar explicaciones, al desplegar el modelo o al enviar una tarea de explicación por lotes. En esta página se describe cómo configurar estas opciones.

Si quieres usar Vertex Explainable AI con un modelo tabular de AutoML, no tienes que hacer ninguna configuración. Vertex AI configura automáticamente el modelo para Vertex Explainable AI. Salta este documento y consulta Cómo obtener explicaciones.

Cuándo y dónde configurar explicaciones

Las explicaciones se configuran al crear o importar un modelo. También puedes configurar explicaciones en un modelo que ya hayas creado, aunque no lo hayas hecho antes.

Configurar explicaciones al crear o importar modelos

Cuando creas o importas un Model, puedes definir una configuración predeterminada para todas sus explicaciones mediante el campo explanationSpec del Model.

Puedes crear un Model entrenado de forma personalizada en Vertex AI de las siguientes formas:

• Importar o registrar un Model en el registro de modelos de Vertex AI
• Crea un recurso TrainingPipeline personalizado que importe un Model.
• Crea un modelo de BigQuery ML y especifica el ajuste model_registry opcional en la sintaxis CREATE MODEL. Esta opción registra automáticamente el modelo en el registro de modelos de Vertex AI y configura su explanationSpec.

En cualquier caso, puedes configurar el Model para que sea compatible con IA explicable de Vertex. En los ejemplos de este documento se presupone que vas a importar un Model. Para configurar Vertex Explainable AI al crear un Model con entrenamiento personalizado mediante un TrainingPipeline, usa los ajustes de configuración que se describen en este documento en el campo modelToUpload del TrainingPipeline.

Configurar explicaciones al desplegar modelos u obtener inferencias por lotes

Cuando despliegas un Model en un recurso Endpoint, puedes hacer lo siguiente:

• Configurar explicaciones, independientemente de si el modelo se ha configurado previamente para las explicaciones. Esto resulta útil si no tenías previsto obtener explicaciones (y omitiste el campo explanationSpec al crear el modelo), pero más adelante decides que quieres explicaciones para el modelo o si quieres anular algunos de los ajustes de las explicaciones.
• Inhabilitar explicaciones. Esto resulta útil si tu modelo está configurado para generar explicaciones, pero no tienes previsto obtenerlas del endpoint. Para inhabilitar las explicaciones al desplegar el modelo en un endpoint, desmarca las opciones de interpretabilidad en la consola de Cloud o define DeployedModel.disableExplanations en true.

Del mismo modo, cuando obtienes inferencias por lotes de un Model, puedes configurar las explicaciones rellenando el BatchPredictionJob.explanationSpeccampo o inhabilitarlas asignando el valor BatchPredictionJob.generateExplanation a false.

Anular la configuración al obtener explicaciones online

Independientemente de si has creado o importado el Model con ajustes de explicación, y de si has configurado los ajustes de explicación durante la implementación, puedes anular los ajustes de explicación iniciales del Model cuando obtengas explicaciones online.

Cuando envías una solicitud explain a Vertex AI, puedes anular parte de la configuración de la explicación que hayas definido previamente para Model o DeployedModel.

En la solicitud explain, puede anular los siguientes campos:

• Valores de referencia de entrada para cualquier modelo entrenado de forma personalizada
• Configuración de visualizaciones para modelos de imágenes
• ExplanationParameters excepto el method

Anula estos ajustes en el campo explanationSpecOverride de la solicitud de explicación.

Importar un modelo con un campo explanationSpec

En función de si sirves inferencias con un contenedor prediseñado o un contenedor personalizado, especifica detalles ligeramente diferentes para ExplanationSpec. Selecciona la pestaña que corresponda al contenedor que estés usando:

Contenedor prediseñado de TensorFlow

Puedes usar cualquiera de los siguientes métodos de atribución para Vertex Explainable AI. Lee la comparación de los métodos de atribución de funciones para seleccionar el más adecuado para tu Model:

En los siguientes ejemplos se presupone que el modelo acepta una sola característica de entrada, como suele ocurrir con los modelos secuenciales de Keras y muchos otros modelos de TensorFlow. Como la función es un tensor de cualquier forma, puede codificar muchos datos. Cuando solicitas explicaciones, Vertex Explainable AI proporciona atribuciones de cada elemento del tensor.

Si tu modelo acepta varios tensores de entrada con nombre, añade las entradas correspondientes al campo de metadatos inputs.

En el caso de los modelos de TensorFlow 2, ExplanationMetadata es opcional. Si se omite, Vertex AI infiere automáticamente los valores del modelo y usa los nombres de los tensores como nombres de las características. En este cuaderno se muestra cómo importar un modelo sin ExplanationMetadata.

Shapley muestreado

En función de la herramienta que quieras usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Consola

Sigue la guía para importar un modelo con la Google Cloud consola. Cuando llegues al paso Explicabilidad, haz lo siguiente:

1. En el método de atribución de funciones, seleccione Muestreo de Shapley (para modelos tabulares).

2. Define el recuento de rutas como el número de permutaciones de funciones que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

   Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

3. Configura cada característica de entrada de tu modelo:

   Nota: En los modelos de TensorFlow 2, el nombre de la función de entrada es opcional.

   1. Escribe el nombre de la función de entrada.

   2. También puedes añadir una o varias líneas de base de entrada. De lo contrario, Vertex Explainable AI elige una línea de base de entrada predeterminada con todos los valores cero, que es una imagen negra para los datos de imagen.

   3. Si importas un modelo de TensorFlow, hay campos de entrada adicionales:

      1. Rellena el campo Nombre del tensor de entrada.

      2. Si procede, rellena los campos Nombre del tensor de índices y Nombre del tensor de forma densa.

      3. La modalidad no se puede actualizar aquí. Se define automáticamente como NUMERIC para los modelos tabulares o como IMAGE para los modelos de imagen.

      4. Si procede, define el campo Codificación. Si no se define ningún valor, se asigna IDENTITY de forma predeterminada.

      5. Si procede, define el campo Nombre del grupo.

4. Si vas a importar un modelo de TensorFlow, especifica los campos de salida:

   1. Define el nombre de salida de la función.
   2. Define el nombre del tensor de salida de tu función.
   3. Si procede, define la asignación de nombres visibles de índice.
   4. Si procede, define la clave de asignación del nombre visible.

5. Cuando hayas terminado de configurar los ajustes de interpretabilidad, haz clic en el botón Importar.

gcloud

1. En TensorFlow 2, ExplanationMetadata es opcional.

   Escribe lo siguiente: ExplanationMetadata en un archivo JSON de tu entorno local. El nombre del archivo no importa, pero en este ejemplo, llámalo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   Haz los cambios siguientes:

   • FEATURE_NAME: cualquier nombre memorable para la función de entrada.
   • INPUT_TENSOR_NAME: nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.
   • OUTPUT_NAME: cualquier nombre fácil de recordar para la salida del modelo.
   • OUTPUT_TENSOR_NAME: nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.

   También puedes añadir líneas de base de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige las líneas de base de entrada para Model.

2. Ejecuta el siguiente comando para crear un recurso Model que admita Vertex Explainable AI. Se destacan las marcas más pertinentes para Vertex Explainable AI.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Haz los cambios siguientes:

   • IMAGE_URI: el URI de un contenedor prediseñado de TensorFlow para servir predicciones.

   • PATH_COUNT: el número de permutaciones de características que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

     Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

   Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• IMAGE_URI: el URI de un contenedor prediseñado de TensorFlow para servir predicciones.

• PATH_COUNT: el número de permutaciones de características que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

  Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

• FEATURE_NAME: cualquier nombre memorable para la función de entrada.
• INPUT_TENSOR_NAME: nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.
• OUTPUT_NAME: cualquier nombre fácil de recordar para la salida del modelo.
• OUTPUT_TENSOR_NAME: nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.

Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

También puedes añadir líneas de base de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige las líneas de base de entrada para Model.

En los modelos de TensorFlow 2, el campo metadata es opcional. Si se omite, Vertex AI infiere automáticamente inputs y outputs del modelo.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Cuerpo JSON de la solicitud:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "sampledShapleyAttribution": {
          "pathCount": PATH_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Degradados integrados

En función de la herramienta que quieras usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Consola

Sigue la guía para importar un modelo con la Google Cloud consola. Cuando llegues al paso Explicabilidad, haz lo siguiente:

1. En el método de atribución de la función, selecciona Gradientes integrados (para modelos tabulares) o Gradientes integrados (para modelos de clasificación de imágenes), según cuál sea más adecuado para tu modelo.

2. Si va a importar un modelo de clasificación de imágenes, siga estos pasos:

   1. Define el Tipo de visualización y el Mapa de colores.

   2. Puedes dejar los valores predeterminados de Clip debajo, Clip arriba, Tipo de superposición y Número de pasos integrales.

   Más información sobre los ajustes de visualización

3. Define el número de pasos que se deben usar para aproximar la integral de ruta durante la atribución de características. Debe ser un número entero comprendido entre [1, 100].

   Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 50.

4. Configura cada característica de entrada de tu modelo:

   Nota: En los modelos de TensorFlow 2, el nombre de la función de entrada es opcional.

   1. Escribe el nombre de la función de entrada.

   2. También puedes añadir una o varias líneas de base de entrada. De lo contrario, Vertex Explainable AI elige una línea de base de entrada predeterminada con todos los valores cero, que es una imagen negra para los datos de imagen.

   3. Si importas un modelo de TensorFlow, hay campos de entrada adicionales:

      1. Rellena el campo Nombre del tensor de entrada.

      2. Si procede, rellena los campos Nombre del tensor de índices y Nombre del tensor de forma densa.

      3. La modalidad no se puede actualizar aquí. Se define automáticamente como NUMERIC para los modelos tabulares o como IMAGE para los modelos de imagen.

      4. Si procede, define el campo Codificación. Si no se define ningún valor, se asigna IDENTITY de forma predeterminada.

      5. Si procede, define el campo Nombre del grupo.

5. Si vas a importar un modelo de TensorFlow, especifica los campos de salida:

   1. Define el nombre de salida de la función.
   2. Define el nombre del tensor de salida de tu función.
   3. Si procede, define la asignación de nombres visibles de índice.
   4. Si procede, define la clave de asignación del nombre visible.

6. Cuando hayas terminado de configurar los ajustes de interpretabilidad, haz clic en el botón Importar.

gcloud

1. En TensorFlow 2, ExplanationMetadata es opcional.

   Escribe lo siguiente: ExplanationMetadata en un archivo JSON de tu entorno local. El nombre del archivo no importa, pero en este ejemplo, llámalo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
         "modality": "MODALITY",
         "visualization": VISUALIZATION_SETTINGS
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   Haz los cambios siguientes:

   • FEATURE_NAME: cualquier nombre memorable para la función de entrada.
   • INPUT_TENSOR_NAME: nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.
   • MODALITY: image si Model acepta imágenes como entrada o numeric si Model acepta datos tabulares como entrada. El valor predeterminado es numeric.

   • VIZUALIZATION_OPTIONS: opciones para visualizar explicaciones. Para saber cómo rellenar este campo, consulta Configurar los ajustes de visualización de datos de imagen.

     Si omite el campo modality o le asigna el valor numeric, omita el campo visualization por completo.modality

   • OUTPUT_NAME: cualquier nombre fácil de recordar para la salida del modelo.
   • OUTPUT_TENSOR_NAME: nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.

   También puedes añadir líneas de base de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige las líneas de base de entrada para Model.

2. Ejecuta el siguiente comando para crear un recurso Model que admita Vertex Explainable AI. Se destacan las marcas más pertinentes para Vertex Explainable AI.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=integrated-gradients \
     --explanation-step-count=STEP_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Haz los cambios siguientes:

   • IMAGE_URI: el URI de un contenedor prediseñado de TensorFlow para servir predicciones.
   • STEP_COUNT: número de pasos que se deben usar para aproximar la integral de la ruta durante la atribución de funciones. Debe ser un número entero comprendido entre [1, 100].

     Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 50.

   Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

   También puedes añadir marcas para configurar la aproximación SmoothGrad de los gradientes.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• IMAGE_URI: el URI de un contenedor prediseñado de TensorFlow para servir predicciones.
• STEP_COUNT: número de pasos que se deben usar para aproximar la integral de la ruta durante la atribución de funciones. Debe ser un número entero comprendido entre [1, 100].

  Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 50.

• FEATURE_NAME: cualquier nombre memorable para la función de entrada.
• INPUT_TENSOR_NAME: nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.
• MODALITY: image si Model acepta imágenes como entrada o numeric si Model acepta datos tabulares como entrada. El valor predeterminado es numeric.

• VIZUALIZATION_OPTIONS: opciones para visualizar explicaciones. Para saber cómo rellenar este campo, consulta Configurar los ajustes de visualización de datos de imagen.

  Si omite el campo modality o le asigna el valor numeric, omita el campo visualization por completo.modality

• OUTPUT_NAME: cualquier nombre fácil de recordar para la salida del modelo.
• OUTPUT_TENSOR_NAME: nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.

Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

También puedes añadir líneas de base de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige las líneas de base de entrada para Model.

También puedes añadir campos para configurar la aproximación SmoothGrad de los gradientes al ExplanationParameters.

En los modelos de TensorFlow 2, el campo metadata es opcional. Si se omite, Vertex AI infiere automáticamente inputs y outputs del modelo.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Cuerpo JSON de la solicitud:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "integratedGradientsAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "MODALITY",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

XRAI

En función de la herramienta que quieras usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Consola

Sigue la guía para importar un modelo con la Google Cloud consola. Cuando llegues al paso Explicabilidad, haz lo siguiente:

1. En el método de atribución de funciones, selecciona XRAI (para modelos de clasificación de imágenes).

2. Define las siguientes opciones de visualización:

   1. Define el Mapa de colores.

   2. Puedes dejar los valores predeterminados de Clip debajo, Clip arriba, Tipo de superposición y Número de pasos integrales.

      Más información sobre los ajustes de visualización

3. Define el número de pasos que se deben usar para aproximar la integral de ruta durante la atribución de características. Debe ser un número entero comprendido entre [1, 100].

   Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 50.

4. Configura cada característica de entrada de tu modelo:

   Nota: En los modelos de TensorFlow 2, el nombre de la función de entrada es opcional.

   1. Escribe el nombre de la función de entrada.

   2. También puedes añadir una o varias líneas de base de entrada. De lo contrario, Vertex Explainable AI elige una línea de base de entrada predeterminada con todos los valores cero, que es una imagen negra para los datos de imagen.

   3. Si importas un modelo de TensorFlow, hay campos de entrada adicionales:

      1. Rellena el campo Nombre del tensor de entrada.

      2. Si procede, rellena los campos Nombre del tensor de índices y Nombre del tensor de forma densa.

      3. La modalidad no se puede actualizar aquí. Se define automáticamente como NUMERIC para los modelos tabulares o como IMAGE para los modelos de imagen.

      4. Si procede, define el campo Codificación. Si no se define ningún valor, se asigna IDENTITY de forma predeterminada.

      5. Si procede, define el campo Nombre del grupo.

5. Si vas a importar un modelo de TensorFlow, especifica los campos de salida:

   1. Define el nombre de salida de la función.
   2. Define el nombre del tensor de salida de tu función.
   3. Si procede, define la asignación de nombres visibles de índice.
   4. Si procede, define la clave de asignación del nombre visible.

6. Cuando hayas terminado de configurar los ajustes de interpretabilidad, haz clic en el botón Importar.

gcloud

1. En TensorFlow 2, ExplanationMetadata es opcional.

   Escribe lo siguiente: ExplanationMetadata en un archivo JSON de tu entorno local. El nombre del archivo no importa, pero en este ejemplo, llámalo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
         "modality": "image",
         "visualization": VISUALIZATION_SETTINGS
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   Haz los cambios siguientes:

   • FEATURE_NAME: cualquier nombre memorable para la función de entrada.
   • INPUT_TENSOR_NAME: nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.
   • VIZUALIZATION_OPTIONS: opciones para visualizar explicaciones. Para saber cómo rellenar este campo, consulta Configurar los ajustes de visualización de datos de imagen.
   • OUTPUT_NAME: cualquier nombre fácil de recordar para la salida del modelo.
   • OUTPUT_TENSOR_NAME: nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.

   También puedes añadir líneas de base de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige las líneas de base de entrada para Model.

2. Ejecuta el siguiente comando para crear un recurso Model que admita Vertex Explainable AI. Se destacan las marcas más pertinentes para Vertex Explainable AI.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=xrai \
     --explanation-step-count=STEP_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Haz los cambios siguientes:

   • IMAGE_URI: el URI de un contenedor prediseñado de TensorFlow para servir predicciones.
   • STEP_COUNT: número de pasos que se deben usar para aproximar la integral de la ruta durante la atribución de funciones. Debe ser un número entero comprendido entre [1, 100].

     Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 50.

   Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

   También puedes añadir marcas para configurar la aproximación SmoothGrad de los gradientes.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• IMAGE_URI: el URI de un contenedor prediseñado de TensorFlow para servir predicciones.
• STEP_COUNT: número de pasos que se deben usar para aproximar la integral de la ruta durante la atribución de funciones. Debe ser un número entero comprendido entre [1, 100].

  Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 50.

• FEATURE_NAME: cualquier nombre memorable para la función de entrada.
• INPUT_TENSOR_NAME: nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.
• VIZUALIZATION_OPTIONS: opciones para visualizar explicaciones. Para saber cómo rellenar este campo, consulta Configurar los ajustes de visualización de datos de imagen.
• OUTPUT_NAME: cualquier nombre fácil de recordar para la salida del modelo.
• OUTPUT_TENSOR_NAME: nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, consulta el artículo Usar TensorFlow con Vertex Explainable AI.

Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

También puedes añadir líneas de base de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige las líneas de base de entrada para Model.

También puedes añadir campos para configurar la aproximación SmoothGrad de los gradientes al ExplanationParameters.

En los modelos de TensorFlow 2, el campo metadata es opcional. Si se omite, Vertex AI infiere automáticamente inputs y outputs del modelo.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Cuerpo JSON de la solicitud:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "xraiAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "image",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Contenedores precompilados de scikit-learn y XGBoost

Si tu Model acepta datos tabulares como entrada y ofrece predicciones mediante un contenedor precompilado de scikit-learn o XGBoost para predicciones, puedes configurarlo para que use el método de atribución de Shapley muestreado para las explicaciones.

En los siguientes ejemplos se da por hecho que tu modelo acepta una sola matriz bidimensional como entrada, lo que suele ocurrir con los modelos de scikit-learn y XGBoost. Cuando solicitas explicaciones, Vertex Explainable AI proporciona atribuciones de cada elemento de la matriz de entrada.

En función de la herramienta que quieras usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Consola

Sigue la guía para importar un modelo con la Google Cloud consola. Cuando llegues al paso Explicabilidad, haz lo siguiente:

1. En el método de atribución de funciones, seleccione Muestreo de Shapley (para modelos tabulares).

2. Define el recuento de rutas como el número de permutaciones de funciones que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

   Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

3. Configura cada característica de entrada de tu modelo:

   1. Escribe el nombre de la función de entrada.

      Si los artefactos de su modelo no incluyen nombres de características, Vertex AI no podrá asignar los nombres de características de entrada especificados al modelo. En ese caso, solo debes proporcionar una función de entrada con cualquier nombre arbitrario y fácil de usar, como input_features. En la respuesta de explicación, obtendrá una lista de atribuciones de N dimensiones, donde N es el número de características del modelo y los elementos de la lista aparecen en el mismo orden que el conjunto de datos de entrenamiento.

   2. También puedes añadir una o varias líneas de base de entrada. De lo contrario, Vertex Explainable AI elige una línea de base de entrada predeterminada con todos los valores cero, que es una imagen negra para los datos de imagen.

4. Define el nombre de salida de la función.

5. Cuando hayas terminado de configurar los ajustes de interpretabilidad, haz clic en el botón Importar.

gcloud

1. Escribe lo siguiente: ExplanationMetadata en un archivo JSON de tu entorno local. El nombre del archivo no importa, pero en este ejemplo, llámalo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
       }
     }
   }
   

   Haz los cambios siguientes:

   • FEATURE_NAME: cualquier nombre memorable para la función de entrada.
   • OUTPUT_NAME: cualquier nombre fácil de recordar para la salida del modelo.

   Si especificas líneas de base de entrada, asegúrate de que coincidan con la entrada de tu modelo, que suele ser una lista de matrices bidimensionales. De lo contrario, el valor predeterminado de la línea de base de entrada es una matriz bidimensional con el valor 0 de la forma de entrada.

2. Ejecuta el siguiente comando para crear un recurso Model que admita Vertex Explainable AI. Se destacan las marcas más pertinentes para Vertex Explainable AI.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Haz los cambios siguientes:

   • IMAGE_URI: el URI de un contenedor precompilado para ofrecer predicciones.

   • PATH_COUNT: el número de permutaciones de características que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

     Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

   Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• IMAGE_URI: el URI de un contenedor precompilado para ofrecer predicciones.

• PATH_COUNT: el número de permutaciones de características que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

  Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

• FEATURE_NAME: cualquier nombre memorable para la función de entrada.
• OUTPUT_NAME: cualquier nombre fácil de recordar para la salida del modelo.

Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

Si especificas líneas de base de entrada, asegúrate de que coincidan con la entrada de tu modelo, que suele ser una lista de matrices bidimensionales. De lo contrario, el valor predeterminado de la línea de base de entrada es una matriz bidimensional con el valor 0 de la forma de entrada.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Cuerpo JSON de la solicitud:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {
         }
       },
       "outputs": {
         "OUTPUT_NAME": {
         }
       }
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Contenedor personalizado

Si tu Model acepta datos tabulares como entrada y ofrece predicciones mediante un contenedor personalizado, puedes configurarlo para que use el método de atribución de Shapley muestreado para las explicaciones.

Nota: Las siguientes instrucciones no funcionan si usas alguno de los contenedores precompilados de Vertex AI para ofrecer predicciones. Debes usar una imagen de contenedor personalizada que no esté gestionada por Vertex AI y que cumpla los requisitos de los contenedores personalizados.

Determinar los nombres de las funciones y de los resultados

En los pasos siguientes, debes proporcionar a Vertex AI los nombres de las funciones que espera tu Model como entrada. También debe especificar la clave que se usa para las salidas en las predicciones de Model.

Determinar los nombres de las funciones

Si tu Model espera que cada instancia de entrada tenga determinadas claves de nivel superior, esas claves serán los nombres de tus funciones.

Por ejemplo, supongamos que tienes un Model que espera que cada instancia de entrada tenga el siguiente formato:

{
  "length": <value>,
  "width": <value>
}

En este caso, los nombres de las funciones son length y width. Aunque los valores de estos campos contengan listas u objetos anidados, length y width son las únicas claves que necesitas para los pasos siguientes. Cuando solicitas explicaciones, Vertex Explainable AI proporciona atribuciones de cada elemento anidado de tus funciones.

Si tu Model espera una entrada sin clave, Vertex Explainable AI considera que el Model tiene una sola función. Puedes usar cualquier cadena memorable para el nombre de la función.

Por ejemplo, supongamos que tienes un Model que espera que cada instancia de entrada tenga el siguiente formato:

[
  <value>,
  <value>
]

En este caso, proporcione a Vertex Explainable AI un solo nombre de función de su elección, como dimensions.

Nota: En los siguientes ejemplos se da por hecho que tu modelo tiene una sola función de entrada. Si tu modelo tiene varias funciones, como se describe en esta sección, añade las entradas correspondientes al campo inputs.

Determinar el nombre de salida

Si tu Model devuelve cada instancia de predicción online con una salida asociada a una clave, esa clave es el nombre de la salida.

Por ejemplo, supongamos que tienes una Model que devuelve cada predicción en el siguiente formato:

{
  "scores": <value>
}

En este caso, el nombre de salida es scores. Si el valor del campo scores es una matriz, cuando obtengas explicaciones, Vertex Explainable AI devolverá las atribuciones de las funciones del elemento con el valor más alto de cada predicción. Para configurar Vertex Explainable AI de forma que proporcione atribuciones de características de elementos adicionales del campo de salida, puede especificar los campos topK o outputIndices de ExplanationParameters. Sin embargo, los ejemplos de este documento no muestran estas opciones.

Si Model devuelve predicciones sin clave, puedes usar cualquier cadena memorable para el nombre de salida. Por ejemplo, esto se aplica si tu Model devuelve una matriz o un escalar para cada predicción.

Crear el Model

En función de la herramienta que quieras usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Consola

Sigue la guía para importar un modelo con la Google Cloud consola. Cuando llegues al paso Explicabilidad, haz lo siguiente:

1. En el método de atribución de funciones, seleccione Muestreo de Shapley (para modelos tabulares).

2. Define el recuento de rutas como el número de permutaciones de funciones que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

   Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

3. Configura cada característica de entrada de tu modelo:

   1. Escribe el nombre de la función de entrada.

      Si los artefactos de su modelo no incluyen nombres de características, Vertex AI no podrá asignar los nombres de características de entrada especificados al modelo. En ese caso, solo debes proporcionar una función de entrada con cualquier nombre arbitrario y fácil de usar, como input_features. En la respuesta de explicación, obtendrá una lista de atribuciones de N dimensiones, donde N es el número de características del modelo y los elementos de la lista aparecen en el mismo orden que el conjunto de datos de entrenamiento.

   2. También puedes añadir una o varias líneas de base de entrada. De lo contrario, Vertex Explainable AI elige una línea de base de entrada predeterminada con todos los valores cero, que es una imagen negra para los datos de imagen.

4. Define el nombre de salida de la función.

5. Cuando hayas terminado de configurar los ajustes de interpretabilidad, haz clic en el botón Importar.

gcloud

1. Escribe lo siguiente: ExplanationMetadata en un archivo JSON de tu entorno local. El nombre del archivo no importa, pero en este ejemplo, llámalo explanation-metadata.json:

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {}
     },
     "outputs": {
       "OUTPUT_NAME": {}
     }
   }
   

   Haz los cambios siguientes:

   • FEATURE_NAME: El nombre de la función, tal como se describe en la sección "Determinar los nombres de las funciones" de este documento.
   • OUTPUT_NAME: El nombre de la salida, tal como se describe en la sección "Determinar el nombre de la salida" de este documento.

   También puedes añadir líneas de base de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige las líneas de base de entrada para Model.

   Si especificas líneas de base de entrada, asegúrate de que coincidan con la entrada de tu modelo, que suele ser una lista de matrices bidimensionales. De lo contrario, el valor predeterminado de la línea de base de entrada es una matriz bidimensional con el valor 0 de la forma de entrada.

2. Ejecuta el siguiente comando para crear un recurso Model que admita Vertex Explainable AI. Se destacan las marcas más pertinentes para Vertex Explainable AI.

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   Haz los cambios siguientes:

   • PATH_COUNT: el número de permutaciones de características que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

     Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

   Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PATH_COUNT: el número de permutaciones de características que se va a usar en el método de atribución de Shapley muestreado. Debe ser un número entero comprendido entre [1, 50].

  Un valor más alto puede reducir el error de aproximación, pero requiere más recursos computacionales. Si no sabes qué valor usar, prueba con 25.

• FEATURE_NAME: El nombre de la función, tal como se describe en la sección "Determinar los nombres de las funciones" de este documento.
• OUTPUT_NAME: El nombre de la salida, tal como se describe en la sección "Determinar el nombre de la salida" de este documento.

Para obtener información sobre los valores adecuados para los demás marcadores de posición, consulta upload y Importar modelos.

También puedes añadir líneas de base de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige las líneas de base de entrada para Model.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

Cuerpo JSON de la solicitud:

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {}
       },
       "outputs": {
         "OUTPUT_NAME": {}
       }
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

Siguientes pasos

• Despliega tu Model en un Endpoint y obtén explicaciones.