پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

خروجی‌های ساختاریافته

با استفاده از text.format در /v1/responses یا response_format در /v1/chat/completions، اطمینان حاصل کنید که پاسخ‌های مدل به یک ساختار JSON خاص پایبند هستند.

مقدمه

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

دو راه اصلی برای اعمال خروجی JSON وجود دارد:

خروجی‌های ساختاریافته (json_schema): (توصیه می‌شود) تضمین می‌کند که خروجی نه تنها JSON معتبر است، بلکه دقیقا با یک JSON Schema ارائه شده مطابقت دارد. این از مشکلاتی مانند کلیدهای گمشده یا مقادیر نامعتبر جلوگیری می‌کند.
حالت JSON (json_object): تضمین می‌کند که خروجی یک شی JSON معتبر است اما در برابر یک طرحواره خاص اعتبارسنجی نمی‌کند. برای هدایت مدل به سمت ساختار مورد نظر، نیاز به پرامپت‌نویسی دقیق دارد.

مزایای خروجی‌های ساختاریافته (json_schema):

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

راهنمای سریع انتخاب

نیاز	استفاده کنید از	دلیل
پاسخ نهایی تایپ‌شده برای UI، ذخیره‌سازی یا routing	`text.format` در Responses با `type: "json_schema"`	پاسخ مستقیم مدل با schema شما محدود می‌شود.
آرگومان ابزار برای کد برنامه شما	فراخوانی تابع با `strict: true`	schema یک عملیات قابل فراخوانی را توصیف می‌کند، نه پاسخ نهایی کاربر.
فقط JSON معتبر لازم است و schema در دسترس نیست	حالت `json_object`	به‌عنوان fallback مفید است، اما همچنان شکل خروجی را در برنامه اعتبارسنجی کنید.
fallback ایمنی یا سیاست محصول	schema شامل فیلدهای nullable یا شیء خطای سطح اپلیکیشن	وقتی ورودی کاربر به task نگاشت نمی‌شود، مدل به یک شکل مجاز برای پاسخ نیاز دارد.

در AvalAI برای گردش‌کارهای جدید خروجی ساختاریافته، /v1/responses را ترجیح دهید و مثال‌های /v1/chat/completions را برای ادغام‌های موجودی نگه دارید که به response_format وابسته‌اند.

مستندات Structured Outputs در OpenAI را مرجع شکل API بدانید، نه تضمین کلی برای همه routeهای ارائه‌دهنده در AvalAI. مدل، endpoint و شکل schema دقیق مورد استفاده در production را تست کنید؛ اگر json_schema در دسترس نبود، به JSON mode همراه با validation سمت برنامه fallback کنید.

دریافت پاسخ ساختاریافته (`json_schema`)

python

import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

event_schema = {
    "name": "calendar_event",
    "strict": True,
    "schema": {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "نام رویداد"},
            "date": {"type": "string", "description": "تاریخ رویداد"},
            "participants": {
                "type": "array",
                "items": {"type": "string"},
                "description": "لیست شرکت‌کنندگان",
            },
        },
        "required": ["name", "date", "participants"],
        "additionalProperties": False,  # مهم برای پایبندی دقیق به طرحواره
    },
}

try:
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=[
            {
                "role": "system",
                "content": "اطلاعات رویداد را در قالب JSON مشخص شده استخراج کنید.",
            },
            {"role": "user", "content": "آلیس و باب جمعه به نمایشگاه علوم می‌روند."},
        ],
        response_format={"type": "json_schema", "json_schema": event_schema},
    )

    message = response.choices[0].message
    if getattr(message, "refusal", None):
        print("Model refused:", message.refusal)
    else:
        print(json.loads(message.content))
except Exception as e:
    print(f"An API error occurred: {e}")

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، برای خروجی ساختاریافته از text.format با type: "json_schema" استفاده کنید. رشته JSON نهایی را از response.output_text بخوانید و اگر لازم است خروجی عادی را از امتناع ایمنی جدا کنید، آیتم‌های response.output را بررسی کنید.

