Method: projects.explain

Performs explanation on the data in the request.

Las Explicaciones de IA implementan un verbo explain personalizado sobre un método HTTP POST. Con el método explain se realiza la predicción de los datos en la solicitud.

La URL se describe en la sintaxis de anotación HTTP de la API de Google:

POST https://ml.googleapis.com/v1/{name=projects/**}:explain

El parámetro name es obligatorio. Debe contener el nombre del modelo y, de manera opcional, una versión. Si especificas un modelo sin una versión, se usará la versión predeterminada para ese modelo.

Ejemplo en el que se especifican el modelo y la versión:

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name/versions/your-version-name:explain

Ejemplo en el que se especifica solo un modelo. Se usa la versión predeterminada siguiente para ese modelo:

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name:explain

En esta página, se describe el formato del cuerpo de la solicitud de explicación y del cuerpo de la respuesta. Para ver una muestra de código mediante la que se indica cómo enviar una solicitud de explicación, consulta la guía sobre cómo usar atribuciones de atributos.

Detalles del cuerpo de la solicitud

TensorFlow

El cuerpo de la solicitud contiene datos con la siguiente estructura (representación JSON):

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

El objeto instances[] es obligatorio y debe contener la lista de instancias de las que se deben obtener explicaciones.

La estructura de cada elemento de la lista de instancias se determina con la definición de entrada del modelo. En las instancias, se pueden incluir entradas con nombre (como objetos) o solo valores sin etiqueta.

No en todos los datos se incluyen entradas con nombre. Algunas instancias son valores JSON sencillos (booleano, número o string). Sin embargo, las instancias suelen ser listas de valores sencillos o listas anidadas complejas.

A continuación, se presentan algunos ejemplos de cuerpos de solicitud.

Datos CSV con cada fila codificada como un valor de string:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

Texto sin formato:

{"instances": ["the quick brown fox", "the lazy dog"]}

Oraciones codificadas como listas de palabras (vectores de strings):

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

Valores escalares de punto flotante:

{"instances": [0.0, 1.1, 2.2]}

Vectores de números enteros:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

Tensores (en este caso, tensores de dos dimensiones):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

Imágenes que se pueden representar de diferentes maneras. En este esquema de codificación, las dos primeras dimensiones representan las filas y columnas de la imagen, y la tercera dimensión contiene listas (vectores) de los valores R, G y B para cada píxel:

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

Codificación de datos

Las strings JSON se deben codificar como UTF-8. Para enviar datos binarios, debes codificar los datos en base64 y marcarlos como binarios. Para marcar una string JSON como binaria, reemplázala por un objeto JSON con un atributo único denominado b64:

{"b64": "..."} 

En el siguiente ejemplo, se muestran dos instancias serializadas tf.Examples que requieren codificación base64 (se usan datos falsos solo para fines ilustrativos):

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

En el siguiente ejemplo, se muestran dos strings de bytes de imagen JPEG, que requieren codificación base64 (se usan datos falsos solo para fines ilustrativos):

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

Tensores de varias entradas

Algunos modelos tienen un grafo de TensorFlow subyacente con el que se aceptan varios tensores de entrada. En este caso, usa los nombres de los pares nombre-valor JSON para identificar los tensores de entrada.

Para un grafo con alias de tensor de entrada "image" (string codificada en base64) y "tag" (string), utiliza lo siguiente:

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

Para un grafo con alias de tensor de entrada “image” (arreglo de 3 dimensiones de entradas de 8 bits) y “tag” (string), usa lo siguiente:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

Explicación de los metadatos

Cuando usas las Explicaciones de IA, debes indicar cuáles de tus tensores corresponden a las predicciones o probabilidades de salida y a las funciones reales. Para ello, agrega un archivo llamado explanation_metadata.json a la carpeta de modelo guardado antes de implementar el modelo en las Explicaciones de IA.

Para facilitar este proceso, asigna un nombre a los tensores de tu grafo de TensorFlow. Antes de entrenar el modelo, configura la propiedad name en tensores sin procesar o de capas de Keras:

auxiliary_output = Dense(1, activation='sigmoid', name='aux_output')

El contenido del archivo debe coincidir con el siguiente esquema:

{
  "inputs": {
    string <input feature key>: {
      "input_tensor_name": string,
      "input_baselines": [
        number,
      ],
      "modality": string
    }
    ...
  },
  "outputs": {
    string <output value key>:  {
      "output_tensor_name": string
    },
    ...
  },
  "framework": string
}
Campos

Clave de valor de salida y clave de atributo de entrada

Cualquier nombre único. El sistema muestra un diccionario con las puntuaciones de atribución de un atributo determinado que aparece en esta clave.
input_tensor_name

string

Obligatorio. El nombre del tensor que contiene las entradas a las que se debe atribuir la predicción del modelo. Dale formato al nombre como name:0. Por ejemplo: aux_output:0.

