Appels d’outils et sorties structurées avec l’API Gemini : guide pour l’architecture

Ce que vous allez apprendre dans ce guide

Vous découvrirez à quoi servent les appels d’outils et les sorties structurées dans l’API Gemini, dans quels cas privilégier chaque approche et comment concevoir un exemple axé sur l’architecture. Le guide s’intéresse notamment à l’extraction d’informations sur des espaces à partir de notes de projet et à la génération, par le modèle, des paramètres nécessaires à l’appel d’une fonction externe.

Ces deux fonctionnalités ne sont pas identiques. Avec l’appel de fonctions, le modèle détermine si l’une des fonctions définies doit être appelée et renvoie les paramètres nécessaires. Avec les sorties structurées, il est invité à produire une réponse conforme à un schéma prédéfini. La première approche sert à interagir avec des outils, la seconde à obtenir des données structurées ; elles peuvent être utilisées à différentes étapes d’un même flux de travail.

Prérequis

La documentation de l’API Gemini de Google propose des exemples avec les SDK Python et JavaScript, ainsi que des exemples en Java, Go et REST. L’exemple Python utilise le client genai du package google, tandis que celui en JavaScript utilise le package @google/genai. Dans l’exemple REST, la clé API est transmise au moyen de la variable GEMINI_API_KEY. Les sources ne précisant ni les étapes d’installation, ni les tarifs, ni les conditions liées aux comptes, il ne faut rien supposer sur ces points ; avant la mise en œuvre, vérifiez séparément les informations à jour sur l’accès à l’API et la tarification.

Le nom du modèle utilisé dans les exemples est gemini-3.8-flash. Le choix du modèle doit dépendre des exigences de l’application ; l’exemple présenté ici reprend le nom indiqué dans la documentation source. Les équipes qui souhaitent utiliser du code doivent disposer du SDK correspondant au langage choisi et d’un accès à l’API Gemini. Ce guide ne nécessite aucun IDE ni plug-in pour logiciel d’architecture en particulier.

Pour l’exemple d’appel de fonctions, l’application doit disposer d’un service ou d’une fonction appelable. Il peut s’agir, par exemple, d’un service interne qui renvoie les données des espaces d’un projet. Le modèle génère la définition de la fonction et ses paramètres ; l’appel du service, le traitement du résultat et, si nécessaire, sa présentation à l’utilisateur restent à la charge de l’application.

Étape par étape : appel de fonctions

1. Définissez la fonction. Précisez son nom, sa description et le schéma de ses paramètres. L’exemple ci-dessous montre une définition de fonction que l’application pourrait fournir pour récupérer les données des espaces d’un projet. project_id est défini comme un paramètre de type texte ; il doit correspondre aux attentes du service réel.

from google import genai

get_room_data_function = {
    "type": "function",
    "name": "get_room_data",
    "description": "Returns room data for a project.",
    "parameters": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string"}
        },
        "required": ["project_id"]
    }
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Mimari projedeki mekân verilerini getir.",
    tools=[{"type": "function", **get_room_data_function}]
)

for step in interaction.steps:
    if step.type == "function_call":
        print(step.name)
        print(step.arguments)

Cet exemple montre comment lire le nom et les arguments de la fonction à l’étape de l’appel. Le code qui relie l’application au service de données n’y figure pas : la définition de la fonction, à elle seule, ne récupère pas les données des espaces. L’application doit prendre en charge l’appel reçu dans son propre service, valider les paramètres et traiter le résultat dans son flux de travail.

1. Limitez le périmètre de la fonction. Son rôle et les paramètres qu’elle attend doivent être explicites. Dans un flux de travail architectural, la consultation de la liste des espaces et la modification d’une fiche de projet sont deux opérations différentes ; les définir séparément permet de préciser l’action à exécuter par l’application. Dans les systèmes réels, prévoyez également des étapes de validation et d’approbation côté application pour toute opération susceptible de modifier des données ou d’avoir des effets externes.

2. Gérez l’appel côté application. Les exemples officiels montrent comment parcourir les étapes d’une interaction pour repérer celles de type function_call, puis lire le nom de la fonction et ses arguments. L’étape suivante consiste à exécuter la fonction correspondante dans l’application et à traiter le résultat. La génération d’un appel de fonction par le modèle ne signifie pas que le service externe a fonctionné : la gestion des erreurs et la vérification du résultat font partie de l’intégration du service.

