Configurare spiegazioni basate su esempi

Per utilizzare spiegazioni basate su esempi, devi configurarle specificando un explanationSpec quando importi o carichi la risorsa Model nel registro dei modelli.

Quindi, quando richiedi spiegazioni online, puoi eseguire l'override di alcuni di questi valori di configurazione specificando un ExplanationSpecOverride nella richiesta. Non puoi richiedere spiegazioni batch perché non sono supportate.

In questa pagina viene descritto come configurare e aggiornare queste opzioni.

Configura le spiegazioni durante l'importazione o il caricamento del modello

Prima di iniziare, assicurati di disporre di quanto segue:

  1. Una località di Cloud Storage contenente gli artefatti del tuo modello. Il tuo modello deve essere un modello di rete neurale profonda (DNN) in cui specifichi il nome di un livello, o firma, il cui output può essere utilizzato come spazio latente, oppure puoi fornire un modello che generi direttamente gli incorporamenti (rappresentazione dello spazio latente). Questo spazio latente acquisisce le rappresentazioni di esempio utilizzate per generare spiegazioni.

  2. Una località di Cloud Storage contenente le istanze da indicizzare per la ricerca approssimativa al vicino più prossimo. Per ulteriori informazioni, consulta i requisiti dei dati di input.

Console

Segui la guida per l'importazione di un modello utilizzando la console Google Cloud.

Nella scheda Spiegabilità, seleziona Spiegazione basata su esempio e compila i campi.

Per informazioni su ogni campo, consulta i suggerimenti nella Google Cloud Console (mostrati di seguito) e la documentazione di riferimento per Example e ExplanationMetadata.

Interfaccia a riga di comando gcloud

  1. Scrivi il seguente elemento ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiama il file explanation-metadata.json:
{
  "inputs": {
    "my_input": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "encoding": "IDENTITY",
    },
    "id": {
      "inputTensorName": "id",
      "encoding": "IDENTITY"
    }
  },
  "outputs": {
    "embedding": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}
  1. (Facoltativo) Se stai specificando il valore NearestNeighborSearchConfig completo, scrivi quanto segue in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio, chiama il file search_config.json:
{
  "contentsDeltaUri": "",
  "config": {
      "dimensions": 50,
      "approximateNeighborsCount": 10,
      "distanceMeasureType": "SQUARED_L2_DISTANCE",
      "featureNormType": "NONE",
      "algorithmConfig": {
          "treeAhConfig": {
              "leafNodeEmbeddingCount": 1000,
              "fractionLeafNodesToSearch": 1.0
          }
      }
    }
  }
  1. Esegui questo comando per caricare il tuo Model.

Se utilizzi una configurazione di ricerca Preset, rimuovi il flag --explanation-nearest-neighbor-search-config-file. Se stai specificando NearestNeighborSearchConfig, rimuovi i flag --explanation-modality e --explanation-query.

I flag più pertinenti per le spiegazioni basate su esempi sono in grassetto.

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

Per saperne di più, consulta gcloud ai model upload.

  1. L'azione di caricamento restituisce un OPERATION_ID che può essere utilizzato per verificare il completamento dell'operazione. Puoi eseguire il polling per verificare lo stato dell'operazione finché la risposta non include "done": true. Utilizza il comando gcloud ai Operations describe per eseguire il polling dello stato, ad esempio:

    gcloud ai operations describe <operation-id>

    Non potrai richiedere spiegazioni fino al termine dell'operazione. A seconda delle dimensioni del set di dati e dell'architettura del modello, questo passaggio può richiedere diverse ore per creare l'indice utilizzato per le query degli esempi.

REST

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT
  • LOCATION

Per scoprire di più sugli altri segnaposto, consulta Model, explanationSpec e Examples.

Per saperne di più sul caricamento dei modelli, consulta il metodo upload e Importazione dei modelli.

Il corpo della richiesta JSON di seguito specifica una configurazione di ricerca Preset. In alternativa, puoi specificare il valore NearestNeighborSearchConfig completo.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

L'azione di caricamento restituisce un OPERATION_ID che può essere utilizzato per verificare il completamento dell'operazione. Puoi eseguire il polling per verificare lo stato dell'operazione finché la risposta non include "done": true. Utilizza il comando gcloud ai Operations describe per eseguire il polling dello stato, ad esempio:

gcloud ai operations describe <operation-id>

Non potrai richiedere spiegazioni fino al termine dell'operazione. A seconda delle dimensioni del set di dati e dell'architettura del modello, questo passaggio può richiedere diverse ore per creare l'indice utilizzato per le query degli esempi.

Python

Consulta la sezione Caricare il modello nel blocco note per le spiegazioni basate su esempi di classificazione delle immagini.

NearestNeighborSearchConfig

Il seguente corpo della richiesta JSON mostra come specificare il valore completo di NearestNeighborSearchConfig (anziché le preimpostazioni) in una richiesta 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": { ... }
    }
  }
}

Nella tabella seguente sono elencati i campi per NearestNeighborSearchConfig.

Campi
dimensions

int32

Obbligatorio. Il numero di dimensioni dei vettori di input.
approximateNeighborsCount

int32

Obbligatorio se viene utilizzato l'algoritmo tree-AH.

Il numero predefinito di vicini da trovare tramite una ricerca approssimativa prima che venga eseguito il riordinamento esatto. Il riordinamento esatto è una procedura in cui i risultati restituiti da un algoritmo di ricerca approssimativa vengono riordinati utilizzando un calcolo della distanza più costoso.

ShardSize ShardSize

Le dimensioni di ogni shard. Quando un indice è di grandi dimensioni, viene segmentato in base alle dimensioni dello shard specificate. Durante la pubblicazione, ogni shard viene pubblicato su un nodo separato e scala in modo indipendente.

