Vous pouvez vous assurer que la sortie générée par un modèle respecte toujours un schéma spécifique afin de recevoir des réponses mises en forme de manière cohérente. Par exemple, vous pouvez avoir un schéma de données établi que vous utilisez pour d'autres tâches. Si le modèle suit le même schéma, vous pouvez extraire directement les données des résultats du modèle sans aucun post-traitement.
Pour spécifier la structure des résultats d'un modèle, définissez un schéma de réponse, qui fonctionne comme un modèle pour les réponses du modèle. Lorsque vous envoyez une requête et incluez le schéma de la réponse, la réponse du modèle suit toujours le schéma défini.
Vous ne pouvez utiliser que Gemini 1.5 Pro pour contrôler la sortie générée.
Exemples de cas d'utilisation
Un des cas d'utilisation de l'application d'un schéma de réponse consiste à s'assurer que la réponse d'un modèle produit dans un format JSON valide et est conforme à votre schéma. Les sorties de modèles génératifs peuvent présenter un certain degré de variabilité. Par conséquent, l'inclusion d'un schéma de réponse vous garantit de toujours recevoir un fichier JSON valide. Par conséquent, vos tâches en aval peuvent s'attendre à une entrée JSON valide à partir des réponses générées.
Vous pouvez également limiter la façon dont un modèle peut répondre. Par exemple, vous pouvez demander à un modèle d'annoter du texte avec des étiquettes définies par l'utilisateur, et non produites par le modèle. Cette contrainte est utile lorsque vous attendez un ensemble spécifique d'étiquettes, tel quepositive ounegative, et ne voulez pas recevoir un mélange d'autres étiquettes comme good ou bad.
Remarques
Les éléments suivants décrivent les limites potentielles si vous prévoyez d'utiliser un schéma de réponse :
- JSON est le seul format de sortie accepté.
- Vous devez utiliser l'API pour définir et utiliser un schéma de réponse. Aucune console n'est compatible.
- Le schéma de réponse est comptabilisé dans la limite des jetons d'entrée.
Avant de commencer
Définissez un schéma de réponse pour spécifier la structure de la sortie d'un modèle, les noms des champs et le type de données attendu pour chaque champ. Vertex AI utilise un sous-ensemble de l'objet de schéma OpenAPI 3.0. Pour en savoir plus, consultez la documentation de référence sur le schéma de Vertex AI.
Pour obtenir des exemples, consultez la section Exemples de schémas et de réponses de modèle.
Comportement du modèle et schéma de réponse
Lorsqu'un modèle génère une réponse, il utilise le nom du champ et le contexte de votre requête. Par conséquent, nous vous recommandons d'utiliser une structure claire et des noms de champs non ambigus pour que votre intention soit claire.
Par défaut, les champs sont facultatifs, ce qui signifie que le modèle peut remplir les champs ou les ignorer. Vous pouvez définir les champs selon vos besoins pour forcer le modèle à fournir une valeur. Si le contexte de la requête d'entrée associée est insuffisant, le modèle génère des réponses principalement basées sur les données sur lesquelles il a été entraîné.
Si les résultats ne sont pas ceux escomptés, ajoutez plus de contexte à vos requêtes d'entrée ou modifiez votre schéma de réponse. Par exemple, examinez les valeurs sans génération contrôlée pour voir comment le modèle réagit. Vous pouvez ensuite mettre à jour le schéma de réponse qui correspond mieux à la sortie du modèle.
Envoyer une requête avec un schéma de réponse
Par défaut, tous les champs sont facultatifs, ce qui signifie qu'un modèle peut générer une réponse à un champ. Pour forcer le modèle à toujours générer une réponse à un champ, définissez le champ comme requis.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
REST
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- GENERATE_RESPONSE_METHOD : type de réponse que le modèle doit générer.
Choisissez une méthode qui génère le mode de renvoi de la réponse du modèle :
streamGenerateContent: la réponse est affichée progressivement à mesure qu'elle est générée afin de réduire la perception de la latence auprès d'un public humain.generateContent: la réponse est renvoyée une fois qu'elle a été entièrement générée.
- LOCATION : région dans laquelle traiter la requête.
- PROJECT_ID : l'ID de votre projet.
- MODEL_ID : ID du modèle multimodal que vous souhaitez utiliser. Vous disposez des options suivantes :
gemini-1.5-pro
- ROLE : rôle dans une conversation associée au contenu. La spécification d'un rôle est requise, même dans les cas d'utilisation à un seul tour.
Les valeurs acceptées incluent les suivantes :
USER: spécifie le contenu que vous envoyez.
- TEXT : instructions textuelles à inclure dans la requête.
- RESPONSE_SCHEMA : schéma que le modèle doit suivre lors de la génération des réponses. Pour en savoir plus, consultez la documentation de référence sur le schéma.
Méthode HTTP et URL :
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD
Corps JSON de la requête :
{
"contents": {
"role": "ROLE",
"parts": {
"text": "TEXT"
}
},
"generation_config": {
"responseMimeType": "application/json",
"responseSchema": RESPONSE_SCHEMA,
}
}
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
$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
Vous devriez recevoir une réponse JSON semblable à la suivante.
Exemple de commande curl
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`
Exemples de schémas et de réponses de modèle
Les sections suivantes présentent divers exemples de requêtes et de schémas de réponse. Un exemple de réponse du modèle est également inclus après chaque exemple de code.
- Résumer les notes et avis dans une liste imbriquée
- Prévoir la météo pour chaque jour de la semaine dans un tableau
- Classer un produit avec une énumération bien définie
- Identifier des objets dans des images
Résumer les notes et avis
L'exemple suivant génère un tableau d'objets, chacun possédant deux propriétés : la note et le nom d'un parfum de glace.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Exemple de réponse du modèle
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
}
Prévoir la météo pour chaque jour de la semaine
L'exemple suivant génère un objet forecast pour chaque jour de la semaine, qui inclut un tableau de propriétés, telles que le niveau de température et d'humidité attendu pour la journée.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Exemple de réponse du modèle
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
}
Classer un produit
L'exemple suivant inclut des énumérations dans lesquelles le modèle doit classer le type et la condition d'un objet à partir d'une liste de valeurs données.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Exemple de réponse du modèle
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
}
Identifier des objets dans des images
L'exemple suivant identifie les objets de deux images stockées sur Cloud Storage.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.
Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Exemple de réponse du modèle
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
}