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 Gemini Enterprise Agent Platform Model as a Service (MaaS) sont compatibles avec les sorties structurées.
Pour en savoir plus sur le concept de sortie structurée, consultez Présentation des 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 pour Python décrites dans le guide de démarrage rapide d'Agent Platform à 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, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les 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 projet Google Cloud .
- 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, 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://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, 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://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 pour Python décrites dans le guide de démarrage rapide d'Agent Platform à 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, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les 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 projet Google Cloud .
Exemple de réponse
Voici un exemple de ce à quoi pourrait ressembler la sortie du 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 respectera le schéma JSON suivant :
{ "name": STRING, "date": STRING, "participants": [STRING] }
Lorsque vous fournissez le prompt "Alice et Bob vont à une foire scientifique vendredi", le modèle peut produire 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 de children, qui peut également être de 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 respectera 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
La réponse peut ressembler à ceci :
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 limiter le modèle pour qu'il ne génère que des objets JSON syntaxiquement valides en définissant le champ response_format sur { "type": "json_object" }. C'est ce qu'on appelle souvent le mode JSON. Le mode JSON est utile pour générer du 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 contraint de ne générer que des chaînes qui s'analysent en objets JSON valides. Bien que ce mode garantisse que la sortie est un JSON syntaxiquement correct, il n'applique aucun schéma spécifique. Pour vous assurer que la sortie du modèle génère un fichier 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 demander au modèle de renvoyer un objet JSON avec une structure spécifique :
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à 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, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les 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.6.
REST
Avant d'utiliser les données de requête ci-dessous, 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.6.
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, 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/endpoints/openapi/chat/completions"
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/endpoints/openapi/chat/completions" | Select-Object -Expand Content
Vous devriez recevoir une réponse JSON semblable à la suivante.
Étapes suivantes
- En savoir plus sur l'appel de fonction
- En savoir plus sur le raisonnement