Configura explicaciones basadas en ejemplos

Para usar explicaciones basadas en ejemplos, debes configurar explicaciones mediante la especificación de un explanationSpec cuando importes o subas el recurso Model en Model Registry.

De esta manera, cuando solicitas explicaciones en línea, puedes anular algunos de esos valores de configuración especificando una ExplanationSpecOverrideen la solicitud. No puedes solicitar explicaciones por lotes; no se admiten.

En esta página, se describe cómo configurar y actualizar estas opciones.

Configura explicaciones cuando importes o subas el modelo

Antes de comenzar, asegúrate de tener lo siguiente:

  1. Una ubicación de Cloud Storage que contiene los artefactos de tu modelo. Tu modelo debe ser un modelo de red neuronal profunda (DNN) en el que proporciones el nombre de una capa, o firma, cuyo resultado se pueda usar como espacio latente, o puedes proporcionar un modelo que genera incorporaciones de forma directa (representación de espacio latente). Este espacio latente captura las representaciones de ejemplo que se usan para generar explicaciones.

  2. Es una ubicación de Cloud Storage que contiene las instancias que se indexarán para la búsqueda de vecinos aproximados más cercanos. Para obtener más información, consulta Requisitos de datos de origen.

Console

Sigue la guía para importar un modelo con la consola de Google Cloud.

En la pestaña Explicabilidad, selecciona Explicación basada en ejemplos y completa los campos.

Para obtener información sobre cada campo, consulta las sugerencias de la consola de Google Cloud (que se muestran a continuación), así como la documentación de referencia de Example y ExplanationMetadata.

Pantalla Importar modelo en la consola que muestra las opciones disponibles en la pestaña Explicabilidad.

gcloud CLI

  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.
{
  "inputs": {
    "my_input": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "encoding": "IDENTITY",
    },
    "id": {
      "inputTensorName": "id",
      "encoding": "IDENTITY"
    }
  },
  "outputs": {
    "embedding": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}
  1. Opcional: Si especificas el NearestNeighborSearchConfig completo, escribe lo siguiente en un archivo JSON en tu entorno local. El nombre del archivo no es importante, pero en este ejemplo se lo llama search_config.json.
{
  "contentsDeltaUri": "",
  "config": {
      "dimensions": 50,
      "approximateNeighborsCount": 10,
      "distanceMeasureType": "SQUARED_L2_DISTANCE",
      "featureNormType": "NONE",
      "algorithmConfig": {
          "treeAhConfig": {
              "leafNodeEmbeddingCount": 1000,
              "fractionLeafNodesToSearch": 1.0
          }
      }
    }
  }
  1. Ejecuta el siguiente comando para subir tu Model

Si usas una configuración de búsqueda Preset, quita la marca --explanation-nearest-neighbor-search-config-file. Si estás especificando NearestNeighborSearchConfig, quita las marcas --explanation-modality y --explanation-query

Las marcas más pertinentes a las explicaciones basadas en ejemplos están en negrita.

gcloud ai models upload \
    --region=LOCATION \
    --display-name=MODEL_NAME \
    --container-image-uri=IMAGE_URI \
    --artifact-uri=MODEL_ARTIFACT_URI \
    --explanation-method=examples \
    --uris=[URI, ...] \
    --explanation-neighbor-count=NEIGHBOR_COUNT \
    --explanation-metadata-file=explanation-metadata.json \
    --explanation-modality=IMAGE|TEXT|TABULAR \
    --explanation-query=PRECISE|FAST \
    --explanation-nearest-neighbor-search-config-file=search_config.json

Consulta gcloud ai models upload para obtener más información.

  1. La acción de carga muestra un OPERATION_ID que se puede usar para verificar cuándo finalizó la operación. Puedes sondear el estado de la operación hasta que la respuesta incluya "done": true. Utiliza el comando gcloud ai operations describe para sondear el estado, por ejemplo:

    gcloud ai operations describe <operation-id>

    No podrás solicitar explicaciones hasta que se complete la operación. Según el tamaño del conjunto de datos y la arquitectura del modelo, este paso puede tardar varias horas en compilar el índice usado para consultar ejemplos.

