Produire du JSON structuré à partir de textes architecturaux avec l’API Gemini

Ce que vous apprendrez dans ce guide

Un brief de projet, une note sur les matériaux ou une description d’espace se présente souvent sous la forme d’un texte libre. Lorsqu’il faut en extraire des informations structurées — comme le nom d’une pièce, ses matériaux ou sa fonction — une réponse en langage naturel peut compliquer les étapes suivantes. La fonctionnalité de sortie structurée de l’API Gemini permet de demander au modèle de respecter un schéma JSON prédéfini.

Nous allons aborder trois aspects : définir les champs attendus, décrire clairement la tâche et ses contraintes dans une consigne, puis ajouter le schéma approprié à la requête API. Les exemples sont conçus pour des flux de travail architecturaux ; les consignes ci-dessous ne figurent pas telles quelles dans les sources, ce sont des exemples originaux élaborés à partir des méthodes documentées.

Prérequis et périmètre

La documentation de Google mentionne la prise en charge de JSON Schema par l’API REST pour les sorties structurées. Pour les SDK Google GenAI, les options documentées pour définir un schéma sont Pydantic en Python et Zod en JavaScript. Les sources présentent également des exemples en Java, Go et dans d’autres langages ; dans ce guide, nous utilisons une ébauche de JSON Schema facile à adapter plutôt que du code.

Les exemples de la documentation précisent que Zod doit être installé pour JavaScript. En revanche, ces sources ne donnent aucune information sur la version du SDK, les conditions liées au compte ou les tarifs. Avant de commencer un projet, vérifiez donc les exigences à jour du SDK et du modèle utilisés dans la documentation correspondante de l’API Gemini. La documentation indique en haut de page que Gemini 4 Argon est disponible, tandis que l’exemple de code utilise le nom de modèle gemini-3.8-flash. Ne considérez pas automatiquement ce nom comme à jour ni comme adapté à tous les usages.

1. Définissez les champs à extraire

Avant de préparer le schéma, déterminez quelles données extraire du texte et le type de chacune. L’ébauche ci-dessous vise, par exemple, à extraire d’un brief d’aménagement intérieur le nom de l’espace, les matériaux mentionnés et sa fonction. Les structures JSON Schema de base telles que object, properties, string et required sont conformes aux exemples des sources.

{
  "type": "object",
  "properties": {
    "mekan_adi": { "type": "string" },
    "malzeme": { "type": "string" },
    "islev": { "type": "string" }
  },
  "required": ["mekan_adi", "malzeme", "islev"]
}

Les trois champs sont obligatoires ici. Si le texte source ne précise pas l’un d’eux, indiquez dans la consigne ce qu’il faut faire : par exemple, laisser le champ vide ou écrire « non précisé ». Ce choix dépend du traitement prévu pour les données du projet. Le définir dès la préparation du schéma aide l’équipe à obtenir des résultats cohérents.

2. Décrivez clairement la tâche et les données d’entrée

Une bonne consigne explique clairement le travail à effectuer, le texte à traiter et le format de réponse. Le guide de Google sur la conception des prompts recommande des instructions précises et explicites, ainsi que l’indication des contraintes et du format attendu lorsque nécessaire. Vous pouvez adapter l’exemple ci-dessous aux champs de votre brief.

À partir du brief de projet d’aménagement intérieur ci-dessous, extrais le nom de l’espace, le matériau explicitement mentionné et la fonction de l’espace. Fonde-toi uniquement sur les informations du texte fourni. Si une information n’y figure pas, écris « non précisé ». Génère la réponse sous la forme d’un objet JSON conforme aux champs du schéma JSON fourni.

Brief : L’espace de lecture situé au rez-de-chaussée comprend des surfaces plaquées en chêne et des tables de travail partagées.

Cette consigne fournit le texte d’entrée, définit la tâche d’extraction et précise la conduite à tenir pour les informations manquantes. La fonctionnalité de sortie structurée permet également de garantir que la réponse attendue respecte le schéma. La consigne et le schéma doivent décrire les mêmes champs : ne demandez pas dans la consigne de nouvelles clés absentes du schéma, et ne retirez pas du schéma des champs demandés.

3. Ajustez les contraintes aux besoins du projet

Dans les documents architecturaux, il est important de distinguer les interprétations des informations sources. Si vous extrayez une liste de matériaux, demandez explicitement de ne pas ajouter de produits ou de caractéristiques techniques absents du texte. L’exemple ci-dessous porte uniquement sur les matériaux écrits dans une description de pièce.

Extrais les revêtements et matériaux de surface mentionnés dans cette description de pièce. Ne propose aucun matériau et n’ajoute ni synonyme ni marque supposée. Réponds uniquement sous la forme d’une liste de noms de matériaux.

Description : Le hall d’entrée sera doté d’un sol en terrazzo et de murs enduits de plâtre peint.

