
فراخوانی تابع (Function Calling) در API هوش مصنوعی با مثال
آموزش Function Calling با API هیبانا؛ تعریف ابزار با tools، اجرای تابع در کد خودتان، حلقهٔ کامل پایتون و نتیجهٔ آزمایش روی پنج مدل.
۶ دقیقه مطالعه
چطور از API هوش مصنوعی JSON قابلاعتماد بگیریم؛ حالت json_object، آزمایش پنج مدل، اعتبارسنجی با Pydantic و تلاش دوباره، با کد پایتون آزمودهشده.

وقتی خروجی مدل را یک انسان میخواند، متن آزاد کافی است. اما وقتی قرار است برنامهٔ شما آن را بخواند، مثلاً برای ذخیره در پایگاه داده، دستهبندی تیکت یا پر کردن یک فرم، به دادهای با شکل ثابت نیاز دارید: یک شیء JSON با کلیدها و نوعهای مشخص. در این مطلب میبینیم پارامتر response_format در API هیبانا دقیقاً چه کاری انجام میدهد و چه کاری نه، نتیجهٔ آزمایش خودمان روی پنج مدل را نشان میدهیم و یک الگوی کامل پایتون میسازیم که JSON مدل را پیش از ورود به برنامه اعتبارسنجی میکند. همهٔ کدها روی API واقعی اجرا شدهاند و خروجیها واقعیاند.
در API رسمی OpenAI دو حالت متفاوت وجود دارد که اغلب با هم اشتباه گرفته میشوند. طبق راهنمای Structured Outputs در مستندات OpenAI:
"type": "json_object") تضمین میکند پاسخ یک JSON معتبر باشد، اما پایبندی به ساختار دلخواه شما را تضمین نمیکند."type": "json_schema") یک JSON Schema میگیرد و پاسخ را به همان ساختار محدود میکند.در مستندات قابلیتهای پیشرفتهٔ هیبانا فقط حالت اول، یعنی json_object، آمده است و همانجا تأکید شده که این پارامتر شکل کلیدها را تضمین نمیکند و باید کلیدهای موردانتظار را در پیام سیستم توضیح دهید. در زمان نگارش این مطلب، در کاتالوگ زندهٔ هیبانا برای همهٔ مدلهای متنی پشتیبانی از حالت JSON ثبت شده است؛ این را در صفحهٔ هر مدل در لیست مدلها میبینید.
نمونهٔ زیر یک نظر کاربر دربارهٔ یک گوشی را به داده تبدیل میکند: حس کلی، نقاط قوت، نقاط ضعف و قیمتی که کاربر گفته است. بهجای YOUR_API_KEY کلید API خودتان را بگذارید. مدل نمونه gpt-5-nano است که برای چنین کاری سریع و کمهزینه است:
import jsonfrom openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api-ai.hibanacloud.ir/v1",) review = "گوشی را هفتهٔ پیش خریدم. باتریاش عالی است ولی دوربینش در شب ضعیف است. قیمتش هم با ۱۸ میلیون تومان کمی بالاست." response = client.chat.completions.create( model="gpt-5-nano", response_format={"type": "json_object"}, messages=[ {"role": "system", "content": ( "نظر کاربر را تحلیل کن و فقط یک شیء JSON با این کلیدها برگردان: " '"sentiment" (یکی از positive، neutral، negative یا mixed)، ' '"pros" (آرایهای از نقاط قوت)، "cons" (آرایهای از نقاط ضعف) ' 'و "price_toman" (عدد صحیح یا null).' )}, {"role": "user", "content": review}, ],) data = json.loads(response.choices[0].message.content)print(json.dumps(data, ensure_ascii=False, indent=2))خروجی واقعی:
{ "sentiment": "mixed", "pros": [ "باتری عالی" ], "cons": [ "دوربین شب ضعیف", "قیمت بالا" ], "price_toman": 18000000}مدل عبارت «۱۸ میلیون تومان» را به عدد 18000000 تبدیل کرد و برای حس کلی مقدار mixed را انتخاب کرد که در فهرست مجاز بود. توجه کنید که همهٔ قواعد، یعنی نام کلیدها، مقدارهای مجاز و نوع هر فیلد، در پیام سیستم نوشته شدهاند؛ response_format بهتنهایی اینها را به مدل نمیگوید.
کتابخانهٔ openai نوع json_schema را هم میفرستد و ممکن است کد فعلی شما از آن استفاده کند. ما همان درخواست بالا را با یک JSON Schema کامل و "strict": True فرستادیم و این بار کلیدها را در پیام سیستم ننوشتیم، چون قرار است اسکیما همین کار را بکند:
response = client.chat.completions.create( model="gpt-5-nano", response_format={ "type": "json_schema", "json_schema": { "name": "product_review", "strict": True, "schema": { "type": "object", "properties": { "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative", "mixed"]}, "pros": {"type": "array", "items": {"type": "string"}}, "cons": {"type": "array", "items": {"type": "string"}}, "price_toman": {"type": ["integer", "null"]}, }, "required": ["sentiment", "pros", "cons", "price_toman"], "additionalProperties": False, }, }, }, messages=[ {"role": "system", "content": "نظر کاربر دربارهٔ محصول را تحلیل کن."}, {"role": "user", "content": review}, ],)درخواست خطایی نداد، اما پاسخ JSON نبود. ابتدای پاسخ واقعی این بود:
تحلیل نظر کاربر: - برداشت کلی: ترکیبی از جنبههای مثبت و منفی. باتری عالی است اما دوربین در شب و قیمت نسبتاً بالا به عنوان نقاط منفی مطرح شدهاند.یعنی در زمان نگارش این مطلب، اسکیما بیصدا نادیده گرفته شد. برای اینکه ببینیم این رفتار به یک مدل محدود است یا نه، هر سه حالت را روی پنج مدل و هر کدام دو بار اجرا کردیم. در حالت json_object و حالت بدون response_format، کلیدها در پیام سیستم نوشته شده بودند:
| مدل | json_schema (بدون کلید در پرامپت) | json_object | بدون response_format |
|---|---|---|---|
gpt-5-nano | متن آزاد (۲ از ۲) | JSON درست (۲ از ۲) | JSON درست (۲ از ۲) |
gemini-3.7-flash | متن آزاد (۲ از ۲) | JSON درست (۲ از ۲) | JSON داخل ``` (۲ از ۲) |
deepseek-v4-flash | متن آزاد (۲ از ۲) | JSON درست (۲ از ۲) | JSON درست (۲ از ۲) |
claude-haiku-4-5 | متن آزاد (۲ از ۲) | JSON داخل ``` (۲ از ۲) | JSON داخل ``` (۲ از ۲) |
gpt-oss | متن آزاد (۲ از ۲) | یک بار درست، یک بار داخل ``` | JSON درست (۲ از ۲) |
این جدول نتیجهٔ سی اجرای کوچک است، نه یک بنچمارک؛ اما سه درس روشن دارد:
json_schema تکیه نکنید. در آزمایش ما هیچ مدلی آن را رعایت نکرد و خطایی هم برنگشت. اسکیما را در پیام سیستم بنویسید.json_object را نگه دارید. برای سه مدل از پنج مدل، همین پارامتر خروجی را کاملاً تمیز کرد.json_object پاسخ را داخل ```json گذاشت و json.loads مستقیم روی آن خطا میدهد.راه مطمئن این است که ساختار را یک بار در کد تعریف کنید، همان را به مدل نشان دهید و پاسخ را با همان تعریف بسنجید. کتابخانهٔ Pydantic هر دو کار را انجام میدهد: model_json_schema() از کلاس شما JSON Schema میسازد و model_validate() پاسخ را بر اساس همان کلاس اعتبارسنجی میکند. ابتدا pip install openai pydantic را اجرا کنید:
import jsonimport refrom typing import Literal, Optional from openai import OpenAIfrom pydantic import BaseModel, ValidationError client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api-ai.hibanacloud.ir/v1",) class Review(BaseModel): sentiment: Literal["positive", "neutral", "negative", "mixed"] pros: list[str] cons: list[str] price_toman: Optional[int] SYSTEM = ( "نظر کاربر دربارهٔ محصول را تحلیل کن و فقط یک شیء JSON برگردان " "که با این JSON Schema مطابقت داشته باشد. هیچ متن دیگری ننویس.\n" + json.dumps(Review.model_json_schema(), ensure_ascii=False)) def parse_json(text: str) -> dict: # بعضی مدلها JSON را داخل بلوک کد Markdown میگذارند match = re.search(r"```(?:json)?\s*(.*?)\s*```", text, re.DOTALL) return json.loads(match.group(1) if match else text) def analyze(review: str, model: str = "gpt-5-nano", attempts: int = 2) -> Review: messages = [ {"role": "system", "content": SYSTEM}, {"role": "user", "content": review}, ] for _ in range(attempts): response = client.chat.completions.create( model=model, response_format={"type": "json_object"}, messages=messages, ) text = response.choices[0].message.content or "" try: return Review.model_validate(parse_json(text)) except (json.JSONDecodeError, ValidationError) as error: # خطا را به مدل برمیگردانیم تا خودش اصلاح کند messages.append({"role": "assistant", "content": text}) messages.append({"role": "user", "content": f"این خروجی معتبر نبود: {error}. فقط JSON درست را برگردان."}) raise ValueError("مدل پس از چند تلاش JSON معتبر برنگرداند") review = "گوشی را هفتهٔ پیش خریدم. باتریاش عالی است ولی دوربینش در شب ضعیف است. قیمتش هم با ۱۸ میلیون تومان کمی بالاست."result = analyze(review)print(result)خروجی واقعی با gpt-5-nano:
sentiment='mixed' pros=['باتری عالی'] cons=['دوربین شب ضعیف است', 'قیمت بالا است'] price_toman=18000000حالا result یک شیء پایتون با نوعهای مشخص است: result.price_toman یک عدد صحیح است و result.sentiment حتماً یکی از چهار مقدار مجاز. همین تابع را با analyze(review, model="claude-haiku-4-5") هم اجرا کردیم. پاسخ خام Claude دوباره داخل ```json بود، اما parse_json آن را جدا کرد و نتیجه در همان تلاش اول معتبر شد. هزینهٔ اجرای gpt-5-nano در آزمایش ما ۱٬۴۴۷ ریال بود؛ قیمت فعلی هر مدل را در صفحهٔ آن مدل ببینید.
حلقهٔ تلاش دوباره فقط وقتی مفید است که پیام خطا برای مدل قابلفهم باشد. Pydantic دقیقاً میگوید کدام فیلد و چرا مشکل دارد. اگر مدل بهجای mixed بنویسد good و قیمت را متنی برگرداند، این خطای واقعی Pydantic است:
2 validation errors for Reviewsentiment Input should be 'positive', 'neutral', 'negative' or 'mixed' [type=literal_error, input_value='good', input_type=str] For further information visit https://errors.pydantic.dev/2.14/v/literal_errorprice_toman Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='۱۸ میلیون', input_type=str] For further information visit https://errors.pydantic.dev/2.14/v/int_parsingهمین متن بهعنوان پیام کاربر به گفتوگو اضافه میشود و مدل در تلاش دوم میداند چه چیزی را درست کند. چند نکتهٔ دیگر:
پاسخ خالی را هم در نظر بگیرید
مدلهای استدلالی مثل gpt-5-nano بخشی از بودجهٔ پاسخ را صرف استدلال میکنند. اگر max_tokens را خیلی کم بگذارید، ممکن است پیش از نوشتن JSON متوقف شوند و content خالی برگردد. عبارت or "" در کد بالا همین حالت را به خطایی تبدیل میکند که میتوان پس از آن دوباره تلاش کرد. نشانههای این مشکل در رفع اشکال آمده است.
برای گرفتن JSON قابلاعتماد از API هیبانا، response_format={"type": "json_object"} را بفرستید، ساختار را با جزئیات در پیام سیستم بنویسید و پاسخ را پیش از استفاده در کد اعتبارسنجی کنید. در زمان نگارش این مطلب، json_schema در آزمایش ما اثری نداشت، پس اسکیما را در پرامپت بگذارید، نه فقط در پارامتر. برای شروع کلید API بگیرید و نمونهٔ بالا را اجرا کنید. جزئیات پارامترها در مستندات قابلیتهای پیشرفته و مستندات Chat Completions آمده است و اگر از مدلهای OpenAI استفاده میکنید، راهنمای API چت جی پی تی در ایران را هم ببینید.

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

متن فارسی را با API هیبانا به فایل صوتی تبدیل کنید؛ آزمایش واقعی شش مدل ElevenLabs، Gemini و MiniMax با هزینه، سرعت و خواندن عدد و تاریخ، همراه نمونهکد پایتون.
۷ دقیقه مطالعه

وردپرس را به API هوش مصنوعی هیبانا وصل کنید؛ با افزونهٔ AI Engine یا یک تابع PHP آزمودهشده، همراه خلاصهٔ خودکار نوشتهها و رفع خطای cURL error 28.
۵ دقیقه مطالعه
GPT، Claude، Gemini و دهها مدل دیگر، با پرداخت ریالی و یک API سازگار با OpenAI.