Mit der Gemini API strukturierte JSON-Ausgaben aus Architekturtexten erzeugen

Was lernen Sie in diesem Leitfaden?

Ein Projektbrief, Materialnotizen oder eine Raumbeschreibung liegen oft als Freitext vor. Wenn daraus Angaben wie Raumname, Material und Nutzungszweck strukturiert extrahiert werden sollen, kann eine Antwort ausschließlich in natürlicher Sprache die Weiterverarbeitung erschweren. Mit der Funktion für strukturierte Ausgaben der Gemini API lässt sich vorgeben, dass die Modellantwort einem zuvor definierten JSON Schema entspricht.

In diesem Beispiel behandeln wir drei Punkte gemeinsam: die erwarteten Felder festlegen, Aufgabe und Einschränkungen in einem klaren Prompt beschreiben und anschließend das passende Schema in die API-Anfrage aufnehmen. Die Beispiele sind auf architektonische Workflows zugeschnitten; die folgenden Prompts stehen nicht wörtlich in den Quellen, sondern sind eigenständige Beispiele auf Grundlage der dokumentierten Methoden.

Voraussetzungen und Umfang

In der Dokumentation von Google wird die Unterstützung von JSON Schema in der REST API für strukturierte Ausgaben erwähnt. Für die Google GenAI SDKs werden Pydantic für Python und Zod für JavaScript als Optionen zur Schema-Definition aufgeführt. Die Quellen enthalten auch Beispiele für Java, Go und weitere Sprachen; in diesem Leitfaden verwenden wir statt Code einen leicht übertragbaren JSON-Schema-Entwurf.

In den Dokumentationsbeispielen wird darauf hingewiesen, dass Zod für JavaScript installiert werden muss. Informationen zu SDK-Version, Kontobedingungen oder Kosten werden in diesen Quellen jedoch nicht genannt. Prüfen Sie deshalb vor Projektbeginn die aktuellen Anforderungen des verwendeten SDKs und Modells in der Gemini-API-Dokumentation. Im oberen Teil der Dokumentation wird Gemini 4 Argon als verfügbar genannt, während im Beispielcode der Modellname gemini-3.8-flash vorkommt. Gehen Sie nicht automatisch davon aus, dass dieses Beispielmodell aktuell oder für jeden Anwendungsfall geeignet ist.

1. Legen Sie fest, welche Felder extrahiert werden sollen

Bevor Sie ein Schema erstellen, entscheiden Sie, welche Daten aus dem Text extrahiert werden sollen und welchen Typ die einzelnen Werte haben. Der folgende Entwurf zielt beispielsweise darauf ab, aus einem Innenraum-Briefing den Raumnamen, das genannte Material und eine Funktionsbeschreibung zu extrahieren. Die grundlegenden JSON-Schema-Strukturen wie object, properties, string und required entsprechen den in den Quellen gezeigten Beispielen.

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

Hier sind alle drei Felder Pflichtfelder. Legen Sie im Prompt außerdem fest, was geschehen soll, wenn eine Angabe im Ausgangstext fehlt. Sie können etwa verlangen, dass das Feld leer bleibt oder mit „nicht angegeben“ ausgefüllt wird. Welche Variante sinnvoll ist, hängt davon ab, wie die Projektdaten verarbeitet werden. Wenn Sie diese Entscheidung bereits bei der Schemaerstellung treffen, lassen sich teamweit konsistente Ergebnisse erzielen.

2. Beschreiben Sie Aufgabe und Eingabe klar

Ein guter Prompt beschreibt verständlich, was zu tun ist, welcher Text verarbeitet werden soll und in welchem Format die Antwort erwartet wird. Der Leitfaden von Google zum Prompt-Design empfiehlt klare und konkrete Anweisungen sowie – falls nötig – die Angabe von Einschränkungen und Formatvorgaben. Das folgende Beispiel können Sie an Ihre eigenen Briefing-Felder anpassen.

