Les développeurs peuvent désormais garantir que le JSON renvoyé par un LLM respecte une forme prédéfinie en intégrant des schémas Zod au Vercel AI SDK ou à l'API tool-use d'Anthropic, éliminant ainsi les plantages au moment de l'exécution qui surviennent lorsqu'un modèle ajoute un champ inattendu.

Le besoin d'une protection concrète est devenu évident en janvier, lorsqu'un classificateur mis en production a commencé à renvoyer une seconde clé « explanation » après trois semaines de fonctionnement impeccable. Le code attendait un champ unique, si bien que la clé supplémentaire a déclenché une exception — sans aucun déploiement de code. Cet incident illustre un problème plus large : la plupart des tutoriels s'arrêtent à JSON.parse(response), en supposant que le modèle respectera le schéma du prompt. En réalité, les LLM s'écartent fréquemment de la trajectoire — en changeant la casse, en ajoutant des champs ou en enveloppant la sortie dans des balises markdown — ce qui entraîne une corruption silencieuse des données ou des échecs complets.

Pourquoi l'analyse JSON brute est risquée

Les LLM sont entraînés pour être utiles, pas obéissants. Un prompt qui demande

{ "category": "string" }

ne lie pas le modèle à cette structure exacte. Même un prompt bien écrit peut être outrepassé par les heuristiques internes du modèle, surtout lorsqu'un réglage de température encourage la créativité ou lorsqu'une instruction en aval l'incite à élaborer. Le résultat est un flux de texte qui ressemble à du JSON mais qui dévie suffisamment pour briser les parseurs qui attendent une forme stricte.

Lorsqu'un tel décalage atteint le code de production, le coût est immédiat : une exception levée, une requête échouée et potentiellement une cascade d'erreurs en aval. Dans les grands services, ces minutes d'indisponibilité se traduisent par une perte de revenus et une érosion de la confiance des utilisateurs.

Zod + Vercel AI SDK : un filet de sécurité en trois étapes

Zod est un validateur de schéma orienté TypeScript qui peut décrire la forme exacte des données qu'un modèle doit émettre. Combiné à l'helper Output.object du Vercel AI SDK, la validation s'effectue automatiquement après que le modèle a généré sa réponse.

  1. Définir le schéma – écrivez un objet Zod qui reflète le JSON souhaité. Pour un classificateur simple, il pourrait s'agir de z.object({ category: z.string() }) ; pour un extracteur de factures complexe, le schéma peut imbriquer des objets, des tableaux et des unions discriminées.
  2. Le transmettre au SDK – enveloppez le schéma avec Output.object(schema). Le SDK injecte un prompt qui indique au modèle de produire un bloc JSON correspondant au schéma et analyse le résultat avec le safeParse de Zod.
  3. Gérer les échecs – safeParse renvoie un objet de résultat au lieu de lever une exception. Si l'analyse échoue, renvoyez l'erreur au modèle et réessayez. On peut donner instruction au modèle de corriger la sortie en se basant sur le message de validation exact, transformant ainsi la plupart des cas limites en une boucle d'auto-correction.

Comme le SDK gère le prompting, l'analyse et la logique de réessai en un seul endroit, les développeurs remplacent une poignée de manipulations de chaînes de caractères ad hoc par un seul appel vérifié par le typage.

Utilisation des outils Anthropic : forcer une sortie structurée

Lorsqu'on travaille directement avec l'API d'Anthropic, la même garantie peut être obtenue via l'« utilisation d'outils » (tool use). Un outil est défini comme une fonction dont le schéma d'entrée est exprimé en JSON Schema ; le modèle d'Anthropic n'appellera l'outil que s'il peut satisfaire le schéma. En réglant tool_choice sur "any" (ou un nom d'outil spécifique), le modèle est contraint de renvoyer un bloc structuré plutôt qu'un texte libre.

Le flux de travail reflète l'approche de Vercel :

  • Écrivez un schéma Zod.
  • Convertissez-le en une charge utile JSON Schema pour la définition de l'outil.
  • Incluez l'outil dans la requête et exigez que le modèle l'invoque.
  • Analysez la réponse de l'outil avec zod.safeParse.

Si le modèle produit toujours des données malformées, le même modèle de réessai avec rétroaction s'applique.

Lorsque la validation échoue malgré tout

Même avec l'application d'un schéma, des décalages occasionnels surviennent. Les raisons incluent :

  • Hallucination du modèle : le modèle peut générer une chaîne qui ressemble à du JSON mais contient des erreurs de syntaxe.
  • Fuite de prompt : les tours de conversation précédents peuvent laisser échapper des instructions de formatage qui outrepassent la demande de schéma.
  • Différences de version : les nouvelles versions des modèles modifient parfois la manière dont ils interprètent les appels d'outils.

La solution recommandée est une boucle de réessai légère. En cas d'échec de l'analyse, le code envoie un prompt de suivi tel que : « Votre dernière sortie n'était pas un JSON valide. Elle contenait... Veuillez renvoyer uniquement les champs définis dans le schéma. » Comme l'erreur de validation est explicite, le modèle peut se corriger lui-même sans intervention humaine.

Considérations de performance et de coût

Adding Zod validation introduces negligible CPU overhead—the safeParse operation runs in microseconds for typical payloads. Network latency is unchanged; the extra round-trip for a retry only occurs on the rare failure case. In practice, the cost of a single prevented exception far outweighs the marginal increase in request time.

Counter-argument: is schema enforcement overkill?

Some developers argue that strict schemas limit the model’s flexibility, especially when new fields could provide valuable context. The trade-off is between safety and openness. In mission-critical services—payment processing, identity verification, compliance reporting—predictability wins. In exploratory prototypes, a looser approach may be acceptable, but even there a minimal guard (e.g., z.object({}).passthrough()) can catch catastrophic parsing errors without discarding useful extensions.

What to watch next

  • SDK evolution: Vercel’s AI SDK roadmap includes built-in retry policies and richer error reporting, which will streamline the repair loop further.
  • Tooling standardization: As more providers adopt tool-use conventions, cross-provider schema validators could emerge, reducing the need for provider-specific adapters.
  • Community patterns: Open-source libraries are beginning to bundle Zod schemas with prompt templates, making the “schema-first” workflow a reusable asset.

Takeaway

By treating a Zod schema as a contract that the model cannot break, developers move from fragile JSON.parse hacks to a deterministic pipeline where unexpected fields cause a controlled validation failure, not a production crash. The combination of Vercel’s Output.object helper and Anthropic’s tool-use mechanism turns LLMs from unpredictable text generators into reliable data providers, letting teams focus on business logic instead of endless edge-case debugging.