Questa pagina mostra come ottenere previsioni e spiegazioni online (in tempo reale) dai tuoi modelli di classificazione o regressione tabulari utilizzando la console Google Cloud o l'API Vertex AI.
Una previsione online è una richiesta sincrona, anziché una previsione batch, che è una richiesta asincrona. Utilizza le previsioni online quando effettui richieste in risposta all'input dell'applicazione o in altre situazioni in cui richiedi un'inferenza tempestiva.
Devi eseguire il deployment di un modello su un endpoint prima che il modello possa essere utilizzato per fornire previsioni online. Il deployment di un modello associa risorse fisiche al modello, in modo che possa fornire previsioni online con bassa latenza.
Gli argomenti trattati sono:
- Deployment di un modello in un endpoint
- Ottieni una previsione online utilizzando il modello di cui hai eseguito il deployment
- Ricevi una spiegazione online utilizzando il modello di cui hai eseguito il deployment
Prima di iniziare
Prima di poter ottenere previsioni online, devi addestrare un modello di classificazione o regressione e evaluate per verificarne l'accuratezza.
esegui il deployment di un modello in un endpoint
Puoi eseguire il deployment di più modelli in un endpoint e di un modello su più endpoint. Per ulteriori informazioni sulle opzioni e sui casi d'uso per il deployment dei modelli, consulta Informazioni sul deployment dei modelli.
Utilizza uno dei seguenti metodi per eseguire il deployment di un modello:
Console Google Cloud
Nella console Google Cloud, nella sezione Vertex AI, vai alla pagina Modelli.
Fai clic sul nome del modello di cui vuoi eseguire il deployment per aprire la relativa pagina dei dettagli.
Seleziona la scheda Deployment e test.
Se è già stato eseguito il deployment del modello in eventuali endpoint, questi sono elencati nella sezione Deployment del modello.
Fai clic su Esegui il deployment nell'endpoint.
Nella pagina Definisci l'endpoint, configura come segue:
Puoi scegliere di eseguire il deployment del modello su un endpoint nuovo o esistente.
- Per eseguire il deployment del modello in un nuovo endpoint, seleziona Crea nuovo endpoint e specifica un nome per il nuovo endpoint.
- Per eseguire il deployment del modello in un endpoint esistente, seleziona Aggiungi a endpoint esistente e seleziona l'endpoint dall'elenco a discesa.
- Puoi aggiungere più di un modello a un endpoint e aggiungerlo a più di un endpoint. Ulteriori informazioni
Fai clic su Continua.
Nella pagina Impostazioni modello, configura come segue:
-
Se esegui il deployment del modello in un nuovo endpoint, accetta 100 per la suddivisione del traffico. Se stai eseguendo il deployment del tuo modello in un endpoint esistente in cui è stato eseguito il deployment di uno o più modelli, devi aggiornare la percentuale di Suddivisione traffico relativa al modello di cui stai eseguendo il deployment e ai modelli di cui è già stato eseguito il deployment, in modo che la somma di tutte le percentuali arrivi al 100%.
-
Inserisci il numero minimo di nodi di computing che vuoi fornire per il modello.
Questo è il numero di nodi disponibili per questo modello in qualsiasi momento. Ti vengono addebitati i nodi utilizzati, sia per gestire il carico di previsione sia per i nodi in standby (minimo), anche senza traffico di previsione. Consulta la pagina relativa ai prezzi.
-
Seleziona il Tipo di macchina.
L'utilizzo di risorse macchina di maggiori dimensioni incrementerà le prestazioni di previsione e aumenteranno i costi.
-
Scopri come modificare le impostazioni predefinite per il logging delle previsioni.
-
Fai clic su Continua.
-
Nella pagina Monitoraggio del modello, fai clic su Continua.
Nella pagina Obiettivi di Monitoring, configura come segue:
- Inserisci la località dei dati di addestramento.
- Inserisci il nome della colonna di destinazione.
Fai clic su Esegui il deployment per eseguire il deployment del modello nell'endpoint.
API
Quando esegui il deployment di un modello utilizzando l'API Vertex AI, devi completare questi passaggi:
- Se necessario, crea un endpoint.
- Recupera l'ID endpoint.
- Eseguire il deployment del modello nell'endpoint.
Creazione di un endpoint
Se esegui il deployment di un modello in un endpoint esistente, puoi saltare questo passaggio.
gcloud
Nell'esempio seguente viene utilizzato il comando gcloud ai endpoints create
:
gcloud ai endpoints create \
--region=LOCATION \
--display-name=ENDPOINT_NAME
Sostituisci quanto segue:
- LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
ENDPOINT_NAME: il nome visualizzato dell'endpoint.
Lo strumento Google Cloud CLI potrebbe richiedere alcuni secondi per creare l'endpoint.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- LOCATION_ID: la tua regione.
- PROJECT_ID: il tuo ID progetto.
- ENDPOINT_NAME: il nome visualizzato dell'endpoint.
Metodo HTTP e URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints
Corpo JSON della richiesta:
{ "display_name": "ENDPOINT_NAME" }
Per inviare la richiesta, espandi una delle seguenti opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateEndpointOperationMetadata", "genericMetadata": { "createTime": "2020-11-05T17:45:42.812656Z", "updateTime": "2020-11-05T17:45:42.812656Z" } } }
"done": true
.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
recupera l'ID endpoint
L'ID endpoint è necessario per eseguire il deployment del modello.
gcloud
Nell'esempio seguente viene utilizzato il comando gcloud ai endpoints list
:
gcloud ai endpoints list \
--region=LOCATION \
--filter=display_name=ENDPOINT_NAME
Sostituisci quanto segue:
- LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
ENDPOINT_NAME: il nome visualizzato dell'endpoint.
Prendi nota del numero visualizzato nella colonna
ENDPOINT_ID
. Utilizza questo ID nel passaggio successivo.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
- PROJECT_ID: il tuo ID progetto.
- ENDPOINT_NAME: il nome visualizzato dell'endpoint.
Metodo HTTP e URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME
Per inviare la richiesta, espandi una delle seguenti opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{ "endpoints": [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID", "displayName": "ENDPOINT_NAME", "etag": "AMEw9yPz5pf4PwBHbRWOGh0PcAxUdjbdX2Jm3QO_amguy3DbZGP5Oi_YUKRywIE-BtLx", "createTime": "2020-04-17T18:31:11.585169Z", "updateTime": "2020-04-17T18:35:08.568959Z" } ] }
Esegui il deployment del modello
Seleziona di seguito la scheda per la tua lingua o il tuo ambiente:
gcloud
Nei seguenti esempi viene utilizzato il comando gcloud ai endpoints deploy-model
.
L'esempio seguente esegue il deployment di Model
in un Endpoint
senza utilizzare GPU
per accelerare la fornitura delle previsioni e senza suddividere il traffico tra più
risorse DeployedModel
:
Prima di utilizzare qualsiasi dato di comando riportato di seguito, effettua le seguenti sostituzioni:
- ENDPOINT_ID: l'ID dell'endpoint.
- LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
- MODEL_ID: l'ID del modello di cui eseguire il deployment.
-
DEPLOYED_MODEL_NAME: un nome per
DeployedModel
. Puoi utilizzare anche il nome visualizzato diModel
perDeployedModel
. -
MACHINE_TYPE: facoltativo. Le risorse della macchina utilizzate per ogni nodo
di questo deployment. L'impostazione predefinita è
n1-standard-2
. Scopri di più sui tipi di macchina. -
MIN_REPLICA_COUNT: numero minimo di nodi per questo deployment.
Il numero di nodi può essere aumentato o diminuito in base al carico della previsione,
fino al numero massimo di nodi e mai inferiore a questo numero di nodi.
Questo valore deve essere maggiore o uguale a 1. Se il flag
--min-replica-count
viene omesso, il valore predefinito è 1. -
MAX_REPLICA_COUNT: il numero massimo di nodi per questo deployment.
Il conteggio dei nodi può essere aumentato o diminuito in base al carico della previsione fino a questo numero di nodi, ma mai inferiore al numero minimo di nodi.
Se ometti il flag
--max-replica-count
, il numero massimo di nodi viene impostato sul valore--min-replica-count
.
Esegui il comando gcloud ai Endpoints deploy-model:
Linux, macOS o Cloud Shell
gcloud ai endpoints deploy-model ENDPOINT_ID\ --region=LOCATION_ID \ --model=MODEL_ID \ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE \ --min-replica-count=MIN_REPLICA_COUNT \ --max-replica-count=MAX_REPLICA_COUNT \ --traffic-split=0=100
Windows (PowerShell)
gcloud ai endpoints deploy-model ENDPOINT_ID` --region=LOCATION_ID ` --model=MODEL_ID ` --display-name=DEPLOYED_MODEL_NAME ` --machine-type=MACHINE_TYPE ` --min-replica-count=MIN_REPLICA_COUNT ` --max-replica-count=MAX_REPLICA_COUNT ` --traffic-split=0=100
Windows (cmd.exe)
gcloud ai endpoints deploy-model ENDPOINT_ID^ --region=LOCATION_ID ^ --model=MODEL_ID ^ --display-name=DEPLOYED_MODEL_NAME ^ --machine-type=MACHINE_TYPE ^ --min-replica-count=MIN_REPLICA_COUNT ^ --max-replica-count=MAX_REPLICA_COUNT ^ --traffic-split=0=100
Suddivisione del traffico
Il flag --traffic-split=0=100
negli esempi precedenti invia il 100% del traffico di previsione
che Endpoint
riceve al nuovo DeployedModel
, rappresentato dall'ID temporaneo 0
. Se il tuo Endpoint
ha già altre
risorse di DeployedModel
, puoi suddividere il traffico tra il nuovo
DeployedModel
e quello precedente.
Ad esempio, per inviare il 20% del traffico al nuovo DeployedModel
e l'80% a uno precedente, esegui questo comando.
Prima di utilizzare qualsiasi dato di comando riportato di seguito, effettua le seguenti sostituzioni:
- OLD_DEPLOYED_MODEL_ID: l'ID dell'elemento
DeployedModel
esistente.
Esegui il comando gcloud ai Endpoints deploy-model:
Linux, macOS o Cloud Shell
gcloud ai endpoints deploy-model ENDPOINT_ID\ --region=LOCATION_ID \ --model=MODEL_ID \ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE \ --min-replica-count=MIN_REPLICA_COUNT \ --max-replica-count=MAX_REPLICA_COUNT \ --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
Windows (PowerShell)
gcloud ai endpoints deploy-model ENDPOINT_ID` --region=LOCATION_ID ` --model=MODEL_ID ` --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE ` --min-replica-count=MIN_REPLICA_COUNT ` --max-replica-count=MAX_REPLICA_COUNT ` --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
Windows (cmd.exe)
gcloud ai endpoints deploy-model ENDPOINT_ID^ --region=LOCATION_ID ^ --model=MODEL_ID ^ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE ^ --min-replica-count=MIN_REPLICA_COUNT ^ --max-replica-count=MAX_REPLICA_COUNT ^ --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
REST
Puoi utilizzare il metodo endpoints.predict per richiedere una previsione online.
Esegui il deployment del modello.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
- PROJECT_ID: il tuo ID progetto.
- ENDPOINT_ID: l'ID dell'endpoint.
- MODEL_ID: l'ID del modello di cui eseguire il deployment.
-
DEPLOYED_MODEL_NAME: un nome per
DeployedModel
. Puoi utilizzare anche il nome visualizzato diModel
perDeployedModel
. -
MACHINE_TYPE: facoltativo. Le risorse della macchina utilizzate per ogni nodo
di questo deployment. L'impostazione predefinita è
n1-standard-2
. Scopri di più sui tipi di macchina. - ACCELERATOR_TYPE: tipo di acceleratore da associare alla macchina. Facoltativo se ACCELERATOR_COUNT non è specificato o è pari a zero. Opzione non consigliata per i modelli AutoML o i modelli con addestramento personalizzato che utilizzano immagini non GPU. Scopri di più.
- ACCELERATOR_COUNT: il numero di acceleratori da utilizzare per ogni replica. Facoltativo. Deve essere zero o non specificato per i modelli AutoML o i modelli con addestramento personalizzato che utilizzano immagini non GPU.
- MIN_REPLICA_COUNT: numero minimo di nodi per questo deployment. Il numero di nodi può essere aumentato o diminuito in base al carico della previsione, fino al numero massimo di nodi e mai inferiore a questo numero di nodi. Questo valore deve essere maggiore o uguale a 1.
- MAX_REPLICA_COUNT: il numero massimo di nodi per questo deployment. Il conteggio dei nodi può essere aumentato o diminuito in base al carico della previsione fino a questo numero di nodi, ma mai inferiore al numero minimo di nodi.
- TRAFFIC_SPLIT_THIS_MODEL: la percentuale del traffico di previsione verso questo endpoint che verrà instradato al modello di cui viene eseguito il deployment con questa operazione. Il valore predefinito è 100. La somma di tutte le percentuali di traffico deve essere pari a 100. Scopri di più sulle suddivisioni del traffico.
- DEPLOYED_MODEL_ID_N: facoltativo. Se viene eseguito il deployment di altri modelli in questo endpoint, devi aggiornare le rispettive percentuali di suddivisione del traffico in modo che la somma di tutte le percentuali arrivi a 100.
- TRAFFIC_SPLIT_MODEL_N: il valore percentuale di suddivisione del traffico per la chiave dell'ID del modello di cui è stato eseguito il deployment.
- PROJECT_NUMBER: il numero di progetto generato automaticamente per il tuo progetto
Metodo HTTP e URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:deployModel
Corpo JSON della richiesta:
{ "deployedModel": { "model": "projects/PROJECT/locations/us-central1/models/MODEL_ID", "displayName": "DEPLOYED_MODEL_NAME", "dedicatedResources": { "machineSpec": { "machineType": "MACHINE_TYPE", "acceleratorType": "ACCELERATOR_TYPE", "acceleratorCount": "ACCELERATOR_COUNT" }, "minReplicaCount": MIN_REPLICA_COUNT, "maxReplicaCount": MAX_REPLICA_COUNT }, }, "trafficSplit": { "0": TRAFFIC_SPLIT_THIS_MODEL, "DEPLOYED_MODEL_ID_1": TRAFFIC_SPLIT_MODEL_1, "DEPLOYED_MODEL_ID_2": TRAFFIC_SPLIT_MODEL_2 }, }
Per inviare la richiesta, espandi una delle seguenti opzioni:
Dovresti ricevere una risposta JSON simile alla seguente:
{ "name": "projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployModelOperationMetadata", "genericMetadata": { "createTime": "2020-10-19T17:53:16.502088Z", "updateTime": "2020-10-19T17:53:16.502088Z" } } }
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Scopri come modificare le impostazioni predefinite per il logging delle previsioni.
Ottieni stato operazione
Alcune richieste avviano operazioni a lunga esecuzione il cui completamento richiede tempo. Queste richieste restituiscono un nome dell'operazione che puoi utilizzare per visualizzare lo stato dell'operazione o annullarla. Vertex AI offre metodi helper per effettuare chiamate su operazioni a lunga esecuzione. Per ulteriori informazioni, vedi Operazioni con le operazioni a lunga esecuzione.
Ottieni una previsione online utilizzando il modello di cui hai eseguito il deployment
Per fare una previsione online, invia uno o più elementi di test a un modello per l'analisi; il modello restituirà risultati basati sull'obiettivo del modello. Utilizza la console Google Cloud o l'API Vertex AI per richiedere una previsione online.
Console Google Cloud
Nella console Google Cloud, nella sezione Vertex AI, vai alla pagina Modelli.
Nell'elenco dei modelli, fai clic sul nome del modello da cui richiedere le previsioni.
Seleziona la scheda Deployment e test.
Nella sezione Testa il modello, aggiungi elementi di test per richiedere una previsione. I dati di previsione di base vengono compilati automaticamente oppure puoi inserire i tuoi dati di previsione e fare clic su Prevedi.
Una volta completata la previsione, Vertex AI restituisce i risultati nella console.
API: classificazione
gcloud
-
Crea un file denominato
request.json
con il seguente contenuto:{ "instances": [ { PREDICTION_DATA_ROW } ] }
Sostituisci quanto segue:
-
PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi e valori delle caratteristiche come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe essere simile alla seguente richiesta di esempio:
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzato per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le previsioni.
-
-
Esegui questo comando:
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Sostituisci quanto segue:
- ENDPOINT_ID: l'ID dell'endpoint.
- LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
REST
Puoi utilizzare il metodo endpoints.predict per richiedere una previsione online.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
-
LOCATION_ID: regione in cui si trova l'endpoint. Ad esempio,
us-central1
. - PROJECT_ID: il tuo ID progetto.
- ENDPOINT_ID: l'ID dell'endpoint.
-
PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi e valori delle caratteristiche come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe essere simile alla seguente richiesta di esempio:
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzato per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le previsioni.
- DEPLOYED_MODEL_ID: viene generato dal metodo
predict
e accettato come input dal metodoexplain
. L'ID del modello utilizzato per generare la previsione. Se hai bisogno di richiedere spiegazioni per una previsione richiesta in precedenza e hai eseguito il deployment di più modelli, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per lo stesso modello che ha fornito la previsione precedente.
Metodo HTTP e URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict
Corpo JSON della richiesta:
{ "instances": [ { PREDICTION_DATA_ROW } ] }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"
PowerShell
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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente:
{ "predictions": [ { "scores": [ 0.96771615743637085, 0.032283786684274673 ], "classes": [ "0", "1" ] } ] "deployedModelId": "2429510197" }
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
API: regressione
gcloud
-
Crea un file denominato "request.json" con i seguenti contenuti:
{ "instances": [ { PREDICTION_DATA_ROW } ] }
Sostituisci quanto segue:
-
PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi e valori delle caratteristiche come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati che contiene un numero, un array di numeri e una categoria, la riga di dati potrebbe essere simile alla seguente richiesta di esempio:
"age":3.6, "sq_ft":5392, "code": "90331"
È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzato per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le previsioni.
-
-
Esegui questo comando:
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Sostituisci quanto segue:
- ENDPOINT_ID: l'ID dell'endpoint.
- LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
REST
Puoi utilizzare il metodo endpoints.predict per richiedere una previsione online.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
-
LOCATION_ID: regione in cui si trova l'endpoint. Ad esempio,
us-central1
. - PROJECT_ID: il tuo ID progetto.
- ENDPOINT_ID: l'ID dell'endpoint.
-
PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi e valori delle caratteristiche come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati che contiene un numero, un array di numeri e una categoria, la riga di dati potrebbe essere simile alla seguente richiesta di esempio:
"age":3.6, "sq_ft":5392, "code": "90331"
È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzato per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le previsioni.
- DEPLOYED_MODEL_ID: viene generato dal metodo
predict
e accettato come input dal metodoexplain
. L'ID del modello utilizzato per generare la previsione. Se hai bisogno di richiedere spiegazioni per una previsione richiesta in precedenza e hai eseguito il deployment di più modelli, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per lo stesso modello che ha fornito la previsione precedente.
Metodo HTTP e URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict
Corpo JSON della richiesta:
{ "instances": [ { PREDICTION_DATA_ROW } ] }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"
PowerShell
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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente:
{ "predictions": [ [ { "value": 65.14233, "lower_bound": 4.6572, "upper_bound": 164.0279 } ] ], "deployedModelId": "DEPLOYED_MODEL_ID" }
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di Vertex AI sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Vertex AI.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
Interpretare i risultati delle previsioni
Classificazione
I modelli di classificazione restituiscono un punteggio di confidenza.
Il punteggio di confidenza indica il livello di associazione del modello a ogni classe o etichetta a un elemento di test. Più elevato è il numero, maggiore è la confidenza del modello che l'etichetta debba essere applicata a quell'elemento. Sei tu a decidere quanto deve essere alto il punteggio di confidenza affinché tu possa accettare i risultati del modello.
Regressione
I modelli di regressione restituiscono un valore di previsione. Per le destinazioni BigQuery, viene restituito anche un intervallo di previsione. L'intervallo di previsione fornisce un intervallo di valori di cui il modello ha una confidenza del 95% contengono il risultato effettivo.
Ricevi una spiegazione online utilizzando il modello di cui hai eseguito il deployment
Puoi richiedere una previsione con spiegazioni (chiamate anche attribuzioni delle caratteristiche) per vedere in che modo il tuo modello ha arrivato a una previsione. I valori di importanza delle caratteristiche locali indicano in che misura ogni caratteristica ha contribuito al risultato della previsione. Le attribuzioni delle caratteristiche sono incluse nelle previsioni di Vertex AI tramite Vertex Explainable AI.
Console
Quando utilizzi la console Google Cloud per richiedere una previsione online, i valori di importanza delle caratteristiche locali vengono restituiti automaticamente.
Se hai utilizzato i valori di previsione precompilati, i valori di importanza delle caratteristiche locali sono tutti pari a zero. Questo perché i valori precompilati sono i dati di previsione di riferimento, quindi la previsione restituita è il valore di previsione di riferimento.
gcloud
Crea un file denominato
request.json
con il seguente contenuto:{ "instances": [ { PREDICTION_DATA_ROW } ] }
Sostituisci quanto segue:
-
PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi e valori delle caratteristiche come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe essere simile alla seguente richiesta di esempio:
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzato per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le previsioni.
-
Esegui questo comando:
gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
Sostituisci quanto segue:
- ENDPOINT_ID: l'ID dell'endpoint.
- LOCATION_ID: la regione in cui stai utilizzando Vertex AI.
Se vuoi inviare una richiesta di spiegazione a un elemento
DeployedModel
specifico inEndpoint
, puoi specificare il flag--deployed-model-id
:gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION \ --deployed-model-id=DEPLOYED_MODEL_ID \ --json-request=request.json
Oltre ai segnaposto descritti in precedenza, sostituisci quanto segue:
-
DEPLOYED_MODEL_ID Facoltativo: l'ID del modello di cui hai eseguito il deployment per il quale vuoi ottenere
spiegazioni. L'ID è incluso nella risposta del metodo
predict
. Se devi richiedere spiegazioni per un determinato modello e hai eseguito il deployment di più modelli nello stesso endpoint, puoi utilizzare questo ID per assicurarti che vengano restituite le spiegazioni per quel determinato modello.
REST
L'esempio seguente mostra una richiesta di previsione online per un modello di classificazione tabulare con attribuzioni di caratteristiche locali. Il formato della richiesta è lo stesso per i modelli di regressione.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
-
LOCATION: regione in cui si trova l'endpoint. Ad esempio,
us-central1
. - PROJECT: il tuo ID progetto.
- ENDPOINT_ID: l'ID dell'endpoint.
-
PREDICTION_DATA_ROW: un oggetto JSON con chiavi come nomi e valori delle caratteristiche come valori delle caratteristiche corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe essere simile alla seguente richiesta di esempio:
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
È necessario fornire un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzato per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per maggiori dettagli, consulta Formato dei dati per le previsioni.
-
(Facoltativo) DEPLOYED_MODEL_ID: l'ID del modello di cui hai eseguito il deployment per il quale vuoi ricevere
spiegazioni. L'ID è incluso nella risposta del metodo
predict
. Se devi richiedere spiegazioni per un determinato modello e hai eseguito il deployment di più modelli nello stesso endpoint, puoi utilizzare questo ID per assicurarti che vengano restituite le spiegazioni per quel determinato modello.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain
Corpo JSON della richiesta:
{ "instances": [ { PREDICTION_DATA_ROW } ], "deployedModelId": "DEPLOYED_MODEL_ID" }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
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/endpoints/ENDPOINT_ID:explain"
PowerShell
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/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, vedi Installare l'SDK Vertex AI per Python. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python.
Ottenere spiegazioni per una previsione restituita in precedenza
Poiché le spiegazioni aumentano l'utilizzo delle risorse, ti consigliamo di prenotare le spiegazioni richieste per situazioni in cui ne hai bisogno in modo specifico. A volte può essere utile richiedere spiegazioni su un risultato di previsione che hai già ricevuto, magari perché la previsione era un'anomalia o non aveva senso.
Se tutte le previsioni provengono dallo stesso modello, puoi semplicemente inviare nuovamente
i dati della richiesta con le spiegazioni richieste questa volta. Tuttavia, se hai più modelli che restituiscono previsioni, devi assicurarti di inviare la richiesta di spiegazione al modello corretto. Puoi visualizzare le spiegazioni per un determinato modello includendo nella tua richiesta l'ID deployedModelID
del modello di cui hai eseguito il deployment, incluso nella risposta della richiesta di previsione originale.
Tieni presente che l'ID del modello di cui è stato eseguito il deployment è diverso dall'ID modello.
Interpretare i risultati della spiegazione
Per calcolare l'importanza delle caratteristiche locali, viene innanzitutto calcolato il punteggio di previsione di riferimento. I valori di riferimento vengono calcolati dai dati di addestramento, utilizzando il valore mediano per le caratteristiche numeriche e la modalità per le caratteristiche categoriche. La previsione generata dai valori di riferimento è il punteggio di previsione di riferimento. I valori di riferimento vengono calcolati una volta sola per un modello e non cambiano.
Per una previsione specifica, l'importanza delle caratteristiche locali per ogni caratteristica indica in che misura la caratteristica è stata aggiunta o sottratta dal risultato rispetto al punteggio della previsione di riferimento. La somma di tutti i valori di importanza delle caratteristiche equivale alla differenza tra il punteggio della previsione di riferimento e il risultato della previsione.
Per i modelli di classificazione, il punteggio è sempre compreso tra 0,0 e 1,0 inclusi. Pertanto, i valori di importanza delle caratteristiche locali per i modelli di classificazione sono sempre compresi tra -1,0 e 1,0 (inclusi).
Per esempi di query di attribuzione delle caratteristiche e per saperne di più, consulta Attribuzioni delle caratteristiche per la classificazione e la regressione.Output di esempio per previsioni e spiegazioni
Classificazione
Il payload restituito per una previsione online da un modello di classificazione tabulare con importanza delle caratteristiche è simile all'esempio seguente.
instanceOutputValue
di 0.928652400970459
è il
punteggio di affidabilità della classe con il punteggio più alto, in questo caso class_a
. Il campo baselineOutputValue
contiene il punteggio di previsione di riferimento, 0.808652400970459
. La funzionalità che ha contribuito maggiormente a questo risultato è stata feature_3
.
{
"predictions": [
{
"scores": [
0.928652400970459,
0.071347599029541
],
"classes": [
"class_a",
"class_b"
]
}
]
"explanations": [
{
"attributions": [
{
"baselineOutputValue": 0.808652400970459,
"instanceOutputValue": 0.928652400970459,
"approximationError": 0.0058915703929231,
"featureAttributions": {
"feature_1": 0.012394922231235,
"feature_2": 0.050212341234556,
"feature_3": 0.057392736534209,
},
"outputIndex": [
0
],
"outputName": "scores"
}
],
}
]
"deployedModelId": "234567"
}
Regressione
Il payload restituito per una previsione online con importanza delle caratteristiche da un modello di regressione tabulare è simile all'esempio seguente.
instanceOutputValue
di 1795.1246466281819
è il valore previsto, con i campi lower_bound
e upper_bound
che forniscono un intervallo di confidenza del 95%.
Il campo baselineOutputValue
contiene il punteggio di previsione di riferimento, 1788.7423095703125
. La funzionalità che ha contribuito maggiormente a questo risultato è stata feature_3
.
{
"predictions": [
{
"value": 1795.1246466281819,
"lower_bound": 246.32196807861328,
"upper_bound": 8677.51904296875
}
]
"explanations": [
{
"attributions": [
{
"baselineOutputValue": 1788.7423095703125,
"instanceOutputValue": 1795.1246466281819,
"approximationError": 0.0038215703911553,
"featureAttributions": {
"feature_1": 0.123949222312359,
"feature_2": 0.802123412345569,
"feature_3": 5.456264423211472,
},
"outputIndex": [
-1
]
}
]
}
],
"deployedModelId": "345678"
}
Passaggi successivi
- Scopri come esportare il modello.