Puoi garantire che l'output generato di un modello rispetti sempre una specifica in modo da ricevere risposte formattate in modo coerente. Ad esempio, potrebbe avere uno schema di dati già definito che utilizzi per altre attività. Se se il modello segue lo stesso schema, puoi estrarre direttamente i dati dell'output del modello senza alcuna post-elaborazione.
Per specificare la struttura dell'output di un modello, definisci uno schema di risposta, che funziona come un modello per le risposte del modello. Quando invii una richiesta e includi lo schema della risposta, la risposta del modello segue sempre l'impostazione .
Puoi utilizzare solo Gemini 1.5 Pro per controllare le conversioni generate come output.
Esempi di casi d'uso
Un caso d'uso per applicare uno schema di risposta è garantire la risposta di un modello produce un JSON valido ed è conforme allo schema. Gli output del modello generativo presentano un certo grado di variabilità, per cui l'inclusione di uno schema di risposta assicura che ricevono sempre un codice JSON valido. Di conseguenza, le attività downstream possono si aspetta un input JSON valido dalle risposte generate.
Un altro esempio è la limitazione del modo in cui un modello può rispondere. Ad esempio, puoi
un modello annota il testo con etichette definite dall'utente, non con le etichette
prodotto dal modello. Questo vincolo è utile quando prevedi che un insieme specifico
come positive
o negative
e non vuoi ricevere una combinazione di
altre etichette, come good
o bad
.
Considerazioni
Le seguenti considerazioni discutono le potenziali limitazioni se prevedi di utilizzare uno schema di risposta:
- JSON è l'unico formato di output supportato.
- Per definire e utilizzare uno schema di risposta, devi utilizzare l'API. Non esiste una console assistenza in tempo reale.
- Lo schema di risposta viene conteggiato ai fini del limite di token di input.
Prima di iniziare
Definisci uno schema di risposta per specificare la struttura dell'output di un modello, il campo e il tipo di dati previsto per ogni campo. Vertex AI utilizza un sottoinsieme dell'oggetto dello schema OpenAPI 3.0. Per ulteriori informazioni, consulta Riferimento allo schema Vertex AI.
Per alcuni esempi, consulta Esempi di schemi e risposte del modello.
Comportamento del modello e schema di risposta
Quando un modello genera una risposta, utilizza il nome del campo e il contesto della tua . Pertanto, ti consigliamo di utilizzare una struttura chiara e non ambigua campi in modo che il tuo intento sia chiaro.
Per impostazione predefinita, i campi sono facoltativi, il che significa che il modello può compilare i campi oppure ignorarle. Puoi impostare i campi come necessari per forzare il modello a fornire un valore. Se il contesto non è sufficiente nel prompt di input associato, genera risposte principalmente in base ai dati con cui è stato addestrato.
Se non vedi i risultati previsti, aggiungi altro contesto all'input o rivedere lo schema di risposta. Ad esempio, esamina il codice senza generazione controllata per vedere come risponde il modello. Puoi aggiorna lo schema di risposta che meglio si adatta all'output del modello.
Invia un prompt con uno schema di risposta
Per impostazione predefinita, tutti i campi sono facoltativi, il che significa che un modello potrebbe generare una risposta in un campo. Per fare in modo che il modello generi sempre una risposta a un campo, imposta il valore se richiesto.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Python Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
REST
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- GENERATE_RESPONSE_METHOD: il tipo di risposta che deve essere generato dal modello.
Scegli un metodo che generi il modo in cui vuoi che venga restituita la risposta del modello:
streamGenerateContent
: la risposta viene riprodotta in streaming durante la generazione per ridurre la percezione della latenza per un pubblico umano.generateContent
: la risposta viene restituita dopo che è stata completamente generata.
- LOCATION: la regione in cui elaborare la richiesta.
- PROJECT_ID: il tuo ID progetto.
- MODEL_ID: l'ID del modello multimodale
che vuoi utilizzare. Le opzioni sono:
gemini-1.5-pro
- ROLE:
Il ruolo in una conversazione associata ai contenuti. La specifica di un ruolo è obbligatoria anche in
e i casi d'uso a turno singolo.
I valori accettati sono:
USER
: specifica i contenuti inviati da te.
- TEXT: Le istruzioni testuali da includere nel prompt.
- RESPONSE_SCHEMA: schema per modello da seguire durante la generazione delle risposte. Per ulteriori informazioni, consulta la sezione di riferimento relativa allo schema.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD
Corpo JSON della richiesta:
{ "contents": { "role": "ROLE", "parts": { "text": "TEXT" } }, "generation_config": { "responseMimeType": "application/json", "responseSchema": RESPONSE_SCHEMA, } }
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_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"
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_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente.
Comando curl di esempio
LOCATION="us-central1"
MODEL_ID="gemini-1.0-pro"
PROJECT_ID="test-project"
GENERATE_RESPONSE_METHOD="generateContent"
cat << EOF > request.json
{
"contents": {
"role": "user",
"parts": {
"text": "List a few popular cookie recipes."
}
},
"generation_config": {
"maxOutputTokens": 2048,
"responseMimeType": "application/json",
"responseSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
},
},
"required": ["recipe_name"],
},
}
}
}
EOF
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${GENERATE_RESPONSE_METHOD} -d \
-d `@request.json`
Esempi di schemi e risposte del modello
Le sezioni seguenti mostrano una varietà di prompt e risposte di esempio e schemi di machine learning. Dopo ogni esempio di codice viene inclusa anche una risposta del modello di esempio.
- Riepilogare le valutazioni delle recensioni in un elenco nidificato
- Prevedere il meteo per ogni giorno della settimana in un array
- Classificare un prodotto con un enum ben definito
- Identificare gli oggetti nelle immagini
Riepilogare le valutazioni delle recensioni
L'esempio seguente restituisce un array di oggetti, in cui ogni oggetto ha due proprietà: la valutazione e il nome di un gusto di gelato.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Python Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Esempio di risposta del modello
candidates { content { role: "model" parts { text: "[\n [\n {\n \"rating\": 4\n },\n {\n \"flavor\": \"Strawberry Cheesecake\"\n },\n {\n \"rating\": 1\n },\n {\n \"flavor\": \"Mango Tango\"\n }\n ]\n] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1139734759926796 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10070161521434784 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.13695430755615234 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.12241825461387634 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.11676400154829025 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.05310790613293648 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.10521054267883301 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.08299414813518524 } } usage_metadata { prompt_token_count: 61 candidates_token_count: 66 total_token_count: 127 }
Previsioni del meteo per ogni giorno della settimana
L'esempio seguente restituisce un oggetto forecast
per ogni giorno
della settimana che include un array di proprietà come la durata prevista del giorno
temperatura e livello di umidità.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Python Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Esempio di risposta del modello
candidates { content { role: "model" parts { text: "{\"forecast\": [{\"Day\": \"Sunday\", \"Forecast\": \"Sunny\", \"Temperature\": 77, \"Humidity\": \n\"50\", \"Wind Speed\": 10}, {\"Day\": \"Monday\", \"Forecast\": \"Partly Cloudy\", \"Temperature\": 72, \"Humidity\": \"55\", \"Wind Speed\": 15}, {\"Day\": \"Tuesday\", \"Forecast\": \"Rain Showers\", \"Temperature\": 64, \"Humidity\": \"70\", \"Wind Speed\": 20}, {\"Day\": \"Wednesday\", \"Forecast\": \"Thunderstorms\", \"Temperature\": 68, \"Humidity\": \"75\", \"Wind Speed\": 25}, {\"Day\": \"Thursday\", \"Forecast\": \"Cloudy\", \"Temperature\": 66, \"Humidity\": \"60\", \"Wind Speed\": 18}, {\"Day\": \"Friday\", \"Forecast\": \"Partly Cloudy\", \"Temperature\": 73, \"Humidity\": \"45\", \"Wind Speed\": 12}, {\"Day\": \"Saturday\", \"Forecast\": \"Sunny\", \"Temperature\": 80, \"Humidity\": \"40\", \"Wind Speed\": 8}]} " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1037486344575882 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.09670579433441162 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.18126320838928223 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10052486509084702 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.15960998833179474 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.09518112242221832 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.1388116478919983 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.10539454221725464 } } usage_metadata { prompt_token_count: 280 candidates_token_count: 249 total_token_count: 529 }
Classificare un prodotto
L'esempio seguente include le enumerazioni in cui il modello deve classificare il tipo e la condizione di un oggetto da un elenco di valori specificati.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Python Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Esempio di risposta del modello
candidates { content { role: "model" parts { text: " [{\n \"item_category\": \"winter apparel\",\n \"subcategory\": \"coat\",\n \"to_discard\": 1\n }] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.08945459872484207 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.13753245770931244 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: NEGLIGIBLE probability_score: 0.19208428263664246 severity: HARM_SEVERITY_LOW severity_score: 0.23810701072216034 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.07585817575454712 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.04336579889059067 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.12667709589004517 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.07396338135004044 } } usage_metadata { prompt_token_count: 38 candidates_token_count: 33 total_token_count: 71 }
Identificare gli oggetti nelle immagini
L'esempio seguente identifica gli oggetti di due immagini archiviati di archiviazione ideale in Cloud Storage.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di Vertex AI con librerie client. Per ulteriori informazioni, consulta API Python Vertex AI documentazione di riferimento.
Per eseguire l'autenticazione su Vertex AI, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Esempio di risposta del modello
candidates { content { role: "model" parts { text: "[\n [\n {\n \"object\": \"globe model\"\n },\n {\n \"object\": \"tablet computer\"\n },\n {\n \"object\": \"shopping cart\"\n },\n {\n \"object\": \"Eiffel Tower model\"\n },\n {\n \"object\": \"airplane model\"\n },\n {\n \"object\": \"coffee cup\"\n },\n {\n \"object\": \"computer keyboard\"\n },\n {\n \"object\": \"computer mouse\"\n },\n {\n \"object\": \"passport\"\n },\n {\n \"object\": \"sunglasses\"\n },\n {\n \"object\": \"US Dollar bills\"\n },\n {\n \"object\": \"notepad\"\n },\n {\n \"object\": \"pen\"\n }\n ],\n [\n {\n \"object\": \"watering can\"\n },\n {\n \"object\": \"oregano\"\n },\n {\n \"object\": \"flower pot\"\n },\n {\n \"object\": \"flower pot\"\n },\n {\n \"object\": \"gardening gloves\"\n },\n {\n \"object\": \"hand rake\"\n },\n {\n \"object\": \"hand trowel\"\n },\n {\n \"object\": \"grass\"\n }\n ]\n] " } } finish_reason: STOP safety_ratings { category: HARM_CATEGORY_HATE_SPEECH probability: NEGLIGIBLE probability_score: 0.1872812658548355 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.16357900202274323 } safety_ratings { category: HARM_CATEGORY_DANGEROUS_CONTENT probability: LOW probability_score: 0.37920594215393066 severity: HARM_SEVERITY_LOW severity_score: 0.29320207238197327 } safety_ratings { category: HARM_CATEGORY_HARASSMENT probability: NEGLIGIBLE probability_score: 0.14175598323345184 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.12074951827526093 } safety_ratings { category: HARM_CATEGORY_SEXUALLY_EXPLICIT probability: NEGLIGIBLE probability_score: 0.12241825461387634 severity: HARM_SEVERITY_NEGLIGIBLE severity_score: 0.0955180674791336 } } usage_metadata { prompt_token_count: 525 candidates_token_count: 333 total_token_count: 858 }