python

import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    instructions="Extract the event information into the specified JSON schema.",
    input="آلیس و باب جمعه به نمایشگاه علوم می‌روند.",
    text={
        "format": {
            "type": "json_schema",
            "name": "calendar_event",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "date": {"type": "string"},
                    "participants": {
                        "type": "array",
                        "items": {"type": "string"},
                    },
                },
                "required": ["name", "date", "participants"],
                "additionalProperties": False,
            },
        }
    },
)

print(json.loads(response.output_text))

response_format در Chat Completions → text.format در Responses
messages → input و راهنمای پایدار system/developer → instructions
choices[0].message.content → response.output_text
برای امتناع‌های ایمنی یا خروجی‌های ترکیبی، response.output را بر اساس نوع آیتم و content-part بررسی کنید.

(توجه: برای جریان‌های جدید خروجی ساختاریافته، /v1/responses همراه text.format را ترجیح دهید. مثال Chat Completions را برای ادغام‌های موجودی نگه دارید که از response_format استفاده می‌کنند).

پیش از اعتماد، Parse کنید

schema ارسالی به API را خط دفاع اول بدانید، نه تنها خط دفاع. پیش از نوشتن در پایگاه داده، اجرای workflow یا نمایش UI دارای دسترسی، response.status، content partهای refusal و invariantهای اختصاصی برنامه را بررسی کنید. سپس JSON کامل را با typeهای runtime برنامه خود parse و validate کنید.

برای workflowهای حساس، نام/نسخه schema، مدل، route و خطاهای validation را log کنید. این کار تشخیص regression را هنگام تغییر prompt، schema یا route ارائه‌دهنده ساده‌تر می‌کند.

همگام نگه داشتن Schema و Typeها

OpenAI توصیه می‌کند از helperهای SDK یا کتابخانه‌های schema مانند Pydantic و Zod استفاده کنید تا typeهای runtime از JSON Schema ارسالی به API جدا و ناسازگار نشوند. اگر schema را دستی نگه می‌دارید، یک بررسی کوچک در CI اضافه کنید که وقتی schema یا type متناظر تغییر می‌کند اما دیگری به‌روز نشده، شکست بخورد.

python

from pydantic import BaseModel, ConfigDict


class CalendarEvent(BaseModel):
    model_config = ConfigDict(extra="forbid")

    name: str
    date: str
    participants: list[str]


event_schema = {
    "name": "calendar_event",
    "strict": True,
    "schema": CalendarEvent.model_json_schema(),
}

طراحی Schema برای قابلیت اعتماد مدل

JSON Schema هم قرارداد API است و هم بخشی از prompt مدل. از نام‌های روشن و مخصوص دامنه استفاده کنید تا مدل بدون prose اضافه هدف را بفهمد:

به‌جای کلیدهای مبهمی مثل flag از نام‌هایی مثل customer_refund_requested استفاده کنید.
برای فیلدهایی که معنا، واحد یا مقدارهای مجازشان ممکن است مبهم باشد، description کوتاه اضافه کنید.
برای وضعیت محصول، priority، route یا categoryهایی که کد downstream به آن‌ها وابسته است، enum بگذارید.
تصمیم‌های نامرتبط را در schemaها یا زیروظیفه‌های جدا نگه دارید؛ یک schema خیلی بزرگ تشخیص خطا را سخت‌تر می‌کند.
پیش از تغییر نام فیلدها، مقدارهای enum، فیلدهای required یا عمق nesting، با ورودی‌های نماینده کاربران eval اجرا کنید.

چک‌لیست قرارداد Schema

پیش از انتشار یک schema برای خروجی ساختاریافته، این موارد را بررسی کنید:

