OpenAI-مطابق API کے ساتھ Python میں فنکشن کالنگ

فنکشن کالنگ (ٹول کالنگ) ایک ماڈل کو اجازت دیتی ہے کہ وہ آپ کے کوڈ سے کسی فنکشن کو چلانے کی درخواست کرے۔ آپ درخواست کے ساتھ ایک tools فہرست بھیجتے ہیں، ماڈل متن کے بجائے tool_calls کے ساتھ جواب دیتا ہے، آپ خود فنکشن چلاتے ہیں، اور اس کا نتیجہ role: tool والے پیغام میں واپس بھیجتے ہیں۔ پھر ماڈل حتمی جواب لکھتا ہے۔ یہ گائیڈ پورا لوپ Python میں OpenAI-مطابق اینڈ پوائنٹ https://api.cheaptokens.dev/v1/chat/completions کے ساتھ MiniMax-M2.7 (id MiniMaxAI/MiniMax-M2.7، 180K کانٹیکسٹ، فی جواب زیادہ سے زیادہ 8,192 آؤٹ پٹ ٹوکنز) کے خلاف دکھاتی ہے۔

ٹول کالنگ کیٹلاگ کے ہر ماڈل کے لیے معاونت شدہ درج ہے (CheapTokens docs، 22 اکتوبر 2026 کو چیک کیا گیا)۔ آپ کو API کلید درکار ہے؛ اگر آپ نے ابھی تک کوئی درخواست نہیں بھیجی، تو اپنی پہلی API درخواست سے شروع کریں۔

فنکشن کالنگ کیسے کام کرتی ہے#

ماڈل کبھی کچھ نہیں چلاتا۔ یہ صرف ایک ساختی درخواست پیدا کرتا ہے: "get_weather کو {\"city\": \"Paris\"} کے ساتھ کال کریں"۔ آپ کا پروگرام اصل کام کرتا ہے اور رپورٹ کرتا ہے۔ اس سے دو درخواستوں کا لوپ بنتا ہے:

1. درخواست 1۔ آپ صارف کا پیغام اور tools فہرست بھیجتے ہیں۔ ماڈل یا تو متن میں جواب دیتا ہے یا ایک یا زیادہ tool_calls واپس کرتا ہے۔
2. آپ کا کوڈ۔ آپ ہر کال کو پارس کرتے ہیں، متعلقہ فنکشن چلاتے ہیں اور نتیجہ جمع کرتے ہیں۔
3. درخواست 2۔ آپ پوری گفتگو دوبارہ بھیجتے ہیں: اصل پیغامات، tool_calls والا اسسٹنٹ پیغام، اور ہر کال کے لیے ایک role: tool پیغام۔ ماڈل حتمی جواب لکھنے کے لیے نتائج استعمال کرتا ہے۔

ہر درخواست پوری تاریخ دوبارہ بھیجتی ہے، اس لیے ٹول لوپس ایک سوال کے مقابلے میں زیادہ ان پٹ ٹوکنز استعمال کرتے ہیں۔ اگر یہ آپ کے لیے نیا ہے، تو ٹوکن کیا ہے پڑھیں۔

کلائنٹ سیٹ اپ کریں#

OpenAI SDK (pip install openai) انسٹال کریں اور اپنی کلید سورس کوڈ کے بجائے ماحولیاتی متغیر میں رکھیں:

export CHEAPTOKENS_API_KEY="your-key-here"

بیس URL https://api.cheaptokens.dev/v1 ہے۔ ماڈل id CheapTokens دستاویزات سے لیں: مختلف فراہم کنندگان ایک ہی ماڈل کو مختلف نام دیتے ہیں۔ یہ گائیڈ MiniMaxAI/MiniMax-M2.7 استعمال کرتی ہے۔

فنکشن کا اعلان کریں اور پہلی درخواست بھیجیں#

فنکشن tools ایرے میں بیان کیا جاتا ہے۔ ہر اندراج میں type: function اور ایک function آبجیکٹ ہوتا ہے جس میں name، description اور JSON Schema کے طور پر لکھا گیا parameters ہوتا ہے۔ تفصیل وہی ہے جو ماڈل پڑھتا ہے تاکہ فیصلہ کرے کہ فنکشن کب کال کرنا ہے، اس لیے اسے مختصر اور ٹھوس جملے کے طور پر لکھیں۔

نیچے ایک مکمل اسکرپٹ ہے۔ موسم کا فنکشن جعلی ڈیٹا کے ساتھ ایک اسٹب ہے، اس لیے مثال کو کسی اضافی سروس کی ضرورت نہیں:

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)

تین تفصیلات طے کرتی ہیں کہ لوپ کام کرتا ہے یا نہیں:

• call.function.arguments ایک JSON سٹرنگ ہے، ڈکشنری نہیں۔ اسے json.loads سے پارس کریں۔
• ہر role: tool پیغام میں اس کال کا tool_call_id ہونا چاہیے جس کا وہ جواب دیتا ہے، جو call.id ہے۔
• ٹول پیغام کا content ایک سٹرنگ ہے۔ ساختی نتائج کے لیے json.dumps استعمال کریں۔

آپ کو کیا نظر آنا چاہیے#

اگر آپ پہلی درخواست کے بعد فیلڈز پرنٹ کریں، تو وہ ایسے دکھتے ہیں (کال id ہر رن میں مختلف ہوتی ہے):

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

