رفتن به محتوا

فراخوانی تابع (Function Calling) در API هوش مصنوعی با مثال

آموزش Function Calling با API هیبانا؛ تعریف ابزار با tools، اجرای تابع در کد خودتان، حلقهٔ کامل پایتون و نتیجهٔ آزمایش روی پنج مدل.

ینال احمدزاده۶ دقیقه مطالعه
رباتی کوچک پشت میز کار که از میان کشوهای یک قفسهٔ چوبی یکی را باز می‌کند و کارتی سفید از آن برمی‌دارد

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

فراخوانی تابع چطور کار می‌کند؟

نکتهٔ اول و مهم‌ترین نکته این است که مدل هیچ تابعی را اجرا نمی‌کند. مدل فقط می‌گوید «این تابع را با این آرگومان‌ها صدا بزن» و اجرای آن با کد خود شماست. طبق راهنمای Function Calling در مستندات OpenAI روند کار پنج مرحله دارد:

  1. درخواست را همراه با فهرست ابزارها (پارامتر tools) می‌فرستید.
  2. مدل به‌جای متن، یک یا چند درخواست فراخوانی (tool_calls) برمی‌گرداند.
  3. تابع را در کد خودتان با همان آرگومان‌ها اجرا می‌کنید.
  4. نتیجه را در یک پیام با نقش tool به گفت‌وگو اضافه می‌کنید و دوباره درخواست می‌فرستید.
  5. مدل پاسخ نهایی را می‌نویسد، یا اگر لازم باشد دوباره تابعی درخواست می‌کند.

API هیبانا با OpenAI سازگار است و همین پارامترها را می‌پذیرد؛ نمونهٔ ساختار درخواست در مستندات قابلیت‌های پیشرفته آمده است. در زمان نگارش این مطلب، در کاتالوگ زندهٔ هیبانا برای همهٔ ۸۰ مدل متنی پشتیبانی از فراخوانی ابزار ثبت شده است؛ مدل‌های امبدینگ مثل bge-m3 این قابلیت را ندارند. وضعیت هر مدل را در صفحهٔ آن در لیست مدل‌ها ببینید.

تعریف تابع و ابزار

ابتدا pip install openai را اجرا کنید و به‌جای YOUR_API_KEY کلید API خودتان را بگذارید. تابع get_product در این نمونه از یک دیکشنری می‌خواند؛ در برنامهٔ واقعی همین‌جا به پایگاه داده یا API انبار وصل می‌شوید:

import jsonfrom openai import OpenAI client = OpenAI(    api_key="YOUR_API_KEY",    base_url="https://api-ai.hibanacloud.ir/v1",) # داده‌های نمونه؛ در برنامهٔ واقعی این‌ها از پایگاه داده می‌آیندPRODUCTS = {    "A-101": {"name": "هدفون بی‌سیم", "price_toman": 2_450_000, "stock": 12},    "A-205": {"name": "پاوربانک ۲۰ هزار", "price_toman": 1_380_000, "stock": 0},}  def get_product(product_id: str) -> dict:    product = PRODUCTS.get(product_id.strip().upper())    if product is None:        return {"error": "محصولی با این شناسه پیدا نشد"}    return {"product_id": product_id.strip().upper(), **product}  tools = [    {        "type": "function",        "function": {            "name": "get_product",            "description": "قیمت فعلی (تومان) و موجودی انبار یک محصول را با شناسهٔ آن برمی‌گرداند.",            "parameters": {                "type": "object",                "properties": {                    "product_id": {                        "type": "string",                        "description": "شناسهٔ محصول، مثل A-101",                    }                },                "required": ["product_id"],            },        },    }] FUNCTIONS = {"get_product": get_product}

هر ابزار یک نام، یک توضیح و یک JSON Schema برای ورودی‌هایش دارد. مدل فقط همین سه چیز را می‌بیند، نه کد تابع را. پس توضیح‌ها باید بگویند تابع چه می‌کند و ورودی چه شکلی دارد. در ادامه می‌بینیم این جمله‌ها چقدر در نتیجه اثر دارند.

اولین پاسخ مدل؛ درخواست فراخوانی

اگر سؤال «قیمت A-101 چند است؟» را با این ابزار به gpt-5-nano بفرستید، finish_reason برابر tool_calls است و پیام مدل این شکل را دارد (خروجی واقعی):