وقتی پایبندی به schema لازم است، نه فقط JSON معتبر، strict: true را تنظیم کنید.
روی هر object مقدار additionalProperties: false بگذارید.
تمام propertyها را در required فهرست کنید؛ برای مقدارهای اختیاری از union شامل null استفاده کنید، مانند {"type": ["string", "null"]}.
schema ریشه را به صورت object نگه دارید، نه anyOf در سطح بالا؛ از anyOf تو در تو فقط وقتی استفاده کنید که route انتخابی آن را پشتیبانی می‌کند.
propertyها را به ترتیبی بچینید که برای انسان‌ها و logهای downstream خواناتر است؛ خروجی ساختاریافته معمولا ترتیب کلیدهای schema را دنبال می‌کند، اما parser برنامه شما باید همچنان بر اساس نام فیلد بخواند، نه فرض موقعیت.
برای schema از نام‌های پایدار و نسخه‌دار مثل support_ticket_v1 استفاده کنید؛ وقتی شکل خروجی ناسازگار تغییر می‌کند نسخه جدید بسازید تا logها، schemaهای cache‌شده و نتایج eval قابل مقایسه بمانند.
schema را کوچک و پایدار نگه دارید. اولین درخواست با schema جدید ممکن است به‌دلیل پردازش و cache شدن schema کمی latency بیشتری داشته باشد.
نام tenant، شناسه کاربر، secret یا منطق حساس کسب‌وکار را داخل نام schema، توضیح فیلدها، enumها یا $defs قرار ندهید. داده مخصوص کاربر را در prompt/input بگذارید و schema را به اندازه‌ای عمومی نگه دارید که reuse و cache شدن آن امن باشد.
هرجا ممکن است از schemaهای تولیدشده با Pydantic یا Zod استفاده کنید تا typeهای اپلیکیشن و schema ارسالی به API همسو بمانند.

برای ابزارهای function، strict: true را صریح تنظیم کنید و به default endpoint تکیه نکنید. رفتار فعلی OpenAI در Responses ممکن است schemaهای سازگار ابزار را تا حد امکان به حالت strict تبدیل کند، اما Chat Completions به‌صورت پیش‌فرض non-strict می‌ماند. اگر schema قابل strict شدن نباشد، metadata ابزار ممکن است به strict: false برگردد؛ این حالت را در تست تشخیص دهید و یا schema را ساده‌تر کنید یا آرگومان‌های best-effort را با احتیاط validate کنید. همچنین cache شدن schema را یک جزئیات performance بدانید: تعریف schema ممکن است توسط provider پردازش و cache شود، بنابراین پیش از استفاده از schemaهای حساس، نیازمندی‌های retention همان route را بررسی کنید.

استفاده دوباره و Schemaهای بازگشتی (Recursive)

وقتی یک شکل object در چند جای مختلف تکرار می‌شود، مانند درخت UI تو در تو، فهرست مرحله‌های workflow یا سلسله‌مراتب category، از $defs و $ref استفاده کنید. زیرمجموعه Structured Outputs در OpenAI از definition و recursion پشتیبانی می‌کند، از جمله recursion ریشه با $ref: "#", اما schema همچنان باید قوانین زیرمجموعه پشتیبانی‌شده را رعایت کند: فیلدهای object باید required باشند، objectها به additionalProperties: false نیاز دارند و محدودیت‌های اندازه و عمق همچنان اعمال می‌شوند.

برای routeهای production در AvalAI:

schemaهای بازگشتی را در عمل کم‌عمق نگه دارید و در سمت برنامه برای عمق، طول آرایه و اندازه رشته محدودیت بگذارید.
برای نوع node، مقدار state و نام action از enum استفاده کنید، نه label آزاد، وقتی کد downstream به آن‌ها وابسته است.
پیش از render کردن UI تولیدشده، اجرای stepهای workflow یا نوشتن رکوردها، پاسخ کامل را با validator خودتان اعتبارسنجی کنید.
route دقیق provider را با یک fixture بازگشتی حداقلی تست کنید؛ اگر شکست خورد، schema را flatten کنید یا از ID و parent reference استفاده کنید.

مدیریت امتناع و خروجی ناقص

خروجی‌های ساختاریافته JSON معتبر برای اپلیکیشن را قابل اعتمادتر می‌کنند، اما امتناع‌های ایمنی و generationهای قطع‌شده همچنان باید صریح مدیریت شوند:

