Questa pagina è stata tradotta dall'API Cloud Translation.

Configurare le spiegazioni basate su esempi

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

Poi, quando richiedi spiegazioni online, puoi sostituire alcuni di questi valori di configurazione specificando un ExplanationSpecOverride nella richiesta. Non puoi richiedere spiegazioni sui batch perché non sono supportate.

Questa pagina descrive 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:

Una posizione Cloud Storage contenente gli artefatti del modello. Il modello deve essere un modello di rete neurale profonda (DNN) in cui fornisci il nome di uno strato o di una firma il cui output può essere utilizzato come spazio latente oppure puoi fornire un modello che generi direttamente gli embedding (rappresentazione dello spazio latente). Questo spazio latente acquisisce le rappresentazioni degli esempi che vengono utilizzate per generare spiegazioni.
Una posizione Cloud Storage contenente le istanze da indicizzare per la ricerca del vicino più prossimo approssimativo. Per ulteriori informazioni, consulta i requisiti dei dati di input.

Console

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

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

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

Schermata Importa modello nella console che mostra le opzioni disponibili nella scheda Spiegabilità.

Interfaccia a riga di comando gcloud

Scrivi quanto segue ExplanationMetadata in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiamalo explanation-metadata.json:

{
  "inputs": {
    "my_input": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "encoding": "IDENTITY",
    },
    "id": {
      "inputTensorName": "id",
      "encoding": "IDENTITY"
    }
  },
  "outputs": {
    "embedding": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

(Facoltativo) Se specifichi il valore completo di NearestNeighborSearchConfig, scrivi quanto segue in un file JSON nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio chiamalosearch_config.json:

{
  "contentsDeltaUri": "",
  "config": {
      "dimensions": 50,
      "approximateNeighborsCount": 10,
      "distanceMeasureType": "SQUARED_L2_DISTANCE",
      "featureNormType": "NONE",
      "algorithmConfig": {
          "treeAhConfig": {
              "leafNodeEmbeddingCount": 1000,
              "fractionLeafNodesToSearch": 1.0
          }
      }
    }
  }

Esegui il seguente comando per caricare il tuo Model.

Se utilizzi una configurazione di ricerca Preset, rimuovi il --explanation-nearest-neighbor-search-config-file flag. Se specifichi 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

Per ulteriori informazioni, consulta gcloud ai models upload.

L'azione di caricamento restituisce un OPERATION_ID che può essere utilizzato per verificare il termine dell'operazione. Puoi eseguire il polling per 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 finché l'operazione non sarà completata. 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 eseguire query sugli esempi.

REST

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

PROJECT
LOCATION

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

Per scoprire di più sul caricamento dei modelli, consulta il metodo upload e l'articolo Importazione dei modelli.

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

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:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'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. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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 alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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 OPERATION_ID che può essere utilizzato per verificare il termine dell'operazione. Puoi eseguire il polling per 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 finché l'operazione non sarà completata. 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 eseguire query sugli esempi.

Python

Consulta la sezione Carica il modello nel notebook di spiegazioni basate su esempi per la classificazione delle immagini.

`NearestNeighborSearchConfig`

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

Le tabelle riportate di seguito elencano i campi per NearestNeighborSearchConfig.

Campi
`dimensions`	`int32` Obbligatorio. Il numero di dimensioni dei vettori di input. Utilizzato solo per gli embedding densi.
`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 approssimativo vengono riordinati utilizzando un calcolo della distanza più costoso.
`ShardSize`	`ShardSize` Le dimensioni di ogni shard. Quando un indice è di grandi dimensioni, viene suddiviso in base alle dimensioni dello shard specificate. Durante la pubblicazione, ogni frammento viene pubblicato su un nodo distinto e viene scalato 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 embedding densi. `TreeAhConfig`: opzioni di configurazione per l'utilizzo dell'algoritmo tree-AH. Per saperne di più, consulta questo post del blog Scalabilità del recupero approfondito con i consigli di TensorFlow e la ricerca vettoriale `BruteForceConfig`: questa opzione implementa la ricerca lineare standard nel database per ogni query. Non sono presenti campi da configurare per una ricerca bruta. Per selezionare questo algoritmo, passa un oggetto vuoto per `BruteForceConfig`.

`DistanceMeasureType`

Enum
`SQUARED_L2_DISTANCE`	Distanza euclidea (L₂)
`L1_DISTANCE`	Distanza di Manhattan (L₁)
`DOT_PRODUCT_DISTANCE`	Valore predefinito. Definito come il negativo del prodotto scalare.
`COSINE_DISTANCE`	Distanza coseno. 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 L2 dell'unità.
`NONE`	Valore predefinito. Non è specificato alcun tipo di normalizzazione.

`TreeAhConfig`

Questi sono i campi da selezionare per l'algoritmo tree-AH (albero poco profondo + hashing asimmetrico).

Campi
`fractionLeafNodesToSearch`	`double`
	La frazione predefinita di nodi foglia in cui è possibile cercare qualsiasi query. Deve essere compreso tra 0,0 e 1,0, esclusi. Se non è impostato, il valore predefinito è 0,05.
`leafNodeEmbeddingCount`	`int32`
	Numero di incorporamenti su ciascun nodo foglia. Se non è impostato, il valore predefinito è 1000.
`leafNodesToSearchPercent`	`int32`
	Funzionalità deprecata, utilizza `fractionLeafNodesToSearch`. La percentuale predefinita di nodi foglia in cui è possibile cercare qualsiasi query. Deve essere compreso tra 1 e 100, inclusi. Se non è impostato, il valore predefinito è 10 (ovvero il 10%).

`BruteForceConfig`

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

Requisiti dei dati di input

Carica il set di dati in una posizione Cloud Storage. Assicurati che i file siano in formato JSON Lines.

I file devono essere in formato JSON Lines. Il seguente esempio è tratto dal notebook di spiegazioni basate su esempi per la 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 ti consente di aggiornare l'indice del vicino più vicino o la configurazione di Example di un modello. Questa operazione è utile se vuoi aggiornare il modello senza indicizzare nuovamente il relativo set di dati. Ad esempio, se l'indice del tuo 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 delle spiegazioni:

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 valore model_id rimane invariato dopo l'operazione UpdateExplanationDataset.
L'operazione UpdateExplanationDataset interessa solo la risorsa Model; non aggiorna i DeployedModel associati. Ciò significa che l'indice di un deployedModel contiene il set di dati al momento del suo dispiegamento. Per aggiornare l'indice di un deployedModel, devi eseguire nuovamente il deployment del modello aggiornato in un endpoint.

Sostituire la configurazione quando si ricevono spiegazioni online

Quando richiedi una spiegazione, puoi sostituire alcuni parametri al volo specificando il campo ExplanationSpecOverride.

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

La tabella seguente riassume i parametri che possono essere ignorati per una 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 affollamento
allow	`String Array`	I tag consentiti per le spiegazioni
deny	`String Array`	I tag non consentiti per le spiegazioni

La pagina Filtro di ricerca vettoriale descrive questi parametri in modo più dettagliato.

Ecco un esempio di corpo della richiesta JSON con sostituzioni:

{
  "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 ricevi 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 pagina dei prezzi.