Questa pagina mostra come ottenere previsioni online (in tempo reale) dai modelli personalizzati addestrati utilizzando la console Google Cloud o l'API Vertex AI.
Formattare l'input per la previsione online
Questa sezione mostra come formattare e codificare le istanze di input di previsione come
JSON, che è obbligatorio se utilizzi il metodo
predict
o explain
. Questo passaggio non è necessario se utilizzi il metodo rawPredict
. Per informazioni su quale metodo scegliere, consulta la sezione Inviare richiesta all'endpoint.
Se utilizzi l'SDK Vertex AI per Python per inviare richieste di previsione, specifica
l'elenco di istanze senza il campo instances
. Ad esempio, specifica [
["the","quick","brown"], ... ]
anziché { "instances": [
["the","quick","brown"], ... ] }
.
Se il modello utilizza un container personalizzato, il dato di input deve essere formattato come JSON ed è presente un campo parameters
aggiuntivo che può essere utilizzato per il container. Scopri di più su come formattare l'input di previsione con i container personalizzati.
Formatta le istanze come stringhe JSON
Il formato di base per la previsione online è un elenco di istanze di dati. Possono essere elenchi di valori semplici o membri di un oggetto JSON, a seconda di come hai configurato gli input nell'applicazione di addestramento. I modelli TensorFlow possono accettare input più complessi, mentre la maggior parte dei modelli scikit-learn e XGBoost si aspetta un elenco di numeri come input.
Questo esempio mostra un tensore di input e una chiave di istanza per un modello TensorFlow:
{"values": [1, 2, 3, 4], "key": 1}
La composizione della stringa JSON può essere complessa, purché segua queste regole:
Il livello superiore dei dati dell'istanza deve essere un oggetto JSON: un dizionario di coppie chiave-valore.
I singoli valori in un oggetto istanza possono essere stringhe, numeri o elenchi. Non puoi incorporare oggetti JSON.
Gli elenchi devono contenere solo elementi dello stesso tipo (inclusi altri elenchi). Non puoi mescolare valori numerici e di stringa.
Le istanze di input per la previsione online vengono passate come corpo del messaggio per la chiamataprojects.locations.endpoints.predict
. Scopri di più sui requisiti di formattazione del corpo della richiesta.
Rendi ogni istanza un elemento di un array JSON e fornisci l'array come campo instances
di un oggetto JSON. Ad esempio:
{"instances": [
{"values": [1, 2, 3, 4], "key": 1},
{"values": [5, 6, 7, 8], "key": 2}
]}
Codifica dei dati binari per l'input di previsione
I dati binari non possono essere formattati come stringhe con codifica UTF-8 supportate da JSON. Se gli input contengono dati binari, devi utilizzare la codifica base64 per rappresentarli. È obbligatoria la seguente formattazione speciale:
La stringa codificata deve essere formattata come oggetto JSON con una singola chiave chiamata
b64
. In Python 3, la codifica base64 restituisce una sequenza di byte. Devi convertire questo valore in una stringa per renderlo serializzabile in JSON:{'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
Nel codice del modello TensorFlow, devi assegnare un nome agli alias per i tensori di input e di output binari in modo che terminino con "_bytes".
Esempi di richieste e risposte
Questa sezione descrive il formato del corpo della richiesta di previsione e del corpo della risposta, con esempi per TensorFlow, scikit-learn e XGBoost.
Dettagli del corpo della richiesta
TensorFlow
Il corpo della richiesta contiene dati con la seguente struttura (rappresentazione JSON):
{
"instances": [
<value>|<simple/nested list>|<object>,
...
]
}
L'oggetto instances[]
è obbligatorio e deve contenere l'elenco delle istanze per le quali ottenere le previsioni.
La struttura di ogni elemento dell'elenco di istanze è determinata dalla definizione di input del modello. Le istanze possono includere input denominati (come oggetti) o contenere solo valori non etichettati.
Non tutti i dati includono input denominati. Alcune istanze sono semplici valori JSON (booleani, numeri o stringhe). Tuttavia, le istanze sono spesso elenchi di valori semplici o elenchi nidificati complessi.
Di seguito sono riportati alcuni esempi di corpo della richiesta.
Dati CSV con ogni riga codificata come valore di stringa:
{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}
Testo normale:
{"instances": ["the quick brown fox", "the lazy dog"]}
Frasi codificate come elenchi di parole (vettori di stringhe):
{ "instances": [ ["the","quick","brown"], ["the","lazy","dog"], ... ] }
Valori scalari in virgola mobile:
{"instances": [0.0, 1.1, 2.2]}
Vettori di numeri interi:
{ "instances": [ [0, 1, 2], [3, 4, 5], ... ] }
Tensori (in questo caso, tensori bidimensionali):
{ "instances": [ [ [0, 1, 2], [3, 4, 5] ], ... ] }
Immagini, che possono essere rappresentate in diversi modi. In questo schema di codifica le prime due dimensioni rappresentano le righe e le colonne dell'immagine e la terza dimensione contiene gli elenchi (vettori) dei valori R, G e B per ogni pixel:
{ "instances": [ [ [ [138, 30, 66], [130, 20, 56], ... ], [ [126, 38, 61], [122, 24, 57], ... ], ... ], ... ] }
Codifica dei dati
Le stringhe JSON devono essere codificate in UTF-8. Per inviare dati binari, devi codificarli in base64 e contrassegnarli come binari. Per contrassegnare una stringa JSON come
binaria, sostituiscila con un oggetto JSON con un singolo attributo denominato
b64
:
{"b64": "..."}
L'esempio seguente mostra due istanze tf.Examples
serializzate che richiedono la codifica base64 (dati falsi, solo a scopo illustrativo):
{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}
L'esempio seguente mostra due stringhe di byte di immagini JPEG che richiedono la codifica base64 (dati falsi, solo a scopo illustrativo):
{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}
Più tensori di input
Alcuni modelli hanno un grafico TensorFlow sottostante che accetta più tensori di input. In questo caso, utilizza i nomi delle coppie nome/valore JSON per identificare i tensori di input.
Per un grafo con gli alias dei tensori di input "tag" (stringa) e "image" (stringa con codifica base64):
{ "instances": [ { "tag": "beach", "image": {"b64": "ASa8asdf"} }, { "tag": "car", "image": {"b64": "JLK7ljk3"} } ] }
Per un grafo con gli alias dei tensori di input "tag" (stringa) e "image" (array tridimensionale di interi a 8 bit):
{ "instances": [ { "tag": "beach", "image": [ [ [138, 30, 66], [130, 20, 56], ... ], [ [126, 38, 61], [122, 24, 57], ... ], ... ] }, { "tag": "car", "image": [ [ [255, 0, 102], [255, 0, 97], ... ], [ [254, 1, 101], [254, 2, 93], ... ], ... ] }, ... ] }
scikit-learn
Il corpo della richiesta contiene dati con la seguente struttura (rappresentazione JSON):
{
"instances": [
<simple list>,
...
]
}
L'oggetto instances[]
è obbligatorio e deve contenere l'elenco delle istanze per le quali ottenere le previsioni. Nell'esempio seguente, ogni istanza di input è un
elenco di valori float:
{
"instances": [
[0.0, 1.1, 2.2],
[3.3, 4.4, 5.5],
...
]
}
La dimensione delle istanze di input deve corrispondere a quella prevista dal modello. Ad esempio, se il modello richiede tre funzionalità, la lunghezza di ogni istanza di input deve essere 3.
XGBoost
Il corpo della richiesta contiene dati con la seguente struttura (rappresentazione JSON):
{
"instances": [
<simple list>,
...
]
}
L'oggetto instances[]
è obbligatorio e deve contenere l'elenco delle istanze per le quali ottenere le previsioni. Nell'esempio seguente, ogni istanza di input è un
elenco di valori float:
{
"instances": [
[0.0, 1.1, 2.2],
[3.3, 4.4, 5.5],
...
]
}
La dimensione delle istanze di input deve corrispondere a quella prevista dal modello. Ad esempio, se il modello richiede tre funzionalità, la lunghezza di ogni istanza di input deve essere 3.
Vertex AI non supporta la rappresentazione sparsa delle istanze di input per XGBoost.
Il servizio di previsione online interpreta in modo diverso gli zeri e i NaN
. Se il valore di una funzionalità è zero, utilizza 0.0
nell'input corrispondente. Se il valore di una funzionalità non è presente, utilizza "NaN"
nell'input corrispondente.
L'esempio seguente rappresenta una richiesta di previsione con una singola istanza di input, in cui il valore della prima caratteristica è 0,0, il valore della seconda caratteristica è 1,1 e il valore della terza caratteristica non è presente:
{"instances": [[0.0, 1.1, "NaN"]]}
PyTorch
Se il tuo modello utilizza un container predefinito PyTorch, gli handler predefiniti di TorchServe si aspettano che ogni istanza sia racchiusa in un campo data
. Ad esempio:
{
"instances": [
{ "data": , <value> },
{ "data": , <value> }
]
}
Dettagli del corpo della risposta
Se la chiamata va a buon fine, il corpo della risposta contiene una voce di previsione per ogni istanza nel corpo della richiesta, fornita nello stesso ordine:
{
"predictions": [
{
object
}
],
"deployedModelId": string
}
Se la previsione non va a buon fine per una qualsiasi istanza, il corpo della risposta non contiene previsioni. ma contiene una singola voce di errore:
{
"error": string
}
L'oggetto predictions[]
contiene l'elenco delle previsioni, una per ogni istanza nella richiesta.
In caso di errore, la stringa error
contiene un messaggio che descrive il problema. L'errore viene restituito anziché un elenco di previsioni se si è verificato un errore durante l'elaborazione di un'istanza.
Anche se esiste una previsione per istanza, il formato di una previsione non è correlato direttamente al formato di un'istanza. Le previsioni assumono il formato specificato nella raccolta di output definita nel modello. La raccolta delle previsioni viene restituita in un elenco JSON. Ogni elemento dell'elenco può essere un valore semplice, un elenco o un oggetto JSON di qualsiasi complessità. Se il tuo modello ha più di un tensore di output, ogni previsione sarà un oggetto JSON contenente una coppia nome-valore per ogni output. I nomi identificano gli alias di output nel grafico.
Esempi di testo della risposta
TensorFlow
Gli esempi seguenti mostrano alcune possibili risposte:
-
Un semplice insieme di previsioni per tre istanze di input, in cui ogni previsione è un valore intero:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Un insieme di previsioni più complesso, ciascuna contenente due valori denominati che corrispondono ai tensori di output, denominati rispettivamente
label
escores
. Il valore dilabel
è la categoria prevista ("auto" o "spiaggia") escores
contiene un elenco di probabilità per l'istanza tra le possibili categorie.{ "predictions": [ { "label": "beach", "scores": [0.1, 0.9] }, { "label": "car", "scores": [0.75, 0.25] } ], "deployedModelId": 123456789012345678 }
-
Una risposta quando si verifica un errore durante l'elaborazione di un'istanza di input:
{"error": "Divide by zero"}
scikit-learn
Gli esempi seguenti mostrano alcune possibili risposte:
-
Un semplice insieme di previsioni per tre istanze di input, in cui ogni previsione è un valore intero:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Una risposta quando si verifica un errore durante l'elaborazione di un'istanza di input:
{"error": "Divide by zero"}
XGBoost
Gli esempi seguenti mostrano alcune possibili risposte:
-
Un semplice insieme di previsioni per tre istanze di input, in cui ogni previsione è un valore intero:
{"predictions": [5, 4, 3], "deployedModelId": 123456789012345678 }
-
Una risposta quando si verifica un errore durante l'elaborazione di un'istanza di input:
{"error": "Divide by zero"}
Inviare una richiesta a un endpoint
Esistono tre modi per inviare una richiesta:
Richiesta di previsione: invia una richiesta a
predict
per ricevere una previsione online.Richiesta di previsione non elaborata: invia una richiesta a
rawPredict
, che consente di utilizzare un payload HTTP arbitrario anziché seguire le linee guida descritte nelle sezioni Formatta l'input di questa pagina. Potresti voler ottenere le previsioni non elaborate se:- Utilizzi un container personalizzato che riceve richieste e invia risposte diverse dalle linee guida.
- Hai bisogno di una latenza inferiore.
rawPredict
salta i passaggi di serializzazione e inoltra direttamente la richiesta al contenitore di previsione. - Pubblichi le previsioni con NVIDIA Triton.
Richiesta di spiegazione: invia una richiesta a
explain
. Se hai configuratoModel
per Vertex Explainable AI, puoi ricevere spiegazioni online. Le richieste di spiegazione online hanno lo stesso formato delle richieste di previsione online e restituiscono risposte simili. L'unica differenza è che le risposte alle spiegazioni online includono le attribuzioni delle funzionalità e le previsioni.
Inviare una richiesta di previsione online
gcloud
Nell'esempio seguente viene utilizzato il comando gcloud ai endpoints predict
:
Scrivi il seguente oggetto JSON in un file nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio, chiamalo
request.json
.{ "instances": INSTANCES }
Sostituisci quanto segue:
- INSTANCES: un array JSON di istanze per le quali vuoi ottenere le previsioni. Il formato di ogni istanza dipende dagli input previsti dal tuo modello ML addestrato. Per ulteriori informazioni, consulta la sezione Formattare l'input per la previsione online.
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
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.
- INSTANCES: un array JSON di istanze per le quali vuoi ottenere le previsioni. Il formato di ogni istanza dipende dagli input previsti dal tuo modello ML addestrato. Per ulteriori informazioni, consulta la sezione Formattare l'input per la previsione online.
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": INSTANCES }
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
- PREDICTIONS: un array JSON di previsioni, una per ogni istanza inclusa nel corpo della richiesta.
-
DEPLOYED_MODEL_ID: l'ID del
DeployedModel
che ha pubblicato le previsioni.
{ "predictions": PREDICTIONS, "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 a Vertex AI, configura le 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 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 a Vertex AI, configura le 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, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.
Inviare una richiesta di previsione online a un endpoint dedicato
Gli endpoint dedicati utilizzano un nuovo percorso dell'URL. Puoi recuperare questo percorso dal campo
dedicatedEndpointDns
nell'API REST o da
Endpoint.dedicated_endpoint_dns
nell'SDK Vertex AI per Python. Puoi anche
costruire il percorso dell'endpoint manualmente utilizzando il seguente codice:
f"https://ENDPOINT_ID.LOCATION_ID-PROJECT_NUMBER.prediction.vertexai.goog/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"
Sostituisci quanto segue:
- ENDPOINT_ID: l'ID dell'endpoint.
- LOCATION_ID: la regione in cui utilizzi Vertex AI.
- PROJECT_NUMBER: il numero del progetto. È diverso dall'ID progetto. Puoi trovare il numero di progetto nella pagina Impostazioni progetto del progetto in Google Cloud Console.
Per inviare una previsione a un endpoint dedicato utilizzando l'SDK Vertex AI per Python, imposta il parametro use_dedicated_endpoint
su True
:
endpoint.predict(instances=instances, use_dedicated_endpoint=True)
Inviare una richiesta di previsione non elaborata online
gcloud
I seguenti esempi utilizzano il comando gcloud ai endpoints raw-predict
:
-
Per richiedere le previsioni con l'oggetto JSON in REQUEST specificato nella riga di comando:
gcloud ai endpoints raw-predict ENDPOINT_ID \ --region=LOCATION_ID \ --request=REQUEST
Per richiedere le previsioni con un'immagine memorizzata nel file
image.jpeg
e l'intestazioneContent-Type
appropriata:gcloud ai endpoints raw-predict ENDPOINT_ID \ --region=LOCATION_ID \ --http-headers=Content-Type=image/jpeg \ --request=@image.jpeg
Sostituisci quanto segue:
- ENDPOINT_ID: l'ID dell'endpoint.
- LOCATION_ID: la regione in cui utilizzi Vertex AI.
- REQUEST: i contenuti della richiesta per cui vuoi ricevere le predizioni. Il formato della richiesta dipende da ciò che il contenitore personalizzato si aspetta, che potrebbe non essere necessariamente un oggetto JSON.
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.
La risposta include le seguenti intestazioni HTTP:
X-Vertex-AI-Endpoint-Id
: l'ID delEndpoint
che ha pubblicato questa previsione.X-Vertex-AI-Deployed-Model-Id
: ID delDeployedModel
dell'endpoint che ha generato questa previsione.
Inviare una richiesta di spiegazione online
gcloud
Nell'esempio seguente viene utilizzato il comando gcloud ai endpoints explain
:
Scrivi il seguente oggetto JSON in un file nel tuo ambiente locale. Il nome del file non è importante, ma per questo esempio, chiamalo
request.json
.{ "instances": INSTANCES }
Sostituisci quanto segue:
- INSTANCES: un array JSON di istanze per le quali vuoi ottenere le previsioni. Il formato di ogni istanza dipende dagli input previsti dal tuo modello ML addestrato. Per ulteriori informazioni, consulta la sezione Formattare l'input per la previsione online.
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
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.
- INSTANCES: un array JSON di istanze per le quali vuoi ottenere le previsioni. Il formato di ogni istanza dipende dagli input previsti dal tuo modello ML addestrato. Per ulteriori informazioni, consulta la sezione Formattare l'input per la previsione online.
Metodo HTTP e URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain
Corpo JSON della richiesta:
{ "instances": INSTANCES }
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: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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
- PREDICTIONS: un array JSON di previsioni, una per ogni istanza inclusa nel corpo della richiesta.
- EXPLANATIONS: un array JSON di spiegazioni, una per ogni previsione.
-
DEPLOYED_MODEL_ID: l'ID del
DeployedModel
che ha pubblicato le previsioni.
{ "predictions": PREDICTIONS, "explanations": EXPLANATIONS, "deployedModelId": "DEPLOYED_MODEL_ID" }
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.
Passaggi successivi
- Scopri di più sui log di previsione online.