Prova i modelli Gemini 1.5, gli ultimi modelli multimodali di Vertex AI, e scopri cosa puoi creare con una finestra contestuale fino a 2 milioni di token. Prova i modelli Gemini 1.5, i più recenti modelli multimodali di Vertex AI, e scopri cosa puoi creare con una finestra contestuale fino a 2 milioni di token.

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 la risorsa Model nel Model Registry.

Quando richiedi spiegazioni online, puoi ignorare 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:

Una località di Cloud Storage che contiene gli artefatti del tuo modello. Il modello deve essere un modello di rete neurale profonda (DNN) 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 (rappresentazione dello spazio latente). Questo spazio latente acquisisce le rappresentazioni di esempio utilizzate per generare spiegazioni.
Una località di Cloud Storage contenente le istanze da indicizzare per la ricerca del vicino più prossimo approssimativo. Per maggiori informazioni, consulta i requisiti dei dati di input.

Console

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

Nella scheda Spiegabilità, seleziona Spiegabilità 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.

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

Esegui questo comando per caricare Model.

Se utilizzi una configurazione di ricerca Preset, rimuovi il flag --explanation-nearest-neighbor-search-config-file. 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 al termine 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, 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 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 fa accedere automaticamente all'interfaccia a riga di comando di gcloud. . 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 all'interfaccia a riga di comando di 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 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 OPERATION_ID che può essere utilizzato per verificare al termine 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 con spiegazioni basate su esempi di classificazione delle immagini.

`NearestNeighborSearchConfig`

Il seguente corpo della richiesta JSON mostra come specificare l'elemento NearestNeighborSearchConfig completo (anziché i valori preimpostati) 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 incorporamenti 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 approssimativa vengono riordinati utilizzando un calcolo delle distanze più costoso.
`ShardSize`	`ShardSize` Le dimensioni di ogni shard. Quando un indice è di grandi dimensioni, viene eseguito lo sharding 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:` `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 dell'algoritmo Tree-AH. Per saperne di più, consulta questo blog Scalabilità del recupero profondo con i motori per suggerimenti TensorFlow e la ricerca vettoriale `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`.

`DistanceMeasureType`

Enum
`SQUARED_L2_DISTANCE`	Distanza euclidea (L₂)
`L1_DISTANCE`	Distanza di Manhattan (L₁)
`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 + Asymmetric Hashing).

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`
	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 questo algoritmo, passa un oggetto vuoto per BruteForceConfig a algorithmConfig.

Requisiti dei dati di input

Carica il set di dati in una località di Cloud Storage. Assicurati che i file siano nel formato Righe JSON.

I file devono essere nel formato JSON Lines. Il seguente esempio è tratto dal blocco note 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 o la configurazione di Example di un modello. Ciò è utile se vuoi aggiornare il modello senza reindicizzare il relativo set di dati. Ad esempio, se l'indice del modello contiene 1000 istanze e vuoi aggiungere altre 500 istanze, puoi chiamare UpdateExplanationDataset per aggiungerle all'indice senza 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:

L'elemento model_id rimane invariato dopo l'operazione UpdateExplanationDataset.
L'operazione UpdateExplanationDataset interessa solo la risorsa Model. Non aggiorna i DeployedModel associati. Ciò significa che un indice di deployedModel contiene il set di dati al momento del deployment. Per aggiornare l'indice di deployedModel, devi eseguire nuovamente il deployment del modello aggiornato in un endpoint.

Sostituisci la configurazione per ricevere spiegazioni online

Quando richiedi una spiegazione, puoi eseguire al volo l'override di alcuni parametri specificando il campo ExplanationSpecOverride.

A seconda dell'applicazione, alcuni vincoli potrebbero essere auspicabili per il tipo di spiegazioni restituite. Ad esempio, per garantire una maggiore varietà di spiegazioni, un utente può specificare un parametro di crowding che impone che nessun singolo tipo di esempi sia sovrarappresentato nelle spiegazioni. Concretamente, se un utente sta cercando di capire perché un uccello è stato etichettato come piano dal suo modello, potrebbe non essere interessato 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 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 ammessi per le spiegazioni

La sezione Filtri 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 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.