OpenAI Fonksiyon Çağırma Nasıl Kullanılır

Bu kılavuzun sonunda bir araç tanımlayabilecek, onu OpenAI'a gönderebilecek, modelin döndürdüğü araç çağrısını okuyabilecek ve döndürdüğü yapılandırılmış argümanlarla kendi işlevinizi çalıştırabileceksiniz. Ayrıca katı modu ve paralel çağrıları açacak, ardından üretici ortama ulaşmadan çıktının doğruluğuna güvenmek için Apidog ile araç tarafını doğrulayacak ve taklit edeceksiniz. Gerçeğin kaynağı olarak OpenAI'ın işlev çağırma dokümantasyonunu başka bir sekmede açık tutun ve daha üst düzey bir bakış açısı için OpenAI Agents SDK ile aracı oluşturma hakkındaki ön bilgimize göz atın.

Başlamadan Önce İhtiyacınız Olanlar

İşlev çağırma (genellikle araç çağırma olarak adlandırılır), bir modelin kodunuza ve harici sistemlere nasıl bağlandığıdır. Uygulamanızın sunduğu işlevleri tanımlarsınız, model kullanıcının isteğini okur ve bir işlev uygun olduğunda, işlev adını ve bir JSON argüman nesnesini döndürür. Model hiçbir şeyi kendi başına çalıştırmaz. Size yapılandırılmış bir istek sunar ve kodu sizin yapar.

Bu ayrım, geliştirme yaparken akılda tutulması gereken şeydir. Model amacı seçer ve parametreleri doldurur. Yürütmenin kontrolü sizde kalır. "Paris'teki hava durumunu öğren" mesajı, elle ayrıştırmak zorunda kalacağınız bir paragraf yerine, temiz bir get_weather({"location": "Paris, France"}) çağrısına dönüşür.

Devam etmek için bir OpenAI API anahtarına ve modelin tetikleyebilmesini istediğiniz kendi kodunuzda bir işlev sahip olmanız gerekir. Bir karar daha: hangi uç noktayı kullanacağınız. Aynı özellik iki yerde çalışır. Daha eski Chat Completions API'si bunu destekler, aynı şekilde Chat Completions ve Assistants API arasında daha önce ayrılmış olanı birleştiren daha yeni Responses API'si de destekler. Şekiller biraz farklılık gösterir ve aşağıdaki adımlar her ikisini de kapsar.

Adım 1: Aracınızı tanımlayın

Bir araç, modelin okuyabileceği bir işlev tanımıdır. Ona bir ad, bir açıklama ve argümanlar için bir JSON Şeması verirsiniz. Açıklama burada önemli bir işlev görür. Modele işlevi ne zaman kullanacağını söyler, bu yüzden onu bir etiket gibi değil, bir talimat gibi yazın.

İşlevin bir function sarmalayıcısı altında bulunduğu Chat Completions biçiminde bir araç tanımı aşağıdadır:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City and country, e.g. Bogotá, Colombia"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"],
      "additionalProperties": false
    }
  }
}

Responses API bunu düzleştirir. name, description, parameters ve strict alanları, iç içe geçmiş bir function anahtarı olmadan, araç nesnesinin en üst düzeyinde yer alır. Aynı bilgi, daha az katman.

Temel hizmet için zaten bir OpenAPI spesifikasyonu bulunduruyorsanız, parametre şekilleri neredeyse doğrudan aktarılır. OpenAPI spesifikasyonlarından test koleksiyonları oluşturma hakkındaki rehberimiz, bu şema çalışmasının nasıl iki kat kazanç sağladığını gösteriyor.

Adım 2: İlk isteğinizi yapın

Aracınızı, kullanıcının mesajıyla birlikte modele gönderin. Bunu yapan tam bir Chat Completions isteği şöyle görünür:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What is the weather in Paris right now?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string"}
            },
            "required": ["location"],
            "additionalProperties": false
          }
        }
      }
    ]
  }'

tools dizisi, bu dönüş için sunmak istediğiniz her işlevi taşır. Model kullanıcı mesajını okur, herhangi bir aracın uygun olup olmadığına karar verir ve yanıt verir. Birini seçtiğinde, bir düz yazı yerine bir araç çağrısı alırsınız, ki bunu bir sonraki adımda okuyacaksınız.

Adım 3: Modelin döndürdüğü araç çağrısını okuyun

