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 :
- Envoyez
json_schemaavec un prompt qui invite à ajouter un champ (« ajoute aussi un court commentaire »). - Si la requête renvoie une erreur, le fournisseur n’accepte pas
json_schema. Essayezjson_object. - Si la réponse contient le champ en trop, le schéma n’est pas imposé. Traitez-le comme le mode JSON.
- Si
json_objectrenvoie 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_reasonen premier. Une réponse qui a atteintmax_tokensest 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 :
- Plat plutôt qu’imbriqué. Deux niveaux suffisent pour la plupart des extractions.
- Des enums plutôt que des chaînes libres pour les catégories.
- Pas d’objets ouverts. Des champs
dictlibres font perdre tout l’intérêt. - Des noms de champs courts, avec des descriptions. Les descriptions du schéma guident le modèle.
- 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.
