BroadRouter
Commencer

Mode JSON ou json_schema : une sortie structurée qui tient

Par l’équipe BroadNet Inference · 4 min de lecture · Publié

Le mode JSON (response_format json_object) promet seulement un JSON valide. La sortie structurée (response_format json_schema) promet aussi vos champs et vos types, là où le fournisseur l’impose. Dans les deux cas, vérifiez finish_reason, parsez et validez contre un schéma, par exemple un modèle Pydantic. Si la validation échoue, renvoyez l’erreur et redemandez, avec un nombre maximal de tentatives.

Votre code a besoin de données, et les modèles écrivent du texte. La sortie structurée comble cet écart, mais « le modèle renvoie du JSON » recouvre trois choses différentes selon la manière dont vous le demandez. Cet article compare les options sur des modèles ouverts compatibles OpenAI, montre comment demander chacune et propose une boucle de validation et de réparation à intégrer telle quelle en production.

Quelle est la différence entre le mode JSON et json_schema ?

Méthode Requête Ce qui vous est promis
Prompt seul « Réponds en JSON avec les champs… » Rien ; en général du JSON, parfois avec du texte en plus
Mode JSON response_format: {"type": "json_object"} Du JSON valide, de forme quelconque
Sortie structurée response_format: {"type": "json_schema", ...} Du JSON conforme à votre schéma, là où c’est imposé

Le guide des Structured Outputs d’OpenAI le dit sans détour : « While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence. » (traduction : « Si les deux garantissent la production d’un JSON valide, seules les Structured Outputs garantissent le respect du schéma. ») Il recommande la sortie structurée plutôt que le mode JSON chaque fois que c’est possible.

Chez les fournisseurs de modèles ouverts, la garantie dépend de la façon dont le serveur l’implémente. Beaucoup utilisent le décodage contraint (constrained decoding), qui bloque les tokens qui casseraient le schéma. Certains acceptent le champ sans l’imposer. C’est pourquoi le code ci-dessous valide dans tous les cas.

Comment demander json_schema ?

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic génère le JSON Schema à partir de votre classe : le schéma et le validateur ne divergent jamais. Si vous n’utilisez pas Pydantic, le générateur de JSON Schema construit un schéma en mode strict à partir d’un objet d’exemple. En mode strict, OpenAI exige additionalProperties: false et que chaque propriété figure parmi les champs obligatoires.

Quel mode votre fournisseur prend-il en charge ?

Faites ce test une fois par modèle avant de bâtir dessus :

  1. Envoyez json_schema avec un prompt qui invite à ajouter un champ (« ajoute aussi un court commentaire »).
  2. Si la requête renvoie une erreur, le fournisseur n’accepte pas json_schema. Essayez json_object.
  3. Si la réponse contient le champ en trop, le schéma n’est pas imposé. Traitez-le comme le mode JSON.
  4. Si json_object renvoie aussi une erreur, utilisez les seules consignes du prompt, avec validation.

Chez BroadNet Inference, la documentation indique la sortie structurée pour GLM 5.3 et Qwen3.8 27B (comparés côte à côte), mais ne nomme pas le paramètre de requête. Faites le test ci-dessus sur le modèle que vous mettez en production.

Comment valider et réparer une sortie incorrecte ?

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

Ce qui fait fonctionner cette boucle :

  • Vérifier finish_reason en premier. Une réponse qui a atteint max_tokens est un JSON tronqué. Relancer avec la même limite échoue de la même façon. Les deux modèles ci-dessus raisonnent avant de répondre, et le raisonnement compte dans la limite : laissez de la marge.
  • Traiter les refus à part. Le guide d’OpenAI note qu’un refus « does not necessarily follow the schema you have supplied » (traduction : « ne suit pas forcément le schéma que vous avez fourni »).
  • Renvoyer l’erreur exacte. Un retry à l’aveugle renvoie souvent la même erreur. « line_items: field required » donne au modèle quelque chose à corriger.
  • Vérifier les règles métier dans le code. Un schéma ne peut pas dire qu’un total doit être égal à la somme de ses lignes. La vérification ci-dessus, si.
  • Plafonner les tentatives. Chaque tentative renvoie tout le prompt en tokens d’entrée.

