Les sorties structurées permettent à un modèle de générer une sortie qui respecte toujours un schéma spécifique. Par exemple, un modèle peut être fourni avec un schéma de réponse pour s'assurer que la réponse produit du code JSON valide. Les modèles Grok disponibles sur la plate-forme Gemini Enterprise Agent Platform Model as a Service (MaaS) sont compatibles avec les sorties structurées.
Pour en savoir plus sur la fonctionnalité de sortie structurée, consultez Introduction aux sorties structurées.
Utiliser des sorties structurées avec l'API Responses
Les modèles suivants montrent comment utiliser des sorties structurées avec l'API Responses :
Python
Avant d'essayer cet exemple, suivez les instructions de configuration Python décrites dans le guide de démarrage rapide de la plate-forme Agent à l'aide des bibliothèques clientes.
Pour vous authentifier auprès d'Agent Platform, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Avant d'exécuter cet exemple, assurez-vous de définir la variable d'environnement OPENAI_BASE_URL ou de configurer des identifiants OAuth.
Pour en savoir plus, consultez Authentification et identifiants.
from openai import OpenAI client = OpenAI()response = client.responses.create( model="MODEL", input="INPUT", text={ "format": { "type": "json_schema", "name": "SCHEMA_NAME", "strict": True, "schema": JSON_SCHEMA } }, stream=False, ) print(response)
- MODEL : nom du modèle que vous souhaitez utiliser, par exemple
xai/grok-4.20-reasoning. - INPUT : prompt ou entrée pour le modèle.
- SCHEMA_NAME : nom du schéma de réponse.
- JSON_SCHEMA : dictionnaire qui définit le schéma JSON, par exemple :
{"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}, "required": ["name", "age"], "additionalProperties": False}
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre Google Cloud projet.
- MODEL : nom du modèle que vous souhaitez utiliser, par exemple
xai/grok-4.20-reasoning. - INPUT : prompt ou entrée pour le modèle.
- SCHEMA_NAME : nom du schéma de réponse.
- JSON_SCHEMA : objet de schéma JSON qui définit la structure de la sortie.
Méthode HTTP et URL :
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses
Corps JSON de la requête :
{
"model": "MODEL",
"input": "INPUT",
"text": {
"format": {
"type": "json_schema",
"name": "SCHEMA_NAME",
"strict": true,
"schema": JSON_SCHEMA
}
},
"stream": false
}
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,
et 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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses"
PowerShell
Enregistrez le corps de la requête dans un fichier nommé request.json,
et 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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses" | Select-Object -Expand Content
Exemple
Les exemples suivants montrent un exemple complet d'utilisation de sorties structurées avec l'API Responses :
Python
Avant d'essayer cet exemple, suivez les instructions de configuration Python décrites dans le guide de démarrage rapide de la plate-forme Agent à l'aide des bibliothèques clientes.
Pour vous authentifier auprès d'Agent Platform, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Avant d'exécuter cet exemple, assurez-vous de définir la variable d'environnement OPENAI_BASE_URL ou de configurer des identifiants OAuth.
Pour en savoir plus, consultez Authentification et identifiants.
from openai import OpenAI client = OpenAI()response = client.responses.create( model="xai/grok-4.20-reasoning", input="Extract: John Doe is 30.", text={ "format": { "type": "json_schema", "name": "person_info", "strict": True, "schema": { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"} }, "required": ["name", "age"], "additionalProperties": False } } }, stream=False, ) print(response)
REST
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses -d \ '{ "model": "xai/grok-4.20-reasoning", "input": "Extract: John Doe is 30.", "text": { "format": { "type": "json_schema", "name": "person_info", "strict": true, "schema": { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "required": [ "name", "age" ], "additionalProperties": false } } }, "stream": false }'
- PROJECT_ID : ID de votre Google Cloud projet.
Exemple de réponse
Voici un exemple de sortie de modèle :
{
"background": false,
"completed_at": 1779159186,
"created_at": 1779159184,
"error": null,
"frequency_penalty": 0,
"id": "kNALat3NENmDifEP14TQ8Qk",
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"max_tool_calls": null,
"metadata": {
"system_fingerprint": "fp_39c5j0a3e9"
},
"model": "xai/grok-4.20-reasoning",
"object": "response",
"output": [
{
"content": [
{
"annotations": [],
"logprobs": [],
"text": "**Extracted Information:**\n\n- **Name:** John Doe\n- **Age:** 30\n\n**Structured output:**\n```json\n{\n \"name\": \"John Doe\",\n \"age\": 30\n}\n```",
"type": "output_text"
}
],
"id": "msg_kNALat3NENmDifEP14TQ8Qk",
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"parallel_tool_calls": true,
"presence_penalty": 0,
"previous_response_id": null,
"prompt_cache_key": null,
"reasoning": {
"effort": "medium",
"summary": "detailed"
},
"safety_identifier": null,
"service_tier": "default",
"status": "completed",
"store": true,
"temperature": 0.7,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_logprobs": 0,
"top_p": 0.95,
"truncation": "disabled",
"usage": {
"extra_properties": {
"google": {
"traffic_type": "ON_DEMAND"
}
},
"input_tokens": 343,
"input_tokens_details": {
"cached_tokens": 0
},
"num_server_side_tools_used": 0,
"num_sources_used": 0,
"output_tokens": 369,
"output_tokens_details": {
"reasoning_tokens": 325
},
"total_tokens": 712
},
"user": null
}
Utiliser des sorties structurées avec l'API Chat Completions
Le cas d'utilisation suivant définit un schéma de réponse qui garantit que la sortie du modèle est un objet JSON avec les propriétés suivantes : nom, date et participants. Le code Python utilise le SDK OpenAI et les objets Pydantic pour générer le schéma JSON.
from pydantic import BaseModel
from openai import OpenAI
client = OpenAI()
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
completion = client.beta.chat.completions.parse(
model="MODEL_NAME",
messages=[
{"role": "system", "content": "Extract the event information."},
{"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
],
response_format=CalendarEvent,
)
print(completion.choices[0].message.parsed)
La sortie du modèle respecte le schéma JSON suivant :
{ "name": STRING, "date": STRING, "participants": [STRING] }
Lorsque le prompt "Alice et Bob vont à une exposition scientifique vendredi" est fourni, le modèle peut générer la réponse suivante :
{
"name": "science fair",
"date": "Friday",
"participants": [
"Alice",
"Bob"
]
}
Exemple détaillé
Le code suivant est un exemple de schéma récursif. La classe UI contient une liste d'éléments children, qui peuvent également appartenir à la classe UI.
from pydantic import BaseModel
from openai import OpenAI
from enum import Enum
from typing import List
client = OpenAI()
class UIType(str, Enum):
div = "div"
button = "button"
header = "header"
section = "section"
field = "field"
form = "form"
class Attribute(BaseModel):
name: str
value: str
class UI(BaseModel):
type: UIType
label: str
children: List["UI"]
attributes: List[Attribute]
UI.model_rebuild() # This is required to enable recursive types
class Response(BaseModel):
ui: UI
completion = client.beta.chat.completions.parse(
model="MODEL_NAME",
messages=[
{"role": "system", "content": "You are a UI generator AI. Convert the user input into a UI."},
{"role": "user", "content": "Make a User Profile Form"}
],
response_format=Response,
)
print(completion.choices[0].message.parsed)
La sortie du modèle respecte le schéma de l'objet Pydantic spécifié dans l'extrait précédent. Dans cet exemple, le modèle peut générer le formulaire d'interface utilisateur suivant :
Form
Input
Name
Email
Age
Une réponse peut se présenter comme suit :
ui = UI(
type=UIType.div,
label='Form',
children=[
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Name')
]
),
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Email')
]
),
UI(
type=UIType.div,
label='Input',
children=[],
attributes=[
Attribute(name='label', value='Age')
]
)
],
attributes=[
Attribute(name='name', value='John Doe'),
Attribute(name='email', value='john.doe@example.com'),
Attribute(name='age', value='30')
]
)
Obtenir des réponses d'objet JSON
Vous pouvez contraindre le modèle à ne générer que des objets JSON valides sur le plan syntaxique en
définissant le response_format champ sur { "type": "json_object" }. On parle souvent de mode JSON. Le mode JSON est utile lorsque vous générez du code JSON à utiliser avec des appels de fonction ou d'autres tâches en aval qui nécessitent une entrée JSON.
Lorsque le mode JSON est activé, le modèle est limité à la génération de chaînes qui sont analysées dans des objets JSON valides. Bien que ce mode garantisse que la sortie est un code JSON syntaxiquement correct, il n'applique aucun schéma spécifique. Pour vous assurer que le modèle génère du code JSON qui suit un schéma spécifique, vous devez inclure des instructions dans le prompt, comme illustré dans l'exemple suivant.
Les exemples suivants montrent comment activer le mode JSON et indiquer au modèle de renvoyer un objet JSON avec une structure spécifique :
Python
Avant d'essayer cet exemple, suivez les instructions de configuration Python décrites dans le guide de démarrage rapide de la plate-forme Agent à l'aide des bibliothèques clientes.
Pour vous authentifier auprès d'Agent Platform, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Avant d'exécuter cet exemple, assurez-vous de définir la variable d'environnement OPENAI_BASE_URL ou de configurer des identifiants OAuth.
Pour en savoir plus, consultez Authentification et identifiants.
from openai import OpenAI client = OpenAI()response = client.chat.completions.create( model="MODEL", response_format={ "type": "json_object" }, messages=[ {"role": "user", "content": "List 5 rivers in South America. Your response must be a JSON object with a single key "rivers", which has a list of strings as its value."}, ] ) print(response.choices[0].message.content)
Remplacez MODEL par le nom du modèle que vous souhaitez utiliser,
par exemple xai/grok-4.1-fast-reasoning.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud.
- LOCATION : région compatible avec les modèles Grok.
- MODEL : nom du modèle que vous souhaitez utiliser,
par exemple
xai/grok-4.1-fast-reasoning.
Méthode HTTP et URL :
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions
Corps JSON de la requête :
{
"model": "MODEL",
"response_format": {
"type": "json_object"
},
"messages": [
{
"role": "user",
"content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."
}
]
}
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,
et 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/endpoints/openapi/chat/completions"
PowerShell
Enregistrez le corps de la requête dans un fichier nommé request.json,
et 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/endpoints/openapi/chat/completions" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON semblable à la suivante.
Étape suivante
- En savoir plus sur les appels de fonction.
- En savoir plus sur le raisonnement.