Configura las explicaciones basadas en atributos

Para usar Vertex Explainable AI con un modelo entrenado personalizado, debes configurar ciertas opciones cuando creas el recurso Model del que planeas solicitar explicaciones, implementar el modelo o enviar un trabajo 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 necesitas realizar ninguna configuración. Vertex AI configura automáticamente el modelo para Vertex Explainable AI. Omite este documento y lee Obtén explicaciones.

Cuándo y dónde configurar las explicaciones

Las explicaciones se configuran cuando creas o importas un modelo. También puedes configurar explicaciones en un modelo que ya hayas creado, incluso si no configuraste las explicaciones antes.

Configura explicaciones cuando creas o importas modelos

Cuando creas o importas un Model, puedes establecer 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 maneras:

En cualquier caso, puedes configurar Model para que sea compatible con Vertex Explainable AI. En los ejemplos de este documento, se supone que importas un Model. Para configurar Vertex Explainable AI cuando creas un Model de entrenamiento personalizado con un TrainingPipeline, usa la configuración que se describe en este documento en el campo modelToUpload del TrainingPipeline.

Configura explicaciones cuando implementes modelos u obtengas predicciones por lotes

Cuando implementas un Model en un recurso Endpoint, puedes realizar una de las siguientes acciones:

  • Configura explicaciones, sin importar si el modelo se configuró antes o no para las explicaciones. Esto es útil si no planeabas obtener explicaciones (y omitiste el campo explanationSpec cuando creaste el modelo), pero decides más tarde que quieres explicaciones para el modelo o deseas anular algunos de los parámetros de configuración de explicaciones.
  • Inhabilita las explicaciones. Esto es útil si tu modelo está configurado para las explicaciones, pero no planeas obtener explicaciones del extremo. Para inhabilitar las explicaciones cuando implementas el modelo en un extremo, desmarca las opciones de explicación en la consola de Cloud o configura DeployedModel.disableExplanations como true.

Del mismo modo, cuando obtienes predicciones por lotes de un Model, puedes configurar explicaciones mediante la propagación del campo BatchPredictionJob.explanationSpec o inhabilitar las explicaciones mediante la configuración de BatchPredictionJob.generateExplanation en false.

Anula la configuración cuando obtengas explicaciones en línea

Independientemente de si creaste o importaste el Model con la configuración de explicaciones y, sin importar si la configuraste durante la implementación, puedes anular los Model de la configuración de explicación inicial cuandoobtienes explicaciones en línea.

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

En la solicitud explain, puedes anular los siguientes campos:

Anula esta configuración en el campo explanationSpecOverride de la solicitud de explicación.

Importa un modelo con un campo explanationSpec

Según si entregas predicciones con un contenedor compilado previamente o un contenedor personalizado, especifica detalles ligeramente diferentes para el ExplanationSpec. Selecciona la pestaña que coincida con el contenedor que usas:

Contenedor previamente compilado 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 atributos a fin de seleccionar el adecuado para tu Model:

Shapley de muestra

Según la herramienta que desees usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Console

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

  1. Para el método de atribución de atributos, selecciona Shapley con muestreo (para modelos tabulares).

  2. Establece el recuento de rutas de acceso en la cantidad de permutaciones de atributos que se usarán para el método de atribución Shapley con muestreo. Debe ser un número entero en el rango [1, 50].

    Un valor más alto puede reducir el error de aproximación, pero es más intensivo en términos de procesamiento. Si no sabes qué valor usar, prueba con 25.

  3. Configura cada atributo de entrada en tu modelo:

    1. Completa el nombre del atributo de entrada.

    2. De forma opcional, puedes agregar uno o más modelos de referencia de entrada. De lo contrario, Vertex Explainable AI elige un modelo de referencia de entrada predeterminado de valores cero, que es una imagen negra para los datos de imagen.

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

      1. Completa el Nombre del tensor de entrada.

      2. Si corresponde, completa el Nombre del tensor de índices o el Nombre del tensor de forma densa.

      3. Aquí no se puede actualizar la Modalidad. Se establece de forma automática en NUMERIC para modelos tabulares o IMAGE en modelos de imagen.

      4. Si corresponde, configura el campo Codificación. El valor predeterminado es IDENTITY si no está configurado.

      5. Si corresponde, configura el campo Nombre del grupo.

  4. Si importas un modelo de TensorFlow, especifica los campos de resultados:

    1. Establece el Nombre de salida de tu atributo.
    2. Configura el Nombre del tensor de salida de tu atributo.
    3. Si corresponde, configura la Índice de asignación del nombre visible.
    4. Si corresponde, configura la clave de asignación del nombre visible.

  5. Haz clic en el botón Importar cuando termines de configurar la explicabilidad.

