Sortie structurée : JSON garanti
På denna sida
Sortie structurée : JSON garanti
La sortie structurée est l’une des fonctionnalités les plus puissantes de l’API Responses. Au lieu d’espérer que le modèle renvoie un JSON valide, tu le garantis en fournissant un schéma. Le modèle est alors structurellement contraint de le suivre. Cela transforme un modèle de langage, générateur de texte créatif, en un composant fiable d’un pipeline de traitement automatisé.
Le problème résolu
Demander du JSON dans le prompt fonctionne la plupart du temps, ce qui rend précisément cette approche dangereuse. Un jour sur cent, le modèle préfixe sa réponse par une phrase d’introduction, enveloppe le tout dans un bloc de code Markdown ou renomme un champ — et ton json.loads() lève une exception en production sur une requête que tu ne peux pas reproduire.
from openai import OpenAI
client = OpenAI()
# Sans structure — le modèle peut retourner n'importe quel format
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me info about Paris in JSON."
)
print(response.output_text)
# Résultat imprévisible :
# Parfois un JSON valide, parfois du texte contenant du JSON,
# parfois un format inattendu...
Le paramètre text change la nature de la garantie. Tu déclares un format json_schema accompagné du schéma attendu, et la sortie s’y conforme : la désérialisation devient une opération sûre.
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me information about Paris.",
text={
"format": {
"type": "json_schema",
"name": "city_info",
"strict": True,
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"country": {"type": "string"},
"population": {"type": "integer"},
"official_language": {"type": "string"},
"landmarks": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["name", "country", "population", "official_language", "landmarks"],
"additionalProperties": False
}
}
}
)
import json
data = json.loads(response.output_text)
print(f"City: {data['name']}")
print(f"Population: {data['population']:,}")
print(f"Landmarks: {', '.join(data['landmarks'])}")
# Résultat GARANTI d'être un JSON valide :
# City: Paris
# Population: 2,161,000
# Landmarks: Eiffel Tower, Louvre, Notre-Dame, Arc de Triomphe, Sacré-Cœur
Pydantic plutôt qu’un schéma JSON écrit à la main
Écrire des schémas à la main devient rapidement fastidieux et sujet aux erreurs de frappe. Pydantic te permet de les décrire sous forme de classes Python, de générer le schéma JSON avec model_json_schema(), puis de valider et typer la réponse avec model_validate_json(). Au bout de la chaîne, tu obtiens un objet Python complet avec autocomplétion dans l’éditeur, plutôt qu’un dictionnaire anonyme.
from pydantic import BaseModel
from typing import Optional
import json
class Product(BaseModel):
name: str
price: float
category: str
in_stock: bool
description: Optional[str] = None
response = client.responses.create(
model="gpt-5.6-terra",
input="Describe a high-end gaming laptop.",
text={
"format": {
"type": "json_schema",
"name": "product",
"strict": True,
"schema": Product.model_json_schema()
}
}
)
# Analyse et validation avec Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Product: {product.name}")
print(f"Price: {product.price} EUR")
print(f"In stock: {'Yes' if product.in_stock else 'No'}")
# Résultat :
# Product: ASUS ROG Strix G18
# Price: 2499.99 EUR
# In stock: Yes
Rien ne te limite aux structures plates. En composant des classes, tu décris des objets imbriqués et des listes d’objets, ce dont tu auras besoin dès que tu créeras un profil client réaliste : une entreprise contient des contacts, et chaque contact possède une adresse.
from pydantic import BaseModel
class Address(BaseModel):
street: str
city: str
postal_code: str
country: str
class Contact(BaseModel):
last_name: str
first_name: str
email: str
phone: str
address: Address
class Company(BaseModel):
name: str
sector: str
employees: int
contacts: list[Contact]
response = client.responses.create(
model="gpt-5.6-terra",
input="Generate a fictional company profile in the tech sector "
"with 2 contacts.",
text={
"format": {
"type": "json_schema",
"name": "company",
"strict": True,
"schema": Company.model_json_schema()
}
}
)
company = Company.model_validate_json(response.output_text)
print(f"Company: {company.name} ({company.sector})")
for c in company.contacts:
print(f" - {c.first_name} {c.last_name}: {c.email}")
Deux cas d’usage courants
Le premier est l’extraction : transformer un texte écrit en un enregistrement exploitable. Une annonce de conférence rédigée en langage naturel devient une ligne de base de données avec un titre, une date, un lieu et un nombre de participants — sans expressions régulières, et sans casser à chaque changement de formulation.
class Event(BaseModel):
title: str
date: str
location: str
attendees: int
text = """
The PyCon France 2026 conference will be held on November 15 and 16
at the Palais des Congrès in Lyon. More than 800 Python developers
are expected for this edition.
"""
response = client.responses.create(
model="gpt-5.6-terra",
input=f"Extract the information from this event:\n{text}",
text={
"format": {
"type": "json_schema",
"name": "event",
"strict": True,
"schema": Event.model_json_schema()
}
}
)
evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} at {evt.location} ({evt.attendees} attendees)")
# Résultat : PyCon France 2026 - November 15-16, 2026 at Lyon (800 attendees)
Le second est la classification. En déclarant une énumération, tu restreins le modèle à un vocabulaire fermé : il ne peut pas répondre « plutôt positif » ou « positif » quand ton code attend positive. C’est la différence entre une valeur utilisable directement et une valeur que tu dois normaliser afterward.
from enum import Enum
class Sentiment(str, Enum):
positive = "positive"
negative = "negative"
neutral = "neutral"
class Analysis(BaseModel):
sentiment: Sentiment
confidence: float
keywords: list[str]
response = client.responses.create(
model="gpt-5.6-terra",
input="Analyze this comment: 'Great service, fast delivery!'",
text={
"format": {
"type": "json_schema",
"name": "sentiment_analysis",
"strict": True,
"schema": Analysis.model_json_schema()
}
}
)
analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentiment: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Résultat : Sentiment: positive (95%)
Ce que requiert le mode strict
La garantie a un prix : lorsque strict: True, le schéma doit adhérer à un sous-ensemble spécifique de JSON Schema. Ces contraintes sont la cause principale des erreurs 400 chez les débutants, il vaut donc mieux les connaître avant de les rencontrer :
- Toutes les propriétés doivent être listées dans
required additionalPropertiesdoit être égal àFalse- Types pris en charge :
string,number,integer,boolean,array,object,null - Pas de
oneOfnianyOfavec des types mélangés - Utilise
Optional[str], qui se traduit par{"anyOf": [{"type": "string"}, {"type": "null"}]}
La règle concernant required surprend souvent : un champ optionnel ne s’exprime pas en le retirant de la liste, mais en autorisant la valeur null, exactement ce que produit Optional[str] côté Pydantic.
Viktiga punkter
- La sortie structurée garantit que la réponse adhère à ton schéma JSON
- Utilise
text={"format": {"type": "json_schema", ...}}dans l’API Responses - Pydantic est l’outil idéal pour définir et valider les schémas
- Active
strict: Truepour une conformité garantie au schéma - Idéal pour l’extraction de données, la classification et la génération structurée