Structured Output

Obtenez des données structurées faciles à analyser et à valider par votre programme.

Structured Output permet au modèle de retourner une structure attendue pour extraire des champs, écrire dans une base de données ou alimenter un workflow. Il sert notamment à classer des tickets, extraire des formulaires, représenter des résultats de modération et produire des rapports structurés.

Structured Output et Tool Calling répondent à des besoins différents

Utilisez Structured Output pour obtenir une réponse structurée, et Tool Calling pour demander à l’application d’exécuter une fonction choisie par le modèle. Les paramètres d’outils peuvent aussi être contraints par un Schema, mais relèvent du cycle d’appels d’outils.

Choisir d’abord le mode de sortie adapté

Mode	Besoin couvert	Travail restant côté client
Demander du JSON dans le prompt	Fournir une contrainte de base aux modèles sans champs dédiés	Extraire, analyser et valider le JSON, puis réessayer en cas d’échec
JSON Object	Demander un objet JSON valide	Valider les champs, types et règles métier
JSON Schema	Fournir la structure cible dans la requête	Gérer les limites du modèle, les refus, les troncatures et les échecs de validation

La prise en charge de JSON Object, de JSON Schema et du respect strict dépend du modèle et du protocole. Un statut 200 ne prouve pas à lui seul que le Schema demandé a été appliqué.

Définir un Schema limité et précis

La structure suivante classe une demande client en ticket :

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account"]
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3
    },
    "summary": {
      "type": "string"
    }
  },
  "required": ["category", "priority", "summary"],
  "additionalProperties": false
}

Choisissez des noms de champs stables et clairs, et des valeurs d’énumération cohérentes avec le code métier. Évitez dès le départ les imbrications profondes, les nombreuses branches facultatives et les expressions régulières difficiles à expliquer.

Obtenir un résultat structuré avec Chat Completions

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Ma clé API ne fonctionne pas. Veuillez classer ma demande."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "category": {
              "type": "string",
              "enum": ["billing", "technical", "account"]
            },
            "priority": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3
            },
            "summary": {"type": "string"}
          },
          "required": ["category", "priority", "summary"],
          "additionalProperties": false
        }
      }
    }
  }'

strict fait partie du format cible, mais sa disponibilité dépend du modèle. Consultez les champs complets dans Chat Completions Reference.

Emplacement des champs selon le protocole

Chat sélectionne json_object ou json_schema dans response_format. Le JSON Schema se trouve dans response_format.json_schema.schema.

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "schema": {"type": "object"}
    }
  }
}

Ces structures ne se transposent pas directement à un autre protocole. Consultez Responses Reference et Gemini Generate Content Reference avant utilisation.

Valider les données après l’analyse

type SupportTicket = {
  category: 'billing' | 'technical' | 'account';
  priority: number;
  summary: string;
};

function parseTicket(raw: string): SupportTicket {
  const value: unknown = JSON.parse(raw);

  if (
    typeof value !== 'object' ||
    value === null ||
    !('category' in value) ||
    !('priority' in value) ||
    !('summary' in value)
  ) {
    throw new Error('Le résultat structuré ne contient pas les champs requis');
  }

  return value as SupportTicket;
}

Cet exemple montre uniquement une vérification minimale. En production, utilisez un validateur Schema cohérent avec le modèle de données métier, et vérifiez les énumérations, longueurs, plages numériques et règles entre champs.

Gérer les résultats incomplets ou invalides

Situation	Traitement
Texte ordinaire retourné	Vérifier la prise en charge du format, l’emplacement des champs et les modifications éventuelles du SDK
JSON impossible à analyser	Conserver la réponse expurgée et la raison de fin, puis limiter les tentatives selon la politique métier
Champs requis absents	Considérer la validation comme échouée, sans masquer les données manquantes par des valeurs par défaut
Sortie tronquée	Ajuster le budget de sortie ou simplifier le Schema, sans inventer le JSON manquant
Refus du modèle	Traiter le refus séparément, sans interpréter son texte comme un objet métier
Structure analysable mais données métier invalides	Retourner une erreur explicite après validation métier ou transmettre à un opérateur

Vérifications avant la mise en production

Le Schema et les types de l’application proviennent d’une même source ou restent synchronisés.
Avant de changer de modèle, revérifiez le protocole, le sous-ensemble Schema et le mode strict.
Les échecs d’analyse, refus, troncatures et sorties vides disposent de branches distinctes.
Les résultats structurés sont revalidés avant une écriture ou une action métier.
Les journaux conservent uniquement les informations expurgées nécessaires au diagnostic.

Après avoir vérifié le modèle dans le Catalogue de modèles, consultez les champs complets dans sa référence API. En cas d’échec, consultez Erreurs et dépannage.