Configura spiegazioni basate su esempi

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

Quando richiedi spiegazioni online, puoi sostituirne alcune di configurazione mediante la specifica ExplanationSpecOverride nella richiesta. Non puoi richiedere spiegazioni batch; non sono supportati.

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 che contiene gli artefatti del tuo modello. Il tuo modello o un modello di rete neurale profonda (DNN, Deep Neural Network, rete neurale profonda) in cui fornisci il nome di uno strato, o firma, il cui output può essere utilizzato come spazio latente, oppure puoi fornire un modello che restituisce direttamente gli incorporamenti (spazio latente rappresentazione). Questo spazio latente cattura le rappresentazioni di esempio che vengono utilizzati per generare spiegazioni.

2. Una località di Cloud Storage che contiene le istanze da indicizzare ricerca del vicino più prossimo approssimato. Per ulteriori informazioni, vedi requisiti dei dati di input.

Nota: devi specificare un Configurazione di ricerca di Preset o full NearestNeighborSearchConfig.

Nota: il completamento del caricamento del modello richiede 1-2 ore. Questo passaggio include due il massimo consumo delle operazioni: l'esecuzione Da batchPredictionJob a generare le rappresentazioni latenti (incorporamenti) e utilizzare Ricerca vettoriale per indicizzare per cercare il vicino più prossimo. Il tempo effettivo per il modello e i dati variano. Si tratta in genere del passaggio che richiede più tempo quando si utilizzano modelli spiegazioni. Gli altri passaggi, come il deployment del modello e la connessione spiegazioni non richiedono previsione o indicizzazione in batch.

Console

Segui la guida per importare un file modello utilizzando la console Google Cloud.

Nella scheda Spiegabilità, seleziona Spiegabilità basata su esempi e compila nei 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 quanto segue 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 specifichi l'intero NearestNeighborSearchConfig, scrivi a un file JSON nel tuo ambiente locale. Il nome del file non importa, 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 Model

Se utilizzi una configurazione di ricerca Preset, rimuovi Flag --explanation-nearest-neighbor-search-config-file. Se che specifica NearestNeighborSearchConfig, rimuovi i flag --explanation-modality e --explanation-query.

I flag più pertinenti alle 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

Consulta la pagina relativa al caricamento dei modelli gcloud ai per ulteriori informazioni.

1. L'azione di caricamento restituisce un valore OPERATION_ID che può essere utilizzato per verificare quando l'operazione è terminata. Puoi eseguire un polling per conoscere lo stato dell'operazione la risposta 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ò ore diverse per creare l'indice usato 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, vedi Model, explanationSpec e Examples.

Per scoprire di più sul caricamento dei modelli, consulta le sezioni upload e Importazione dei modelli.

Il corpo della richiesta JSON seguente 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 delle seguenti opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: Il comando seguente presuppone che tu abbia eseguito l'accesso a l'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud di Google. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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)

Nota: Il comando seguente presuppone che tu abbia eseguito l'accesso a l'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login di Google. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list

Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

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 valore OPERATION_ID che può essere utilizzato per verificare quando l'operazione è terminata. Puoi eseguire un polling per conoscere lo stato dell'operazione la risposta 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ò ore diverse per creare l'indice usato per le query degli esempi.

Python

Consulta la sezione Caricamento del modello nella sezione Classificazione delle immagini spiegazioni basate su esempi un blocco note.

NearestNeighborSearchConfig

Il corpo della richiesta JSON seguente dimostra come specificare l'intero NearestNeighborSearchConfig (anziché predefiniti) in uno 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": { ... }
    }
  }
}

Le tabelle riportate di seguito elencano i campi per NearestNeighborSearchConfig.