REST

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

  • PROJECT
  • LOCATION

Para obtener información sobre los otros marcadores de posición, consulta Model, explanationSpec y Examples.

Para obtener más información sobre cómo subir modelos, consulta el método upload y Cómo importar modelos.

En el siguiente cuerpo de la solicitud JSON, se especifica una configuración de búsqueda Preset. Como alternativa, puedes especificar el NearestNeighborSearchConfig completo.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "model": {
    "displayName": "my-model",
    "artifactUri": "gs://your-model-artifact-folder",
    "containerSpec": {
      "imageUri": "us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-11:latest",
    },
    "explanationSpec": {
      "parameters": {
        "examples": {
          "gcsSource": {
            "uris": ["gs://your-examples-folder"]
          },
          "neighborCount": 10,
          "presets": {
            "modality": "image"
          }
        }
      },
      "metadata": {
        "outputs": {
            "embedding": {
                "output_tensor_name": "embedding"
            }
        },
        "inputs": {
          "my_fancy_input": {
            "input_tensor_name": "input_tensor_name",
            "encoding": "identity",
            "modality": "image"
          },
          "id": {
            "input_tensor_name": "id",
            "encoding": "identity"
          }
        }
      }
    }
  }
}

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/models/MODEL_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UploadModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T01:21:10.147035Z",
      "updateTime": "2022-01-08T01:21:10.147035Z"
    }
  }
}

La acción de carga muestra un OPERATION_ID que se puede usar para verificar cuándo finalizó la operación. Puedes sondear el estado de la operación hasta que la respuesta incluya "done": true. Utiliza el comando gcloud ai operations describe para sondear el estado, por ejemplo:

gcloud ai operations describe <operation-id>

No podrás solicitar explicaciones hasta que se complete la operación. Según el tamaño del conjunto de datos y la arquitectura del modelo, este paso puede tardar varias horas en compilar el índice usado para consultar ejemplos.

Python

Consulta la sección Sube el modelo en el notebook de explicaciones de clasificación de imágenes basadas en ejemplos.

NearestNeighborSearchConfig

En el siguiente cuerpo de solicitud JSON, se muestra cómo especificar el NearestNeighborSearchConfig completo (en lugar de los predeterminados) en una solicitud upload.

{
  "model": {
    "displayName": displayname,
    "artifactUri": model_path_to_deploy,
    "containerSpec": {
      "imageUri": DEPLOY_IMAGE,
    },
    "explanationSpec": {
      "parameters": {
        "examples": {
          "gcsSource": {
            "uris": [DATASET_PATH]
          },
          "neighborCount": 5,
          "nearest_neighbor_search_config": {
            "contentsDeltaUri": "",
            "config": {
              "dimensions": dimensions,
              "approximateNeighborsCount": 10,
              "distanceMeasureType": "SQUARED_L2_DISTANCE",
              "featureNormType": "NONE",
              "algorithmConfig": {
                  "treeAhConfig": {
                      "leafNodeEmbeddingCount": 1000,
                      "fractionLeafNodesToSearch": 1.0
                  }
                }
              }
          }
        }
      },
      "metadata": { ... }
    }
  }
}

En las siguientes tablas, se enumeran los campos de NearestNeighborSearchConfig.

Campos
dimensions

int32

Obligatorio. La cantidad de dimensiones de los vectores de entrada. Solo se usa para embeddings densos.

approximateNeighborsCount

int32

Es obligatorio si se usa el algoritmo de árbol AH.

Es la cantidad predeterminada de vecinos que se deben encontrar mediante la búsqueda aproximada antes de realizar el reordenamiento exacto. El reordenamiento exacto es un procedimiento en el que los resultados que muestra un algoritmo de búsqueda aproximada se ordenan a través de un cálculo de distancias más costoso.

