Funktionsschemas für die API definieren
Schreiben Sie JSON-Schema-Definitionen für Ihre Funktionen, übergeben Sie sie im Parameter tools und verstehen Sie, wie das Modell entscheidet, wann und wie es sie aufruft.
Funktionsschemas für die API definieren 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.
Was ist Function Calling?
OpenAIs function calling (heute tool calling genannt) ermöglicht es Ihnen, dem Modell Python-Funktionen in einem strukturierten JSON-Schema-Format zu beschreiben. Wenn das Modell feststellt, dass eine Funktion aufgerufen werden sollte, gibt es statt eines Freitexts ein strukturiertes JSON-Objekt mit dem Funktionsnamen und den Argumenten zurück, das Ihr Code anschließend zuverlässig ausführt.
Die Struktur des tools-Parameters
Sie übergeben Ihre Funktionsdefinitionen in der API im Parameter tools als Liste von Objekten. Jedes Objekt hat den Wert 'function' für type und einen Schlüssel function, der den Namen, die Beschreibung und ein JSON Schema für die Parameter enthält.
from openai import OpenAI
client = OpenAI()
tools = [
{
'type': 'function',
'function': {
'name': 'get_current_weather',
'description': 'Get the current weather in a given location.',
'parameters': {
'type': 'object',
'properties': {
'location': {
'type': 'string',
'description': 'City and country, e.g. London, UK'
},
'unit': {
'type': 'string',
'enum': ['celsius', 'fahrenheit'],
'description': 'Temperature unit to use.'
}
},
'required': ['location']
}
}
}
]JSON Schema für Parameter
Das Feld parameters folgt der Spezifikation von JSON Schema. Verwenden Sie type, um string, number, integer, boolean, array oder object festzulegen. Verwenden Sie für jede Eigenschaft description, um dem Modell die Bedeutung des Feldes zu erklären. Führen Sie erforderliche Felder im Array required auf; optionale Felder können dort weggelassen werden.
# A more complex schema with multiple types
create_event_tool = {
'type': 'function',
'function': {
'name': 'create_calendar_event',
'description': 'Create a new calendar event. Use when the user wants to schedule a meeting or appointment.',
'parameters': {
'type': 'object',
'properties': {
'title': {'type': 'string', 'description': 'Event title.'},
'start_time': {'type': 'string', 'description': 'ISO 8601 datetime, e.g. 2024-03-15T14:00:00.'},
'duration_minutes': {'type': 'integer', 'description': 'Duration in minutes.', 'minimum': 5},
'attendees': {
'type': 'array',
'items': {'type': 'string'},
'description': 'List of email addresses of attendees.'
},
'location': {'type': 'string', 'description': 'Physical or virtual meeting location.'}
},
'required': ['title', 'start_time', 'duration_minutes']
}
}
}API-Aufruf mit Tools
Übergeben Sie die Liste tools direkt an chat.completions.create. Das Modell kann mit einer normalen Textnachricht antworten, wenn es ohne Funktion antworten kann, oder mit einem tool_calls-Objekt, das Sie anweist, eine Funktion auszuführen. Prüfen Sie immer finish_reason, um zu erkennen, welcher Fall vorliegt.
response = client.chat.completions.create(
model='gpt-4o',
messages=[
{'role': 'user', 'content': 'What is the weather in Tokyo?'}
],
tools=tools
)
print('Finish reason:', response.choices[0].finish_reason)
# 'tool_calls' means the model wants to call a function
# 'stop' means the model gave a regular text response
choice = response.choices[0].message
if response.choices[0].finish_reason == 'tool_calls':
print('Model wants to call:', choice.tool_calls[0].function.name)Tool-Auswahl mit tool_choice steuern
Der Parameter tool_choice steuert, ob das Modell eine Funktion aufrufen muss oder frei wählen kann. Mit 'auto' überlassen Sie die Entscheidung dem Modell. Mit 'required' erzwingen Sie einen Tool-Aufruf. Wenn Sie einen bestimmten Funktionsnamen angeben, erzwingen Sie den Aufruf genau dieser Funktion. Das ist nützlich für Extraktionsaufgaben, bei denen Sie immer eine strukturierte Ausgabe benötigen.
# Force the model to always call extract_contact
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'Hi, I am John Smith, john@example.com, +1-555-0100.'}],
tools=[extract_contact_tool],
tool_choice={'type': 'function', 'function': {'name': 'extract_contact'}}
)
# With tool_choice forced, finish_reason will always be 'tool_calls'Enum-Felder für eingeschränkte Auswahlmöglichkeiten
Verwenden Sie das Feld enum in Ihrem JSON Schema, wenn ein Parameter auf eine feste Menge von Werten beschränkt werden soll. Das verbessert die Zuverlässigkeit erheblich: Das Modell erfindet deutlich seltener eine ungültige Option, wenn es die genau zulässigen Werte im Schema sehen kann.
classify_sentiment_tool = {
'type': 'function',
'function': {
'name': 'classify_sentiment',
'description': 'Classify the sentiment of a customer review.',
'parameters': {
'type': 'object',
'properties': {
'sentiment': {
'type': 'string',
'enum': ['positive', 'negative', 'neutral', 'mixed'],
'description': 'The sentiment classification.'
},
'confidence': {
'type': 'number',
'minimum': 0.0,
'maximum': 1.0,
'description': 'Model confidence from 0 to 1.'
}
},
'required': ['sentiment', 'confidence']
}
}
}Verschachtelte Objekt-Schemas
JSON Schema unterstützt verschachtelte Objekte. Verwenden Sie 'type': 'object' mit eigenen properties, um komplexe hierarchische Datenstrukturen zu definieren. Das eignet sich besonders zum Extrahieren strukturierter Daten aus unstrukturiertem Text wie E-Mails oder Dokumenten.
extract_order_tool = {
'type': 'function',
'function': {
'name': 'extract_order',
'description': 'Extract order details from a customer email.',
'parameters': {
'type': 'object',
'properties': {
'customer': {
'type': 'object',
'properties': {
'name': {'type': 'string'},
'email': {'type': 'string', 'format': 'email'}
},
'required': ['name']
},
'items': {
'type': 'array',
'items': {
'type': 'object',
'properties': {
'product_id': {'type': 'string'},
'quantity': {'type': 'integer', 'minimum': 1}
},
'required': ['product_id', 'quantity']
}
}
},
'required': ['customer', 'items']
}
}
}Schemas aus Pydantic-Modellen generieren
JSON Schemas von Hand zu schreiben ist mühsam und fehleranfällig. Definieren Sie Ihre Datenstruktur stattdessen als Pydantic model und verwenden Sie .schema(), um das JSON Schema automatisch zu generieren. Beim Deserialisieren der Modellantwort erhalten Sie dadurch außerdem eine Validierung auf Python-Ebene.
from pydantic import BaseModel, Field
from typing import Optional, List
class ContactInfo(BaseModel):
name: str = Field(description='Full name of the person.')
email: Optional[str] = Field(None, description='Email address.')
phone: Optional[str] = Field(None, description='Phone number in E.164 format.')
company: Optional[str] = Field(None, description='Company or organization.')
# Auto-generate the JSON Schema
schema = ContactInfo.schema()
# Build the tool definition
extract_contact_tool = {
'type': 'function',
'function': {
'name': 'extract_contact',
'description': 'Extract contact information from text.',
'parameters': schema
}
}Wirksame Funktionsbeschreibungen schreiben
Die Funktionsbeschreibung ist das wichtigste Signal, anhand dessen das Modell entscheidet, wann es ein Tool aufrufen soll. Eine gute Beschreibung erläutert den Anwendungsfall konkret, nennt, wann die Funktion aufgerufen werden sollte und wann nicht, und beschreibt, wie die Ausgabe aussieht. Vage Beschreibungen führen dazu, dass das Modell die falsche Funktion aufruft oder geeignete Aufrufmöglichkeiten verpasst.
- Vage: 'Get weather data.'
- Gut: 'Get the current weather conditions for a specific city. Use when the user explicitly asks about weather in a named location. Returns temperature, conditions, and humidity.'
Strict Mode für garantierte Schemaeinhaltung
Der strict mode von OpenAI für strukturierte Ausgaben garantiert, dass das Modell JSON erzeugt, das exakt Ihrem Schema entspricht: ohne zusätzliche Felder und ohne fehlende erforderliche Felder. Aktivieren Sie ihn, indem Sie 'strict': true in der Funktionsdefinition festlegen. Hinweis: Für den Strict Mode ist additionalProperties: false in allen Schemaobjekten erforderlich.
strict_tool = {
'type': 'function',
'function': {
'name': 'classify_ticket',
'description': 'Classify a support ticket into category and priority.',
'strict': True, # Enable strict schema adherence
'parameters': {
'type': 'object',
'additionalProperties': False, # Required for strict mode
'properties': {
'category': {
'type': 'string',
'enum': ['billing', 'technical', 'account', 'other']
},
'priority': {
'type': 'string',
'enum': ['low', 'medium', 'high', 'urgent']
}
},
'required': ['category', 'priority']
}
}
}Ihre Funktionsschemas testen
Testen Sie jedes Funktionsschema vor der Bereitstellung mit vielfältigen Eingaben: normalen Fällen, Grenzfällen und adversarialen Eingaben. Überprüfen Sie, ob das Modell die richtige Funktion aufruft, gültige Argumenttypen erzeugt, optionale Felder korrekt verarbeitet und Enum-Beschränkungen einhält. Verwenden Sie den OpenAI Playground, um schnell zu iterieren, bevor Sie produktiven Code schreiben.
Kurztest
Testen Sie Ihr Verständnis der Definition von Funktionsschemas für die OpenAI API.
Zusammenfassung der Lektion
In dieser Lektion haben Sie gelernt: Funktionsschemas verwenden JSON Schema, um Parametertypen, Beschreibungen und Einschränkungen zu definieren, tool_choice steuert, ob das Modell eine Funktion aufrufen muss oder frei wählt, und Pydantic-Modelle können JSON Schema automatisch generieren und so das manuelle Schreiben von Schemas reduzieren. Als Nächstes lernen Sie, Tool-Aufrufe in Ihrer Anwendung zu verarbeiten, indem Sie sie erkennen, ausführen und die Ergebnisse zurücksenden.
Häufig gestellte Fragen
Ist die Lektion „Funktionsschemas für die API definieren“ kostenlos?
Ja — der vollständige Text von „Funktionsschemas für die API definieren“ 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 „Funktionsschemas für die API definieren“?
Schreiben Sie JSON-Schema-Definitionen für Ihre Funktionen, übergeben Sie sie im Parameter tools und verstehen Sie, wie das Modell entscheidet, wann und wie es sie aufruft. 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 „Funktionsschemas für die API definieren“?
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
- Funktionsschemas für die API definieren
- Tool-Aufrufe in Ihrer Anwendung verarbeiten
- Parallele Funktionsaufrufe
- Eine natürlichsprachliche Datenbankschnittstelle entwickeln