Funktion skeemojen määrittäminen API:a varten
Kirjoita funktioillesi JSON Schema -määritykset, välitä ne tools-parametrissa ja ymmärrä, miten malli päättää, milloin ja miten niitä kutsutaan.
Funktion skeemojen määrittäminen API:a varten on ilmainen AI Engineering Academy-oppitunti CoddyKitissä. Tämä on oppitunti 1/4. Voit lukea koko oppitunnin alta ilmaiseksi ja harjoitella sen jälkeen käytännössä selaimessa sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla. Oppitunti kuuluu AI Engineering Academy-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. AI Engineering Academy-kurssilla on yhteensä 4 oppituntia.
Mitä function calling tarkoittaa?
OpenAI:n function calling (jonka nimi on nykyään tool calling) mahdollistaa Python-funktioiden kuvaamisen mallille jäsennellyssä JSON Schema -muodossa. Kun malli päättelee, että funktiota pitäisi kutsua, se palauttaa vapaamuotoisen tekstin sijaan jäsennellyn JSON-olion, joka sisältää funktion nimen ja argumentit — koodinne suorittaa funktion sitten luotettavasti.
tools-parametrin rakenne
Välitätte funktioiden määritelmät API:lle tools-parametrissa olioluettelona. Jokaisen olion type on 'function', ja sen function-avain sisältää nimen, kuvauksen ja parametrit määrittävän JSON Scheman.
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']
}
}
}
]Parametrien JSON Schema
parameters-kenttä noudattaa JSON Schema -määritystä. Määrittäkää type-kentällä tyypiksi string, number, integer, boolean, array tai object. Kuvatkaa jokainen ominaisuus description-kentällä, jotta malli ymmärtää kentän merkityksen. Luetelkaa pakolliset kentät required-taulukossa — valinnaiset kentät voi jättää siitä pois.
# 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-kutsun tekeminen työkalujen kanssa
Välittäkää tools-luettelo suoraan chat.completions.create-kutsulle. Malli voi vastata tavallisella tekstiviestillä, jos se pystyy vastaamaan ilman funktiota, tai palauttaa tool_calls-olion, joka ohjeistaa suorittamaan funktion. Tarkistakaa aina finish_reason, jotta tiedätte, kummasta tilanteesta on kyse.
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)Työkalujen valinnan hallinta tool_choice-parametrilla
tool_choice-parametri määrittää, onko mallin kutsuttava funktiota vai saako se valita vapaasti. Asettamalla arvoksi 'auto' annatte mallin päättää. Arvo 'required' pakottaa työkalukutsun. Tietyn funktion nimen käyttäminen pakottaa kutsumaan juuri kyseistä funktiota — tämä on hyödyllistä poimintatehtävissä, joissa haluatte aina jäsennellyn tulosteen.
# 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-kentät rajoitettuihin valintoihin
Käyttäkää JSON Scheman enum-kenttää aina, kun parametri tulee rajoittaa ennalta määrättyyn arvojoukkoon. Tämä parantaa luotettavuutta huomattavasti — malli keksii virheellisen vaihtoehdon paljon epätodennäköisemmin, kun se näkee skeemassa tarkasti luetellut sallitut arvot.
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']
}
}
}Sisäkkäiset objektiskeemat
JSON Schema tukee sisäkkäisiä objekteja. Määritelkää monimutkaiset hierarkkiset tietorakenteet käyttämällä 'type': 'object'-määritystä ja sen omia properties-ominaisuuksia. Tämä sopii erinomaisesti rakenteisen datan poimimiseen jäsentämättömästä tekstistä, kuten sähköposteista tai asiakirjoista.
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']
}
}
}Skeemojen luominen Pydantic-malleista
JSON-skeemojen kirjoittaminen käsin on työlästä ja altista virheille. Määritelkää sen sijaan tietorakenne Pydantic-mallina ja luokaa JSON Schema automaattisesti käyttämällä .schema()-metodia. Näin saatte myös Python-tason validoinnin, kun sarjoistatte mallin vastauksen.
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
}
}Tehokkaiden funktiokuvausten kirjoittaminen
Funktiokuvaus on tärkein signaali, jonka perusteella malli päättää, milloin työkalua kutsutaan. Hyvä kuvaus kertoo tarkasti käyttötapauksen, mainitsee, milloin funktio tulee kutsua ja milloin sitä ei tule kutsua, sekä kuvaa tulosteen. Epämääräiset kuvaukset saavat mallin kutsumaan väärää funktiota tai jättämään oikean funktion kutsumatta.
- Epämääräinen: 'Hae säätiedot.'
- Hyvä: 'Hae tietyn kaupungin tämänhetkiset sääolosuhteet. Käytä tätä, kun käyttäjä kysyy suoraan nimetyn sijainnin säästä. Palauttaa lämpötilan, sääolosuhteet ja ilmankosteuden.'
Tiukka tila skeeman noudattamisen varmistamiseen
OpenAI:n jäsenneltyjen tulosteiden tiukka tila takaa, että malli tuottaa JSON-muotoisen vastauksen, joka vastaa skeemaanne täsmälleen — ylimääräisiä kenttiä ei ole eikä pakollisia kenttiä puutu. Ottakaa se käyttöön asettamalla funktiomääritykseen 'strict': true. Huomautus: tiukka tila edellyttää, että kaikissa skeeman objekteissa on additionalProperties: false.
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']
}
}
}Funktioskeemojen testaaminen
Testatkaa jokainen funktioskeema ennen käyttöönottoa monipuolisilla syötteillä: tavallisilla tapauksilla, poikkeustapauksilla ja haitallisilla syötteillä. Varmistakaa, että malli kutsuu oikeaa funktiota, tuottaa kelvollisia argumenttityyppejä, käsittelee valinnaiset kentät oikein ja noudattaa enum-rajoituksia. Käyttäkää OpenAI Playgroundia nopeaan iterointiin ennen tuotantokoodin kirjoittamista.
Pikatarkistus
Testatkaa ymmärrystänne OpenAI API:n funktioskeemojen määrittämisestä.
Oppitunnin kertaus
Tässä oppitunnissa opitte, että funktioskeemat käyttävät JSON Schemaa parametrityyppien, kuvausten ja rajoitusten määrittämiseen, tool_choice määrittää, onko mallin kutsuttava funktiota vai saako se valita vapaasti ja Pydantic-mallit voivat luoda JSON Scheman automaattisesti, mikä vähentää skeemojen manuaalista kirjoittamista. Seuraavaksi opitte käsittelemään työkalukutsuja sovelluksessanne tunnistamalla ja suorittamalla ne sekä lähettämällä tulokset takaisin.
Opi Python tekoälytuutorin avulla — ilmaiseksi
Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.
- Kurssit
- 30
- Oppitunnit
- 120
Usein kysytyt kysymykset
Onko oppitunti ”Funktion skeemojen määrittäminen API:a varten” ilmainen?
Kyllä – oppitunnin ”Funktion skeemojen määrittäminen API:a varten” koko tekstin voi lukea täällä verkossa ilmaiseksi. Jos haluat harjoitella interaktiivisesti sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla sekä avata koko AI Engineering Academy-kurssin, päivitä CoddyKit PROhon. AI Engineering Academy-kurssilla on yhteensä 4 oppituntia.
Mitä opin oppitunnilla ”Funktion skeemojen määrittäminen API:a varten”?
Kirjoita funktioillesi JSON Schema -määritykset, välitä ne tools-parametrissa ja ymmärrä, miten malli päättää, milloin ja miten niitä kutsutaan. Harjoittelet AI Engineering Academy-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.
Tarvitsenko kokemusta aloittaakseni AI Engineering Academy-opiskelun?
Aiempi kokemus ei ole tarpeen. CoddyKitin AI Engineering Academy-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 1/4.
Kuinka kauan ”Funktion skeemojen määrittäminen API:a varten”-oppitunnin suorittaminen kestää?
Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.
Voinko kirjoittaa ja suorittaa koodia tällä AI Engineering Academy-oppitunnilla?
Kyllä. Jokainen AI Engineering Academy-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.
Kaikki tämän kurssin oppitunnit
- Funktion skeemojen määrittäminen API:a varten
- Työkalukutsujen käsittely sovelluksessa
- Funktioiden rinnakkainen kutsuminen
- Luonnollisen kielen tietokantakäyttöliittymän rakentaminen