ShardSize ShardSize

El tamaño de cada fragmento. Cuando un índice es grande, se fragmenta en función del tamaño de fragmento especificado. Durante la entrega, cada fragmento se entrega en un nodo separado y escala de forma independiente.

distanceMeasureType

DistanceMeasureType

La medida de distancia usada en la búsqueda de vecino más cercano.
featureNormType

FeatureNormType

Tipo de normalización que se realizará en cada vector.

algorithmConfig oneOf:

La configuración de los algoritmos que Vector Search usa para realizar una búsqueda eficiente. Solo se usa para embeddings densos.

  • TreeAhConfig: Opciones de configuración para usar el algoritmo de AH-Tree. Para obtener más información, consulta este blog Escala la recuperación profunda con los recomendadores de TensorFlow y Vector Search
  • BruteForceConfig: Con esta opción, se implementa la búsqueda lineal estándar en la base de datos de cada consulta. No hay campos para configurar en la búsqueda por fuerza bruta. Si deseas seleccionar este algoritmo, pasa un objeto vacío para BruteForceConfig.

DistanceMeasureType

Enums
SQUARED_L2_DISTANCE Distancia euclidiana (L2)
L1_DISTANCE Distancia de Manhattan (L1)
DOT_PRODUCT_DISTANCE Valor predeterminado Se define como un negativo del producto escalar.
COSINE_DISTANCE Distancia de coseno. Te sugerimos usar DOT_PRODUCT_distance + UNIT_L2_NORM en lugar de la distancia COSINE. Nuestros algoritmos se optimizaron más para la distancia DOT_ PRODUCT y, cuando se combina con UNIT_L2_NORM, ofrece la misma clasificación y equivalencia matemática que la distancia COSINE.

FeatureNormType

Enums
UNIT_L2_NORM Tipo de normalización de la unidad L2.
NONE Valor predeterminado No se especifica ningún tipo de normalización.

TreeAhConfig

Estos son los campos que se seleccionan para el algoritmo de árbol AH (árbol superficial + hash asimétrico).

Campos
fractionLeafNodesToSearch double
La fracción predeterminada de nodos de hoja que se pueden buscar en cualquier consulta. Debe estar entre 0.0 y 1.0, exclusivo. El valor predeterminado es 0.05 si no se configura.
leafNodeEmbeddingCount int32
Cantidad de incorporaciones en cada nodo hoja El valor predeterminado es 1,000 si no se configura.
leafNodesToSearchPercent int32
Obsoleto: Usa fractionLeafNodesToSearch.

El porcentaje predeterminado de nodos de hoja que se pueden buscar en cualquier consulta. Debe estar entre 1 y 100, inclusive. El valor predeterminado es 10 (significa 10%) si no se configura.

BruteForceConfig

Esta opción implementa la búsqueda lineal estándar en la base de datos para cada consulta. No hay campos para configurar en una búsqueda por fuerza bruta. A fin de seleccionar este algoritmo, pasa un objeto vacío para BruteForceConfig a algorithmConfig.

Requisitos de los datos de entrada

Sube tu conjunto de datos a una ubicación de Cloud Storage. Asegúrate de que los archivos estén en formato de líneas JSON.

Los archivos deben estar en formato de líneas JSON. El siguiente ejemplo es del notebook de explicaciones basadas en ejemplos de clasificación de imágenes:

{"id": "0", "bytes_inputs": {"b64": "..."}}
{"id": "1", "bytes_inputs": {"b64": "..."}}
{"id": "2", "bytes_inputs": {"b64": "..."}}

Actualiza el índice o la configuración

Vertex AI te permite actualizar el índice de vecino más cercano de un modelo o la configuración de Example. Esto es útil si deseas actualizar tu modelo sin volver a indexar su conjunto de datos. Por ejemplo, si el índice de tu modelo contiene 1,000 instancias y deseas agregar 500 instancias más, puedes llamar a UpdateExplanationDataset para agregarla al índice sin volver a procesar las 1,000 instancias originales.