Quelles fonctionnalités de schéma posent problème ?

Gardez des schémas ennuyeux :

  1. Plat plutôt qu’imbriqué. Deux niveaux suffisent pour la plupart des extractions.
  2. Des enums plutôt que des chaînes libres pour les catégories.
  3. Pas d’objets ouverts. Des champs dict libres font perdre tout l’intérêt.
  4. Des noms de champs courts, avec des descriptions. Les descriptions du schéma guident le modèle.
  5. Les champs optionnels en nullable. En mode strict, déclarez chaque champ obligatoire et autorisez null.

Le guide d’OpenAI signale que certaines fonctionnalités de JSON Schema ne sont pas prises en charge en mode strict. Les serveurs de modèles ouverts ont leurs propres limites. Si un schéma est refusé, simplifiez-le avant de changer de mode.

Comment surveiller la sortie structurée en production ?

Une boucle qui répare en silence peut masquer un problème qui vous coûte des tokens chaque jour. Journalisez trois chiffres par point d’appel :

Indicateur Ce qu’il vous apprend
Taux de réussite à la première tentative L’adéquation entre modèle et schéma ; une baisse suit souvent un changement de prompt ou de modèle
Nombre moyen de tentatives par réussite Le coût en tokens des réparations
Échecs définitifs Les entrées que votre pipeline ne sait pas traiter ; relisez-les à la main

Si le taux de réussite à la première tentative passe sous votre niveau habituel, simplifiez le schéma ou essayez un autre modèle avant d’ajouter des retries. Gardez un échantillon des réponses brutes en échec, pour tester vos corrections sur des cas réels.

Quand utiliser plutôt un outil ?

Utilisez la sortie structurée pour la réponse finale : une extraction, une classification, un plan. Utilisez l’appel d’outils quand le modèle a besoin que votre code fasse quelque chose avant de continuer. Beaucoup d’agents utilisent les deux : des outils pendant la boucle, un schéma pour la dernière étape. Pour un exemple d’image vers JSON, voir lire des factures en arabe avec un modèle de vision.

La place de BroadNet Inference

BroadNet Inference indique la sortie structurée pour GLM 5.3 et Qwen3.8 27B, derrière le format standard des chat completions : le code ci-dessus tourne donc sans modification avec le SDK Python d’OpenAI. Qwen3.8 27B accepte aussi les images, ce qui convient à l’extraction de documents. La documentation de BroadNet n’indique pas de sortie structurée pour DeepSeek V4.1 Flash ni pour Gemma 4 VL 26B : utilisez-y la voie des consignes de prompt seules, avec validation. Comparez les prix au token sur la page des prix.

Questions fréquentes

Quelle est la différence entre le mode JSON et la sortie structurée ?

Le mode JSON, response_format de type json_object, promet seulement que la réponse se parse en JSON. La sortie structurée, de type json_schema, promet aussi les champs et les types que vous avez définis, là où le fournisseur l’impose. OpenAI recommande la sortie structurée plutôt que le mode JSON quand c’est possible.

Les modèles ouverts prennent-ils en charge response_format avec json_schema ?

Cela dépend du fournisseur. Certains acceptent json_schema, d’autres seulement json_object, et d’autres ignorent le champ. Envoyez une requête de test avec un schéma et un prompt qui pousse le modèle à ajouter un champ en trop, puis vérifiez la réponse.

Faut-il quand même valider la sortie structurée ?

Oui. Les réponses peuvent être tronquées par max_tokens, être des refus, et enfreindre des règles métier qu’un schéma ne peut pas exprimer, comme des totaux qui doivent tomber juste.

Combien de fois relancer en cas de JSON invalide ?

Deux ou trois tentatives en incluant l’erreur de validation suffisent en général. Au-delà, journalisez l’entrée et orientez-la vers une solution de repli, un modèle plus puissant ou une personne. Les boucles sans limite gaspillent des tokens.

Sortie structurée ou appel d’outils : que choisir ?

Utilisez la sortie structurée quand vous voulez la réponse finale sous une forme fixe. Utilisez l’appel d’outils quand le modèle a besoin que votre code fasse quelque chose avant de continuer.

Lire en MarkdownDemander à ChatGPTDemander à ClaudeDemander à Perplexity