{  "content": "",  "role": "assistant",  "tool_calls": [    {      "id": "call_zu8LxR6uWNWZEFbAbRKWypfJ",      "function": {        "arguments": "{\"product_id\":\"A-101\"}",        "name": "get_product"      },      "type": "function"    }  ]}

دو نکته در این پاسخ هست. arguments یک رشته است، نه شیء؛ باید خودتان آن را با json.loads باز کنید و ممکن است JSON نامعتبر باشد. و id را باید در پیام نتیجه برگردانید تا مدل بداند هر نتیجه مال کدام فراخوانی است.

حلقهٔ کامل؛ از سؤال تا پاسخ نهایی

بسیاری از نمونه‌ها دقیقاً دو درخواست می‌فرستند: یکی برای گرفتن فراخوانی و یکی برای پاسخ نهایی. اما مدل ممکن است در یک دور چند تابع بخواهد یا پس از دیدن نتیجه، تابع دیگری درخواست کند. در آزمایش ما gpt-oss در یک اجرا دو محصول را در دو دور جدا پرسید و در اجرای دیگر هر دو را با هم. پس به‌جای دو مرحلهٔ ثابت، یک حلقه بنویسید که تا رسیدن به پاسخ متنی ادامه دهد:

def ask(question: str, model: str = "gpt-5-nano", max_rounds: int = 5) -> str:    messages = [        {"role": "system", "content": "تو دستیار فروشگاه هستی. قیمت و موجودی را فقط از ابزار get_product بگیر."},        {"role": "user", "content": question},    ]    for _ in range(max_rounds):        response = client.chat.completions.create(model=model, messages=messages, tools=tools)        message = response.choices[0].message        if not message.tool_calls:            return message.content  # پاسخ نهایی؛ دیگر تابعی لازم نیست         messages.append(message)  # درخواست فراخوانی مدل باید در تاریخچه بماند        for call in message.tool_calls:            print("tool call:", call.function.name, call.function.arguments)            function = FUNCTIONS.get(call.function.name)            try:                args = json.loads(call.function.arguments or "{}")                result = function(**args) if function else {"error": "تابع ناشناخته"}            except (json.JSONDecodeError, TypeError) as error:                result = {"error": f"آرگومان نامعتبر: {error}"}            messages.append({                "role": "tool",                "tool_call_id": call.id,                "content": json.dumps(result, ensure_ascii=False),            })    raise RuntimeError("مدل پس از چند دور به پاسخ نهایی نرسید")  print(ask("قیمت A-101 چند است و A-205 موجود است؟"))

خروجی واقعی با gpt-5-nano:

tool call: get_product {"product_id": "A-101"}tool call: get_product {"product_id": "A-205"}- A-101: قیمت 2,450,000 تومان. موجودی: 12 عدد در انبار.- A-205: موجود نیست در حال حاضر (موجودی 0). نیاز دارید محصول جایگزین پیشنهاد بدهم؟ یا می‌خواهم زمانی که دوباره موجود شد به شما اطلاع بدهم.

مدل در یک دور دو فراخوانی موازی خواست و پاسخ را دقیقاً بر اساس داده‌های تابع نوشت. چند جزء این حلقه عمدی است:

  • خطا را به مدل برگردانید، نه به کاربر. برای شناسهٔ ناموجود A-999 تابع {"error": ...} برگرداند و مدل به کاربر گفت چنین محصولی پیدا نشد و شناسهٔ درست را خواست، بی‌آنکه قیمتی بسازد.
  • سقف دور بگذارید. هر دور یک درخواست جدید و هزینه‌دار است و max_rounds جلوی حلقهٔ بی‌پایان را می‌گیرد.
  • مدل همیشه تابع صدا نمی‌زند. برای «یک جملهٔ خوشامد کوتاه بگو» هیچ فراخوانی‌ای انجام نشد و حلقه در همان دور اول پاسخ را برگرداند.

همین تابع ask را بدون تغییر با چهار مدل دیگر هم اجرا کردیم: deepseek-v4-flash، claude-haiku-4-5، gemini-3.7-flash و gpt-oss. هر چهار مدل هر دو محصول را درست خواستند و پاسخ درست دادند. هزینهٔ هر بار اجرای کامل در آزمایش ما از حدود ۱٬۰۰۰ ریال برای gpt-oss تا حدود ۱۲٬۰۰۰ ریال برای Claude Haiku 4.5 بود؛ قیمت فعلی هر مدل را در صفحهٔ آن ببینید.