gcloud

  1. Para TensorFlow 2, ExplanationMetadata es opcional.

    Escribe el siguiente ExplanationMetadata en un archivo JSON en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama explanation-metadata.json.

    explanation-metadata.json

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

    Reemplaza lo siguiente:

    • FEATURE_NAME: Cualquier nombre que sea fácil de recordar para la función de entrada.
    • INPUT_TENSOR_NAME: El nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, lee Usa TensorFlow con Vertex Explainable AI.
    • OUTPUT_NAME: Cualquier nombre fácil de recordar para la salida de tu modelo.
    • OUTPUT_TENSOR_NAME: El nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, lee Usa TensorFlow con Vertex Explainable AI.

    De manera opcional, puedes agregar referencias de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige modelos de referencia de entrada para el Model.

  2. Ejecuta el siguiente comando para crear un recurso Model que admita Vertex Explainable AI. Se destacan las marcas más pertinentes a 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

    Reemplaza lo siguiente:

    Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

De manera opcional, puedes agregar referencias de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige modelos de referencia de entrada para el Model.

Para los modelos de TensorFlow 2, el campo metadata es opcional. Si se omite, Vertex AI infiere de forma automática el inputs y el 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

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

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

Gradientes integrados

Según la herramienta que desees usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Console

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

  1. Para el método de atribución de atributos, selecciona gradientes integrados (en modelos tabulares) o gradientes integrados (para modelos de clasificación de imágenes), el que sea más apropiado para tu modelo.

  2. Si importas un modelo de clasificación de imágenes, haz lo siguiente:

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

    2. Puedes dejar Recortar abajo, Recortar arriba, Tipo de superposición y Cantidad de pasos integrales en su configuración predeterminada.

    Obtén más información sobre la configuración de visualización.

  3. Establece la cantidad de pasos que se deben usar para aproximar la integral de la ruta de acceso durante la atribución de la función. Debe ser un número entero en el rango [1, 100].

    Un valor más alto puede reducir el error de aproximación, pero es más intensivo en términos de procesamiento. Si no sabes qué valor usar, prueba con 50.

  4. Configura cada atributo de entrada en tu modelo:

    1. Completa el nombre del atributo de entrada.

    2. De forma opcional, puedes agregar uno o más modelos de referencia de entrada. De lo contrario, Vertex Explainable AI elige un modelo de referencia de entrada predeterminado de valores cero, que es una imagen negra para los datos de imagen.

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

      1. Completa el Nombre del tensor de entrada.

      2. Si corresponde, completa el Nombre del tensor de índices o el Nombre del tensor de forma densa.

      3. Aquí no se puede actualizar la Modalidad. Se establece de forma automática en NUMERIC para modelos tabulares o IMAGE en modelos de imagen.

      4. Si corresponde, configura el campo Codificación. El valor predeterminado es IDENTITY si no está configurado.

      5. Si corresponde, configura el campo Nombre del grupo.

  5. Si importas un modelo de TensorFlow, especifica los campos de resultados:

    1. Establece el Nombre de salida de tu atributo.
    2. Configura el Nombre del tensor de salida de tu atributo.
    3. Si corresponde, configura la Índice de asignación del nombre visible.
    4. Si corresponde, configura la clave de asignación del nombre visible.

  6. Haz clic en el botón Importar cuando termines de configurar la explicabilidad.

