Réponses IA en JSON : valider le contrat avec Symfony

Décodage strict, types, clés et limites : validez les réponses JSON d’une IA avec Symfony Validator avant de les enregistrer.

Demander « réponds uniquement en JSON » ne constitue pas un contrat d’API. Le modèle peut ajouter une phrase, oublier une clé ou retourner un nombre à la place d’un texte. Même un JSON syntaxiquement correct peut être inutilisable pour l’application. Avant de persister une proposition IA, je sépare le décodage, la validation de sa structure et sa vérification métier.

Repères vérifiés le . L’exemple s’exécute avec PHP 8.4 et le composant Validator de Symfony 7.4. Il accepte une réponse brute et ne dépend d’aucun SDK de modèle ni d’un appel payant.

Écrire le contrat avant le prompt

Prenons une suggestion de fiche éditoriale : un titre de 120 caractères au maximum, un résumé de 600 caractères et un à cinq mots-clés courts. Ces limites répondent à l’interface qui affichera le résultat. Je refuse les clés supplémentaires afin de détecter un changement de format, au lieu de laisser un champ inattendu atteindre la persistance.

{
  "title": "Préparer une migration Symfony",
  "summary": "Inventorier les dépendances et vérifier les parcours essentiels.",
  "tags": ["Symfony", "Migration"]
}

Un fournisseur proposant une sortie structurée peut réduire les écarts de format. Le contrat local reste utile : il protège l’application lors d’un changement de modèle, d’une régression ou d’un résultat réutilisé depuis le cache. Il donne aussi les mêmes critères aux tests, indépendamment du fournisseur.

Décoder sans réparation silencieuse

Je borne la taille reçue avant de décoder. Dans une intégration HTTP, cette limite doit aussi être appliquée à la réception, avec un délai maximal. Le drapeau JSON_THROW_ON_ERROR distingue un document invalide d’une valeur null. Le manuel PHP de json_decode décrit également le paramètre de profondeur utilisé dans l’exemple.

Une réponse entourée de balises Markdown est refusée. Ajouter une succession de remplacements pour retrouver un objet quelque part dans le texte rend les erreurs difficiles à observer. Si un ancien fournisseur exige un adaptateur de nettoyage, je le garde séparé, explicite et testé avec ses propres cas limites.

Valider les champs avec Symfony Validator

composer require symfony/validator:"7.4.*"

Placez ce fichier à côté du dossier vendor d’un petit projet de test. Dans une application Symfony, injectez plutôt ValidatorInterface dans un service : il n’est pas nécessaire de reconstruire le validateur à chaque réponse.

<?php

declare(strict_types=1);

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Validation;

require __DIR__ . '/vendor/autoload.php';

function validateAiJson(string $json): array
{
    if (strlen($json) > 12000) {
        throw new DomainException('Réponse trop volumineuse.');
    }
    $decoded = json_decode($json, false, 32, JSON_THROW_ON_ERROR);
    if (!$decoded instanceof stdClass) {
        throw new DomainException('Un objet JSON est attendu.');
    }
    $data = get_object_vars($decoded);
    $text = static fn (int $max): Assert\Sequentially => new Assert\Sequentially([
        new Assert\Type('string'), new Assert\NotBlank(), new Assert\Length(max: $max),
    ]);
    $rules = new Assert\Collection(
        fields: [
            'title' => $text(120),
            'summary' => $text(600),
            'tags' => new Assert\Sequentially([
                new Assert\Type('array'),
                new Assert\Count(min: 1, max: 5),
                new Assert\All($text(40)),
            ]),
        ],
        allowExtraFields: false,
        allowMissingFields: false,
    );
    $errors = Validation::createValidator()->validate($data, $rules);
    if (count($errors) > 0) {
        throw new DomainException('Réponse hors contrat.');
    }

    return $data;
}

La contrainte Collection impose la présence des champs et refuse les clés supplémentaires. Sequentially contrôle d’abord le type, puis le contenu : la longueur ne doit pas être vérifiée sur un objet ou un tableau inattendu. La contrainte Type permet notamment de distinguer une chaîne d’un entier sans conversion implicite.

Tester les réponses gênantes

Le premier test utilise une réponse valide :

require "validate-ai-json.php";

$result = validateAiJson('{"title":"Un titre","summary":"Un résumé.","tags":["Symfony"]}');
assert($result["title"] === "Un titre");

Ajoutez les cas suivants à votre suite de tests. Une erreur doit être visible sans afficher le contenu brut à l’utilisateur ni l’enregistrer tel quel dans les logs.

  • JSON tronqué, texte explicatif et bloc Markdown : échec du décodage.
  • Liste JSON à la racine, objet vide ou réponse null : rejet du format.
  • Titre numérique, résumé sous forme de tableau, mot-clé null : rejet du type.
  • Clé manquante ou clé supplémentaire : rejet du contrat.
  • Six mots-clés, titre trop long et réponse supérieure à 12 000 octets : rejet des limites.

Valide ne veut pas dire vrai

Un texte qui respecte les types peut inventer une référence ou une date. Pour une extraction de facture, une quantité ou un prix, la règle métier doit s’appuyer sur une source vérifiable et conserver son lien avec le document original. Pour notre fiche éditoriale, je présente le résultat comme une suggestion et je laisse une personne le relire.

Le même principe s’applique aux actions : une chaîne intitulée « commande » ou « URL » ne reçoit aucun droit d’exécution parce qu’elle est passée dans Validator. L’application choisit explicitement les opérations autorisées. Au rendu, conservez l’échappement des textes dans Twig ; la validation de longueur ne nettoie pas du HTML.

En cas d’échec, prévoyez une seule correction bornée ou un retour manuel selon votre usage. Une boucle qui redemande au modèle de réparer jusqu’à obtenir un succès peut multiplier les coûts et masquer un contrat mal conçu. Mesurez le taux de rejet par modèle et version de prompt : c’est un signal de qualité, pas une raison d’assouplir automatiquement les règles.

← Tous les articles