توضیح ابزار را جدی بگیرید

برای اینکه ببینیم متن توضیح‌ها چقدر مهم است، سؤال کوتاه «A-101 چند است؟» را سه بار با ابزار بالا و سه بار با نسخه‌ای کوتاه‌تر به gpt-5-nano فرستادیم. در نسخهٔ کوتاه، توضیح تابع فقط «قیمت و موجودی محصول» بود و توضیح product_id حذف شده بود:

تعریف ابزارنتیجه
توضیح کامل با مثال «مثل A-101»فراخوانی درست تابع (۳ از ۳)
توضیح کوتاه، بدون مثالپاسخ متنی و درخواست شناسهٔ محصول از کاربر (۳ از ۳)
توضیح کوتاه، همراه با پیام سیستمباز هم پاسخ متنی (۳ از ۳)

مدل در نسخهٔ کوتاه نفهمید که «A-101» همان شناسهٔ محصول است و از کاربر شناسه خواست. این آزمایشی کوچک است، نه بنچمارک، اما درسش روشن است: در توضیح پارامترها شکل ورودی را با یک مثال بگویید. راهنمای OpenAI هم توصیه می‌کند نام تابع‌ها، توضیح پارامترها و دستورها روشن و دقیق باشند و تعداد تابع‌های در دسترس در هر نوبت کمتر از ۲۰ باشد. یادتان باشد تعریف ابزارها جزو توکن‌های ورودی هر درخواست حساب می‌شود؛ دربارهٔ محاسبهٔ هزینه در توکن چیست و هزینهٔ API چطور حساب می‌شود نوشته‌ایم.

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

پارامتر tool_choice تعیین می‌کند مدل چه زمانی ابزار صدا بزند. طبق مرجع Chat Completions در مستندات OpenAI این مقدارها را می‌پذیرد و ما هر کدام را با gpt-5-nano و gpt-oss آزمودیم:

  • "auto" (پیش‌فرض): مدل خودش تصمیم می‌گیرد.
  • "required": مدل باید دست‌کم یک ابزار صدا بزند. هر دو مدل get_product را صدا زدند.
  • {"type": "function", "function": {"name": "get_product"}}: فراخوانی همین تابع اجباری است. نتیجه همان بود.
  • "none": مدل ابزاری صدا نمی‌زند، حتی اگر ابزارها در درخواست باشند. هر دو مدل پاسخ متنی دادند.

پارامتر parallel_tool_calls: false هم فراخوانی‌ها را به حداکثر یکی در هر دور محدود می‌کند؛ با آن، gpt-5-nano برای همان سؤال دو محصولی فقط A-101 را در دور اول خواست. حلقهٔ بالا این حالت را هم بدون تغییر پشتیبانی می‌کند.

فیلد "strict": true در تعریف تابع را هم فرستادیم. درخواست بدون خطا پذیرفته شد و gpt-5-nano و deepseek-v4-flash آرگومان‌های درست فرستادند، اما از روی چند اجرا نمی‌توان گفت این فیلد در هیبانا واقعاً اعمال می‌شود. در مطلب خروجی JSON دیدیم json_schema بی‌صدا نادیده گرفته شد؛ پس آرگومان‌ها را همیشه در کد خودتان اعتبارسنجی کنید.

تابع‌های خطرناک را بدون تأیید اجرا نکنید

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

جمع‌بندی

فراخوانی تابع یعنی مدل تصمیم می‌گیرد و کد شما اجرا می‌کند: ابزارها را با tools و توضیح دقیق معرفی کنید، فراخوانی‌ها را در یک حلقه اجرا کنید، نتیجه را با نقش tool و همان tool_call_id برگردانید و آرگومان‌ها را پیش از اجرا بسنجید. برای شروع کلید API بگیرید و نمونهٔ بالا را اجرا کنید. پارامترهای درخواست در مستندات Chat Completions آمده‌اند؛ اگر می‌خواهید ابزارهای آماده را بدون نوشتن تابع به مدل وصل کنید، MCP چیست را بخوانید و برای خطاهای HTTP مثل ۴۰۲ و ۴۲۹ سراغ خطاهای API هوش مصنوعی بروید.

مطالب مرتبط

با یک کلید به همه مدل‌ها وصل شوید

GPT، Claude، Gemini و ده‌ها مدل دیگر، با پرداخت ریالی و یک API سازگار با OpenAI.