OpenAI function calling, modelin uygulamanızdaki tanımlı bir işlev için yapılandırılmış argüman önermesini sağlar. İşlevi model kendisi çalıştırmaz: argümanları doğrulayıp gerçek kodu uygulamanız yürütür, sonucu API’ye geri gönderir. Bu ayrım güvenlik ve hata yönetiminin temelidir.
1. Senaryoyu ve Yetkiyi Belirleyin
Örneğimiz yalnız get_order_status(order_id) ile kullanıcının kendi sipariş durumunu okur. Sipariş kimliği tahmin edilebilir olsa bile kullanıcı oturumunu doğrulamadan veri döndürmeyin. İade, ödeme ve silme gibi yazma işlemleri için ayrıca açık kullanıcı niyeti ve uygulama tarafı yetkilendirme gerekir.
2. Fonksiyonu JSON Şemasıyla Tanımlayın
Responses API isteğinde tools dizisine type: function, ad, açıklama ve parameters JSON şeması eklenir. strict: true kullanacaksanız tüm özellikleri şemaya uygun ve additionalProperties: false ile belirtin. Şema, girdinin biçimini daraltır; veritabanı yetkisi veya iş kuralı denetiminin yerine geçmez.
tools = [{
"type": "function", "name": "get_order_status",
"description": "Oturumu açık kullanıcının sipariş durumunu getirir",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
"additionalProperties": False
},
"strict": True
}]3. Responses API İsteği Gönderin
API anahtarını sunucu ortam değişkeninde tutun; tarayıcı JavaScript’ine, açık depoya veya yazı örneğine koymayın. Kullandığınız modelin tool çağrısını desteklediğini resmî model belgesinden kontrol edin.
from openai import OpenAI
import os, json
client = OpenAI()
model = os.environ["OPENAI_MODEL"]
items = [{"role": "user", "content": "123 numaralı siparişimin durumu nedir?"}]
response = client.responses.create(model=model, input=items, tools=tools)4. Dönen Çağrıları Ayırın ve Argümanları Doğrulayın
response.output içinde sıfır, bir veya birden fazla function_call öğesi olabilir. Her çağrının name, JSON arguments ve call_id alanlarını kullanın. Beklenmeyen fonksiyon adını reddedin; JSON ayrıştırma hatasını yakalayın. Yetki denetimini kullanıcı oturumuna göre uygulayın, modelin verdiği order_id değerine güvenmeyin.
5. Uygulama Kodunu Çalıştırın
Yalnız izin verdiğiniz fonksiyonları eşleyin. Okuma işlemlerinde bile kayıt sahibini sorgulayın; yazma işlemlerinde idempotency, işlem günlüğü ve gerektiğinde insan onayı kullanın. Başarısız veritabanı sorgusunu kullanıcıya ham gizli kayıtlarla döndürmeyin.
6. Sonucu call_id ile Geri Gönderin
items += response.output
for call in response.output:
if call.type != "function_call":
continue
if call.name != "get_order_status":
raise ValueError("İzin verilmeyen fonksiyon")
args = json.loads(call.arguments)
result = get_order_status_for_current_user(args["order_id"])
items.append({
"type": "function_call_output",
"call_id": call.call_id,
"output": json.dumps(result, ensure_ascii=False)
})get_order_status_for_current_user, uygulamanızda oturum ve sahiplik kontrolü yapan bir örnek fonksiyondur; burada tanımlı olmadığı için kodu aynen çalıştırmadan kendi veri katmanınızla doldurun. Akışta araç çağrısı yoksa boş sonuç göndermeyin; doğrudan yanıtı ele alın.
7. Son Yanıtı ve Hataları İşleyin
if any(item.type == "function_call" for item in response.output):
final = client.responses.create(model=model, input=items, tools=tools)
print(final.output_text)
else:
print(response.output_text)İkinci yanıtta da araç çağrısı gelebilir. Üretim uygulamasında birden çok çağrıyı işleyen, adım sayısını sınırlayan bir döngü kurun. Ağ hatalarında zaman aşımı ve ölçülü retry kullanın; ödeme gibi yan etkili işlemi körlemesine tekrarlamayın. Gizli anahtar ve kişisel veriyi günlüklerde maskeleyin.
Sonuç: Function calling başarısı yalnız şemanın geçerli olmasına değil, uygulama tarafında yetki, gerçek işlev, call_id eşleme ve hata yönetimine bağlıdır. Güncel API alanları için resmî OpenAI Docs kılavuzunu izleyin.
Kaynaklar ve İleri Okuma