امتناع‌ها: در Chat Completions مقدار message.refusal را بررسی کنید یا در Responses، content partهای response.output را پیش از parse کردن output_text ببینید.
پاسخ ناقص: در Responses پیش از parse کردن، response.status == "incomplete" و response.incomplete_details.reason را بررسی کنید. در Chat Completions مقدار finish_reason را ببینید. اگر محدودیت خروجی یا فیلتر محتوا generation را زود متوقف کرد، با دستورالعمل شفاف‌تر، schema کوچک‌تر یا سقف توکن خروجی بالاتر دوباره تلاش کنید.
ناسازگاری ورودی کاربر: به مدل بگویید وقتی ورودی به schema نگاشت نمی‌شود چه کند؛ مثلا فیلدهای null یا یک شیء خطای سطح اپلیکیشن برگرداند.

python

response = client.responses.create(
    model="gpt-5.5",
    input="یک خلاصه تیکت پشتیبانی را به صورت JSON استخراج کن.",
    text={
        "format": {
            "type": "json_schema",
            "name": "support_ticket",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "priority": {"type": "string", "enum": ["low", "medium", "high"]},
                },
                "required": ["summary", "priority"],
                "additionalProperties": False,
            },
        }
    },
)

if response.status == "incomplete":
    raise RuntimeError(f"Incomplete response: {response.incomplete_details.reason}")

for item in response.output:
    if item.type == "message":
        for content in item.content:
            if content.type == "refusal":
                raise RuntimeError(f"Model refused: {content.refusal}")

print(response.output_text)

خروجی‌های ساختاریافته جریانی

خروجی‌های ساختاریافته را می‌توان از طریق Responses API به‌صورت جریانی نیز دریافت کرد. زمانی از streaming استفاده کنید که می‌خواهید UI با رسیدن فیلدها به‌روزرسانی شود، اما هر delta را متن ناقص بدانید: JSON کامل را فقط پس از آماده شدن پاسخ نهایی parse و اعتبارسنجی کنید.

python

import os
from typing import List

from openai import OpenAI
from pydantic import BaseModel, ConfigDict


class EntitiesModel(BaseModel):
    model_config = ConfigDict(extra="forbid")

    attributes: List[str]
    colors: List[str]
    animals: List[str]


client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

with client.responses.stream(
    model="gpt-5.5",
    instructions="Extract entities from the input text.",
    input="روباه قهوه‌ای سریع از روی سگ تنبل با چشم‌های آبی پرید.",
    text_format=EntitiesModel,
) as stream:
    refusal_text = ""
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "response.refusal.delta":
            refusal_text += event.delta
            print(event.delta, end="", flush=True)
        elif event.type == "response.failed":
            raise RuntimeError(event.response.error)
        elif event.type == "error":
            raise RuntimeError(event.error)

    final_response = stream.get_final_response()
    if final_response.status == "incomplete":
        raise RuntimeError(
            f"خروجی ساختاریافته ناقص است: {final_response.incomplete_details.reason}"
        )
    if refusal_text:
        raise RuntimeError(f"Model refused: {refusal_text}")

    print("\n\nFinal JSON:")
    print(final_response.output_text)

وقتی SDK از stream helper پشتیبانی می‌کند، آن را ترجیح دهید؛ schema، رویدادها و پاسخ نهایی را در یک جریان نگه می‌دارد.
دلتاهای refusal را از دلتاهای JSON جدا نگه دارید؛ refusal را به عنوان خروجی ساختاریافته parse نکنید.
در مدیریت raw event، response.output_text.delta متن جزئی را حمل می‌کند؛ helperهای پایتون معمولا پایان را با response.completed نشان می‌دهند، در حالی که streamهای جاوااسکریپت ممکن است response.output_text.done را هم به‌عنوان مرز متن خروجی ارائه کنند. شیء پاسخ نهایی را منبع حقیقت بدانید.
بعد از پایان stream، پیش از parse کردن final_response.status را بررسی کنید تا توقف به‌دلیل max-output یا content-filter به JSON ناقص تبدیل نشود.
از فیلدهای JSON ناقص برای اجرای اقدام‌های downstream استفاده نکنید، مگر اینکه برنامه شما اصلاح یا rollback را تحمل کند.
برای آرگومان‌های ابزار، از رویدادهای جریانی فراخوانی تابع در راهنمای فراخوانی تابع استفاده کنید.