Étape par étape : sorties structurées

1. Déterminez les données nécessaires. Par exemple, pour extraire d’une note de projet le nom d’un espace, sa surface et ses exigences, vous pouvez créer un schéma combinant objet, tableau, texte et entier. Choisissez les types de champs en fonction de l’utilisation prévue dans l’application. La source présente également des options de définition de schémas avec Pydantic pour Python et Zod pour JavaScript, en plus de JSON Schema.

2. Ajoutez le schéma à la requête. L’exemple Python ci-dessous montre comment demander une réponse au format JSON et la récupérer dans le champ output_text. Les noms de champs sont proposés à titre d’exemple pédagogique axé sur l’architecture ; les informations à extraire des documents de projet doivent être définies selon les besoins métier.

from google import genai

client = genai.Client()
room_schema = {
    "type": "object",
    "properties": {
        "rooms": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "room_name": {"type": "string"},
                    "area_m2": {"type": "integer"},
                    "requirements": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["room_name", "area_m2", "requirements"]
            }
        }
    },
    "required": ["rooms"]
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Proje notundaki mekânları çıkar: giriş holü 12 m²; doğal ışık gereksinimi var.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": room_schema
    }
)

print(interaction.output_text)

Le schéma définit les champs de la réponse et les types de données attendus, mais il ne permet pas de vérifier des informations absentes de la note de projet. Par exemple, si la surface n’est pas indiquée dans le texte, l’application doit vérifier cette donnée séparément ou gérer son absence dans son propre modèle de données. Il est également important de choisir des champs obligatoires susceptibles d’être présents dans les documents sources.

1. Validez le résultat dans l’application. Les sorties structurées sont conçues pour faciliter l’analyse des données ; elles ne garantissent pas l’exactitude des décisions architecturales. Comparez les résultats du modèle aux documents du projet, aux plans cotés ou aux données officielles. Ne transférez pas sans validation dans un dessin ou une base de données de projet les informations susceptibles d’avoir des conséquences, telles que les surfaces, les noms de personnes, les dates et les exigences techniques.

Erreurs fréquentes

L’une des erreurs les plus courantes consiste à croire que le modèle exécute de lui-même le système externe lorsqu’il effectue un appel de fonction. Le modèle peut fournir le nom de l’appel et ses paramètres ; l’application doit associer cet appel au service approprié et l’exécuter. Des noms de fonctions ambigus, des descriptions trop générales ou l’absence de paramètres requis dans le schéma compliquent également l’intégration.

Pour les sorties structurées, n’oubliez pas que le respect du schéma ne garantit pas l’exactitude de chaque information. De plus, définir des champs obligatoires sans vérifier s’ils figurent dans le texte source peut produire des enregistrements incomplets ou inutilisables. Considérez la sortie du modèle comme une étape de structuration des données, et non comme le résultat final vérifié du flux de travail.

Prochaines étapes pour l’architecture et l’archviz

Les agences peuvent envisager ces approches lorsqu’elles doivent répartir les notes de projet dans des champs précis ou récupérer des données à partir d’outils internes. Elles peuvent également aider les étudiants à apprendre à extraire des données structurées d’un texte et à comprendre les bases de l’intégration d’API. Toutefois, ces fonctionnalités ne sont pas présentées dans les sources comme des plug-ins directement connectés à un logiciel BIM, CAO ou de visualisation ; l’application doit mettre en place cette connexion séparément.

Pour un premier essai, utilisez une fonction en lecture seule, à portée limitée, et un schéma facile à vérifier. Commencez par examiner l’extraction des champs dans quelques notes de projet, puis comparez les résultats aux sources. Avant de déployer un outil à l’échelle de l’agence, clarifiez l’accès à l’API et les éventuels coûts d’utilisation, le service auquel les données du projet seront envoyées et la compatibilité avec l’infrastructure logicielle existante. Ces points n’étant pas détaillés dans les textes sources, ils doivent être évalués selon l’organisation et l’application choisie.

Sources et licence

Ce guide est une adaptation en turc des documents publiés par Google pour l’API Gemini : « Function calling with the Gemini API » et « Structured outputs ». Les deux sources sont sous licence CC BY 4.0. Les exemples axés sur l’architecture ont été préparés spécialement pour ce guide.