آموزش Function Calling در API هوش مصنوعی: فراخوانی تابع قدم‌به‌قدم

Function calling یا فراخوانی تابع یکی از مهم‌ترین قابلیت‌های API مدل‌های هوش مصنوعی است که به مدل اجازه می‌دهد با کد و سرویس‌های شما کار کند. مدل خودش تابع را اجرا نمی‌کند؛ فقط تصمیم می‌گیرد کدام تابع با چه آرگومان‌هایی صدا زده شود و برنامه شما آن را اجرا می‌کند. در این راهنما مفهوم، مراحل کار، یک نمونه کد پایتون و نکات مهم را بر پایه مستندات رسمی OpenAI مرور می‌کنیم.

Function calling دقیقاً چیست؟

مدل‌های زبانی به‌تنهایی به داده زنده، پایگاه داده یا سرویس‌های داخلی شما دسترسی ندارند. با function calling شما فهرستی از ابزارها (tools) را همراه درخواست می‌فرستید و هر ابزار یک نام، یک توضیح و یک طرح پارامتر (JSON Schema) دارد. اگر مدل تشخیص دهد برای پاسخ به ابزار نیاز است، به‌جای متن معمولی یک «درخواست فراخوانی ابزار» برمی‌گرداند.

مثال‌های رایج: گرفتن وضعیت سفارش، محاسبه قیمت، جستجو در پایگاه دانش، ثبت تیکت یا خواندن آب‌وهوا.

مراحل کار با function calling

طبق مستندات، جریان کار به‌صورت زیر است:

1. ابزارها را همراه پیام کاربر به مدل می‌فرستید.
2. مدل در صورت نیاز، یک یا چند فراخوانی ابزار با آرگومان‌های JSON برمی‌گرداند.
3. برنامه شما تابع متناظر را اجرا می‌کند.
4. نتیجه را همراه شناسه همان فراخوانی (مثل call_id) دوباره به مدل می‌دهید.
5. مدل با استفاده از نتیجه، پاسخ نهایی را برای کاربر می‌نویسد.

تعریف ابزار با JSON Schema

هر ابزار با نام، توضیح و پارامترها تعریف می‌شود. توضیح روشن بسیار مهم است، چون مدل بر اساس آن تصمیم می‌گیرد چه زمانی ابزار را صدا بزند:

tools = [{
    "type": "function",
    "name": "get_order_status",
    "description": "وضعیت یک سفارش را با شماره سفارش برمی‌گرداند.",
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "شماره سفارش مشتری"
            }
        },
        "required": ["order_id"],
        "additionalProperties": False
    },
    "strict": True
}]

گزینه strict برای تضمین پیروی آرگومان‌ها از طرح تعریف‌شده در مستندات توصیه شده است.

نمونه کد پایتون با Responses API

الگوی زیر از ساختار نمونه مستندات OpenAI الهام گرفته شده است. نام مدل را با مدل مورد استفاده خودتان جایگزین کنید، چون نام مدل‌ها با زمان تغییر می‌کند:

import json
from openai import OpenAI

client = OpenAI()

def get_order_status(order_id):
    # در پروژه واقعی از پایگاه داده بخوانید
    return {"order_id": order_id, "status": "shipped"}

input_list = [{"role": "user", "content": "سفارش 1234 در چه وضعیتی است؟"}]

response = client.responses.create(
    model="YOUR_MODEL_NAME",
    tools=tools,
    input=input_list,
)

input_list += response.output

for item in response.output:
    if item.type == "function_call" and item.name == "get_order_status":
        args = json.loads(item.arguments)
        result = get_order_status(args["order_id"])
        input_list.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(result),
        })

final = client.responses.create(
    model="YOUR_MODEL_NAME",
    tools=tools,
    input=input_list,
)
print(final.output_text)

نکته کلیدی این است که خروجی مدل (شامل فراخوانی ابزار) را به فهرست ورودی اضافه می‌کنید و نتیجه تابع را با همان call_id برمی‌گردانید.

کنترل رفتار با tool_choice

مستندات چند حالت برای پارامتر tool_choice معرفی می‌کند:

نکات مهم برای استفاده در پروژه واقعی

• آرگومان‌ها را اعتبارسنجی کنید. خروجی مدل را قبل از اجرا بررسی کنید، مخصوصاً برای توابعی که داده تغییر می‌دهند.
• توابع خطرناک را محدود کنید. حذف داده یا پرداخت را بدون تأیید کاربر انجام ندهید.
• توضیح‌ها را دقیق بنویسید. نام و توضیح مبهم باعث انتخاب اشتباه ابزار می‌شود.
• تعداد ابزارها را کم نگه دارید. ابزارهای زیاد و شبیه هم تصمیم‌گیری مدل را سخت می‌کنند.
• هزینه را در نظر بگیرید. تعریف ابزارها هم جزو ورودی است و توکن مصرف می‌کند؛ درباره محاسبه هزینه توکن‌ها در مقاله جداگانه‌ای در بلاگ نوشته‌ایم.
• کلید API را امن نگه دارید و آن را داخل کد قرار ندهید.

خطاها و حالت‌های خاص

ممکن است مدل چند فراخوانی ابزار را هم‌زمان برگرداند؛ بنابراین حلقه‌ای بنویسید که همه آیتم‌های خروجی را بررسی کند و برای هر کدام نتیجه جداگانه بفرستد. اگر تابع شما با خطا مواجه شد، پیام خطای روشن را به‌عنوان خروجی برگردانید تا مدل بتواند به کاربر توضیح دهد یا آرگومان را اصلاح کند. همچنین برای جلوگیری از حلقه‌های بی‌پایان، تعداد دورهای فراخوانی را محدود کنید و زمان اجرای هر تابع را با مهلت (timeout) کنترل کنید.

Function calling در پروژه‌های ایرانی

کاربردهای عملی فراوانی وجود دارد: دستیار پشتیبانی فروشگاه که وضعیت سفارش را از سیستم شما می‌خواند، ربات تلگرامی که رزرو ثبت می‌کند، یا ابزار داخلی که گزارش‌های فروش را خلاصه می‌کند. در همه این موارد مدل فقط «مغز تصمیم‌گیر» است و منطق کسب‌وکار در کد شما می‌ماند، که هم کنترل بیشتری می‌دهد و هم خطا را کم می‌کند.

بسته به سرویس‌دهنده، نام پارامترها و ساختار پاسخ ممکن است کمی متفاوت باشد؛ مثلاً هم Chat Completions و هم Responses API از ابزارها پشتیبانی می‌کنند اما قالب پیام‌ها فرق دارد. همیشه مستندات نسخه‌ای را که استفاده می‌کنید بخوانید.

جمع‌بندی

Function calling پل میان مدل زبانی و دنیای واقعی برنامه شماست: ابزارها را با JSON Schema تعریف می‌کنید، مدل تصمیم می‌گیرد، شما اجرا می‌کنید و نتیجه را برمی‌گردانید. با اعتبارسنجی آرگومان‌ها و محدود کردن دسترسی‌ها می‌توانید دستیارهای قابل‌اعتماد بسازید. اگر برای شروع به کلید API مدل‌های GPT، Claude، Gemini و دیگر مدل‌ها نیاز دارید، از فروشگاه الین‌لند با پرداخت ریالی و تحویل فوری تهیه کنید.