مدل‌های پشتیبانی شده

خروجی‌های ساختاریافته (json_schema) معمولا توسط مدل‌های جدیدتر موجود از طریق AvalAI پشتیبانی می‌شود، مانند:

gpt-5.5 و اسنپ‌شات‌های آن
gpt-5.4 و اسنپ‌شات‌های آن
مدل‌های پیشرفته دیگر ممکن است بسته به ارائه‌دهنده و route از خروجی ساختاریافته پشتیبانی کنند. صفحه ارائه‌دهنده و مسیر دقیق /v1/responses یا /v1/chat/completions مورد استفاده را تست کنید.

مدل‌های قدیمی‌تر ممکن است فقط از حالت پایه json_object پشتیبانی کنند.

پیش از استفاده production از یک مدل یا route ارائه‌دهنده:

یک درخواست happy-path، یک ورودی ناسازگار با task و یک درخواست حساس از نظر safety اجرا کنید تا خروجی JSON عادی، مسیر refusal و مدیریت خروجی ناقص را verify کنید.
تأیید کنید route انتخابی از شکل schema مورد نیاز شما پشتیبانی می‌کند (strict: true، فیلدهای اختیاری nullable، anyOf تو در تو، $defs و اندازه enumها).
نام/نسخه schema را همراه response ID و مدل ثبت کنید تا خطاهای آینده را بتوان به تغییر prompt، schema یا route نسبت داد.

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

فراخوانی تابع: زمانی استفاده کنید که می‌خواهید مدل JSON را به طور خاص برای فراخوانی توابع/ابزارهای برنامه شما خروجی دهد (مانند پرس‌وجو از پایگاه داده، فراخوانی API خارجی). به راهنمای فراخوانی تابع مراجعه کنید .
خروجی‌های ساختاریافته (text.format در Responses و response_format در Chat Completions): زمانی استفاده کنید که می‌خواهید پاسخ مستقیم مدل به کاربر در یک فرمت JSON خاص باشد (مانند تجزیه و نمایش در رابط کاربری، استخراج داده‌های ساختاریافته).

حالت JSON (`json_object`)

برای مدل‌هایی که از json_schema پشتیبانی نمی‌کنند، می‌توانید از حالت JSON ساده‌تر استفاده کنید: در Responses مقدار text.format={"type":"json_object"} و در Chat Completions مقدار response_format={"type":"json_object"} را تنظیم کنید.

ملاحظات مهم برای حالت json_object:

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

python

# مثال پایتون با استفاده از AvalAI با حالت json_object
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

try:
    response = client.chat.completions.create(
        model="gpt-5.4-mini",  # به‌روزرسانی شده از gpt-3.5-turbo منسوخ شده
        messages=[
            {
                "role": "system",
                "content": "شما یک دستیار مفید هستید که برای خروجی JSON طراحی شده‌اید.",
            },
            {
                "role": "user",
                "content": "نام و شهر کاربر را استخراج کنید: جان دو در لندن زندگی می‌کند.",
            },
        ],
        response_format={"type": "json_object"},
    )
    # ... (اعتبارسنجی و مدیریت خطا را برای محتوای پاسخ اضافه کنید) ...
    print(response.choices[0].message.content)
except Exception as e:
    print(f"An error occurred: {e}")

نسخه معادل Responses API

