Gemini API: Tool-Aufrufe und strukturierte Ausgaben für die Architektur

Was erfahren Sie in diesem Leitfaden?

Sie lernen, wozu Tool-Aufrufe und strukturierte Ausgaben in der Gemini API dienen, für welche Aufgaben sich die beiden Ansätze eignen und wie sich ein Architekturbeispiel gestalten lässt. Im Mittelpunkt steht, Rauminformationen aus Projektnotizen zusammenzustellen und das Modell die für eine externe Funktion erforderlichen Parameter erzeugen zu lassen.

Die beiden Funktionen sind nicht dasselbe. Beim Function Calling entscheidet das Modell, ob eine der definierten Funktionen aufgerufen werden soll, und gibt die erforderlichen Parameter zurück. Bei strukturierten Ausgaben wird dagegen verlangt, dass die Antwort einem vorab festgelegten Schema entspricht. Der erste Ansatz dient der Interaktion mit Tools, der zweite der Ausgabe strukturierter Daten. Bei Bedarf lassen sie sich in unterschiedlichen Phasen desselben Workflows einsetzen.

Voraussetzungen

Die Gemini-API-Dokumentation von Google enthält neben SDK-Beispielen für Python und JavaScript auch Beispiele für Java, Go und REST. Das Python-Beispiel verwendet den Client genai aus dem Paket google, das JavaScript-Beispiel das Paket @google/genai. Im REST-Beispiel wird der API-Schlüssel über die Variable GEMINI_API_KEY übergeben. Da die Quellen weder Installationsschritte noch Gebühren oder Kontobedingungen erläutern, sollten hierzu keine Annahmen getroffen werden. Prüfen Sie vor der Implementierung die aktuellen Informationen zu API-Zugriff und Preisen.

In den Beispielen wird das Modell gemini-3.8-flash verwendet. Die Modellauswahl sollte sich nach den Anforderungen der Anwendung richten; das hier gezeigte Beispiel folgt dem Modellnamen in der Quelldokumentation. Teams, die mit Code arbeiten, benötigen das passende SDK für ihre Programmiersprache sowie Zugriff auf die Gemini API. Dieser Leitfaden setzt weder eine bestimmte IDE noch ein Plugin für Architektursoftware voraus.

Für das Beispiel zum Function Calling muss die Anwendung über einen aufrufbaren Dienst oder eine Funktion verfügen. Das könnte etwa ein interner Dienst sein, der Raumeinträge eines Projekts zurückgibt. Das Modell erzeugt die Funktionsdefinition und die Parameter; den Dienst aufzurufen, das zurückgegebene Ergebnis zu verarbeiten und es gegebenenfalls Nutzenden anzuzeigen, bleibt Aufgabe des Anwendungs-Workflows.

Schritt für Schritt: Function Calling

1. Definieren Sie die Funktion. Legen Sie den Namen, die Beschreibung und das Parameterschema der Funktion fest. Das folgende Beispiel zeigt eine mögliche Funktionsdefinition, über die die Anwendung Raumdaten eines Projekts abrufen kann. project_id ist als Textparameter angegeben und sollte den Anforderungen des tatsächlichen Dienstes entsprechen.

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)

Das Beispiel zeigt, wie sich der Funktionsname und die Argumente aus dem Function-Call-Schritt des Modells auslesen lassen. Code, der die Anwendung mit dem Datendienst verbindet, ist hier nicht enthalten: Die Funktionsdefinition allein ruft keine Raumdaten ab. Die Anwendung muss den zurückgegebenen Aufruf an ihren eigenen Dienst weiterleiten, die Parameter validieren und das Ergebnis im eigenen Workflow verarbeiten.

1. Halten Sie den Funktionsumfang eng begrenzt. Es sollte klar sein, was eine Funktion tut und welche Parameter sie benötigt. In einem Architektur-Workflow sind das Abrufen einer Raumliste und das Ändern eines Projektdatensatzes unterschiedliche Vorgänge. Werden solche Aufgaben separat definiert, ist klarer, welche Aktion die Anwendung ausführen soll. Planen Sie bei realen Systemen außerdem anwendungsseitige Validierungs- und Bestätigungsschritte für Vorgänge ein, die Daten verändern oder Auswirkungen außerhalb der Anwendung haben können.

2. Steuern Sie den Aufruf auf Anwendungsebene. Die offiziellen Beispiele zeigen, wie in den Interaktionsschritten nach Schritten vom Typ function_call gesucht und der Funktionsname sowie die Argumente ausgelesen werden. Im nächsten Schritt sollte die entsprechende Anwendungsfunktion ausgeführt und das Ergebnis verarbeitet werden. Dass das Modell einen Funktionsaufruf erzeugt, bedeutet nicht, dass der externe Dienst erfolgreich war. Fehlerbehandlung und Ergebniskontrolle gehören zur Dienstintegration.

