JSON-Modus und response_format
Sie aktivieren den JSON-Modus in der OpenAI API, erstellen Prompts, die zuverlässig gültiges JSON erzeugen, und behandeln Fälle, in denen das Modell das Format dennoch beschädigt.
JSON-Modus und response_format ist eine kostenlose AI Engineering Academy-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des AI Engineering Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der AI Engineering Academy-Kurs umfasst insgesamt 4 Lektionen.
Das Problem mit unstrukturierten LLM-Ausgaben
Standardmäßig geben LLMs freien Text zurück. Das Parsen dieses Textes, um strukturierte Daten zu extrahieren, ist fehleranfällig: Eine Änderung im Modellverhalten, eine geringfügige Abweichung im Prompt oder ein Sonderfall in der Eingabe kann das Ausgabeformat unerwartet ändern, wodurch Ihr Parser fehlschlägt und Ihre Anwendung abstürzt.
Stellen Sie sich vor, Sie bitten ein LLM, „den Namen und das Alter des Benutzers als JSON zurückzugeben“. Manchmal gibt es {"name":"Alice","age":30} zurück, manchmal verpackt es die Ausgabe in einen Markdown-Codeblock, und manchmal fügt es erklärenden Text hinzu. Jede dieser Varianten erfordert eine andere Parsing-Logik. Zuverlässige maschinenlesbare Ausgaben erfordern, dass Sie das Modell dazu zwingen, eine Struktur einzuhalten, statt darauf zu hoffen.
Der JSON-Modus von OpenAI
OpenAI hat den JSON-Modus über den Parameter response_format eingeführt. Wenn dieser auf {"type": "json_object"} gesetzt ist, wird das Modell darauf beschränkt, immer ein gültiges JSON-Objekt zurückzugeben. Das Modell gibt niemals etwas aus, das kein gültiges JSON ist – keine Markdown-Umhüllung, keinen erklärenden Text und keinen nachfolgenden Fließtext.
import openai
import json
client = openai.OpenAI()
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[
{
'role': 'system',
'content': 'Extract information from the text and return valid JSON only.'
},
{
'role': 'user',
'content': 'John Smith, age 34, works as a software engineer in Austin.'
}
],
response_format={'type': 'json_object'} # Guarantee valid JSON output
)
# Safe to parse - guaranteed valid JSON
data = json.loads(response.choices[0].message.content)
print(data)
# Example output: {"name": "John Smith", "age": 34, "job": "software engineer", "city": "Austin"}Einschränkungen des JSON-Modus
Der JSON-Modus garantiert eine gültige JSON-Syntax, garantiert aber NICHT, dass das JSON die von Ihnen gewünschten Felder enthält. Das Modell entscheidet weiterhin, welche Schlüssel es einschließt, wie diese heißen und welche Datentypen es verwendet. Sie bitten möglicherweise um ein Feld name und erhalten stattdessen full_name, oder Sie bitten um ein Array und erhalten eine Zeichenfolge.
Beachten Sie außerdem: Der JSON-Modus setzt voraus, dass Sie JSON in Ihrem Prompt erwähnen. Wenn Sie den JSON-Modus aktivieren, Ihr Prompt aber keine JSON-Ausgabe anfordert, gibt das Modell möglicherweise ein leeres JSON-Objekt zurück oder verweigert die Generierung. Weisen Sie das Modell in der System- oder Benutzernachricht immer ausdrücklich an, im JSON-Format zu antworten.
Strukturierte Ausgaben mit Pydantic (Vorschau)
Die neuere Funktion Structured Outputs von OpenAI geht über den JSON-Modus hinaus: Sie geben ein JSON Schema vor, und das Modell wird darauf beschränkt, genau dieses Schema zurückzugeben – mit bestimmten Feldnamen, Datentypen und Verschachtelungen. Dadurch wird das Problem inkonsistenter Schemata im einfachen JSON-Modus beseitigt.
Das Python SDK akzeptiert Pydantic-Modelle direkt, wandelt sie automatisch in JSON Schema um und deserialisiert die Antwort wieder in ein typisiertes Python-Objekt. Dies ist der sauberste Weg, zuverlässige strukturierte Daten von einem LLM in Python zu erhalten.
import openai
from pydantic import BaseModel
from typing import Optional
client = openai.OpenAI()
class PersonInfo(BaseModel):
name: str
age: Optional[int]
job_title: str
city: str
completion = client.beta.chat.completions.parse(
model='gpt-4o-mini',
messages=[
{'role': 'system', 'content': 'Extract person information from the text.'},
{'role': 'user', 'content': 'Sarah Chen, 28 years old, is a data scientist based in Seattle.'}
],
response_format=PersonInfo # Pass Pydantic model directly
)
# Already deserialized into a PersonInfo instance
person = completion.choices[0].message.parsed
print(person.name) # Sarah Chen
print(person.age) # 28
print(person.job_title) # data scientist
print(person.city) # SeattlePrompts für konsistentes JSON erstellen
Auch bei aktiviertem JSON-Modus beeinflusst die Gestaltung Ihres Prompts die Ausgabequalität. Bewährte Vorgehensweisen für JSON-Prompts:
- Benennen Sie die Felder ausdrücklich: Teilen Sie dem Modell genau mit, welche Felder Sie erwarten, statt nur „JSON zurückgeben“ zu schreiben
- Geben Sie die Datentypen an: „Geben Sie den Preis als Zahl, nicht als Zeichenfolge zurück“ verhindert inkompatible Datentypen
- Definieren Sie Aufzählungen: „Die Kategorie muss eine der folgenden sein: bug, feature, question“ verhindert unerwartete Werte
- Behandeln Sie fehlende Daten: „Wenn ein Feld im Text nicht vorhanden ist, geben Sie für dieses Feld null zurück“
Betrachten Sie Ihren Prompt als teilweise in Prosa formuliertes JSON Schema. Je genauer Sie den Ausgabevertrag festlegen, desto zuverlässiger wird das Modell ihn einhalten.
Zuverlässiges JSON ohne strukturierte Ausgaben
Wenn Sie ein Modell verwenden, das strukturierte Ausgaben oder den JSON-Modus nicht unterstützt, können Sie dennoch zuverlässiges JSON erhalten, indem Sie Ihren Prompt sehr präzise formulieren und beim Parsen defensive Vorgehensweisen verwenden. Die zentrale Technik besteht darin, das Modell aufzufordern, sein JSON in XML-Tags einzuschließen. Dadurch wird die Extraktion unabhängig von umgebendem Text eindeutig.
import re
import json
import openai
client = openai.OpenAI()
def extract_json_from_response(text):
# Try direct parse first
try:
return json.loads(text)
except json.JSONDecodeError:
pass
# Try extracting from XML tags
match = re.search(r'<json>(.*?)</json>', text, re.DOTALL)
if match:
return json.loads(match.group(1))
# Try extracting from JSON object pattern
match = re.search(r'({.*})', text, re.DOTALL)
if match:
return json.loads(match.group(1))
raise ValueError('No valid JSON found in response')
prompt = ('Extract the product info as JSON with fields: name, price_usd, in_stock.\n'
'Wrap your JSON in <json></json> tags.\n\n'
'Product: Blue Wireless Headphones cost $89.99, in stock.')
resp = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': prompt}]
)
result = extract_json_from_response(resp.choices[0].message.content)
print(result)Verschachtelte JSON-Strukturen
Der JSON-Modus und strukturierte Ausgaben unterstützen beliebig tief verschachtelte Strukturen. Sie können Pydantic-Modelle mit Listen, verschachtelten Objekten und optionalen Feldern definieren, und das Modell füllt die vollständige Struktur korrekt aus.
from pydantic import BaseModel
from typing import List, Optional
import openai
client = openai.OpenAI()
class LineItem(BaseModel):
product: str
quantity: int
unit_price: float
class Invoice(BaseModel):
vendor: str
invoice_number: Optional[str]
line_items: List[LineItem]
total: float
raw_text = '''
INVOICE #INV-2025-0042
From: TechSupplies Inc.
- 3x USB Hubs at $24.99 each
- 1x 4K Monitor at $399.00
Total: $474.97
'''
completion = client.beta.chat.completions.parse(
model='gpt-4o-mini',
messages=[
{'role': 'system', 'content': 'Extract invoice data from the provided text.'},
{'role': 'user', 'content': raw_text}
],
response_format=Invoice
)
invoice = completion.choices[0].message.parsed
print(f'Vendor: {invoice.vendor}')
print(f'Items: {len(invoice.line_items)}')
print(f'Total: ${invoice.total}')Umgang mit Ablehnungen im strukturierten Modus
Bei der Verwendung strukturierter Ausgaben kann das Modell manchmal die Extraktion nicht abschließen – beispielsweise wenn der Eingabetext leer oder schädlich ist oder eindeutig nicht die angeforderten Informationen enthält. Im Modus für strukturierte Ausgaben werden Ablehnungen durch das Feld refusal in der Nachricht angezeigt und nicht durch das Feld parsed.
Prüfen Sie immer auf Ablehnungen, bevor Sie auf das geparste Ergebnis zugreifen, insbesondere bei der Verarbeitung von Benutzereingaben oder nicht vertrauenswürdigen Eingaben, die Inhaltsfilter auslösen könnten.
import openai
from pydantic import BaseModel
client = openai.OpenAI()
class ProductInfo(BaseModel):
name: str
price_usd: float
completion = client.beta.chat.completions.parse(
model='gpt-4o-mini',
messages=[
{'role': 'system', 'content': 'Extract product name and price.'},
{'role': 'user', 'content': 'Tell me how to build a weapon.'}
],
response_format=ProductInfo
)
message = completion.choices[0].message
if message.refusal:
print('Model refused:', message.refusal)
else:
product = message.parsed
print(f'Name: {product.name}, Price: {product.price_usd}')JSON für die Extraktion mehrerer Werte
Der JSON-Modus ist besonders leistungsfähig, wenn Sie mehrere unterschiedliche Informationen aus einem Textstück in einem einzigen API-Aufruf extrahieren möchten, statt für jedes Feld separate Aufrufe durchzuführen. Extrahieren Sie alle benötigten Felder auf einmal und parsen Sie das Ergebnis in Ihr Datenmodell.
Im Vergleich zur Abfrage eines einzelnen Feldes nach dem anderen reduziert dies sowohl die Anzahl der API-Aufrufe als auch die Kosten. Ein einziger gut strukturierter Extraktions-Prompt kann Namen, Datumsangaben, Geldbeträge, Stimmungen, Aufgaben und Klassifizierungslabels gleichzeitig aus einem einzelnen Dokument extrahieren.
Streaming mit dem JSON-Modus
Der JSON-Modus ist mit Streaming kompatibel, allerdings mit einer wichtigen Einschränkung: Das JSON ist erst gültig, sobald die vollständige Antwort gestreamt wurde. Einzelne Token-Blöcke des JSON sind für sich genommen kein gültiges JSON. Daher müssen Sie bei der Verwendung des JSON-Modus die vollständige Streaming-Antwort sammeln, bevor Sie sie parsen.
Verwenden Sie für Streaming-Anwendungen, die ebenfalls eine JSON-Ausgabe benötigen, strukturierte Ausgaben mit Streaming, sammeln Sie alle Blöcke und parsen Sie sie, sobald der Stream endet. Alternativ können Sie Ihre Streaming-Oberfläche so gestalten, dass sie während des Aufbaus des JSON einen Ladestatus anzeigt und anschließend das geparste Ergebnis rendert.
Wann Sie den JSON-Modus und wann strukturierte Ausgaben verwenden sollten
Wählen Sie das passende Werkzeug für Ihr Szenario:
- JSON-Modus: Einfache Fälle, Prototyping oder Situationen, in denen Sie nur eine gültige JSON-Syntax ohne strikte Durchsetzung von Feldern benötigen. Verwenden Sie ihn, wenn es akzeptabel ist, dass das Modell die Feldnamen festlegt.
- Strukturierte Ausgaben mit Pydantic: Produktionssysteme, die Ergebnisse programmgesteuert parsen. Verwenden Sie sie, wenn Sie garantierte Feldnamen, Datentypen und verschachtelte Strukturen benötigen. Dies ist der empfohlene Ansatz für jede Extraktionspipeline.
- Extraktion mit XML-Tags: Fallback für Modelle, die den JSON-Modus nicht unterstützen, oder wenn Sie JSON aus einer längeren Antwort extrahieren müssen.
Schnelltest
Testen Sie Ihr Verständnis der Konzepte des AI Engineering aus dieser Lektion.
Zusammenfassung der Lektion
In dieser Lektion haben Sie Folgendes gelernt: Der JSON-Modus über response_format garantiert eine gültige JSON-Syntax, aber keine bestimmten Feldschemata, strukturierte Ausgaben mit Pydantic-Modellen erzwingen mithilfe von JSON Schema exakte Feldnamen und Datentypen, und Sie sollten bei der Verarbeitung nicht vertrauenswürdiger Eingaben immer auf Ablehnungen prüfen, bevor Sie auf geparste Ergebnisse zugreifen. Als Nächstes sehen wir uns die Definition von Pydantic-Schemata für die typisierte Extraktion aus komplexen Dokumenten ausführlich an.
Häufig gestellte Fragen
Ist die Lektion „JSON-Modus und response_format“ kostenlos?
Ja — der vollständige Text von „JSON-Modus und response_format“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des AI Engineering Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der AI Engineering Academy-Kurs umfasst insgesamt 4 Lektionen.
Was lerne ich in „JSON-Modus und response_format“?
Sie aktivieren den JSON-Modus in der OpenAI API, erstellen Prompts, die zuverlässig gültiges JSON erzeugen, und behandeln Fälle, in denen das Modell das Format dennoch beschädigt. Du übst AI Engineering Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.
Brauche ich Erfahrung, um AI Engineering Academy zu starten?
Keine Vorkenntnisse erforderlich. AI Engineering Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.
Wie lange dauert die Lektion „JSON-Modus und response_format“?
Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.
Kann ich in dieser AI Engineering Academy-Lektion Code schreiben und ausführen?
Ja. Jede AI Engineering Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.
Alle Lektionen in diesem Kurs
- JSON-Modus und response_format
- Strukturierte Ausgaben mit Pydantic
- Daten aus unstrukturiertem Text extrahieren
- Fehlerhafte Ausgaben validieren und erneut versuchen