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 batch, in quanto non sono supportate.

Questa pagina descrive come configurare e aggiornare queste opzioni.

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

Prima di iniziare, assicurati di disporre di quanto segue:

1. Una posizione Cloud Storage che contiene gli artefatti del modello. Il modello deve essere un modello basato su rete neurale profonda (DNN) in cui fornisci il nome di un livello o di una 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 degli esempi utilizzati per generare spiegazioni.

2. Un percorso Cloud Storage che contiene le istanze da indicizzare per la ricerca approssimativa del vicino più prossimo. Per ulteriori informazioni, consulta i requisiti dei dati di input.

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

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

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

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

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

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"

$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

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

gcloud ai operations describe <operation-id>

NearestNeighborSearchConfig

Il seguente corpo della richiesta JSON mostra come specificare l'intero 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": { ... }
    }
  }
}

Queste tabelle elencano i campi per NearestNeighborSearchConfig.

DistanceMeasureType

FeatureNormType

TreeAhConfig

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

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

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 delle spiegazioni basate 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 ti consente di aggiornare l'indice dei vicini più prossimi di un modello o la configurazione di Example. Questa operazione è utile se vuoi aggiornare il modello senza reindicizzare il 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 delle spiegazioni:

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 e non aggiorna alcun DeployedModel associato. Ciò significa che l'indice di un deployedModel contiene il set di dati al momento del deployment. Per aggiornare l'indice di un deployedModel, devi eseguire nuovamente il deployment del modello aggiornato in un endpoint.

Ignorare la configurazione quando si ottengono spiegazioni online

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

A seconda dell'applicazione, alcune limitazioni potrebbero essere auspicabili per il tipo di spiegazioni restituite. Ad esempio, per garantire la diversità delle spiegazioni, un utente può specificare un parametro di affollamento che stabilisce che nessun tipo di esempi sia sovra rappresentato nelle spiegazioni. In concreto, 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 seguente tabella riepiloga i parametri che possono essere sostituiti per una richiesta di spiegazione basata su esempi:

La sezione Filtro di Vector Search descrive questi parametri in modo più dettagliato.

Ecco un esempio di corpo della 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 ottieni 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.