ساختار خروجی هوش مصنوعی: آموزش Structured Outputs و JSON Schema در API

خروجی ساختاریافته (Structured Outputs) قابلیتی در API هوش مصنوعی است که تضمین می‌کند پاسخ مدل دقیقاً با JSON Schema تعریف‌شده توسط شما هماهنگ باشد. اگر تا حالا مجبور شده‌اید با پرامپت‌های «فقط JSON برگردان!» مدل را مجبور به رعایت قالب کنید، این راهنما برای شماست. بر پایه مستندات رسمی OpenAI، مفهوم، روش استفاده و محدودیت‌ها را مرور می‌کنیم.

مشکل خروجی آزاد چیست؟

وقتی از مدل می‌خواهید داده‌ای را استخراج کند (مثلاً نام، تاریخ و شرکت‌کنندگان یک رویداد از یک متن)، ممکن است پاسخ شامل توضیح اضافه باشد، یک کلید جا بیفتد یا مقدار یک فیلد از لیست مجاز بیرون باشد. برنامه شما باید این حالت‌ها را بررسی و دوباره تلاش کند. طبق مستندات، Structured Outputs این دردسر را کم می‌کند: مدل کلید لازم را حذف نمی‌کند و مقدار نامعتبر برای enum تولید نمی‌کند.

مزایای خروجی ساختاریافته در API

• ایمنی نوع: نیازی به اعتبارسنجی و تلاش مجدد برای قالب نادرست نیست.
• امتناع قابل تشخیص: رد درخواست به دلایل ایمنی به‌صورت برنامه‌نویسی قابل شناسایی است.
• پرامپت ساده‌تر: دیگر لازم نیست برای رعایت قالب، دستورهای تأکیدی طولانی بنویسید.

دو روش استفاده

مستندات دو شکل برای این قابلیت معرفی می‌کند:

1. Function calling: وقتی مدل را به ابزارها و توابع برنامه‌تان وصل می‌کنید (راهنمای function calling را در همین وبلاگ ببینید).
2. قالب پاسخ json_schema: وقتی فقط می‌خواهید پاسخ نهایی به کاربر یا برنامه شما ساختار مشخصی داشته باشد.

قاعده ساده: اگر مدل باید کاری در دنیای بیرون انجام دهد، function calling؛ اگر فقط داده ساختاریافته می‌خواهید، json_schema.

نمونه کد پایتون برای استخراج اطلاعات

کتابخانه رسمی پایتون اجازه می‌دهد ساختار را با Pydantic تعریف کنید. نام مدل را با مدلی که از آن استفاده می‌کنید جایگزین کنید؛ طبق مستندات، این قابلیت از GPT-4o به بعد پشتیبانی می‌شود:

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

response = client.responses.parse(
    model="YOUR_MODEL_NAME",
    input=[
        {"role": "system", "content": "اطلاعات رویداد را استخراج کن."},
        {"role": "user", "content": "سارا و علی جمعه به نمایشگاه علمی می‌روند."},
    ],
    text_format=CalendarEvent,
)

event = response.output_parsed
print(event.name, event.date, event.participants)

نتیجه از قبل به یک شیء پایتون تبدیل شده و لازم نیست رشته JSON را خودتان تجزیه کنید.

قوانین مهم JSON Schema در Structured Outputs

برای اینکه طرح شما پذیرفته شود، چند شرط مستندات را رعایت کنید:

اگر می‌خواهید یک فیلد اختیاری باشد، طبق مستندات می‌توانید نوع آن را اتحادی با null تعریف کنید، ولی خود فیلد همچنان باید در required بیاید.

JSON mode و تفاوتش با خروجی ساختاریافته

مدل‌های قدیمی‌تر مثل gpt-4-turbo و پیش از آن، به‌جای Structured Outputs از JSON mode استفاده می‌کنند. JSON mode فقط به معتبر بودن JSON کمک می‌کند، نه به تطابق با طرح مشخص شما. پس اگر مدل شما از Structured Outputs پشتیبانی می‌کند، همان را انتخاب کنید.

نکات عملی برای پروژه‌های فارسی

• برای نام کلیدها از انگلیسی استفاده کنید و مقدارها می‌توانند فارسی باشند.
• در فیلد description هر ویژگی توضیح کوتاه بنویسید؛ مدل از آن برای فهم منظور شما استفاده می‌کند.
• برای فیلدهایی با گزینه‌های ثابت (مثل وضعیت سفارش) از enum استفاده کنید.
• همچنان خروجی را قبل از ذخیره در پایگاه داده بررسی منطقی کنید؛ ساختار درست به معنی درست بودن محتوا نیست.
• حالت امتناع مدل را در کد خود مدیریت کنید تا برنامه در این شرایط خطا ندهد.

کاربردها

استخراج اطلاعات از ایمیل و فاکتور، دسته‌بندی تیکت‌های پشتیبانی، تولید داده برای فرم‌ها، تبدیل متن آزاد به رکورد پایگاه داده و ساخت پاسخ‌هایی که مستقیماً در رابط کاربری نمایش داده می‌شوند، از رایج‌ترین موارد هستند.

چرا ساختار پاسخ برای سئو و تجربه کاربر مهم است؟

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

الگوی پیشنهادی برای شروع

1. ابتدا خروجی دلخواه را روی کاغذ به‌صورت یک نمونه JSON بنویسید.
2. از روی آن طرح را با Pydantic یا JSON Schema بسازید.
3. برای هر فیلد توضیح کوتاه بنویسید.
4. با چند ورودی واقعی و متفاوت تست کنید، از جمله ورودی ناقص یا نامربوط.
5. اگر طرح بزرگ شد، آن را به چند درخواست کوچک‌تر تقسیم کنید تا از محدودیت‌های اندازه دور بمانید.

جمع‌بندی

خروجی ساختاریافته در API هوش مصنوعی به شما کمک می‌کند به‌جای مبارزه با قالب پاسخ، روی منطق برنامه تمرکز کنید. طرح را با Pydantic یا JSON Schema بنویسید، همه فیلدها را required کنید، additionalProperties را false بگذارید و پاسخ قابل‌اعتمادتری بگیرید. برای شروع و تهیه کلید API مدل‌های هوش مصنوعی با پرداخت ریالی، به فروشگاه الین‌لند سر بزنید.