Para actualizar el conjunto de datos de explicación, haz lo siguiente:

Python

def update_explanation_dataset(model_id, new_examples):
    response = clients["model"].update_explanation_dataset(model=model_id,  examples=new_examples)
    update_dataset_response = response.result()
    return update_dataset_response

PRESET_CONFIG = {
    "modality": "TEXT",
    "query": "FAST"
}
NEW_DATASET_FILE_PATH = "new_dataset_path"
NUM_NEIGHBORS_TO_RETURN = 10

EXAMPLES = aiplatform.Examples(presets=PRESET_CONFIG,
                                    gcs_source=aiplatform.types.io.GcsSource(uris=[NEW_DATASET_FILE_PATH]),
                                      neighbor_count=NUM_NEIGHBORS_TO_RETURN)

MODEL_ID = 'model_id'
update_dataset_response = update_explanation_dataset(MODEL_ID, EXAMPLES)

Notas de uso:

  • El model_id no se modifica después de la operación UpdateExplanationDataset.

  • La operación UpdateExplanationDataset solo afecta al recurso Model; no actualiza ningún DeployedModel asociado. Esto significa que el índice de un deployedModel contiene el conjunto de datos en el momento en que se implementó. Para actualizar el índice de un deployedModel, debes volver a implementar el modelo actualizado en un extremo.

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

Cuando solicitas una explicación, puedes anular algunos de los parámetros sobre la marcha especificando el campo ExplanationSpecOverride.

Según la aplicación, algunas restricciones pueden ser convenientes según el tipo de explicaciones que se muestran. Por ejemplo, para garantizar la diversidad de explicaciones, un usuario puede especificar un parámetro de multitud que indique que ningún tipo de ejemplos está representado en exceso en las explicaciones. En concreto, si un usuario intenta comprender por qué su modelo etiquetó un ave como un avión, es posible que no le interese ver demasiados ejemplos de aves como explicaciones para investigar mejor la causa raíz.

En la siguiente tabla, se resumen los parámetros que se pueden anular para una solicitud de explicación basada en ejemplos:

Nombre de la propiedad Valor de la propiedad Descripción
neighborCount int32 La cantidad de ejemplos que se muestran como explicación
crowdingCount int32 Cantidad máxima de ejemplos que se mostrarán con la misma etiqueta de multitud
allow String Array Las etiquetas que pueden tener las explicaciones
deny String Array Las etiquetas que no pueden tener las explicaciones

El filtro de Vector Search describe estos parámetros con más detalle.

Este es un ejemplo de un cuerpo de solicitud JSON con anulaciones:

{
  "instances":[
    {
      "id": data[0]["id"],
      "bytes_inputs": {"b64": bytes},
      "restricts": "",
      "crowding_tag": ""
    }
  ],
  "explanation_spec_override": {
    "examples_override": {
      "neighbor_count": 5,
      "crowding_count": 2,
      "restrictions": [
        {
          "namespace_name": "label",
          "allow": ["Papilloma", "Rift_Valley", "TBE", "Influenza", "Ebol"]
        }
      ]
    }
  }
}

¿Qué sigue?

Este es un ejemplo de la respuesta de una solicitud explain basada en ejemplos:

[
   {
      "neighbors":[
         {
            "neighborId":"311",
            "neighborDistance":383.8
         },
         {
            "neighborId":"286",
            "neighborDistance":431.4
         }
      ],
      "input":"0"
   },
   {
      "neighbors":[
         {
            "neighborId":"223",
            "neighborDistance":471.6
         },
         {
            "neighborId":"55",
            "neighborDistance":392.7
         }
      ],
      "input":"1"
   }
]

Precios

Consulta la sección sobre explicaciones basadas en ejemplos en la página de precios.