Questa pagina è stata tradotta dall'API Cloud Translation.

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 sui 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:

Una posizione Cloud Storage contenente gli artefatti del 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 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, vedi requisiti dei dati di input.

Console

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

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

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

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

(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 questo comando per caricare 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

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

L'azione di caricamento restituisce un OPERATION_ID che può essere utilizzato per verificare il termine dell'operazione. 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ò richiedere diverse ore per creare l'indice utilizzato per eseguire query sugli 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 riportato 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 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)

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 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 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 Carica il modello nel notebook di spiegazioni basate su esempi per la classificazione delle immagini.

`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. 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 viene eseguito 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 è di grandi dimensioni, viene suddiviso in base alle dimensioni dello shard specificate. Durante la pubblicazione, ogni shard viene pubblicato su un nodo separato 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 gli incorporamenti densi. `TreeAhConfig`: opzioni di configurazione per l'utilizzo del l'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 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 (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 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. Se non è impostato, il valore predefinito è 0,05.
`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. Se non è impostato, il valore predefinito è 10 (ovvero il 10%).

`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 siano in formato JSON Lines.

I file devono essere nel 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 consente di aggiornare l'indice del vicino più prossimo di un modello Configurazione di Example. Questa operazione è utile se vuoi aggiornare il modello senza indicizzare nuovamente 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 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:

model_id rimane invariato dopo l'operazione UpdateExplanationDataset.
L'operazione UpdateExplanationDataset interessa solo la risorsa Model. non aggiorna nulla 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 dei parametri nella volare specificando ExplanationSpecOverride .

A seconda dell'applicazione, potrebbero essere auspicabili alcuni vincoli sul tipo di spiegazioni 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 per dare una spiegazione indagare meglio sulla causa principale.

La seguente tabella 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 crowding
allow	`String Array`	I tag consentiti per le spiegazioni
deny	`String Array`	I tag non consentiti per le spiegazioni

Il 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 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 pagina dei prezzi.