Definiowanie schematów funkcji dla API
Napisz definicje JSON Schema dla funkcji, przekaż je w parametrze tools i poznaj sposób, w jaki model decyduje, kiedy oraz jak je wywoływać.
Definiowanie schematów funkcji dla API to bezpłatna lekcja AI Engineering Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Engineering Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.
Czym jest wywoływanie funkcji?
Wywoływanie funkcji OpenAI (obecnie nazywane wywoływaniem narzędzi) umożliwia opisanie funkcji języka Python za pomocą ustrukturyzowanego formatu JSON Schema. Gdy model ustali, że należy wywołać funkcję, zamiast generować swobodny tekst zwraca ustrukturyzowany obiekt JSON zawierający nazwę funkcji i argumenty — a kod może go następnie niezawodnie wykonać.
Struktura parametru tools
Definicje funkcji przekazuje się do API w parametrze tools jako listę obiektów. Każdy obiekt ma wartość type równą 'function' oraz klucz function zawierający nazwę, opis i schemat JSON definiujący parametry.
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 dla parametrów
Pole parameters jest zgodne ze specyfikacją JSON Schema. Użyj type, aby określić typ string, number, integer, boolean, array lub object. Użyj description dla każdej właściwości, aby wyjaśnić modelowi znaczenie pola. Wymagane pola wymień w tablicy required — pola opcjonalne można pominąć w tablicy required.
# 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']
}
}
}Wywoływanie API z użyciem narzędzi
Przekaż listę tools bezpośrednio do chat.completions.create. Model może odpowiedzieć zwykłą wiadomością tekstową (jeśli potrafi odpowiedzieć bez użycia funkcji) albo zwrócić obiekt tool_calls instruujący o wykonaniu funkcji. Zawsze sprawdzaj finish_reason, aby wiedzieć, z którym przypadkiem masz do czynienia.
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)Sterowanie wyborem narzędzia za pomocą tool_choice
Parametr tool_choice określa, czy model musi wywołać funkcję, czy może swobodnie dokonać wyboru. Ustawienie 'auto' pozwala modelowi zdecydować. Ustawienie 'required' wymusza wywołanie narzędzia. Ustawienie konkretnej nazwy funkcji wymusza wywołanie dokładnie tej funkcji — jest to przydatne w zadaniach ekstrakcji, w których zawsze potrzebny jest ustrukturyzowany wynik.
# 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'Pola Enum dla ograniczonych wyborów
Pola enum w schemacie JSON należy używać zawsze, gdy parametr powinien być ograniczony do ustalonego zbioru wartości. Znacznie zwiększa to niezawodność — model dużo rzadziej wymyśli nieprawidłową opcję, gdy widzi w schemacie dokładną listę dozwolonych wartości.
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']
}
}
}Zagnieżdżone schematy obiektów
JSON Schema obsługuje zagnieżdżone obiekty. Użyj 'type': 'object' wraz z własną sekcją properties, aby definiować złożone, hierarchiczne struktury danych. Jest to idealne rozwiązanie do wyodrębniania uporządkowanych danych z nieustrukturyzowanego tekstu, takiego jak wiadomości e-mail lub dokumenty.
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']
}
}
}Generowanie schematów na podstawie modeli Pydantic
Ręczne pisanie schematów JSON jest żmudne i podatne na błędy. Zamiast tego zdefiniuj strukturę danych jako model Pydantic i użyj .schema(), aby automatycznie wygenerować schemat JSON. Otrzymasz również walidację na poziomie języka Python podczas deserializacji odpowiedzi modelu.
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
}
}Pisanie skutecznych opisów funkcji
Opis funkcji to najważniejszy sygnał, na podstawie którego model decyduje, kiedy wywołać narzędzie. Dobry opis precyzyjnie określa przypadek użycia, informuje, kiedy funkcję należy wywołać, a kiedy nie należy tego robić, oraz opisuje oczekiwany wynik. Niejasne opisy powodują, że model wywołuje niewłaściwą funkcję albo nie wykorzystuje okazji do wywołania właściwej.
- Niejasny: 'Pobierz dane pogodowe.'
- Dobry: 'Pobierz bieżące warunki pogodowe dla określonego miasta. Użyj, gdy użytkownik wyraźnie pyta o pogodę w wymienionej lokalizacji. Zwraca temperaturę, warunki pogodowe i wilgotność.'
Tryb ścisły zapewniający zgodność ze schematem
Tryb ścisły OpenAI dla uporządkowanych danych gwarantuje, że model wygeneruje kod JSON dokładnie zgodny ze schematem — bez dodatkowych pól i bez brakujących pól wymaganych. Włącz go, ustawiając 'strict': true w definicji funkcji. Uwaga: tryb ścisły wymaga ustawienia additionalProperties: false we wszystkich obiektach schematu.
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']
}
}
}Testowanie schematów funkcji
Przed wdrożeniem przetestuj każdy schemat funkcji przy użyciu różnorodnych danych wejściowych: przypadków typowych, brzegowych i celowo problematycznych. Sprawdź, czy model wywołuje właściwą funkcję, generuje argumenty właściwych typów, prawidłowo obsługuje opcjonalne pola i przestrzega ograniczeń enum. Użyj OpenAI Playground, aby szybko wprowadzać poprawki przed napisaniem kodu produkcyjnego.
Szybkie sprawdzenie
Sprawdź, czy rozumiesz definiowanie schematów funkcji dla API OpenAI.
Podsumowanie lekcji
W tej lekcji poznali Państwo następujące zagadnienia: schematy funkcji używają JSON Schema do definiowania typów, opisów i ograniczeń parametrów, tool_choice określa, czy model musi wywołać funkcję, czy może samodzielnie zdecydować, a modele Pydantic mogą automatycznie generować JSON Schema, ograniczając konieczność ręcznego pisania schematów. W następnej części nauczą się Państwo przetwarzać wywołania narzędzi w aplikacji, wykrywając je, wykonując i odsyłając wyniki.
Często zadawane pytania
Czy lekcja „Definiowanie schematów funkcji dla API” jest bezpłatna?
Tak — pełny tekst „Definiowanie schematów funkcji dla API” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Engineering Academy, przejdź na CoddyKit PRO. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Definiowanie schematów funkcji dla API”?
Napisz definicje JSON Schema dla funkcji, przekaż je w parametrze tools i poznaj sposób, w jaki model decyduje, kiedy oraz jak je wywoływać. Ćwiczysz AI Engineering Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć AI Engineering Academy?
Nie wymagamy żadnego doświadczenia. AI Engineering Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.
Ile czasu zajmuje lekcja „Definiowanie schematów funkcji dla API”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji AI Engineering Academy?
Tak. Każda lekcja AI Engineering Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Definiowanie schematów funkcji dla API
- Przetwarzanie wywołań narzędzi w aplikacji
- Równoległe wywoływanie funkcji
- Budowanie interfejsu bazy danych w języku naturalnym