gcloud

  1. Para TensorFlow 2, ExplanationMetadata es opcional.

    Escribe el siguiente ExplanationMetadata en un archivo JSON en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama 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"
    }
  }
}

    Reemplaza lo siguiente:

    • FEATURE_NAME: Cualquier nombre que sea fácil de recordar para la función de entrada.
    • INPUT_TENSOR_NAME: El nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, lee Usa TensorFlow con Vertex Explainable AI.
    • MODALITY: image si Model acepta imágenes como entrada o numeric si Model acepta datos tabulares como entrada. La configuración predeterminada es numeric.

    • VIZUALIZATION_OPTIONS: Opciones para visualizar explicaciones. Si quieres aprender a propagar este campo, lee Configura los ajustes de visualización para los datos de imágenes.

      Si omites el campo modality o configuras el campo modality como numeric, omite el campo visualization por completo.

    • OUTPUT_NAME: Cualquier nombre fácil de recordar para la salida de tu modelo.
    • OUTPUT_TENSOR_NAME: El nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, lee Usa TensorFlow con Vertex Explainable AI.

    De manera opcional, puedes agregar referencias de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige modelos de referencia de entrada para el Model.

  2. Ejecuta el siguiente comando para crear un recurso Model que admita Vertex Explainable AI. Se destacan las marcas más pertinentes a 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

    Reemplaza lo siguiente:

    Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

    De forma opcional, puedes agregar marcas para configurar la aproximación de SmoothGrad.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • IMAGE_URI: El URI de un contenedor compilado previamente de TensorFlow para entregar predicciones.
  • STEP_COUNT: la cantidad de pasos que se deben usar para aproximar la integral de la ruta durante la atribución de la función. Debe ser un número entero en el rango [1, 100].

    Un valor más alto puede reducir el error de aproximación, pero es más intensivo en términos de procesamiento. Si no sabes qué valor usar, prueba con 50.

  • FEATURE_NAME: Cualquier nombre que sea fácil de recordar para la función de entrada.
  • INPUT_TENSOR_NAME: El nombre del tensor de entrada en TensorFlow. Para encontrar el valor correcto de este campo, lee Usa TensorFlow con Vertex Explainable AI.
  • MODALITY: image si Model acepta imágenes como entrada o numeric si Model acepta datos tabulares como entrada. La configuración predeterminada es numeric.

  • VIZUALIZATION_OPTIONS: Opciones para visualizar explicaciones. Si quieres aprender a propagar este campo, lee Configura los ajustes de visualización para los datos de imágenes.

    Si omites el campo modality o configuras el campo modality como numeric, omite el campo visualization por completo.

  • OUTPUT_NAME: Cualquier nombre fácil de recordar para la salida de tu modelo.
  • OUTPUT_TENSOR_NAME: El nombre del tensor de salida en TensorFlow. Para encontrar el valor correcto de este campo, lee Usa TensorFlow con Vertex Explainable AI.

Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

De manera opcional, puedes agregar referencias de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige modelos de referencia de entrada para el Model.

De manera opcional, puedes agregar campos para configurar la aproximación de SmoothGrad de gradientes a ExplanationParameters.

Para los modelos de TensorFlow 2, el campo metadata es opcional. Si se omite, Vertex AI infiere de forma automática el inputs y el 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

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

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

Según la herramienta que desees usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Console

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

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

  2. Establece las siguientes opciones de visualización:

    1. Configura el Mapa de colores.

    2. Puedes dejar Recortar abajo, Recortar arriba, Tipo de superposición y Cantidad de pasos integrales en su configuración predeterminada.

      Obtén más información sobre la configuración de visualización.

  3. Establece la cantidad de pasos que se deben usar para aproximar la integral de la ruta de acceso durante la atribución de la función. Debe ser un número entero en el rango [1, 100].

    Un valor más alto puede reducir el error de aproximación, pero es más intensivo en términos de procesamiento. Si no sabes qué valor usar, prueba con 50.

  4. Configura cada atributo de entrada en tu modelo:

    1. Completa el nombre del atributo de entrada.

    2. De forma opcional, puedes agregar uno o más modelos de referencia de entrada. De lo contrario, Vertex Explainable AI elige un modelo de referencia de entrada predeterminado de valores cero, que es una imagen negra para los datos de imagen.

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

      1. Completa el Nombre del tensor de entrada.

      2. Si corresponde, completa el Nombre del tensor de índices o el Nombre del tensor de forma densa.

      3. Aquí no se puede actualizar la Modalidad. Se establece de forma automática en NUMERIC para modelos tabulares o IMAGE en modelos de imagen.

      4. Si corresponde, configura el campo Codificación. El valor predeterminado es IDENTITY si no está configurado.

      5. Si corresponde, configura el campo Nombre del grupo.

  5. Si importas un modelo de TensorFlow, especifica los campos de resultados:

    1. Establece el Nombre de salida de tu atributo.
    2. Configura el Nombre del tensor de salida de tu atributo.
    3. Si corresponde, configura la Índice de asignación del nombre visible.
    4. Si corresponde, configura la clave de asignación del nombre visible.

  6. Haz clic en el botón Importar cuando termines de configurar la explicabilidad.