Dans cet exemple, le format demandé est une liste ; ne l’utilisez donc pas directement pour la même tâche que le schéma précédent, qui attend un objet JSON. Le format de réponse dépend du besoin : avec une sortie structurée, le schéma doit correspondre au résultat décrit dans la consigne. Plutôt que de réutiliser un seul schéma pour des tâches de nature différente, réévaluez les champs et les types de données propres à chaque tâche.

4. Montrez le format attendu avec un exemple de réponse

Lorsque la classification ou le style rédactionnel demandé peut prêter à interprétation s’il est décrit uniquement en langage naturel, l’ajout de courts exemples peut clarifier le format. Le guide de Google indique qu’avec l’approche few-shot, on peut présenter au modèle des exemples d’entrées et de réponses attendues, et qu’il est utile de varier les exemples tout en les rendant explicites.

Classe la nouvelle note de pièce en utilisant les champs de l’exemple ci-dessous.

Note d’exemple : « Plan de travail de cuisine en composite de quartz, portes de placard en laque mate. »
Sortie d’exemple : {"mekan": "Cuisine", "malzemeler": ["composite de quartz", "laque mate"]}

Nouvelle note : « La pièce de travail comprend un parquet en bois et des murs peints sur enduit. »
Réponds uniquement en conservant la même structure de champs.

Cet exemple montre la structure de sortie ; vous devez définir séparément le schéma utilisé dans la requête API réelle. Le guide source indique qu’il est possible de commencer avec un petit nombre d’exemples et qu’il peut être nécessaire de tester ce nombre selon le cas d’usage. Il prévient également qu’un trop grand nombre d’exemples peut entraîner un surajustement du modèle.

Erreurs fréquentes

L’erreur la plus fréquente consiste à décrire les exigences uniquement dans la consigne, sans préciser de schéma côté API. Google indique qu’il est possible de demander en langage naturel des formats JSON simples, mais recommande la fonctionnalité de sortie structurée pour les besoins plus complexes en JSON Schema. Un autre problème est le décalage entre les champs ou les formats de réponse demandés dans la consigne et ceux du schéma. Commencez par clarifier les champs et leurs types, puis rédigez la consigne en conséquence.

Autre erreur : attendre du modèle qu’il complète des détails absents de la source lorsque le texte est ambigu. Précisez dans la consigne les informations à extraire, celles à exclure et la manière de représenter les données manquantes. Le schéma contribue à la cohérence du format, mais ne garantit pas à lui seul l’exactitude ni l’exhaustivité de la source du projet. Comparer les données générées au brief d’origine est important, notamment pour les livrables et la documentation.

Utilisation dans les flux de travail d’architecture et de visualisation

Cette approche peut être utile aux agences d’architecture, aux architectes d’intérieur et aux étudiants qui doivent classer un grand nombre de notes de projet selon les mêmes champs. Extraire les matériaux, les types d’espaces ou les fonctions décrits dans des fiches de pièce constitue un point de départ structuré lorsque ces données doivent ensuite être transférées vers un autre outil. Les sources ne décrivent aucune intégration avec un logiciel BIM, CAO ou de visualisation en particulier ; la connexion et la compatibilité doivent donc être évaluées séparément.

Les agences peuvent commencer par tester un petit ensemble de textes pour vérifier la pertinence des champs, puis contrôler les résultats obtenus avec le même schéma et la même consigne sur différents briefs. Pour les étudiants, cette méthode permet d’apprendre de façon concrète à extraire des données d’un texte libre et à comprendre la structure JSON. Les sources ne donnent aucune information sur le matériel, les licences ou le coût d’utilisation de l’API ; vérifiez ces éléments dans la documentation des services concernés avant de passer en production.

Étapes suivantes

Commencez par choisir un seul cas d’usage, par exemple l’extraction de matériaux à partir de notes de pièce. Définissez les champs et créez le schéma, puis testez-le avec une consigne claire. Comparez les résultats au texte source, observez les erreurs récurrentes et n’ajoutez des exemples à la consigne que si cela s’avère nécessaire. Si vous utilisez Python, envisagez Pydantic ; avec JavaScript, évaluez l’option de définition de schéma avec Zod. L’utilisation de l’API REST est également prise en charge dans la documentation.

Lorsque le projet prend de l’ampleur, documentez les changements de schéma et les champs attendus pour l’équipe. Vous pourrez ainsi mieux suivre la cohérence de la structure des données entre les différentes tâches de traitement des briefs architecturaux. Pour commencer, l’objectif n’est pas de tout automatiser, mais de tester une tâche textuelle répétitive avec des règles explicites et un format de réponse vérifiable.

Sources et licence

Ce guide est adapté en turc à partir des documents de Google « Structured outputs » et « Prompt design strategies ». Les deux sources sont sous licence CC BY 4.0.