رفتن به محتوا

خروجی JSON ساختاریافته از مدل‌های هوش مصنوعی؛ حالت JSON و اعتبارسنجی

چطور از API هوش مصنوعی JSON قابل‌اعتماد بگیریم؛ حالت json_object، آزمایش پنج مدل، اعتبارسنجی با Pydantic و تلاش دوباره، با کد پایتون آزموده‌شده.

مهدی سهندی۵ دقیقه مطالعه
رباتی کوچک که تکه‌های درهم کاغذ را در جعبه‌های مرتب و هم‌اندازه روی یک قفسه می‌چیند

وقتی خروجی مدل را یک انسان می‌خواند، متن آزاد کافی است. اما وقتی قرار است برنامهٔ شما آن را بخواند، مثلاً برای ذخیره در پایگاه داده، دسته‌بندی تیکت یا پر کردن یک فرم، به داده‌ای با شکل ثابت نیاز دارید: یک شیء JSON با کلیدها و نوع‌های مشخص. در این مطلب می‌بینیم پارامتر response_format در API هیبانا دقیقاً چه کاری انجام می‌دهد و چه کاری نه، نتیجهٔ آزمایش خودمان روی پنج مدل را نشان می‌دهیم و یک الگوی کامل پایتون می‌سازیم که JSON مدل را پیش از ورود به برنامه اعتبارسنجی می‌کند. همهٔ کدها روی API واقعی اجرا شده‌اند و خروجی‌ها واقعی‌اند.

دو سطح از «خروجی JSON»

در API رسمی OpenAI دو حالت متفاوت وجود دارد که اغلب با هم اشتباه گرفته می‌شوند. طبق راهنمای Structured Outputs در مستندات OpenAI:

  • حالت JSON ("type": "json_object") تضمین می‌کند پاسخ یک JSON معتبر باشد، اما پایبندی به ساختار دلخواه شما را تضمین نمی‌کند.
  • Structured Outputs ("type": "json_schema") یک JSON Schema می‌گیرد و پاسخ را به همان ساختار محدود می‌کند.

در مستندات قابلیت‌های پیشرفتهٔ هیبانا فقط حالت اول، یعنی json_object، آمده است و همان‌جا تأکید شده که این پارامتر شکل کلیدها را تضمین نمی‌کند و باید کلیدهای موردانتظار را در پیام سیستم توضیح دهید. در زمان نگارش این مطلب، در کاتالوگ زندهٔ هیبانا برای همهٔ مدل‌های متنی پشتیبانی از حالت JSON ثبت شده است؛ این را در صفحهٔ هر مدل در لیست مدل‌ها می‌بینید.

اولین درخواست با json_object

نمونهٔ زیر یک نظر کاربر دربارهٔ یک گوشی را به داده تبدیل می‌کند: حس کلی، نقاط قوت، نقاط ضعف و قیمتی که کاربر گفته است. به‌جای 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 به‌تنهایی این‌ها را به مدل نمی‌گوید.

json_schema در هیبانا؛ آزمایش ما

کتابخانهٔ 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 درست (۲ از ۲)

این جدول نتیجهٔ سی اجرای کوچک است، نه یک بنچمارک؛ اما سه درس روشن دارد:

  1. به json_schema تکیه نکنید. در آزمایش ما هیچ مدلی آن را رعایت نکرد و خطایی هم برنگشت. اسکیما را در پیام سیستم بنویسید.
  2. json_object را نگه دارید. برای سه مدل از پنج مدل، همین پارامتر خروجی را کاملاً تمیز کرد.
  3. کد شما باید JSON داخل بلوک کد را هم بفهمد. Claude Haiku 4.5 حتی با 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

همین متن به‌عنوان پیام کاربر به گفت‌وگو اضافه می‌شود و مدل در تلاش دوم می‌داند چه چیزی را درست کند. چند نکتهٔ دیگر:

  • تعداد تلاش را محدود نگه دارید. هر تلاش دوباره یک درخواست جدید است و هزینه دارد. دو تلاش معمولاً کافی است؛ پس از آن خطا را ثبت کنید و موضوع را به انسان بسپارید.
  • اعتبارسنجی معنایی را فراموش نکنید. JSON معتبر یعنی شکل درست، نه محتوای درست. اگر مثلاً جمع ردیف‌های یک فاکتور باید با مبلغ کل برابر باشد، این را جداگانه در کد بررسی کنید؛ نمونه‌ای از این کار در ارسال تصویر و PDF به API هوش مصنوعی آمده است.
  • خطاهای HTTP را جدا از خطای JSON مدیریت کنید. خطاهایی مثل ۴۰۲ یا ۴۲۹ ربطی به شکل پاسخ ندارند و تلاش دوبارهٔ بالا آن‌ها را نمی‌گیرد. راه‌حل هر کدام را در خطاهای API هوش مصنوعی نوشته‌ایم.

پاسخ خالی را هم در نظر بگیرید

مدل‌های استدلالی مثل gpt-5-nano بخشی از بودجهٔ پاسخ را صرف استدلال می‌کنند. اگر max_tokens را خیلی کم بگذارید، ممکن است پیش از نوشتن JSON متوقف شوند و content خالی برگردد. عبارت or "" در کد بالا همین حالت را به خطایی تبدیل می‌کند که می‌توان پس از آن دوباره تلاش کرد. نشانه‌های این مشکل در رفع اشکال آمده است.

جمع‌بندی

برای گرفتن JSON قابل‌اعتماد از API هیبانا، response_format={"type": "json_object"} را بفرستید، ساختار را با جزئیات در پیام سیستم بنویسید و پاسخ را پیش از استفاده در کد اعتبارسنجی کنید. در زمان نگارش این مطلب، json_schema در آزمایش ما اثری نداشت، پس اسکیما را در پرامپت بگذارید، نه فقط در پارامتر. برای شروع کلید API بگیرید و نمونهٔ بالا را اجرا کنید. جزئیات پارامترها در مستندات قابلیت‌های پیشرفته و مستندات Chat Completions آمده است و اگر از مدل‌های OpenAI استفاده می‌کنید، راهنمای API چت جی پی تی در ایران را هم ببینید.

مطالب مرتبط

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

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