Questa pagina mostra come ottenere spiegazioni e previsioni online (in tempo reale) dai modelli di classificazione o regressione tabulari utilizzando la console Google Cloud o l'API Vertex AI.
Una previsione online è una richiesta sincrona, mentre una previsione batch è una richiesta asincrona. Utilizza le previsioni online quando effettui richieste in risposta all'input dell'applicazione o in altre situazioni in cui hai bisogno di un'inferenza tempestiva.
Devi eseguire il deployment di un modello in un endpoint prima di poterlo usare 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:
- Eseguire il deployment di un modello in un endpoint
- Ottieni una previsione online utilizzando il modello di cui è stato eseguito il deployment
- Ottieni una spiegazione online utilizzando il modello di cui è stato eseguito il deployment
Prima di iniziare
Prima di poter ottenere previsioni online, devi prima addestrare un modello di classificazione o regressione e valutarlo per verificarne l'accuratezza.
Eseguire il deployment di un modello in un endpoint
Puoi eseguire il deployment di più modelli in un endpoint e puoi eseguire il deployment di un modello in più di un endpoint. Per ulteriori informazioni sulle opzioni e sui casi d'uso per il deployment dei modelli, consulta Informazioni sul deployment dei modelli.
Per eseguire il deployment di un modello, utilizza uno dei seguenti metodi:
Console Google Cloud
Nella console Google Cloud, nella sezione Vertex AI, vai alla pagina Modelli.
Fai clic sul nome del modello che vuoi implementare per aprire la relativa pagina dei dettagli.
Seleziona la scheda Deployment e test.
Se il modello è già stato implementato in uno o più endpoint, questi sono elencati nella sezione Esegui il deployment del modello.
Fai clic su Esegui il deployment nell'endpoint.
Nella pagina Definisci il tuo 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 fornisci 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 un modello a più endpoint. Scopri di più.
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 esegui il deployment del modello in un endpoint esistente in cui sono già stati dipiamente uno o più modelli, devi aggiornare la percentuale di Suddivisione traffico per il modello di cui stai eseguendo il deployment e per i modelli già dipiamente in modo che tutte le percentuali sommino al 100%.
-
Inserisci il numero minimo di nodi di calcolo che vuoi fornire per il tuo modello.
Si tratta del 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 di riserva (minimi), anche senza traffico di previsione. Consulta la pagina dei prezzi.
-
Seleziona il tipo di macchina.
Risorse di macchine più grandi aumenteranno le prestazioni di previsione e i costi.
-
Scopri come modificare le impostazioni predefinite per la registrazione delle previsioni.
-
Fai clic su Continua.
-
Nella pagina Monitoraggio del modello, fai clic su Continua.
Nella pagina Scopi del monitoraggio, configura come segue:
- Inserisci la posizione 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, completa i seguenti passaggi:
- Crea un endpoint, se necessario.
- Recupera l'ID endpoint.
- Esegui il deployment del modello nell'endpoint.
Creazione di un endpoint
Se stai eseguendo il deployment di un modello in un endpoint esistente, puoi saltare questo passaggio.
gcloud
L'esempio seguente utilizza 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 utilizzi 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, apporta 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 di queste 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 di configurazione Java riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Vertex AI.
Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js di Vertex AI.
Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.
Recuperare l'ID endpoint
Per eseguire il deployment del modello, devi disporre dell'ID endpoint.
gcloud
L'esempio seguente utilizza 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 utilizzi 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, apporta le seguenti sostituzioni:
- LOCATION_ID: la regione in cui utilizzi 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 di queste 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 la scheda di seguito per la tua lingua o il tuo ambiente:
gcloud
I seguenti esempi utilizzano il comando gcloud ai endpoints deploy-model
.
L'esempio seguente esegue il deployment di un Model
in un Endpoint
senza utilizzare GPU per accelerare l'invio di previsioni e senza suddividere il traffico tra più risorse DeployedModel
:
Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
- ENDPOINT_ID: l'ID dell'endpoint.
- LOCATION_ID: la regione in cui utilizzi Vertex AI.
- MODEL_ID: l'ID del modello da implementare.
-
DEPLOYED_MODEL_NAME: un nome per il
DeployedModel
. Puoi utilizzare il nome visualizzato delModel
anche 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 macchine. -
MIN_REPLICA_COUNT: il 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 meno di questo numero.
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 numero di nodi può essere aumentato o diminuito in base al carico della previsione, fino a questo numero di nodi e mai inferiore al numero minimo di nodi.
Se il flag
--max-replica-count
viene omesso, il numero massimo di nodi viene impostato sul valore di--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 ricevuto da Endpoint
al nuovo DeployedModel
, rappresentato dall'ID temporaneo 0
. Se il tuo Endpoint
ha già altre risorseDeployedModel
, puoi suddividere il traffico tra il nuovoDeployedModel
e quello precedente.
Ad esempio, per inviare il 20% del traffico al nuovo DeployedModel
e l'80% a uno precedente,
esegui il seguente comando.
Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
- OLD_DEPLOYED_MODEL_ID: l'ID del
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
Utilizza il metodo endpoints.predict per richiedere una previsione online.
Esegui il deployment del modello.
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- LOCATION_ID: la regione in cui utilizzi Vertex AI.
- PROJECT_ID: il tuo ID progetto.
- ENDPOINT_ID: l'ID dell'endpoint.
- MODEL_ID: l'ID del modello da implementare.
-
DEPLOYED_MODEL_NAME: un nome per il
DeployedModel
. Puoi utilizzare il nome visualizzato delModel
anche 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 macchine. - ACCELERATOR_TYPE: il tipo di acceleratore da collegare alla macchina. Facoltativo se ACCELERATOR_COUNT non è specificato o è pari a zero. Non consigliato per i modelli AutoML o 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 pari a zero o non specificato per i modelli AutoML o con addestramento personalizzato che utilizzano immagini non GPU.
- MIN_REPLICA_COUNT: il 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 meno di questo numero. Questo valore deve essere maggiore o uguale a 1.
- MAX_REPLICA_COUNT: il numero massimo di nodi per questo deployment. Il numero di nodi può essere aumentato o diminuito in base al carico della previsione, fino a questo numero di nodi e mai inferiore al numero minimo di nodi.
- TRAFFIC_SPLIT_THIS_MODEL: la percentuale del traffico di previsione per questo endpoint da inoltrare 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 al 100%. Scopri di più sulle suddivisioni del traffico.
- DEPLOYED_MODEL_ID_N: facoltativo. Se in questo endpoint sono di cui è stato eseguito il deployment di altri modelli, devi aggiornare le relative percentuali di suddivisione del traffico in modo che tutte le percentuali sommate diano 100.
- TRAFFIC_SPLIT_MODEL_N: il valore percentuale della suddivisione del traffico per la chiave ID modello di cui è stato eseguito il deployment.
- PROJECT_NUMBER: il numero di progetto generato automaticamente del 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 di queste 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 di configurazione Java riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Vertex AI.
Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js di Vertex AI.
Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Scopri come modificare le impostazioni predefinite per la registrazione delle previsioni.
Recupera lo stato dell'operazione
Alcune richieste avviano operazioni a lunga esecuzione che richiedono tempo per essere completate. Queste richieste restituiscono un nome dell'operazione, che puoi utilizzare per visualizzarne lo stato o annullarla. Vertex AI fornisce metodi di assistenza per effettuare chiamate a operazioni di lunga durata. Per ulteriori informazioni, consulta Utilizzo delle operazioni di lunga durata.
Ottenere una previsione online utilizzando il modello di cui è stato eseguito il deployment
Per fare una previsione online, invia uno o più elementi di test a un modello per analizzarli e il modello restituisce risultati in base al suo scopo. Utilizza la console Google Cloud o l'API Vertex AI per richiedere una predizione 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 tuo modello, aggiungi elementi di test per richiedere una previsione. I dati di previsione di riferimento vengono compilati automaticamente oppure puoi inserire i tuoi dati di previsione e fare clic su Prevedi.
Al termine della previsione, Vertex AI restituisce i risultati nella console.
API: classificazione
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 le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe avere il seguente aspetto:
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
È obbligatorio specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per informazioni dettagliate, 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 utilizzi Vertex AI.
REST
Utilizza il metodo endpoints.predict per richiedere una previsione online.
Prima di utilizzare i dati della richiesta, apporta 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 le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe avere il seguente aspetto:
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
È obbligatorio specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per informazioni dettagliate, consulta Formato dei dati per le previsioni.
- DEPLOYED_MODEL_ID: output del metodo
predict
e accettato come input dal metodoexplain
. L'ID del modello utilizzato per generare la previsione. Se devi richiedere spiegazioni per una previsione richiesta in precedenza e hai implementato più di un modello, 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
,
quindi esegui il comando seguente:
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
,
quindi esegui il comando seguente:
$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 di configurazione Java riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Vertex AI.
Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js di Vertex AI.
Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, 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 le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di numeri e una categoria, la riga di dati potrebbe avere il seguente aspetto:
"age":3.6, "sq_ft":5392, "code": "90331"
È obbligatorio specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per informazioni dettagliate, 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 utilizzi Vertex AI.
REST
Utilizza il metodo endpoints.predict per richiedere una previsione online.
Prima di utilizzare i dati della richiesta, apporta 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 le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di numeri e una categoria, la riga di dati potrebbe avere il seguente aspetto:
"age":3.6, "sq_ft":5392, "code": "90331"
È obbligatorio specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per informazioni dettagliate, consulta Formato dei dati per le previsioni.
- DEPLOYED_MODEL_ID: output del metodo
predict
e accettato come input dal metodoexplain
. L'ID del modello utilizzato per generare la previsione. Se devi richiedere spiegazioni per una previsione richiesta in precedenza, e hai implementato più di un modello, 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
,
quindi esegui il comando seguente:
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
,
quindi esegui il comando seguente:
$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 di configurazione Java riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Vertex AI.
Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js di Vertex AI.
Per autenticarti in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.
Interpreta i risultati della previsione
Classificazione
I modelli di classificazione restituiscono un punteggio di affidabilità.
Il punteggio di confidenza indica quanto il modello associa ciascuna classe o etichetta a un elemento di test. Più alto è il numero, maggiore è la certezza del modello che l'etichetta debba essere applicata a quell'elemento. Sei tu a decidere quanto deve essere alto il punteggio di affidabilità per accettare i risultati del modello.
Regressione
I modelli di regressione restituiscono un valore di previsione. Per le destinazioni BigQuery, inoltre, restituisce un intervallo di previsione. L'intervallo di previsione fornisce un intervallo di valori che il modello ritiene con una probabilità del 95% contenere il risultato effettivo.
Ottenere una spiegazione online utilizzando il modello di cui è stato eseguito il deployment
Puoi richiedere una previsione con spiegazioni (chiamate anche attribuzioni delle caratteristiche) per vedere in che modo il modello è arrivato a una previsione. I valori di importanza delle caratteristiche locali indicano in che misura ciascuna 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 dell'importanza delle funzionalità locali vengono restituiti automaticamente.
Se hai utilizzato i valori di previsione precompilati, i valori dell'importanza delle funzionalità 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 i seguenti contenuti:{ "instances": [ { PREDICTION_DATA_ROW } ] }
Sostituisci quanto segue:
-
PREDICTION_DATA_ROW: un oggetto JSON con le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe avere il seguente aspetto:
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
È necessario specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per informazioni dettagliate, 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 utilizzi Vertex AI.
Se vuoi, puoi inviare una richiesta di spiegazione a un
DeployedModel
specifico suEndpoint
specificando 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 vuoi ricevere le spiegazioni. L'ID è incluso nella risposta del metodo
predict
. Se devi richiedere spiegazioni per un determinato modello e hai più modelli di cui è stato eseguito il deployment nello stesso endpoint, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite per quel determinato modello.
REST
L'esempio riportato di seguito mostra una richiesta di previsione online per un modello di classificazione tabulare con attribuzioni delle caratteristiche locali. Il formato della richiesta è lo stesso per i modelli di regressione.
Prima di utilizzare i dati della richiesta, apporta 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 le chiavi come nomi delle funzionalità e i valori come valori delle funzionalità corrispondenti. Ad esempio, per un set di dati con un numero, un array di stringhe e una categoria, la riga di dati potrebbe avere il seguente aspetto:
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
È obbligatorio specificare un valore per ogni caratteristica inclusa nell'addestramento. Il formato dei dati utilizzati per la previsione deve corrispondere a quello utilizzato per l'addestramento. Per informazioni dettagliate, consulta Formato dei dati per le previsioni.
-
DEPLOYED_MODEL_ID (facoltativo): l'ID del modello di cui vuoi ottenere le spiegazioni. L'ID è incluso nella risposta del metodo
predict
. Se devi richiedere spiegazioni per un determinato modello e hai più di un modello di cui è stato eseguito il deployment nello stesso endpoint, puoi utilizzare questo ID per assicurarti che le spiegazioni vengano restituite 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
,
quindi esegui il comando seguente:
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
,
quindi esegui il comando seguente:
$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, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.
Ricevere spiegazioni per una previsione restituita in precedenza
Poiché le spiegazioni aumentano l'utilizzo delle risorse, ti consigliamo di richiederle solo quando ne hai bisogno. A volte può essere utile richiedere spiegazioni per un risultato di previsione che hai già ricevuto, ad esempio perché la previsione era un outlier o non aveva senso.
Se tutte le previsioni provengono dallo stesso modello, puoi semplicemente inviare nuovamente i dati della richiesta, questa volta con le spiegazioni richieste. 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 l'ID deployedModelID
del modello di cui è stato eseguito il deployment nella richiesta, che è incluso nella risposta della richiesta di previsione originale.
Tieni presente che l'ID modello di cui è stato eseguito il deployment è diverso dall'ID modello.
Interpreta i risultati della spiegazione
Per calcolare l'importanza delle caratteristiche locali, viene prima calcolato il punteggio di previsione di riferimento. I valori di riferimento vengono calcolati dai dati di addestramento, utilizzando il valore mediano per le funzionalità numeriche e la modalità per le funzionalità categoriche. La previsione generata dai valori di riferimento è il punteggio di previsione di riferimento. I valori di riferimento vengono calcolati una volta per un modello e non cambiano.
Per una previsione specifica, l'importanza locale della caratteristica per ogni caratteristica indica quanto la caratteristica ha aggiunto o sottratto al risultato rispetto al punteggio di previsione di riferimento. La somma di tutti i valori dell'importanza delle caratteristiche è uguale alla differenza tra il punteggio di previsione di riferimento e il risultato della previsione.
Per i modelli di classificazione, il punteggio è sempre compreso tra 0,0 e 1,0, compreso. 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 funzionalità e per scoprire di più, consulta Attribuzione delle funzionalità per la classificazione e la regressione.Esempio di output per previsioni e spiegazioni
Classificazione
Il payload restituito per una previsione online da un modello di classificazione tabulare con importanza delle caratteristiche è simile a questo esempio.
Il 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 caratteristica che ha contribuito maggiormente a questo risultato è 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 a questo esempio.
instanceOutputValue
di 1795.1246466281819
è il valore previsto, mentre i campi lower_bound
e upper_bound
forniscono l'intervallo di confidenza del 95%.
Il campo baselineOutputValue
contiene il
punteggio di previsione di riferimento, 1788.7423095703125
. La caratteristica che ha contribuito maggiormente a questo risultato è 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.