Gemini API Function Calling: Tool-Aufrufe in Architektur-Workflows

Was erfahren Sie in diesem Leitfaden?

Gemini API Function Calling ermöglicht es einem Modell, statt nur einen Antworttext zu erzeugen eine Funktion auszuwählen, die in externen Systemen verwendet werden kann, und die dafür erforderlichen Parameter vorzubereiten. Ausgeführt wird die Funktion nicht vom Modell selbst, sondern von der Anwendung, die das Modell mit dem externen System verbindet. Im Leitfaden von Google wird dieser Ansatz beschrieben, um externe Systeme zu bedienen, Informationen aus Quellen wie APIs oder Datenbanken abzurufen und die Fähigkeiten mithilfe von Tools wie Berechnungen zu erweitern.

Für Architektur-, Innenarchitektur- und Visualisierungsteams kann diese Struktur als Grundlage für eine Anwendung dienen, die beispielsweise einen Materialkatalog durchsucht oder Projektinformationen abruft. Das folgende Beispiel zeigt, wie das Modell die Parameter für eine Katalogsuchfunktion vorbereitet. Die Anbindung an einen echten Katalog und die Nutzung der Ergebnisse hängen von der Entwicklung der Anwendung ab.

Voraussetzungen

Für den Einstieg benötigen Sie einen Gemini API-Schlüssel und eine Umgebung, die API-Anfragen senden kann. Der offizielle Einstiegsleitfaden zeigt die Verwendung des Python-SDKs, des JavaScript-SDKs und von REST; außerdem enthält er Beispiele für Java und Go. In dieser Anleitung wird Python verwendet.

Google AI Studio erstellt für neue Nutzer automatisch ein Projekt und einen API-Schlüssel. Den Schlüssel erhalten Sie auf der Seite „API keys“ in AI Studio. Der Leitfaden zeigt, wie der Schlüssel als Umgebungsvariable festgelegt wird. Mit dem API-Schlüssel werden Anfragen einem Konto zugeordnet und die Nutzung über dieses Konto nachverfolgt; außerdem trägt er dazu bei, Sicherheitsgrenzen für Anfragen durchzusetzen.

Beim Wechsel zur kostenpflichtigen Nutzung werden für das Konto höhere Anfragekontingente freigeschaltet. Dafür muss Cloud Billing eingerichtet werden. Laut Google-Leitfaden ist für kostenpflichtige Credits eine Vorauszahlung von mindestens 5 US-Dollar oder dem entsprechenden Betrag in einer anderen Währung erforderlich. Dabei handelt es sich nicht um eine Kostenschätzung für die Nutzung, sondern um die im Leitfaden genannte Vorauszahlungsbedingung. Prüfen Sie die Konto- und Abrechnungseinstellungen, bevor Sie zur kostenpflichtigen Nutzung wechseln.

Der Befehl zur Installation des Python-SDKs aus dem offiziellen Leitfaden lautet:

pip install -U google-genai

Schritt für Schritt einen Funktionsaufruf erstellen

1. Legen Sie den Zweck der Funktion fest. Funktionsname und Beschreibung sollten klar ausdrücken, was die Anwendung tut. In diesem Beispiel sollen passende Materialoptionen für ein Projekt in einem externen Katalog gesucht werden. Die Katalogabfrage selbst wird hier nicht ausgeführt; gezeigt wird, wie das Modell die dafür erforderlichen Argumente erstellt.

2. Definieren Sie die Informationen, die das Modell erhalten soll. Eine Nutzeranfrage könnte beispielsweise so lauten:

Projem için açık renkli, taş görünümlü zemin kaplamalarını malzeme kataloğunda ara.

Dieser Text veranschaulicht, wie das Modell eine natürlichsprachliche Anfrage in Funktionsparameter umwandelt. Welche Felder auf Anwendungsseite erforderlich sind, richtet sich nach der Struktur des Katalogs. Im folgenden Beispiel wird die Suchanfrage in einem einzigen Textfeld gespeichert.

1. Erstellen Sie das Funktionsschema. In den Beispielen von Google zu Function Calling werden Funktionsname, Beschreibung und Parameterschema festgelegt. Die Parametertypen werden angegeben; erforderliche Felder kommen in die Liste required. search_materials und das Feld query sind Beispiele, die für einen Architekturmaterialkatalog angepasst wurden.

from google import genai

search_materials_function = {
    "type": "function",
    "name": "search_materials",
    "description": "Searches a project material catalog using a text query.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The material search query."
            }
        },
        "required": ["query"]
    }
}

Formulieren Sie die Beschreibung so, dass sie die tatsächliche Aufgabe der Funktion erläutert. Wählen Sie auch Parameternamen, die mit den von der angebundenen Anwendung erwarteten Feldern übereinstimmen. Benötigt ein Katalog mehrere Filter, sollte das Schema entsprechend gestaltet werden. Die Felder und Filter müssen sich jedoch auf Informationen stützen, die im System tatsächlich vorhanden sind.