gcloud

  1. Para TensorFlow 2, ExplanationMetadata es opcional.

    Escribe el siguiente ExplanationMetadata en un archivo JSON en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama 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"
    }
  }
}

    Reemplaza lo siguiente:

    De manera opcional, puedes agregar referencias de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige modelos de referencia de entrada para el Model.

  2. Ejecuta el siguiente comando para crear un recurso Model que admita Vertex Explainable AI. Se destacan las marcas más pertinentes a 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

    Reemplaza lo siguiente:

    Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

    De forma opcional, puedes agregar marcas para configurar la aproximación de SmoothGrad.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

De manera opcional, puedes agregar referencias de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige modelos de referencia de entrada para el Model.

De manera opcional, puedes agregar campos para configurar la aproximación de SmoothGrad de gradientes a ExplanationParameters.

Para los modelos de TensorFlow 2, el campo metadata es opcional. Si se omite, Vertex AI infiere de forma automática el inputs y el 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

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

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 previamente compilados de scikit-learn y XGBoost

Si el Model acepta datos tabulares como entrada y entrega predicciones mediante un contenedor de scikit-learn o XGBoost compilado con anterioridad para la predicción, puedes configurarlo de la siguiente manera: usa el método de atribución de Shapley con muestreo para obtener explicaciones.

Según la herramienta que desees usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Console

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

  1. Para el método de atribución de atributos, selecciona Shapley con muestreo (para modelos tabulares).

  2. Establece el recuento de rutas de acceso en la cantidad de permutaciones de atributos que se usarán para el método de atribución Shapley con muestreo. Debe ser un número entero en el rango [1, 50].

    Un valor más alto puede reducir el error de aproximación, pero es más intensivo en términos de procesamiento. Si no sabes qué valor usar, prueba con 25.

  3. Configura cada atributo de entrada en tu modelo:

    1. Completa el nombre del atributo de entrada.

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

    2. De forma opcional, puedes agregar uno o más modelos de referencia de entrada. De lo contrario, Vertex Explainable AI elige un modelo de referencia de entrada predeterminado de valores cero, que es una imagen negra para los datos de imagen.

  4. Establece el Nombre de salida de tu atributo.

  5. Haz clic en el botón Importar cuando termines de configurar la explicabilidad.

gcloud

  1. Escribe el siguiente ExplanationMetadata en un archivo JSON en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama explanation-metadata.json.

    explanation-metadata.json

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

    Reemplaza lo siguiente:

    • FEATURE_NAME: Cualquier nombre que sea fácil de recordar para la función de entrada.
    • OUTPUT_NAME: Cualquier nombre fácil de recordar para la salida de tu modelo.

    Si especificas modelos de referencia de entrada, asegúrate de que coincidan con la entrada del modelo, que suele ser una lista de matrices 2-D. De lo contrario, el valor predeterminado para el modelo de referencia de entrada es una matriz 2-D de 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 a 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

    Reemplaza lo siguiente:

    Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

Si especificas modelos de referencia de entrada, asegúrate de que coincidan con la entrada del modelo, que suele ser una lista de matrices 2-D. De lo contrario, el valor predeterminado para el modelo de referencia de entrada es una matriz 2-D de 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

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

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 entrega predicciones con un contenedor personalizado, puedes configurarlo para que use el método de atribución de Shapley de muestra para obtener explicaciones.

