Mendefinisikan Skema Fungsi untuk API
Tulis definisi JSON Schema untuk fungsi Anda, teruskan definisi tersebut dalam parameter tools, dan pahami cara model menentukan kapan serta bagaimana fungsi tersebut dipanggil.
Mendefinisikan Skema Fungsi untuk API adalah pelajaran AI Engineering Academy gratis di CoddyKit. Ini adalah pelajaran 1 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar AI Engineering Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus AI Engineering Academy mencakup 4 pelajaran total.
Apa Itu Pemanggilan Fungsi?
Pemanggilan fungsi OpenAI (yang sekarang disebut pemanggilan alat) memungkinkan Anda mendeskripsikan fungsi Python kepada model dalam format JSON Schema terstruktur. Ketika model menentukan bahwa suatu fungsi perlu dipanggil, alih-alih menghasilkan teks bebas, model mengembalikan objek JSON terstruktur yang berisi nama fungsi dan argumen — lalu kode Anda mengeksekusinya secara andal.
Struktur Parameter Alat
Anda meneruskan definisi fungsi ke API dalam parameter tools sebagai daftar objek. Setiap objek memiliki type bernilai 'function' dan kunci function yang berisi nama, deskripsi, serta JSON Schema yang mendefinisikan parameter.
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 untuk Parameter
Kolom parameters mengikuti spesifikasi JSON Schema. Gunakan type untuk menentukan string, angka, bilangan bulat, boolean, array, atau objek. Gunakan description untuk setiap properti guna memberi tahu model arti kolom tersebut. Cantumkan kolom wajib dalam array required — kolom opsional dapat dihilangkan dari 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']
}
}
}Melakukan Panggilan API dengan Alat
Teruskan daftar tools langsung ke chat.completions.create. Model dapat merespons dengan pesan teks biasa (jika dapat menjawab tanpa fungsi), atau dengan objek tool_calls yang menginstruksikan Anda untuk mengeksekusi fungsi. Selalu periksa finish_reason untuk mengetahui kasus yang sedang terjadi.
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)Mengontrol Pemilihan Alat dengan tool_choice
Parameter tool_choice mengontrol apakah model harus memanggil fungsi atau dapat memilih dengan bebas. Menetapkannya ke 'auto' memungkinkan model menentukan pilihan. Menetapkannya ke 'required' memaksa pemanggilan alat. Menetapkannya ke nama fungsi tertentu memaksa pemanggilan tepat fungsi tersebut — berguna untuk tugas ekstraksi ketika Anda selalu menginginkan output terstruktur.
# 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'Kolom Enum untuk Pilihan Terbatas
Gunakan bidang enum dalam JSON Schema kapan pun suatu parameter harus dibatasi pada sekumpulan nilai tetap. Hal ini sangat meningkatkan keandalan—model jauh lebih kecil kemungkinannya menciptakan opsi yang tidak valid ketika dapat melihat nilai yang diizinkan secara tepat dalam skema.
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']
}
}
}Skema Objek Bersarang
JSON Schema mendukung objek bersarang. Gunakan 'type': 'object' dengan properties-nya sendiri untuk mendefinisikan struktur data hierarkis yang kompleks. Cara ini ideal untuk mengekstrak data terstruktur dari teks yang tidak terstruktur, seperti surel atau dokumen.
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']
}
}
}Membuat Skema dari Model Pydantic
Menulis JSON Schema secara manual itu merepotkan dan rentan terhadap kesalahan. Sebagai gantinya, definisikan struktur data Anda sebagai model Pydantic dan gunakan .schema() untuk membuat JSON Schema secara otomatis. Cara ini juga memberi Anda validasi pada tingkat Python saat Anda melakukan deserialisasi respons model.
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
}
}Menulis Deskripsi Fungsi yang Efektif
Deskripsi fungsi adalah sinyal utama yang digunakan model untuk memutuskan kapan harus memanggil suatu alat. Deskripsi yang baik menjelaskan kasus penggunaan secara spesifik, menyebutkan kapan fungsi harus dan tidak boleh dipanggil, serta menjelaskan bentuk keluarannya. Deskripsi yang samar menyebabkan model memanggil fungsi yang salah atau melewatkan kesempatan untuk memanggil fungsi yang tepat.
- Samar: 'Dapatkan data cuaca.'
- Baik: 'Dapatkan kondisi cuaca saat ini untuk kota tertentu. Gunakan ketika pengguna secara eksplisit menanyakan cuaca di lokasi yang disebutkan. Mengembalikan suhu, kondisi, dan kelembapan.'
Mode Ketat untuk Kepatuhan Skema yang Terjamin
mode ketat OpenAI untuk keluaran terstruktur menjamin model menghasilkan JSON yang persis sesuai dengan skema Anda—tanpa bidang tambahan dan tanpa bidang wajib yang hilang. Aktifkan dengan menetapkan 'strict': true dalam definisi fungsi. Catatan: mode ketat mengharuskan additionalProperties: false dalam semua objek skema.
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']
}
}
}Menguji Skema Fungsi Anda
Sebelum menerapkan ke produksi, uji setiap skema fungsi dengan masukan yang beragam: kasus normal, kasus batas, dan masukan yang bersifat menyerang. Pastikan model memanggil fungsi yang tepat, menghasilkan tipe argumen yang valid, menangani bidang opsional dengan benar, dan mematuhi batasan enum. Gunakan OpenAI Playground untuk melakukan iterasi dengan cepat sebelum menulis kode produksi.
Pemeriksaan Singkat
Uji pemahaman Anda tentang pendefinisian skema fungsi untuk API OpenAI.
Rangkuman Pelajaran
Dalam pelajaran ini, Anda mempelajari bahwa: skema fungsi menggunakan JSON Schema untuk mendefinisikan tipe, deskripsi, dan batasan parameter, tool_choice mengontrol apakah model harus memanggil fungsi atau dapat memilih dengan bebas, dan model Pydantic dapat membuat JSON Schema secara otomatis untuk mengurangi penulisan skema secara manual. Selanjutnya, kita akan mempelajari cara memproses pemanggilan alat dalam aplikasi dengan mendeteksi, menjalankan, dan mengirimkan kembali hasilnya.
Pertanyaan yang Sering Diajukan
Apakah pelajaran “Mendefinisikan Skema Fungsi untuk API” gratis?
Ya — teks lengkap “Mendefinisikan Skema Fungsi untuk API” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus AI Engineering Academy, upgrade ke CoddyKit PRO. Kursus AI Engineering Academy mencakup 4 pelajaran total.
Apa yang akan aku pelajari di “Mendefinisikan Skema Fungsi untuk API”?
Tulis definisi JSON Schema untuk fungsi Anda, teruskan definisi tersebut dalam parameter tools, dan pahami cara model menentukan kapan serta bagaimana fungsi tersebut dipanggil. Kamu berlatih AI Engineering Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.
Apakah aku perlu pengalaman untuk memulai AI Engineering Academy?
Tidak diperlukan pengalaman sebelumnya. AI Engineering Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 1 dari 4.
Berapa lama pelajaran “Mendefinisikan Skema Fungsi untuk API” memakan waktu?
Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.
Bisakah aku menulis dan menjalankan kode dalam pelajaran AI Engineering Academy ini?
Ya. Setiap pelajaran AI Engineering Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.
Semua pelajaran dalam kursus ini
- Mendefinisikan Skema Fungsi untuk API
- Memproses Pemanggilan Alat di Aplikasi Anda
- Pemanggilan Fungsi secara Paralel
- Membangun Antarmuka Basis Data Bahasa Alami