1. Senden Sie die Anfrage an die Gemini API und prüfen Sie den Aufrufschritt. In den Beispielen des Einstiegsleitfadens kommen der Client genai.Client(), die Anfrage interactions.create und Ergebnisfelder wie interaction.output_text zum Einsatz. Die Dokumentation zu Function Calling zeigt, wie in den Antwortschritten der Typ function_call überprüft und der Funktionsname samt Argumenten ausgelesen wird.

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Projem için açık renkli, taş görünümlü zemin kaplamalarını ara.",
    tools=[search_materials_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print("İşlev:", step.name)
        print("Argümanlar:", step.arguments)

In diesem Beispiel werden als Ausgabe der Funktionsname und die Argumente des Aufrufs erwartet. Prüfen Sie die vom Modell vorbereiteten Argumente auf Anwendungsseite. Der Zugriff auf den Katalog, die Ausführung der Abfrage und die Anzeige der Ergebnisse für den Nutzer sind Anwendungsschritte, die über dieses Beispiel hinausgehen.

1. Testen Sie die Eingaben vor dem produktiven Einsatz. Beobachten Sie anhand verschiedener Projektanfragen, welche Funktion das Modell auswählt und welche Argumente es erstellt. Entwerfen Sie in Ihrem eigenen System die erforderlichen Prüfungen, damit die Anwendung auch bei unklaren Anfragen sicher und korrekt arbeitet. Die Referenzleitfäden erläutern die API-Nutzung und die Aufrufschritte, garantieren jedoch weder die Richtigkeit eines bestimmten Architekturmaterialkatalogs noch die Qualität seiner Daten.

Häufige Fehler

• Eine unklare Funktionsbeschreibung: Die Aufgabe des ausgewählten Tools sollte eindeutig beschrieben sein. Funktionsname, Beschreibung und Parameterdefinitionen müssen zusammenpassen.

• Parameter nicht auf die Anwendung abstimmen: Die Felder im Schema müssen mit den Informationen übereinstimmen, die das externe System erwartet. Andernfalls kann die Anwendung die vom Modell erstellten Argumente möglicherweise nicht korrekt verwenden.

• Den Modellaufruf mit der eigentlichen Ausführung verwechseln: Function Calling erstellt den Aufruf und die Argumente für die Kommunikation mit einem externen System. Ob die Funktion im realen System ausgeführt wird, hängt von der Anbindung auf Anwendungsseite ab.

• Den API-Schlüssel nachlässig verwalten: Der Schlüssel hilft dabei, API-Anfragen einem Konto zuzuordnen und die Nutzung nachzuverfolgen. Im Einstiegsleitfaden wird beispielhaft gezeigt, wie der Schlüssel in einer Umgebungsvariable gespeichert wird.

• Nutzungslimits und Kosten außer Acht lassen: Beim Wechsel zum kostenpflichtigen Tarif ändern sich die Anfragekontingente und die Abrechnungseinstellungen. Prüfen Sie vor der Nutzung die Angaben zu Nutzung und Abrechnung in AI Studio.

Auswirkungen auf Architektur- und Visualisierungs-Workflows

Dieser Ansatz kann für Teams nützlich sein, die natürlichsprachliche Anfragen an von der Anwendung definierte Tools weiterleiten möchten. In einem Innenarchitekturprojekt könnte das Modell beispielsweise eine Materialanfrage in eine strukturierte Katalogabfrage umwandeln. Auch der Abruf von Informationen aus einer externen API oder Datenbank gehört zu den im Leitfaden genannten Einsatzbereichen. Das bedeutet nicht, dass bereits eine fertige Anbindung an Revit, 3ds Max oder eine andere Designsoftware besteht; die Integration muss eingerichtet werden.

Für Büros und Studierende sind vor allem der API-Schlüssel, die Kompatibilität der Anwendung mit dem externen System, Anfragekontingente und mögliche Bedingungen für die kostenpflichtige Nutzung wichtig. In den Quellen werden keine besonderen Hardwareanforderungen genannt. Statt von bestimmten Hardwarevoraussetzungen auszugehen, sollten Sie daher die API-Nutzung und die Frage prüfen, welche Daten im Workflow nach außen übertragen werden.

Nächste Schritte

Erstellen Sie zunächst ein Schema für eine klar abgegrenzte Funktion wie die Katalogsuche und prüfen Sie die zurückgegebenen Argumente anhand von Beispielanfragen. Legen Sie anschließend eine externe API oder Datenquelle fest, die diese Argumente auf Anwendungsseite verarbeitet. Wenn Sie eine andere Sprache bevorzugen, können Sie auch die JavaScript- oder REST-Beispiele im offiziellen Einstiegsleitfaden ansehen. Für mehrstufige Gespräche beschreibt der Leitfaden previous_interaction_id, bei dem der Server den Verlauf verwaltet, als empfohlene Methode zur Zustandsverwaltung.

Quellen und Lizenz

Dieser Leitfaden wurde anhand der Dokumentation von Google zu Gemini API Function Calling und des Einstiegsleitfadens erstellt. Beide Quellen stehen unter der Lizenz CC BY 4.0. Der Inhalt wurde ins Türkische übersetzt und an das Szenario eines Architekturmaterialkatalogs angepasst.