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 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 explicaciones cuando importes o subas el modelo
Antes de comenzar, asegúrate de tener 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 ejemplo 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 llamaexplanation-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 de tu entorno local (opcional). El nombre del archivo no es importante, pero en este ejemplo se lo llamasearch_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 de 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 aparecen 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 cómo subir modelos, consulta el método upload
y la importación de modelos.
El cuerpo de la solicitud JSON que aparece a continuación especifica una configuración de búsqueda Preset
. Como alternativa, puedes especificar el objeto 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 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 |
Obligatorio. La cantidad de dimensiones de los vectores de entrada. Solo se usa para embeddings densos. |
approximateNeighborsCount |
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 |
La medida de distancia usada en la búsqueda de vecino más cercano. |
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.
|
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 tengan 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 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, sigue estos pasos:
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ónUpdateExplanationDataset
.La operación
UpdateExplanationDataset
solo afecta al recursoModel
; no actualiza ningúnDeployedModel
asociado. Esto significa que el índice dedeployedModel
contiene el conjunto de datos en el momento en que se implementó. Para actualizar el índice dedeployedModel
, 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?
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.