Model bir işlevi çağırmaya karar verdiğinde metin döndürmez. Yanıttan okuduğunuz bir araç çağrısı döndürür.

Chat Completions'ta, asistan mesajı bir tool_calls dizisi taşır. Her girişte bir id, function türünde bir type ve name ile arguments dizisine sahip bir function nesnesi bulunur:

{
  "id": "call_12345xyz",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
  }
}

Responses API'sinde, çağrı output dizisinde daha düz bir şekilde görünür: function_call türünde bir type, bir call_id, bir name ve arguments:

{
  "type": "function_call",
  "call_id": "call_12345xyz",
  "name": "get_weather",
  "arguments": "{\"location\":\"Paris, France\"}"
}

Bir ayrıntı insanları yanıltır: arguments ayrıştırılmış bir nesne değil, JSON kodlu bir dizedir. Kendiniz ayrıştırırsınız, işlevinizi çalıştırırsınız, ardından modeli yanıtını tamamlayabilmesi için sonucu geri gönderirsiniz.

Adım 4: Sonucu modele döndürün

İşlevinizi çalıştırdıktan sonra, modelin nihai bir yanıt üretebilmesi için sonucu geri verin. Chat Completions'ta, çağrı id'sine anahtarlanmış bir tool rol mesajı eklersiniz. Responses API'sinde, call_id'ye anahtarlanmış bir function_call_output öğesi gönderirsiniz. Her iki durumda da döngü aynıdır: model sorar, siz çalıştırırsınız, sonucu döndürürsünüz, model yanıt verir.

Adım 5: Paralel çağrıları ve katı modu ekleyin

İki ayar, bunun ne kadar güvenilir ve ne kadar hızlı olduğunu değiştirir ve temel döngü çalıştığında bunları eklersiniz.

Paralel araç çağrıları. Varsayılan olarak model, tek bir dönüşte birden fazla araç çağrısı döndürebilir. Bir kullanıcı üç şehirdeki hava durumunu sorduğunda, aynı anda üç çağrı alabilir ve bunları birlikte çalıştırabilirsiniz. Dönüş başına en fazla bir çağrıyı zorlamak istediğinizde, parallel_tool_calls değerini false olarak ayarlayın.

Katı mod. İşlev tanımında strict: true olarak ayarlayın ve modelin argümanlarının en iyi çaba yerine JSON Şemanızla eşleşmesi garanti edilir. OpenAI her zaman etkinleştirilmesini önerir. Katı modun kuralları vardır: her nesne additionalProperties: false'a ihtiyaç duyar ve properties içindeki her alan required içinde görünmelidir. Bir alanı isteğe bağlı yapmak için onu required'dan çıkarmazsınız; izin verilen türler listesine null eklersiniz.

İsteğe bağlı alan kuralı insanları şaşırtır. Diyelim ki get_weather içinde unit isteğe bağlı. Katı modda, onu yine de required içinde listelersiniz, ardından şemada boş bırakılabilir olarak işaretlersiniz, örneğin "unit": {"type": ["string", "null"], "enum": ["celsius", "fahrenheit"]}. Model artık gerçek bir birim veya açık bir null geçirebilir, ancak anahtarı asla atlayamaz. Bu öngörülebilirlik meselenin özüdür: ayrıştırma kodunuz her seferinde tam olarak hangi anahtarları bekleyeceğini bilir.

Katı mod, bozuk JSON'u azaltır, ancak değerlerin iş açısından anlamlı olup olmadığını kontrol etmez. Bir konum şemaya göre geçerli olabilir ve yine de hizmet vermediğiniz bir şehir olabilir. İşte burada test devreye girer.

Apidog'da nasıl test edilir

Model size bir araç çağrısı verir. Bunu canlı bir işleve bağlamadan önce iki garantiyi istersiniz: argümanların beklediğiniz şekle uyması ve işlevinizin çağıracağı alt sistem API'sinin varsaydığınız gibi davranması. Apidog bunun her iki tarafını da kapsar ve hangisi konusunda hassas olmakta fayda var.

Apidog, API tarafını doğrular ve taklit eder. Uygulamanızın işlevlerini yürütmez. İyi yaptığı şey, etraflarındaki sözleşmedir.