فقط زمانی از JSON mode استفاده کنید که پایبندی کامل به schema لازم نیست یا در دسترس نیست. در Responses، مقدار text.format را روی json_object بگذارید و در دستورالعمل‌ها صریحا بخواهید فقط JSON معتبر تولید شود.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.4-mini",
    instructions="You are a helpful assistant. Output only valid JSON.",
    input="نام و شهر کاربر را استخراج کنید: جان دو در لندن زندگی می‌کند.",
    text={"format": {"type": "json_object"}},
)

print(response.output_text)

JSON mode فقط معتبر بودن JSON را تضمین می‌کند، نه پایبندی به schema.
وقتی مدل پشتیبانی می‌کند، خروجی‌های ساختاریافته json_schema را ترجیح دهید.
JSON ناقص را هنگام رسیدن به محدودیت خروجی، امتناع یا توقف توسط فیلتر محتوا تشخیص دهید.

بهترین شیوه‌ها و نکات

طراحی طرحواره: از نام‌ها و توضیحات واضح و توصیفی برای کلیدها در طرحواره JSON خود استفاده کنید.
مدیریت ورودی کاربر: به مدل دستور دهید که چگونه در صورت نامربوط بودن ورودی کاربر یا عدم امکان نگاشت آن به طرحواره پاسخ دهد (مانند بازگرداندن مقادیر null، ساختار خطای خاص).
مدیریت خطا: مدیریت خطای قوی را برای خطاهای API، پاسخ‌های refusal بالقوه (با json_schema)، JSON ناقص (به ویژه با json_object یا max_tokens پایین) و شکست‌های اعتبارسنجی پیاده‌سازی کنید.
تکرار: پرامپت‌ها و طرحواره‌های خود را با استفاده از داده‌های ارزیابی آزمایش و اصلاح کنید.

عیب‌یابی شکست‌های خروجی ساختاریافته

نشانه	علت محتمل	چه چیزی را تغییر دهید
API schema را رد می‌کند	`additionalProperties: false` جا افتاده، همه propertyها در `required` نیستند، constraint پشتیبانی‌نشده استفاده شده یا ریشه schema از `anyOf` شروع شده است	schema را ساده‌تر کنید، همه propertyها را در `required` بیاورید، برای فیلدهای اختیاری از union شامل `null` استفاده کنید و keywordهای اعتبارسنجی پشتیبانی‌نشده را حذف کنید
اولین درخواست با schema کندتر است	schema در حال پردازش و cache شدن است	schemaها را پایدار نگه دارید، nameها را reuse کنید، schemaهای مهم را هنگام deploy گرم کنید و برای هر درخواست کاربر schema یک‌بارمصرف نسازید
schema شامل مقدارهای حساس است	جزئیات tenant/کاربر داخل نام schema، توضیح‌ها، enumها یا `$defs` قرار گرفته است	مقدارهای حساس را به input درخواست منتقل کنید، نام schema را عمومی و نسخه‌دار نگه دارید و نیازمندی‌های retention route را بررسی کنید
مدل امتناع می‌کند	درخواست باعث refusal ایمنی شده و ممکن است با schema شما منطبق نباشد	پیش از parse کردن `output_text`، مقدار `message.refusal` یا content partهای `response.output` را بررسی کنید و یک UI جایگزین امن نشان دهید
خروجی ناقص است	سقف توکن، فیلتر محتوا یا قطع ارتباط generation را متوقف کرده است	پیش از parse کردن، در Responses مقدار `response.status` / `incomplete_details` و در Chat Completions مقدار `finish_reason` را بررسی کنید
JSON mode گیر می‌کند یا whitespace برمی‌گرداند	پرامپت صریحا تولید JSON را درخواست نکرده است	یک instruction از نوع system/developer اضافه کنید که واژه `JSON` را داشته باشد، یا در صورت امکان `json_schema` Structured Outputs را ترجیح دهید
typeهای برنامه از schema جدا می‌شوند	JSON Schema و مدل runtime جداگانه نگهداری می‌شوند	schemaها را از Pydantic/Zod تولید کنید یا در CI بررسی کنید که وقتی یکی تغییر کرد، دیگری هم به‌روز شده باشد

مثال‌های مرتبط