distanceMeasureType

DistanceMeasureType

La misurazione della distanza utilizzata nella ricerca del vicino più prossimo.
featureNormType

FeatureNormType

Tipo di normalizzazione da eseguire su ciascun vettore.

algorithmConfig oneOf:

La configurazione degli algoritmi che Vector Search utilizza per una ricerca efficiente.

  • TreeAhConfig: opzioni di configurazione per l'utilizzo dell'algoritmo ad albero ad albero. Per saperne di più, consulta questo blog Scaling deep Retrieval with TensorFlow Recommenders and Vector Search
  • BruteForceConfig: questa opzione implementa la ricerca lineare standard nel database per ogni query. Non ci sono campi da configurare per una ricerca di forza bruta. Per selezionare questo algoritmo, trasmetti un oggetto vuoto per BruteForceConfig.

DistanceMeasureType

Enum
SQUARED_L2_DISTANCE Distanza euclidea (L2)
L1_DISTANCE Distanza di Manhattan (L1)
DOT_PRODUCT_DISTANCE Valore predefinito. Definito come un valore negativo del prodotto scalare.
COSINE_DISTANCE Distanza coseno. Consigliamo vivamente di utilizzare DOT_PRODUCT_DISTANZA + UNIT_L2_NORM anziché la distanza COSINE. I nostri algoritmi sono stati ottimizzati maggiormente per la distanza DOT_PRODUCT e, se combinati con UNIT_L2_NORM, offrono lo stesso ranking e le stesse equivalenze matematica della distanza COSINE.

FeatureNormType

Enum
UNIT_L2_NORM Tipo di normalizzazione dell'unità L2.
NONE Valore predefinito. Nessun tipo di normalizzazione specificato.

TreeAhConfig

Questi sono i campi da selezionare per l'algoritmo ad albero ad albero (Shallow Tree + hashing asimmetrico).

Campi
fractionLeafNodesToSearch double
La frazione predefinita di nodi foglia in cui è possibile cercare qualsiasi query. Deve essere compresa tra 0,0 e 1,0, esclusi. Se non è impostata, il valore predefinito è 0,05.
leafNodeEmbeddingCount int32
Numero di incorporamenti su ciascun nodo foglia. Se non è impostato, il valore predefinito è 1000.
leafNodesToSearchPercent int32
Deprecata, utilizza fractionLeafNodesToSearch.

La percentuale predefinita di nodi foglia in cui è possibile cercare qualsiasi query. Deve essere compreso tra 1 e 100 inclusi. Il valore predefinito è 10 (significa 10%) se non impostato.

BruteForceConfig

Questa opzione implementa la ricerca lineare standard nel database per ogni query. Non ci sono campi da configurare per una ricerca di forza bruta. Per selezionare questo algoritmo, passa un oggetto vuoto per BruteForceConfig a algorithmConfig.

Requisiti dei dati di input

Caricare il set di dati in una località di Cloud Storage. Assicurati che i file siano in formato JSON Lines.

I file devono essere in formato JSON Lines. Il seguente esempio è tratto dal blocco note basato su esempi di classificazione delle immagini:

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

Aggiorna l'indice o la configurazione

Vertex AI consente di aggiornare l'indice del vicino più prossimo di un modello o la configurazione di Example. Ciò è utile se vuoi aggiornare il modello senza reindicizzare il suo set di dati. Ad esempio, se l'indice del modello contiene 1000 istanze e vuoi aggiungerne altre 500, puoi chiamare UpdateExplanationDataset per aggiungerle all'indice senza rielaborare le 1000 istanze originali.

Per aggiornare il set di dati di spiegazione:

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)

Note sull'utilizzo:

  • model_id rimane invariato dopo l'operazione UpdateExplanationDataset.

  • L'operazione UpdateExplanationDataset interessa solo la risorsa Model; non aggiorna le DeployedModel associate. Questo significa che l'indice di deployedModel contiene il set di dati al momento del deployment. Per aggiornare l'indice di un elemento deployedModel, devi eseguire nuovamente il deployment del modello aggiornato in un endpoint.

Esegui l'override della configurazione quando ricevi spiegazioni online

Quando richiedi una spiegazione, puoi sostituire alcuni parametri all'istante specificando il campo ExplanationSpecOverride.

A seconda dell'applicazione, potrebbero essere utili alcuni vincoli sul tipo di spiegazioni che vengono restituite. Ad esempio, per garantire la diversità delle spiegazioni, un utente può specificare un parametro di crowding che indica che nessun singolo tipo di esempi è sovrarappresentato nelle spiegazioni. Concretamente, se un utente sta cercando di capire perché un uccello è stato etichettato come un aereo dal suo modello, potrebbe non essere interessato a vedere troppi esempi di uccelli come spiegazioni per indagare meglio sulla causa principale.

La seguente tabella riassume i parametri che possono essere sostituiti per una richiesta di spiegazione basata su esempio:

Nome proprietà Valore della proprietà Descrizione
neighborCount int32 Il numero di esempi da restituire come spiegazione
crowdingCount int32 Numero massimo di esempi da restituire con lo stesso tag di crowding
allow String Array I tag consentiti per le spiegazioni
deny String Array I tag non consentiti per le spiegazioni

L'opzione Filtro ricerca vettoriale descrive questi parametri in modo più dettagliato.

Ecco un esempio di corpo di richiesta JSON con override:

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

Passaggi successivi

Ecco un esempio di risposta a una richiesta explain basata su esempio:

[
   {
      "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"
   }
]

Prezzi

Consulta la sezione sulle spiegazioni basate su esempi nella pagina dei prezzi.