Configura explicaciones basadas en ejemplos

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

Luego, cuando solicites explicaciones en línea, podrás anular algunos de esos valores de configuración si especificas un ExplanationSpecOverride en 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 las explicaciones cuando importes o subas el modelo

Antes de comenzar, asegúrate de haber hecho lo siguiente:

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.
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.

CLI de gcloud

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"
    }
  }
}

Si especificas el NearestNeighborSearchConfig completo, escribe lo siguiente en un archivo JSON en tu entorno local (opcional). 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
          }
      }
    }
  }

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 especificas 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.

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 la carga de modelos, consulta el método upload y la importación de modelos.

El cuerpo de la solicitud JSON a continuación 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:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, 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/locations/LOCATION/models:upload"

PowerShell (Windows)

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/locations/LOCATION/models:upload" | Select-Object -Expand Content

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 basadas en ejemplos de clasificación de imágenes.

`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.
`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.
`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:` `TreeAhConfig` `BruteForceConfig` La configuración de los algoritmos que Vector Search usa para realizar una búsqueda eficiente. `TreeAhConfig`: Opciones de configuración para usar el algoritmo de AH-Tree. Consulta este blog para obtener más detalles: 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 (L₂)
`L1_DISTANCE`	Distancia de Manhattan (L₁)
`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 el 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 o la configuración 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 explicaciones, 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 permanece sin cambios 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 una 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 si especificas 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?

Implementa tu Model en un Endpoint y obtén explicaciones basadas en ejemplos.

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

[
   {
      "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.