ویژگی‌های JSON Schema پشتیبانی شده (زیرمجموعه)

خروجی‌های ساختاریافته (json_schema) از زیرمجموعه قابل توجهی از مشخصات JSON Schema پشتیبانی می‌کند، از جمله:

انواع: string, number, integer, boolean, object, array
ویژگی‌های شی: properties, required, additionalProperties: false (الزامی)
آرایه‌ها: items (با یک زیرطرحواره معتبر)
شمارش‌ها: enum (محدودیت‌هایی برای کل مقادیر/کاراکترها اعمال می‌شود)
ترکیب: anyOf (طرحواره‌های تو در تو نیز باید معتبر باشند)، $defs / $ref (برای تعاریف و بازگشت)

محدودیت‌های کلیدی:

شی ریشه نمی‌تواند anyOf باشد.
تمام ویژگی‌های تعریف شده در یک شی در طرحواره به عنوان required در نظر گرفته می‌شوند. برای شبیه‌سازی اختیاری بودن از {"type": ["string", "null"]} استفاده کنید.
additionalProperties: false برای اشیا اجباری است.
محدودیت اندازه اعمال می‌شود: حداکثر ۵۰۰۰ property شیء در کل، حداکثر ۱۰ سطح nesting، و حداکثر ۱۲۰٬۰۰۰ کاراکتر مجموع برای نام propertyها، نام definitionها، مقدارهای enum و مقدارهای const.
محدودیت enum اعمال می‌شود: حداکثر ۱۰۰۰ مقدار enum در کل schema؛ برای یک enum رشته‌ای با بیش از ۲۵۰ مقدار، طول مجموع رشته‌های enum باید کمتر از ۱۵٬۰۰۰ کاراکتر بماند.
keywordهای پشتیبانی‌نشده شامل کنترل‌های ترکیبی مثل allOf، not، dependentRequired، dependentSchemas، if، then و else هستند. routeهای مدل fine-tuned می‌توانند محدودیت‌های type-specific بیشتری مثل minLength، pattern، minimum، patternProperties و minItems را هم پشتیبانی نکنند.

اگر از یک ویژگی طرحواره پشتیبانی نشده با json_schema استفاده شود، API خطا برمی‌گرداند.

خروجی‌های ساختاریافته ​

مقدمه ​

راهنمای سریع انتخاب ​

دریافت پاسخ ساختاریافته (json_schema) ​

پیش از اعتماد، Parse کنید ​

همگام نگه داشتن Schema و Typeها ​

طراحی Schema برای قابلیت اعتماد مدل ​

چک‌لیست قرارداد Schema ​

استفاده دوباره و Schemaهای بازگشتی (Recursive) ​

مدیریت امتناع و خروجی ناقص ​

خروجی‌های ساختاریافته جریانی ​

مدل‌های پشتیبانی شده ​

چه زمانی از خروجی‌های ساختاریافته در مقابل فراخوانی تابع استفاده کنیم ​

حالت JSON (json_object) ​

بهترین شیوه‌ها و نکات ​

عیب‌یابی شکست‌های خروجی ساختاریافته ​

مثال‌های مرتبط ​

ویژگی‌های JSON Schema پشتیبانی شده (زیرمجموعه) ​

خروجی‌های ساختاریافته

مقدمه

راهنمای سریع انتخاب

دریافت پاسخ ساختاریافته (`json_schema`)

پیش از اعتماد، Parse کنید

همگام نگه داشتن Schema و Typeها

طراحی Schema برای قابلیت اعتماد مدل

چک‌لیست قرارداد Schema

استفاده دوباره و Schemaهای بازگشتی (Recursive)

مدیریت امتناع و خروجی ناقص

خروجی‌های ساختاریافته جریانی

مدل‌های پشتیبانی شده

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

حالت JSON (`json_object`)

بهترین شیوه‌ها و نکات

عیب‌یابی شکست‌های خروجی ساختاریافته

مثال‌های مرتبط

ویژگی‌های JSON Schema پشتیبانی شده (زیرمجموعه)