OpenAI uyumlu bir API ile Python'da fonksiyon çağırma

Fonksiyon çağırma (araç çağırma), bir modelin kodunuzdan bir fonksiyon çalıştırmasını istemesini sağlar. İstekle birlikte bir tools listesi gönderirsiniz, model metin yerine tool_calls ile yanıt verir, fonksiyonu kendiniz çalıştırırsınız ve sonucunu role: tool içeren bir mesajla geri gönderirsiniz. Ardından model nihai yanıtı yazar. Bu kılavuz, MiniMax-M2.7 (id MiniMaxAI/MiniMax-M2.7, 180K bağlam, yanıt başına en fazla 8.192 çıktı token'ı) ile OpenAI uyumlu https://api.cheaptokens.dev/v1/chat/completions uç noktasına karşı tüm döngüyü Python'da gösterir.

Araç çağırma, katalogdaki her model için destekleniyor olarak listelenmiştir (CheapTokens dokümanları, 22 Ekim 2026'da kontrol edildi). Bir API anahtarına ihtiyacınız var; henüz bir istek yapmadıysanız ilk API isteğiniz ile başlayın.

Fonksiyon çağırma nasıl çalışır#

Model hiçbir şeyi çalıştırmaz. Yalnızca yapılandırılmış bir istek üretir: "{\"city\": \"Paris\"} ile get_weather çağır". Programınız gerçek işi yapar ve geri bildirir. Bu, iki istekten oluşan bir döngü oluşturur:

1. İstek 1. Kullanıcı mesajını ve tools listesini gönderirsiniz. Model ya metinle yanıt verir ya da bir veya daha fazla tool_calls döndürür.
2. Kodunuz. Her çağrıyı ayrıştırır, eşleşen fonksiyonu çalıştırır ve sonucu toplarsınız.
3. İstek 2. Tüm konuşmayı yeniden gönderirsiniz: orijinal mesajlar, tool_calls içeren asistan mesajı ve her çağrı için bir role: tool mesajı. Model, nihai yanıtı yazmak için sonuçları kullanır.

Her istek tüm geçmişi yeniden gönderir, bu nedenle araç döngüleri tek bir sorudan daha fazla giriş token'ı kullanır. Bu sizin için yeni ise, token nedir yazısını okuyun.

İstemciyi kurun#

OpenAI SDK'yı (pip install openai) kurun ve anahtarınızı kaynak kod yerine bir ortam değişkenine koyun:

export CHEAPTOKENS_API_KEY="your-key-here"

Temel URL https://api.cheaptokens.dev/v1'dir. Model id'sini CheapTokens dokümantasyonundan alın: farklı sağlayıcılar aynı modeli farklı adlandırır. Bu kılavuz MiniMaxAI/MiniMax-M2.7 kullanır.

Bir fonksiyon tanımlayın ve ilk isteği gönderin#

Bir fonksiyon tools dizisinde tanımlanır. Her girişte type: function ve name, description ve JSON Schema olarak yazılmış parameters içeren bir function nesnesi bulunur. Modelin fonksiyonu ne zaman çağıracağına karar vermek için okuduğu şey açıklamadır, bu yüzden onu kısa ve somut bir cümle olarak yazın.

Aşağıda eksiksiz bir betik var. Hava durumu fonksiyonu sahte verilerle bir saplamadır, böylece örnek ek hizmet gerektirmez:

import json
import os

from openai import OpenAI

client = OpenAI(
    base_url='https://api.cheaptokens.dev/v1',
    api_key=os.environ['CHEAPTOKENS_API_KEY'],
)
MODEL = 'MiniMaxAI/MiniMax-M2.7'


def get_weather(city: str) -> dict:
    # Stub with fake data: replace with a real lookup
    fake = {'Paris': 14, 'Tokyo': 19}
    return {'city': city, 'temp_c': fake.get(city, 10)}


FUNCTIONS = {'get_weather': get_weather}

tools = [
    {
        'type': 'function',
        'function': {
            'name': 'get_weather',
            'description': 'Get the current temperature in Celsius for a city.',
            'parameters': {
                'type': 'object',
                'properties': {
                    'city': {'type': 'string', 'description': 'City name, for example Paris'},
                },
                'required': ['city'],
            },
        },
    }
]

messages = [{'role': 'user', 'content': 'What is the weather in Paris right now?'}]

# Step 1: the model decides whether to call a function
first = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
message = first.choices[0].message

if not message.tool_calls:
    print(message.content)
    raise SystemExit

# Step 2: run every requested call and send the results back
messages.append(message)
for call in message.tool_calls:
    args = json.loads(call.function.arguments)
    result = FUNCTIONS[call.function.name](**args)
    messages.append({
        'role': 'tool',
        'tool_call_id': call.id,
        'content': json.dumps(result),
    })

final = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
print(final.choices[0].message.content)

Döngünün çalışıp çalışmadığına üç ayrıntı karar verir:

• call.function.arguments bir JSON dizesidir, sözlük değil. json.loads ile ayrıştırın.
• Her role: tool mesajı, yanıtladığı çağrının tool_call_id değerini taşımalıdır; bu da call.id'dur.
• Bir araç mesajının content değeri bir dizedir. Yapılandırılmış sonuçlar için json.dumps kullanın.

Görmeniz gerekenler#

İlk istekten sonra alanları yazdırırsanız, şöyle görünürler (çağrı id'si her çalıştırmada farklıdır):

finish_reason: tool_calls
call.id: call_abc123
call.function.name: get_weather
call.function.arguments: {"city": "Paris"}

Ardından betik nihai yanıtı yazdırır; "Şu anda Paris'te 14 °C." gibi düz bir cümle. İfade her çalıştırmada değişir; sayı fonksiyonunuzdan gelir.

Birden fazla çağrı ve daha uzun döngüler#

Bir model tek bir yanıtta birden fazla çağrı döndürebilir; örneğin iki şehirdeki hava durumunu sorduğunuzda. Bu nedenle örnek message.tool_calls üzerinde döner ve her çağrıyı kendi id'siyle yanıtlar. OpenAI'nin fonksiyon çağırma kılavuzu da aynı davranışı açıklar: varsayılan tool_choice değeri auto iken model sıfır, bir veya birkaç fonksiyon çağırabilir (OpenAI dokümanları, 22 Ekim 2026'da kontrol edildi; sayfada son güncelleme tarihi yok ve daha yeni Responses API şeklini açıklıyor, bu kılavuz ise /v1/chat/completions uç noktasının Chat Completions şeklini kullanıyor).

Ajanlar, model araç istemeyi bırakana kadar iki adımı tekrarlar. İstekleri bir döngüye alın ve her zaman bir adım sınırı belirleyin:

for _ in range(5):  # safety limit against endless loops
    response = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
    message = response.choices[0].message
    if not message.tool_calls:
        print(message.content)
        break
    messages.append(message)
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)
        result = FUNCTIONS[call.function.name](**args)
        messages.append({'role': 'tool', 'tool_call_id': call.id, 'content': json.dumps(result)})

Yanıtın token token görünmesini istiyorsanız, bunu Python'da akış ile birleştirin.

MiniMax-M2.7 neden araç döngülerine uygundur#

Bir araç döngüsü, büyüyen bir geçmişle çok sayıda istek gönderir. Bu desen için CheapTokens MiniMax-M2.7 sunar: 180K bağlam, yanıt başına en fazla 8.192 çıktı token'ı, günün her saatinde yoğun saatler olmadan tek fiyat ve tüm modeller için tek bakiye. Giriş ve çıktı birlikte sayıldığında, OpenRouter'ın referans fiyatından daha ucuzdur (CheapTokens fiyat karşılaştırması, 31 Ekim 2026'da kontrol edildi).

1M token başına güncel fiyatlar: giriş $0.05, çıktı $0.15. Örnek bir iş yükü olarak (ölçüm değil), toplamda yaklaşık 2.700 giriş ve 350 çıktı token'ı içeren yukarıdaki iki isteklik gidiş-dönüş $0.00019 tutar. Tam fiyat listesi fiyatlandırma sayfasında.

Başka bir modeli denemek için yalnızca id'yi değiştirin; id listesi modeller sayfasında.

Çalışmazsa#

• message.tool_calls değeri None. Model metinle yanıt verdi. Fonksiyon description açıklamasını daha belirgin yapın ve sorunun gerçekten fonksiyona ihtiyaç duyduğundan emin olun.
• arguments üzerinde json.JSONDecodeError. Model geçersiz JSON üretti. json.loads ifadesini try/except içine alın ve hata metnini araç sonucu olarak geri gönderin, böylece model düzeltilmiş argümanlarla yeniden deneyebilir.
• İkinci istek başarısız oluyor veya model sonucu yok sayıyor. Her çağrının eşleşen tool_call_id değerine sahip tam olarak bir role: tool mesajı olduğunu ve tool_calls içeren asistan mesajının bunlardan önce geçmişte bulunduğunu kontrol edin.
• FUNCTIONS[...] içinde KeyError. Model, kaydetmediğiniz bir fonksiyonun adını verdi. Çökmek yerine araç sonucu olarak kısa bir hata dizesi döndürün.
• Yanıt kesiliyor. finish_reason değerini kontrol edin: length değeri çıktı token sınırına ulaşıldığı anlamına gelir. Bir AI yanıtı neden cümle ortasında durur yazısına bakın.
• 401 veya kimlik doğrulama hataları. Anahtarın CHEAPTOKENS_API_KEY içinde olduğunu ve temel URL'nin /v1 ile bittiğini kontrol edin.

Sonraki adımlar#

Saplamayı gerçek bir fonksiyonla değiştirin: bir veritabanı sorgusu, bir arama çağrısı veya bir hesap makinesi. tools ve FUNCTIONS dizilerine daha fazla giriş ekleyin ve her fonksiyon sonucunu kısa tutun, çünkü sonraki her istekte geçmişe geri gider. Bir anahtar almak ve ilk çağrıyı yapmak için CheapTokens dokümanlarını açın.