Определение схем функций для API
Напишите определения JSON Schema для функций, передайте их в параметре tools и разберитесь, как модель решает, когда и каким образом их вызывать.
«Определение схем функций для API» — бесплатный урок AI Engineering Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Engineering Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Engineering Academy содержит 4 уроков всего.
Части этого урока еще не переведены и отображаются на английском.
What Is Function Calling?
OpenAI's function calling (now called tool calling) lets you describe Python functions to the model in a structured JSON Schema format. When the model determines a function should be called, instead of producing free-text it returns a structured JSON object with the function name and arguments — which your code then executes reliably.
The tools Parameter Structure
You pass your function definitions to the API in the tools parameter as a list of objects. Each object has a type of 'function' and a function key containing the name, description, and a JSON Schema defining the parameters.
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 for Parameters
The parameters field follows the JSON Schema specification. Use type to specify string, number, integer, boolean, array, or object. Use description for each property to tell the model what the field means. List required fields in the required array — optional fields can be omitted from 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']
}
}
}Making the API Call with Tools
Pass the tools list directly to chat.completions.create. The model may respond with a regular text message (if it can answer without a function), or it may respond with a tool_calls object instructing you to execute a function. Always check finish_reason to know which case you're in.
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)Controlling Tool Selection with tool_choice
The tool_choice parameter controls whether the model must call a function or can choose freely. Setting it to 'auto' lets the model decide. Setting it to 'required' forces a tool call. Setting it to a specific function name forces exactly that function to be called — useful for extraction tasks where you always want structured output.
# 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 Fields for Constrained Choices
Use the enum field in your JSON Schema whenever a parameter should be restricted to a fixed set of values. This dramatically improves reliability — the model is much less likely to invent an invalid option when it can see the exact allowed values listed in the schema.
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']
}
}
}Nested Object Schemas
JSON Schema supports nested objects. Use 'type': 'object' with its own properties to define complex hierarchical data structures. This is ideal for extracting structured data from unstructured text like emails or documents.
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']
}
}
}Generating Schemas from Pydantic Models
Writing JSON Schemas by hand is tedious and error-prone. Instead, define your data structure as a Pydantic model and use .schema() to generate the JSON Schema automatically. This also gives you Python-level validation when you deserialize the model's response.
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
}
}Writing Effective Function Descriptions
The function description is the key signal the model uses to decide when to call a tool. A good description is specific about the use case, mentions when the function should and should not be called, and describes what the output will be. Vague descriptions cause the model to call the wrong function or miss opportunities to call the right one.
- Vague: 'Get weather data.'
- Good: '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 for Guaranteed Schema Adherence
OpenAI's strict mode for structured outputs guarantees the model will produce JSON that exactly matches your schema — no extra fields, no missing required fields. Enable it by setting 'strict': true in the function definition. Note: strict mode requires additionalProperties: false in all schema objects.
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']
}
}
}Testing Your Function Schemas
Before deploying, test each function schema with diverse inputs: normal cases, edge cases, and adversarial inputs. Verify the model calls the right function, produces valid argument types, handles optional fields correctly, and respects enum constraints. Use the OpenAI Playground to iterate quickly before writing production code.
Quick Check
Test your understanding of defining function schemas for the OpenAI API.
Lesson Recap
In this lesson you learned: function schemas use JSON Schema to define parameter types, descriptions, and constraints, tool_choice controls whether the model must call a function or chooses freely, and Pydantic models can auto-generate JSON Schema to reduce manual schema writing. Next up we learn to process tool calls in your application by detecting, executing, and sending results back.
Часто задаваемые вопросы
Урок «Определение схем функций для API» бесплатный?
Да — полный текст урока «Определение схем функций для API» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Engineering Academy, подпишись на CoddyKit PRO. Курс AI Engineering Academy содержит 4 уроков всего.
Чему я научусь в уроке «Определение схем функций для API»?
Напишите определения JSON Schema для функций, передайте их в параметре tools и разберитесь, как модель решает, когда и каким образом их вызывать. Ты практикуешь AI Engineering Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать AI Engineering Academy?
Предыдущий опыт не требуется. AI Engineering Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.
Сколько времени занимает урок «Определение схем функций для API»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке AI Engineering Academy?
Да. Каждый урок AI Engineering Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Определение схем функций для API
- Обработка вызовов инструментов в приложении
- Параллельный вызов функций
- Создание интерфейса базы данных на естественном языке