Extrahiere aus dem folgenden Innenraum-Projektbrief den Raumnamen, das ausdrücklich genannte Material und die Funktion des Raums. Verwende ausschließlich Informationen aus dem Text. Wenn eine Angabe im Text fehlt, schreibe dafür „nicht angegeben“. Gib die Antwort als JSON-Objekt aus, dessen Felder dem bereitgestellten JSON-Schema entsprechen.

Briefing: Im Erdgeschoss befindet sich ein Lesebereich mit Eichenfurnieroberflächen und gemeinschaftlich genutzten Arbeitstischen.

Dieser Prompt gibt den Text als Eingabe vor, definiert die Extraktionsaufgabe und legt fest, wie mit unbekannten Angaben umzugehen ist. Die Funktion für strukturierte Ausgaben sorgt zudem dafür, dass die erwartete Antwort dem Schema entspricht. Prompt und Schema sollten dieselben Felder beschreiben: Verlangen Sie im Prompt keine zusätzlichen Schlüssel, die im Schema fehlen, und lassen Sie angeforderte Felder nicht aus dem Schema weg.

3. Grenzen Sie die Vorgaben entsprechend dem Projektbedarf ein

In Architekturdokumenten ist es wichtig, Interpretationen von Quellenangaben zu trennen. Wenn Sie beispielsweise eine Materialliste extrahieren, weisen Sie ausdrücklich an, keine Produkte oder technischen Eigenschaften hinzuzufügen, die im Text nicht vorkommen. Der folgende Prompt konzentriert sich darauf, ausschließlich die schriftlich genannten Materialien aus einer Raumbeschreibung zu sammeln.

Extrahiere die in dieser Raumbeschreibung genannten Verkleidungs- und Oberflächenmaterialien. Schlage keine neuen Materialien vor und ergänze weder Synonyme noch vermutete Marken. Gib das Ergebnis als Liste aus, die ausschließlich Materialnamen enthält.

Beschreibung: In der Eingangshalle sind ein Terrazzo-Boden und eine gestrichene Gipswandoberfläche vorgesehen.

In diesem Beispiel wird eine Listenform verlangt. Verwenden Sie es daher nicht unverändert für dieselbe Aufgabe wie das vorherige Schema, das ein JSON-Objekt erwartet. Das Antwortformat richtet sich nach dem Bedarf: Wenn Sie strukturierte Ausgaben verwenden, muss das Schema zum im Prompt beschriebenen Ergebnis passen. Statt ein einziges Schema für verschiedene Aufgabentypen wiederzuverwenden, sollten Sie die Felder und Datentypen für jede Aufgabe neu prüfen.

4. Zeigen Sie das Format anhand einer Beispielantwort

Wenn sich die gewünschte Klassifizierung oder das Schreibmuster einer Aufgabe mit Worten nur schwer eindeutig beschreiben lässt, können kurze Beispiele das Format verdeutlichen. Laut Google-Leitfaden lässt sich beim Few-Shot-Ansatz ein Beispiel für Eingabe und erwartetes Antwortformat zeigen; klare und abwechslungsreiche Beispiele können dabei hilfreich sein.

Klassifiziere die neue Raumnotiz anhand der Felder im folgenden Beispiel.

Beispielnotiz: „Küchenarbeitsplatte aus Quarzkomposit, Schrankfronten matt lackiert.“
Beispielausgabe: {"mekan": "Küche", "malzemeler": ["Quarzkomposit", "matte Lackierung"]}

Neue Notiz: „Im Arbeitszimmer gibt es einen Holzboden und gestrichenen Putz.“
Antworte ausschließlich im selben Feldformat.

Dieses Beispiel veranschaulicht das Ausgabeformat. Das Schema, das in der tatsächlichen API-Anfrage verwendet wird, müssen Sie zusätzlich definieren. Der Quellleitfaden empfiehlt, mit wenigen Beispielen zu beginnen und je nach Anwendungsfall auszuprobieren, wie viele Beispiele sinnvoll sind. Außerdem wird darauf hingewiesen, dass zu viele Beispiele zu einer Überanpassung des Modells führen können.