Determina los nombres de los atributos y los resultados

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

Determina los nombres de los atributos

Si tu Model espera que cada instancia de entrada tenga ciertas claves de nivel superior, esas claves son los nombres de las características.

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

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

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

Si tu Model espera una entrada sin clave, entonces, la Vertex Explainable AI considera que Model tiene un solo atributo. Puedes usar cualquier string fácil de recordar para el nombre del atributo.

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

[
  <value>,
  <value>
]

En este caso, proporciona a Vertex Explainable AI un nombre de atributo único que elijas, como dimensions.

Determina el nombre de salida

Si tu Model muestra cada instancia de predicción en línea con resultado con clave, esa clave es tu nombre de resultado.

Por ejemplo, considera un Model que muestra 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 un arreglo, cuando obtengas explicaciones, Vertex Explainable AI muestra atribuciones de atributos para el elemento con el valor más alto en cada predicción. Si deseas configurar Vertex Explainable AI a fin de proporcionar atribuciones de atributos para elementos adicionales del campo de salida, puedes especificar los campos topK o outputIndices de ExplanationParameters. Sin embargo, en los ejemplos de este documento, no se demuestran estas opciones.

Si tu Model muestra predicciones sin clave, puedes usar cualquier string que se pueda recordar para el nombre de salida. Por ejemplo, esto se aplica si tu Model muestra un arreglo o un escalar para cada predicción.

Crea Model

Según la herramienta que desees usar para crear o importar el Model, selecciona una de las siguientes pestañas:

Console

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

  1. Para el método de atribución de atributos, selecciona Shapley con muestreo (para modelos tabulares).

  2. Establece el recuento de rutas de acceso en la cantidad de permutaciones de atributos que se usarán para el método de atribución Shapley con muestreo. Debe ser un número entero en el rango [1, 50].

    Un valor más alto puede reducir el error de aproximación, pero es más intensivo en términos de procesamiento. Si no sabes qué valor usar, prueba con 25.

  3. Configura cada atributo de entrada en tu modelo:

    1. Completa el nombre del atributo de entrada.

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

    2. De forma opcional, puedes agregar uno o más modelos de referencia de entrada. De lo contrario, Vertex Explainable AI elige un modelo de referencia de entrada predeterminado de valores cero, que es una imagen negra para los datos de imagen.

  4. Establece el Nombre de salida de tu atributo.

  5. Haz clic en el botón Importar cuando termines de configurar la explicabilidad.

gcloud

  1. Escribe el siguiente ExplanationMetadata en un archivo JSON en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama explanation-metadata.json.

    explanation-metadata.json

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

    Reemplaza lo siguiente:

    • FEATURE_NAME: Es el nombre de la función, como se describe en la sección "Determina los nombres de las funciones" de este documento.
    • OUTPUT_NAME: Es el nombre del resultado, como se describe en la sección "Determina el nombre de salida" de este documento.

    De manera opcional, puedes agregar referencias de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige modelos de referencia de entrada para el Model.

    Si especificas modelos de referencia de entrada, asegúrate de que coincidan con la entrada del modelo, que suele ser una lista de matrices 2-D. De lo contrario, el valor predeterminado para el modelo de referencia de entrada es una matriz 2-D de 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 a 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

    Reemplaza lo siguiente:

    Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PATH_COUNT: La cantidad de permutaciones de funciones que se usarán para el método de atribución de Shapley de muestra. Debe ser un número entero en el rango [1, 50].

    Un valor más alto puede reducir el error de aproximación, pero es más intensivo en términos de procesamiento. Si no sabes qué valor usar, prueba con 25.

  • FEATURE_NAME: Es el nombre de la función, como se describe en la sección "Determina los nombres de las funciones" de este documento.
  • OUTPUT_NAME: Es el nombre del resultado, como se describe en la sección "Determina el nombre de salida" de este documento.

Si quieres obtener información sobre los valores adecuados para los otros marcadores de posición, consulta upload y, también, Importa modelos.

De manera opcional, puedes agregar referencias de entrada al ExplanationMetadata. De lo contrario, Vertex AI elige modelos de referencia de entrada para el 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

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

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

¿Qué sigue?