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

1. 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.

2. 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.

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

DistanceMeasureType

FeatureNormType

TreeAhConfig

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

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 aggiungere elementi 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; 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 seguente tabella riassume i parametri che possono essere ignorati per una richiesta di spiegazione basata su esempi:

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.