AI Engineering Academy · Ders

API İçin İşlev Şemaları Tanımlama

İşlevleriniz için JSON Schema tanımları yazın, bunları tools parametresinde gönderin ve modelin işlevleri ne zaman ve nasıl çağıracağına nasıl karar verdiğini anlayın.

API İçin İşlev Şemaları Tanımlama, CoddyKit'te ücretsiz bir AI Engineering Academy dersidir. Bu, 4 dersinin 1. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, AI Engineering Academy öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. AI Engineering Academy kursu toplamda 4 dersten oluşur.

Bu dersin bazı bölümleri henüz çevrilmemiş olup İngilizce olarak gösterilmektedir.

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.

Sıkça Sorulan Sorular

“API İçin İşlev Şemaları Tanımlama” dersi ücretsiz mi?

Evet — “API İçin İşlev Şemaları Tanımlama” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve AI Engineering Academy kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. AI Engineering Academy kursu toplamda 4 dersten oluşur.

“API İçin İşlev Şemaları Tanımlama” dersinde ne öğreneceğim?

İşlevleriniz için JSON Schema tanımları yazın, bunları tools parametresinde gönderin ve modelin işlevleri ne zaman ve nasıl çağıracağına nasıl karar verdiğini anlayın. AI Engineering Academy ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

AI Engineering Academy öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te AI Engineering Academy, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 1. dersidir.

“API İçin İşlev Şemaları Tanımlama” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu AI Engineering Academy dersinde kod yazıp çalıştırabilir miyim?

Evet. Her AI Engineering Academy dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

← AI Engineering Academy Sayfasına Dön