input_baselines

<integer>|<simple list>

Opcional. El valor de los modelos de referencia o el ejemplo “no informativo” de esta función en particular. Considera usar el promedio o 0.
La forma de cada modelo de referencia debe coincidir con la forma del tensor codificado. Si se proporciona un escalar, transmitimos a la misma forma que el tensor codificado.
Si proporcionas varios modelos de referencia, el sistema promedia las atribuciones entre ellos. Por ejemplo, es posible que desees comparar las atribuciones con una imagen completamente negra o blanca.

modality

string

Opcional. Se puede establecer en image si el tensor de entrada es una imagen. En ese caso, el sistema mostrará una representación gráfica de las atribuciones.

El tensor especificado en input_tensor_name debe ser el siguiente:

  • Para imágenes en color: Un tensor denso en 4-D de dtype float32 y forma [batch_size, height, width, 3] cuyos elementos son valores de color RGB de píxeles normalizados al rango [0, 1].
  • Para imágenes en escala de grises: Un tensor denso en 3D de dtype float32 y forma [batch_size, height, width] cuyos elementos son valores negros de píxeles normalizados al rango [0, 1].
output_tensor_name

string

Obligatorio. El nombre del tensor que contiene la salida a la que se debe atribuir la predicción del modelo.

framework

string

Obligatorio. Debe establecerse en tensorflow.

Ajusta la configuración de visualización

Cuando obtienes explicaciones sobre los datos de imagen con los gradientes integrados o los métodos XRAI, puedes ajustar la configuración de visualización de tus resultados si la incluyes en el archivo explanation_metadata.json. Esta configuración es opcional.

Para ajustar la configuración de visualización, incluye la configuración de visualización dentro del objeto de entrada que deseas visualizar:

{
  "inputs": {
    string <input feature key>: {
      "input_tensor_name": string,
      "input_baselines": [
        number,
      ],
      "modality": string
      "visualization": {
        "type": string,
        "polarity": string,
        "clip_below_percentile": number,
        "clip_above_percentile": number,
        "color_map": string,
        "overlay_type": string
      }
    }
    ...
  },
  "outputs": {
    string <output value key>:  {
      "output_tensor_name": string
    },
    ...
  },
  "framework": string
}

Detalles sobre la configuración de visualización

Todas las opciones de configuración de visualización son opcionales, por lo que puedes especificar todos estos valores, algunos de ellos o ninguno.

"visualization": {
  "type": string,
  "polarity": string,
  "clip_below_percentile": number,
  "clip_above_percentile": number,
  "color_map": string,
  "overlay_type": string
}

Consulta las imágenes de salida y las configuraciones de ejemplo.

Campos

type

string

Opcional. El tipo de visualización. Los valores válidos son outlines o pixels. Para los gradientes integrados, puedes usar cualquier configuración. La configuración predeterminada es outlines.
En el caso de XRAI, pixels es la configuración predeterminada. No se recomienda outlines para XRAI.

polarity

string

Opcional. La direccionalidad de los valores de atribución que se muestran. Los valores válidos son positive, negative o both. La configuración predeterminada es positive.

clip_below_percentile

number

Opcional. Excluye atribuciones por debajo del percentil especificado. El valor válido es un decimal en el rango [0, 100].

clip_above_percentile

number

Opcional. Excluye las atribuciones por encima del percentil especificado. El valor válido es un decimal en el rango [0, 100]. Debe ser mayor que clip_below_percentile.

color_map

string

Opcional. Los valores válidos son red_green, pink_green y viridis. La configuración predeterminada es pink_green para los gradientes integrados y viridis para XRAI.

overlay_type

string

Opcional. El tipo de superposición que modifica cómo se muestran las atribuciones sobre las imágenes de entrada originales.
Los valores válidos son none, grayscale, original y mask_black.

  • none: Las atribuciones se muestran solas sobre una imagen negra, sin superponerse con la imagen de entrada.
  • grayscale: Las atribuciones se superponen con una versión en escala de grises de la imagen de entrada.
  • original: Las atribuciones se superponen con la imagen de entrada original.
  • mask_black: Las atribuciones se usan como máscara para enfatizar las partes predictivas de la imagen. La opacidad de los píxeles en la imagen original corresponde a la intensidad de las atribuciones para el píxel correspondiente.

La configuración predeterminada es original para los gradientes integrados y grayscale para XRAI.

Consulta las imágenes de ejemplo que muestran cada overlay_type.

Detalles del cuerpo de la respuesta

Las respuestas son muy similares a las solicitudes.

Si la llamada es exitosa, el cuerpo de la respuesta contendrá una entrada de explicaciones por instancia en el cuerpo de solicitud en el mismo orden:

{
  "explanations": [
    {
      object
    }
  ]
}

Si la explicación falla en alguna instancia, el cuerpo de la respuesta no contendrá explicaciones. En su lugar, contendrá una entrada de error:

