Comment l'IA génère du JSON conforme à JSON Schema : du Prompt au Structured Output

Articles précédents de cette série abordéspourquoi les agents ont besoin de JSON(Tool Calling au flux de données MCP),pourquoi JSON Schema⟧ est devenu une infrastructure(Schéma, Appel de fonction et évolution MCP), etConfiguration Structured Output spécifique à Gemini(Guide Gémeaux API).

Cet article fait un zoom arrière :quel que soit le modèle API que vous utilisez, comment passer de « veuillez répondre en JSON » à « la sortie doit correspondre à ce schéma JSON »? Les fournisseurs ont convergé vers cela en 2024-2026 sous des noms tels que Structured Outputs⟧ / JSON Schema⟧ mode — même idée, noms de champs légèrement différents, sous-ensembles de schéma et limites avec Tool Calling.

Quatre niveaux, chacun plus « strict » que le précédent

Les équipes utilisent généralement quatre approches pour obtenir JSON à partir d'un modèle — la fiabilité diffère d'un ordre de grandeur :

For production extraction, classification, or form filling, aim for L3. L0–L1 suit exploration; L2 when shape varies and you only need JSON.parse. L3 is the contract programs can consume directly.

Ce que JSON Schema⟧ contrôle — et ce qu'il ne contrôle pas

JSON Schéma⟧décrit la structure du document : champs, types, clés requises, énumérations, plages, forme des éléments du tableau. Le fournisseur Structured Outputs⟧ compile ce schéma dans la génération – et ne se contente pas de le coller dans l'invite.

Schema can enforce: syntax shape (object / array / string / integer), required, enum, minimum / maximum, additionalProperties: false, nested objects and arrays.

Schema cannot enforce business correctness. Example: “total_cents must equal sum of line items” — assert that in code after Schema validation. Schema also does not fact-check: a well-typed fabricated invoice number is still hallucination.

Tool inputSchema uses the same language; Structured Output constrains the final reply, Tool Calling constrains tool arguments. See guide de flux de données.

Décodage contraint : pourquoi Schema bat Prompt

Les invites ne font qu’augmenter les chances de conformité. Structure structurée utilisedécodage contraint: à chaque jeton, le décodeur supprime les jetons qui briseraient la syntaxe JSON ou violeraient le schéma.

Vous obtenez généralement un JSON analysable et de forme correcte sans clôtures de démarques supprimant les regex. Les implémentations diffèrent (FSM, grammaire, masques logit), mais le contrat développeur est le même :transmettre le schéma à l'API, pas seulement à l'invite.

Garanties de décodage contraintstructure, passémantique. Revalidez toujours avec le même schéma et ajoutez des règles métier en production.

Comparaison OpenAI, Gemini, Anthropic

Même concept, noms de champs différents. Exemple : extraire un objet de facture.

When migrating vendors, keep the Schema itself standard JSON Schema⟧ (type, properties, required, enum); SDKs only wrap the request. Do not mix OpenAPI 3.0 uppercase types (OBJECT) with JSON Schema⟧ lowercase (object).

Écrire un bon schéma : de Pydantic à la production

Recommended flow: define types in Pydantic / Zod → export JSON Schema⟧ → tune → send to API. Put semantics in description — it enters model context and disambiguates “qty = pieces vs boxes”; type: integer alone cannot.

from pydantic import BaseModel, Field


class LineItem(BaseModel):
    name: str = Field(description="Product name")
    qty: int = Field(description="Quantity, positive integer", ge=1)
    unit_price_cents: int = Field(description="Unit price in cents", ge=0)


class Invoice(BaseModel):
    vendor: str
    currency: str = Field(description="ISO 4217, e.g. CNY")
    items: list[LineItem]
    total_cents: int

schema = Invoice.model_json_schema()
# In production add additionalProperties: false

Règles pratiques :

• Prefer object root over root-level array; { "items": [...] } is more stable on some APIs.
• Start with type / properties / required / enum, then add additionalProperties, min/max; do not dump full Draft 2020-12 — some keywords are ignored.
• Gardez la nidification peu profonde; les références circulaires sont rejetées – aplatissez le schéma.
• Schéma divisé vs invite: Schéma = forme ; Invite = sémantique (« extraire la facture du texte ci-dessous… »).

Exemple OpenAI Structured Outputs⟧

Chat Completions supports json_schema response format since 2024. With strict: true, output should only contain Schema fields:

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class Invoice(BaseModel):
    vendor: str
    total_cents: int

response = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "user", "content": "Extract invoice: Acme sold 2 keyboards for 398 CNY."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "invoice",
            "strict": True,
            "schema": Invoice.model_json_schema(),
        },
    },
)

data = response.choices[0].message.content  # JSON string
import json
invoice = json.loads(data)

Gemini uses response_mime_type + response_json_schema — see the Gemini article. For Anthropic, check current SDK structured output docs — same idea, official field names.

Pipeline de production : générer → analyser → valider → réessayer

La Structured Output n'est pas « un seul appel API et c'est fait ». Corrigez ces quatre étapes :

1. Generate: call model with Schema; log prompt, Schema version, raw content.
2. Parse: JSON.parse (or SDK parsed); on failure, retry whole response — no half-parse.
3. Schema validate: run same JSON Schema⟧ via AJV / jsonschema / Pydantic; retry or degrade on failure.
4. Validation commerciale: assertions personnalisées (totaux, clés étrangères) ; humain ou moteur de règles en cas de panne.

En cours de développement, stockez le schéma plus 2 à 3 échantillons positifs/négatifs dans le dépôt ; utilisez JSON Toolbox⟧ localement pour la structure et Diff — même état d'esprit que les tests de contrat REST, le consommateur est le LLM.

Pièges courants : demander « expliquez alors JSON » alors que le JSON Mode⟧ est activé ; troncature (augmenter le nombre maximum de jetons ou diviser les tâches) ; Clés API dans les démos frontend ; La version du schéma dérive de l'invite.

En quoi diffère-t-il de Tool Calling

Une boucle d’agent complète ressemble souvent à :Structured Output extrait l'intention → Tool Calling agit → Structured Output ou résume en prose pour l'utilisateur. N'utilisez pas Structured Output pour prétendre que « le paiement API a été appelé » – le modèle ne l'a pas appelé.

FAQ

Résumé

Pour obtenir JSON qui correspond au JSON Schema⟧ de l'IA, l'ordre compte :définissez d'abord le schéma, activez le JSON Mode⟧ / Structured Output, puis écrivez l'invite. Invite = sémantique ; Schéma = forme ; Pydantic / Zod sont des fronts conviviaux pour les auteurs ; Les APIdes fournisseurs exposent les canaux de schéma.

Exécutez une vraie facture ou prenez en charge la transcription de bout en bout : Schéma → Appel API → Collez la sortie dans un validateur. Lorsqu'il correspond, câblez la base de données ou l'agent suivant. Les arguments de l'outil passent toujours par Tool Calling / MCP — ne fusionnent pas en une seule API.