Häufige Fehler

Ein häufiges Problem ist, die Anforderungen nur im Prompt zu beschreiben, ohne auf API-Seite ein Schema anzugeben. Google zufolge lassen sich einfache JSON-Formate in natürlicher Sprache anfordern; bei komplexeren Anforderungen an JSON Schema wird jedoch die Funktion für strukturierte Ausgaben empfohlen. Ein zweites Problem: Schema und Prompt verlangen unterschiedliche Felder oder Antwortformate. Legen Sie zuerst Felder und Datentypen fest und formulieren Sie den Prompt anschließend passend zu dieser Struktur.

Ein weiterer Fehler besteht darin, bei unklaren Texten zu erwarten, dass das Modell Details ergänzt, die in der Quelle nicht vorkommen. Geben Sie im Prompt an, welche Informationen extrahiert und welche weggelassen werden sollen und wie fehlende Angaben darzustellen sind. Ein Schema trägt zur Formatkonsistenz bei; es garantiert jedoch nicht automatisch die Richtigkeit oder Vollständigkeit der Projektquelle. Besonders bei Abgabe- und Dokumentationsprozessen ist es wichtig, die erzeugten Datensätze mit dem Originalbriefing abzugleichen.

Einsatz in Architektur- und Visualisierungs-Workflows

Dieser Ansatz kann für Architekturbüros, Innenarchitektinnen und Innenarchitekten sowie Studierende nützlich sein, die eine große Zahl von Projektnotizen in dieselben Felder aufteilen müssen. Das Extrahieren von Materialnamen, Raumtypen oder Funktionsbeschreibungen aus Raumbeschreibungen bietet einen strukturierten Ausgangspunkt für Workflows, in denen diese Daten anschließend an ein anderes Tool übergeben werden. Die Quellen beschreiben keine Integration mit einer bestimmten BIM-, CAD- oder Visualisierungssoftware. Verbindung und Kompatibilität müssen daher separat geprüft werden.

Büros sollten zunächst mit einer kleinen Textmenge testen, ob die Felder zweckmäßig sind. Anschließend sollten sie prüfen, wie dasselbe Schema und derselbe Prompt bei unterschiedlichen Briefings funktionieren. Für Studierende verbindet die Methode auf praktische Weise die Datenextraktion aus Freitext mit dem Verständnis der JSON-Struktur. Die Quellen enthalten keine Angaben zu Hardware, Lizenzen oder API-Nutzungskosten. Prüfen Sie diese Punkte vor dem Einsatz in der Produktion in der Dokumentation des jeweiligen Dienstes.

Nächste Schritte

Wählen Sie zunächst einen einzelnen Anwendungsfall aus, zum Beispiel die Extraktion von Materialien aus einer Raumnotiz. Legen Sie die Felder fest, erstellen Sie das Schema und testen Sie es anschließend mit einem klar formulierten Prompt. Vergleichen Sie die Ergebnisse mit dem Quelltext, beobachten Sie wiederkehrende Fehler und ergänzen Sie Beispiele im Prompt nur, wenn sie tatsächlich nötig sind. Wenn Sie Python verwenden, prüfen Sie Pydantic als Option zur Schema-Definition; bei JavaScript kommt Zod infrage. Auch die Nutzung der REST API wird in der Dokumentation unterstützt.

Wenn das Projekt wächst, dokumentieren Sie Schemaänderungen und erwartete Felder im Team. So lässt sich leichter nachverfolgen, ob dieselbe Datenstruktur in verschiedenen Aufgaben zur Verarbeitung von Architekturbriefings erhalten bleibt. Das Ziel für den Einstieg ist nicht, alles zu automatisieren, sondern eine wiederkehrende Textaufgabe mit klaren Regeln und einem überprüfbaren Antwortformat zu testen.

Quelle und Lizenz

Dieser Leitfaden wurde auf Grundlage der Google-Dokumentation „Structured outputs“ und „Prompt design strategies“ ins Türkische übertragen. Beide Quellen stehen unter der Lizenz CC BY 4.0.