{
  "error": string
}

El objeto explanations[] contiene la lista de explicaciones, una para cada instancia de la solicitud.

En caso de que se produzca un error, la string error contendrá un mensaje en el que se describe el problema. Se muestra el error en lugar de una lista de explicaciones si se produjo cuando se procesaban las instancias.

A pesar de que hay una explicación por instancia, el formato de una explicación no está relacionado directamente con el formato de una instancia. Con las explicaciones, se toma cualquier formato que se especifique en la colección de salidas definida en el modelo. La colección de explicaciones se muestra en una lista JSON. Cada miembro de la lista puede ser un valor sencillo, una lista o un objeto JSON de cualquier complejidad. Si tu modelo tiene más de un tensor de salida, cada explicación será un objeto JSON que contiene un par nombre/valor para cada salida. Con los nombres se pueden identificar los alias de salida en el grafo.

Ejemplos del cuerpo de la respuesta

La siguiente respuesta de explicaciones es para una atribución de atributos individuales en datos tabulares. Es parte del notebook de ejemplo para datos tabulares. En el notebook, se muestra cómo analizar las respuestas de las explicaciones y trazar los datos de las atribuciones.

Las atribuciones de atributos aparecen dentro del objeto attributions_by_label:

{
 "explanations": [
  {
   "attributions_by_label": [
    {
     "approx_error": 0.001017811509478243,
     "attributions": {
      "data": [
       -0.0,
       1.501250445842743,
       4.4058547498107075,
       0.016078486742916454,
       -0.03749384209513669,
       -0.0,
       -0.2621846305120581,
       -0.0,
       -0.0,
       0.0
      ]
      ...
     },
     "baseline_score": 14.049912452697754,
     "example_score": 19.667699813842773,
     "label_index": 0,
     "output_name": "duration"
    }
    ...
   ]
  }
 ]
}
  • approx_error es un error de aproximación para las atribuciones de atributos. Las atribuciones de atributos se basan en una aproximación de los valores de Shapley. Obtén más información sobre el error de aproximación.
  • El objeto attributions contiene un par clave-valor destinado a cada atributo de entrada para el que solicitaste explicaciones.
    • Para cada atributo de entrada, la clave es la misma que la clave de atributo de entrada que configuraste en tu archivo explanation_metadata.json. En este ejemplo, es “data”.
    • Los valores son las atribuciones de cada atributo. La forma de las atribuciones coincide con el tensor de entrada. En este ejemplo, es una lista de valores escalares. Obtén más información sobre estos valores de atribución.
  • baseline_score es la salida del modelo para el modelo de referencia que estableciste. Según el modelo, puedes establecer el modelo de referencia en cero, un valor aleatorio o valores de mediana. Obtén más información sobre cómo seleccionar los modelos de referencia.
  • example_score es la predicción para la instancia de entrada que proporcionaste. En este ejemplo, example_score es la duración prevista de un viaje en bicicleta compartido en minutos. En general, la example_score de cualquier instancia es la predicción de esa instancia.
  • label_index es el índice en el tensor de salida que se explica.
  • output_name es la misma que la clave de atributo de salida que configuraste en el archivo explanation_metadata.json. En este ejemplo, es “duration”.

Valores de atribución individuales

En esta tabla, se muestran más detalles sobre los atributos que corresponden a estos valores de atribución de ejemplo. Los valores de atribución positivos aumentan el valor previsto en esa cantidad, mientras que los valores de atribución negativos disminuyen el valor previsto. La distancia euclidean entre las ubicaciones de inicio y finalización del viaje en bicicleta tuvo el mayor efecto en la duración prevista del viaje en bicicleta (19,667 minutos), dado que aumentó el valor en 4,498.

Nombre del atributo Valor del atributo Valor de la atribución
start_hr 19 0
weekday 1 -0.0661425
euclidean 3920.76 4.49809
temp 52.5 0.0564195
dew_point 38.8 -0.072438
wdsp 0 0
max_temp 64.8 -0.226125
fog 0 -0
prcp 0.06 -0
rain_drizzle 0 0

Si quieres obtener más información, prueba el notebook de ejemplo para datos tabulares.

Especificación de la API

En la siguiente sección, se describe la especificación del método explain como se define en el documento de descubrimiento de la API de entrenamiento y predicción de AI Platform. Consulta las secciones anteriores de este documento para obtener información detallada sobre el método.

HTTP request

POST https://{endpoint}/v1/{name=projects/**}:explain

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of a model or a version.

Authorization: requires the predict permission on the specified resource.

Authorization requires one or more of the following IAM permissions on the specified resource name:

  • ml.models.predict
  • ml.versions.predict

Request body

The request body contains data with the following structure:

JSON representation
{
  "httpBody": {
    object (HttpBody)
  }
}
Fields
httpBody

object (HttpBody)

Required. The explanation request body.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.