پھر اسکرپٹ حتمی جواب پرنٹ کرتا ہے، ایک سادہ جملہ جیسے "It is currently 14 °C in Paris." الفاظ ہر رن میں بدلتے ہیں؛ نمبر آپ کے فنکشن سے آتا ہے۔

متعدد کالز اور طویل لوپس#

ایک ماڈل ایک ہی جواب میں ایک سے زیادہ کال واپس کر سکتا ہے، مثلاً جب آپ دو شہروں کے موسم کے بارے میں پوچھیں۔ اسی لیے مثال message.tool_calls پر لوپ کرتی ہے اور ہر کال کا جواب اس کی اپنی id سے دیتی ہے۔ OpenAI کی فنکشن کالنگ گائیڈ بھی یہی رویہ بیان کرتی ہے: auto کے ڈیفالٹ tool_choice کے ساتھ ماڈل صفر، ایک یا کئی فنکشنز کال کر سکتا ہے (OpenAI docs، 22 اکتوبر 2026 کو چیک کیا گیا؛ صفحے پر آخری تازہ کاری کی تاریخ نہیں ہے اور یہ نئے Responses API شکل کو بیان کرتا ہے، جبکہ یہ گائیڈ /v1/chat/completions اینڈ پوائنٹ کی Chat Completions شکل استعمال کرتی ہے)۔

ایجنٹس دونوں مراحل کو دہراتے ہیں جب تک ماڈل ٹولز مانگنا بند نہ کرے۔ درخواستوں کو لوپ میں لپیٹیں اور ہمیشہ ایک سٹیپ حد مقرر کریں:

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)})

اگر آپ چاہتے ہیں کہ جواب ٹوکن بہ ٹوکن ظاہر ہو، تو اسے Python میں اسٹریمنگ کے ساتھ ملائیں۔

MiniMax-M2.7 ٹول لوپس کے لیے کیوں موزوں ہے#

ایک ٹول لوپ بڑھتی ہوئی تاریخ کے ساتھ بہت سی درخواستیں بھیجتا ہے۔ اس پیٹرن کے لیے CheapTokens MiniMax-M2.7 پیش کرتا ہے: 180K کانٹیکسٹ، فی جواب زیادہ سے زیادہ 8,192 آؤٹ پٹ ٹوکنز، دن کے کسی بھی وقت ایک قیمت بغیر پیک آورز کے، اور تمام ماڈلز کے لیے ایک بیلنس۔ ان پٹ اور آؤٹ پٹ ملا کر، یہ OpenRouter کی حوالہ قیمت سے سستا ہے (CheapTokens قیمت کا موازنہ، 31 اکتوبر 2026 کو چیک کیا گیا)۔

فی 1M ٹوکنز موجودہ قیمتیں: ان پٹ $0.05، آؤٹ پٹ $0.15۔ بطور مثال ورک لوڈ (پیمائش نہیں)، اوپر دیا گیا دو درخواستوں والا راؤنڈ ٹرپ کل تقریباً 2,700 ان پٹ اور 350 آؤٹ پٹ ٹوکنز کے ساتھ $0.00019 لاگت کرتا ہے۔ مکمل قیمت کی فہرست قیمتوں کے صفحے پر ہے۔

کوئی اور ماڈل آزمانے کے لیے صرف id تبدیل کریں؛ ids کی فہرست ماڈلز کے صفحے پر ہے۔

اگر یہ کام نہ کرے#

• message.tool_calls None ہے۔ ماڈل نے متن میں جواب دیا۔ فنکشن description کو مزید مخصوص بنائیں، اور یقینی بنائیں کہ سوال کو واقعی فنکشن کی ضرورت ہے۔
• arguments پر json.JSONDecodeError۔ ماڈل نے غلط JSON پیدا کیا۔ json.loads کو try/except میں لپیٹیں اور غلطی کا متن ٹول نتیجے کے طور پر واپس بھیجیں، تاکہ ماڈل درست دلائل کے ساتھ دوبارہ کوشش کر سکے۔
• دوسری درخواست ناکام ہو یا ماڈل نتیجہ نظر انداز کرے۔ چیک کریں کہ ہر کال کے لیے بالکل ایک role: tool پیغام ہے جس کی tool_call_id مماثل ہے، اور tool_calls والا اسسٹنٹ پیغام ان سے پہلے تاریخ میں موجود ہے۔
• FUNCTIONS[...] میں KeyError۔ ماڈل نے ایسا فنکشن نام دیا جو آپ نے رجسٹر نہیں کیا۔ کریش ہونے کے بجائے ٹول نتیجے کے طور پر ایک مختصر غلطی سٹرنگ واپس کریں۔
• جواب کٹ گیا ہے۔ finish_reason چیک کریں: قدر length کا مطلب ہے کہ آؤٹ پٹ ٹوکن حد پہنچ گئی۔ AI جواب جملے کے بیچ کیوں رک جاتا ہے دیکھیں۔
• 401 یا تصدیقی غلطیاں۔ چیک کریں کہ کلید CHEAPTOKENS_API_KEY میں ہے اور بیس URL /v1 پر ختم ہوتا ہے۔

اگلے مراحل#

اسٹب کو حقیقی فنکشن سے بدلیں: ڈیٹا بیس کوئری، سرچ کال یا کیلکولیٹر۔ tools اور FUNCTIONS میں مزید اندراجات شامل کریں، اور ہر فنکشن کا نتیجہ مختصر رکھیں، کیونکہ یہ ہر اگلی درخواست میں تاریخ میں واپس جاتا ہے۔ کلید حاصل کرنے اور پہلی کال کرنے کے لیے CheapTokens docs کھولیں۔