Schritt für Schritt: Strukturierte Ausgaben

1. Legen Sie die benötigten Datenfelder fest. Für die Extraktion von Raumnamen, Flächen und Anforderungspunkten aus einer Projektnotiz lässt sich beispielsweise ein Schema aus Objekten, Arrays, Text- und Ganzzahltypen erstellen. Wählen Sie die Feldtypen danach aus, wie die Anwendung diese Daten verwenden soll. Neben JSON Schema erläutert die Quelle auch Optionen zur Schema-Definition mit Pydantic für Python und Zod für JavaScript.

2. Fügen Sie das Schema der Anfrage hinzu. Das folgende Python-Beispiel zeigt, wie sich eine Antwort als JSON anfordern und über das Feld output_text auslesen lässt. Die Feldnamen dienen als Architekturbeispiel; welche Informationen aus Projektdokumenten entnommen werden sollen, muss anhand der jeweiligen Anforderungen festgelegt werden.

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)

Das Schema legt die Felder der Antwort und die erwarteten Datentypen fest. Es bestätigt jedoch keine Informationen, die in der Projektnotiz nicht enthalten sind. Fehlt beispielsweise die Flächenangabe im Text, muss die Anwendung diese Daten separat überprüfen oder den Umgang mit fehlenden Angaben im eigenen Datenmodell regeln. Wichtig ist auch, Pflichtfelder so auszuwählen, dass sie in den Quelldokumenten voraussichtlich vorhanden sind.

1. Validieren Sie das Ergebnis in der Anwendung. Strukturierte Ausgaben sollen die Verarbeitung von Daten erleichtern; sie sind keine Prüfung, die die Richtigkeit architektonischer Entscheidungen garantiert. Vergleichen Sie die Modellausgabe mit Projektdokumenten, einem Aufmaßplan oder einem autorisierten Datensatz. Übernehmen Sie insbesondere Angaben zu Fläche, Personen, Datum und technischen Anforderungen nicht ungeprüft in Zeichnungen oder Projektdatenbanken.

Häufige Fehler

Ein grundlegender Fehler ist die Annahme, das Modell führe mit Function Calling das externe System automatisch aus. Das Modell kann den Funktionsnamen und die Parameter liefern; die Anwendung muss den Aufruf dem passenden Dienst zuordnen und ausführen. Auch unklare Funktionsnamen, allgemeine Beschreibungen oder nicht im Schema definierte Pflichtparameter erschweren die Integration.

Bei strukturierten Ausgaben gilt: Dass die Antwort dem Schema entspricht, bedeutet nicht, dass alle enthaltenen Informationen korrekt sind. Werden Pflichtfelder festgelegt, ohne zu prüfen, ob sie in den Quelltexten vorkommen, kann das zu unvollständigen oder unbrauchbaren Datensätzen führen. Betrachten Sie die Modellausgabe als strukturierten Datenschritt, nicht als abschließend geprüfte Information des Workflows.

Weitere Schritte in Architektur- und Archviz-Workflows

Büros können diese Ansätze für Prozesse prüfen, in denen Projektnotizen in bestimmte Felder aufgeteilt oder Daten aus internen Tools abgerufen werden müssen. Auch für Studierende eignen sie sich, um die strukturierte Extraktion aus Texten und die Grundlagen der API-Integration kennenzulernen. Die Funktionen werden in den Quellen jedoch nicht als direkt mit bestimmter BIM-, CAD- oder Visualisierungssoftware verbundenes Plugin vorgestellt. Eine solche Verbindung müsste die Anwendung separat herstellen.

Verwenden Sie für den ersten Versuch eine eng begrenzte, nur lesende Funktion und ein überschaubares Schema, das sich überprüfen lässt. Prüfen Sie zunächst anhand einiger Projektnotizen, wie die Felder extrahiert werden, und vergleichen Sie anschließend die Ergebnisse mit den Quellen. Klären Sie vor dem Einsatz eines bürointern geteilten Tools den API-Zugriff, mögliche Nutzungskosten, den Dienst, an den Projektdaten übermittelt werden, und die Kompatibilität mit der vorhandenen Softwareinfrastruktur. Da diese Punkte in den Quellen nicht näher ausgeführt werden, müssen sie je nach Organisation und gewählter Anwendung gesondert geprüft werden.

Quellen und Lizenz

Dieser Leitfaden wurde anhand der von Google veröffentlichten Gemini-API-Dokumentationen „Function calling with the Gemini API“ und „Structured outputs“ ins Türkische übertragen. Beide Quellen stehen unter der Lizenz CC BY 4.0. Die Architekturbeispiele wurden für diesen Leitfaden neu erstellt.