Argümanların yapısını doğrulayın. Gerçek bir araç çağrısından arguments dizesini alın, bunu bir istek gövdesi olarak ele alın ve Apidog'da üzerinde doğrulamalar yapın. location'ın var olduğunu ve bir dize olduğunu, bir enum alanının yalnızca izin verilen bir değeri içerdiğini, gerekli alanların mevcut olduğunu kontrol edin. Yükten belirli alanları çekmek, JSONPath ifadeleri ile kolaydır ve daha derin yapısal kontroller için, katı modda OpenAI'a verdiğiniz şemanın aynısını yansıtan bir JSON Şemasına karşı doğrulama vardır. Modelin çıktısı, işlevinizin beklediği aynı şemadan geçerse, döngüyü tamamlamış olursunuz.

İşlevin çağıracağı alt sistem API'sini taklit edin. get_weather işleviniz muhtemelen bir hava durumu sağlayıcısını çağırır. Geliştirme sırasında bu sağlayıcı hız sınırlamasına tabi olabilir, ücretli olabilir veya henüz oluşturulmamış olabilir. Apidog'da gerçekçi bir hava durumu yükü döndüren bir sahte API kurun, işlevinizi sahteye yönlendirin ve gerçek hizmet üzerinde bir istek harcamadan tüm çağrı yolunu uygulayın. Canlı API'nin nadiren talep üzerine ürettiği hata durumları da dahil olmak üzere yanıtı kontrol edersiniz, böylece bir kullanıcı bulmadan önce kodunuzun bir zaman aşımı veya 429'u işlediğini doğrulayabilirsiniz.

Özetle iş akışı şöyledir: OpenAI'dan bir araç çağrısı yakalayın, argümanlarını Apidog'daki şemanıza göre doğrulayın, ardından işlevinizi gerçek API'nin Apidog taklidi üzerinde çalıştırın. Canlı çağrıları yakmadan veya uç durumları tahmin etmeden her iki uçtaki sözleşmeyi doğrulayın.

Sıkça sorulan sorular

İşlev çağırma hem Chat Completions hem de Responses API'sinde çalışır mı? Evet. Her iki uç nokta da bunu destekler. Responses API, daha önce Chat Completions ve Assistants API arasında bölünmüş olan yetenekleri birleştirir. Temel fark şekildir: Chat Completions işlevi bir function anahtarının altına yerleştirir ve tool_calls döndürürken, Responses API düz bir araç tanımı kullanır ve output dizisinde function_call öğeleri döndürür.

Model neden argümanları bir nesne yerine dize olarak döndürür? arguments alanı JSON kodlu metindir. Kullanmadan önce kodunuzda ayrıştırırsınız. Bu, her iki API'de de tutarlıdır, bu nedenle her zaman JSON ayrıştırıcınızdan geçirin ve körü körüne güvenmek yerine sonucu doğrulayın. Bu argümanları JSON Şeması doğrulamasından geçirmek, hatalı biçimlendirilmiş bir yükü işlevinize ulaşmadan önce yakalar.

Katı mod, işlevin başarılı olacağını garanti eder mi? Hayır. Katı mod, argümanların JSON Şemanızla eşleşmesini garanti eder, böylece yapı güvenilir olur. Değerlerin iş mantığınız için doğru olup olmadığını kontrol etmez ve işlevinizi çalıştırmaz. Değerleri yine de siz doğrular ve alt sistem çağrısının hatalarını kendiniz ele alırsınız.

Apidog gerçek işlevimi çalıştırabilir mi? Hayır ve çalışmaya da çalışmaz. Apidog, modelin ürettiği argümanları doğrular ve işlevinizin bağlı olduğu API'yi taklit eder. Uygulamanız yine de kendi işlevlerini yürütür. Apidog, canlıya geçmeden önce girişlere ve bağımlılıklara güvenebilmeniz için her iki taraftaki sözleşmeyi kapsar.

Sonuç

Artık tam döngüye sahipsiniz: araçlarınızı açıkça tanımlayın, istekle birlikte gönderin, tool_calls veya function_call çıktısını okuyun, sonucu döndürün, ardından katı modu açın ve paralel çağrıların yardımcı olup olmadığına karar verin. Üretim öncesinde güvende olmak için argümanların şemanızla eşleştiğini doğrulayarak ve alt sistem API'sini taklit ederek testlerle bitirin.

Test tarafını denemek ister misiniz? Araç çağırma argümanlarını şemanıza göre doğrulamak ve işlevlerinizin bağlı olduğu API'leri tek bir yerden taklit etmek için Apidog'u indirin.