Campi
dimensions	int32 Obbligatorio. Il numero di dimensioni dei vettori di input. Usato per contenuti densi incorporamenti.
approximateNeighborsCount	int32 Obbligatorio se viene utilizzato l'algoritmo Tree-AH. Il numero predefinito di vicini da trovare tramite una ricerca approssimativa prima il riordinamento esatto. Il riordinamento esatto è una procedura in cui i risultati restituiti da un algoritmo di ricerca approssimativo vengono riordinati utilizzando di calcolo delle distanze più costoso.
ShardSize	ShardSize Le dimensioni di ogni shard. Quando un indice è grande, viene eseguito lo sharding in base la dimensione dello shard specificata. Durante la pubblicazione, ogni shard viene pubblicato su una e scalare 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: TreeAhConfig BruteForceConfig La configurazione degli algoritmi utilizzati da Vector Search per una ricerca efficiente. Utilizzato solo per gli incorporamenti densi. TreeAhConfig: opzioni di configurazione per l'utilizzo del l'algoritmo Tree-AH. Per ulteriori informazioni, visita questo blog Scalabilità il recupero approfondito con i motori per suggerimenti di TensorFlow Ricerca vettoriale BruteForceConfig: questa opzione implementa lo standard una ricerca lineare nel database. Non esistono campi per configura una ricerca di forza bruta. Per selezionare questo algoritmo, passa 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. Ti consigliamo vivamente di utilizzare DOT_PRODUCT_DISTANCE + 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 la stessa equivalenza 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 Tree-AH (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. In caso contrario, il valore predefinito è 0,05. per iniziare.
leafNodeEmbeddingCount	int32
	Numero di incorporamenti su ciascun nodo foglia. In caso contrario, il valore predefinito è 1000. per iniziare.
leafNodesToSearchPercent	int32
	Deprecato, 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 (ovvero 10%) se non impostato.

BruteForceConfig

Questa opzione implementa la ricerca lineare standard nel database per ogni query. Non esistono campi da configurare per una ricerca di forza bruta. Per selezionare l'opzione passa un oggetto vuoto per BruteForceConfig a algorithmConfig.

Requisiti dei dati di input

Carica il set di dati in una posizione di Cloud Storage. Assicurati che i file nel formato JSON Formato delle linee.

I file devono essere nel formato JSON Lines. Il seguente esempio è tratto dal modello image spiegazioni basate su esempi di classificazione blocco note:

{"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 Configurazione di Example. Questo è è utile se vuoi aggiornare il modello senza reindicizzare il relativo set di dati. Per Ad esempio, se l'indice del modello contiene 1000 istanze e vuoi aggiungere Altre 500 istanze, puoi chiamare UpdateExplanationDataset per aggiungerle alla senza dover rielaborare le 1000 istanze originali.

Per aggiornare il set di dati 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:

• Il model_id rimane invariato dopo il UpdateExplanationDataset operativa.

• L'operazione UpdateExplanationDataset interessa solo la risorsa Model. non aggiorna nulla DeployedModel associati. Ciò significa che un indice di deployedModel contiene il set di dati in quel momento di cui è stato eseguito il deployment. Per aggiornare l'indice di deployedModel, devi eseguire nuovamente il deployment ha aggiornato il modello in un endpoint.

Sostituisci la configurazione per ricevere spiegazioni online

Quando richiedi una spiegazione, puoi sostituire alcuni dei parametri nella volare specificando ExplanationSpecOverride .

A seconda dell'applicazione, alcuni vincoli potrebbero essere auspicabili sul tipo di spiegazioni che vengono restituite. Ad esempio, per garantire la diversità spiegazioni, un utente può specificare un parametro di crowding che impone che gli esempi singoli sono sovrarappresentati nelle spiegazioni. Concretamente, se un utente sta cercando di capire perché un uccello è stato etichettato come aereo dal suo modello, potrebbero non essere interessati a vedere troppi esempi di uccelli come spiegazione per indagare meglio sulla causa principale.

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

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 ammessi per le spiegazioni

Il filtro di ricerca vettoriale descrive questi parametri in modo più dettagliato.

Ecco un esempio di corpo di una 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

• Esegui il deployment di Model in un Endpoint e ottenere spiegazioni basate su esempi.

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

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