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

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

در Chat Completions این کار معمولاً با response_format انجام می‌شود.

وضعیت پشتیبانی در گدارAI

گدارAI در مسیر POST /v1/chat/completions فیلد response_format را برای حالت‌های json_object و json_schema پشتیبانی می‌کند. در مسیرهای ارائه‌دهنده‌ای که قرارداد OpenAI-compatible را مستقیم می‌پذیرند، این فیلد بدون حذف به ارائه‌دهنده فرستاده می‌شود و پاسخ مدل، از جمله فیلدهایی مثل refusal، به همان شکل OpenAI-compatible برمی‌گردد.

این قابلیت به مدل و ارائه‌دهنده وابسته است. اگر مسیر انتخابی هنوز تبدیل بومی برای response_format نداشته باشد، گدارAI درخواست را با خطای روشن رد می‌کند تا تنظیم ساختاریافته بی‌اثر نماند.

در Responses API، شکل رسمی این قابلیت با text.format فرستاده می‌شود. گدارAI این فیلد را در مسیر POST /v1/responses برای ارائه‌دهنده‌های OpenAI-compatible عبور می‌دهد.

چه مسئله‌ای را حل می‌کند؟

اگر فقط در پرامپت بنویسید «JSON بده»، هنوز ممکن است مدل:

• متن توضیحی اضافه کند.
• نام فیلدها را تغییر دهد.
• نوع داده‌ها را اشتباه بسازد.
• فیلدهایی تولید کند که اپلیکیشن شما انتظار ندارد.

response_format این ریسک را کم می‌کند و قرارداد بین مدل و سرویس شما را روشن‌تر می‌سازد.

دو حالت اصلی

حالت	کاربرد
json_object	وقتی فقط JSON معتبر می‌خواهید و schema دقیق لازم نیست.
json_schema	وقتی ساختار، فیلدها و نوع داده‌ها باید دقیق‌تر کنترل شوند.

برای جریان‌های مهم محصول، json_schema معمولاً انتخاب مطمئن‌تری است.

json_object

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "You return valid JSON only."
    },
    {
      "role": "user",
      "content": "سه مزیت استفاده از کلید دسترسی مجازی را به صورت JSON بده."
    }
  ],
  "response_format": {
    "type": "json_object"
  }
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "You return valid JSON only."
    },
    {
      "role": "user",
      "content": "سه مزیت استفاده از کلید دسترسی مجازی را به صورت JSON بده."
    }
  ],
  "response_format": {
    "type": "json_object"
  }
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "You return valid JSON only."
    },
    {
      "role": "user",
      "content": "سه مزیت استفاده از کلید دسترسی مجازی را به صورت JSON بده."
    }
  ],
  "response_format": {
    "type": "json_object"
  }
}'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.chat.completions.create(
    "model": "openai:default:gpt-4o-mini",
    messages=[
        {
          "role": "system",
          "content": "You return valid JSON only."
        },
        {
          "role": "user",
          "content": "سه مزیت استفاده از کلید دسترسی مجازی را به صورت JSON بده."
        }
      ],
    response_format={
        "type": "json_object"
      }

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.chat.completions.create({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "You return valid JSON only."
    },
    {
      "role": "user",
      "content": "سه مزیت استفاده از کلید دسترسی مجازی را به صورت JSON بده."
    }
  ],
  "response_format": {
    "type": "json_object"
  }
});

console.log(response);

این حالت برای خروجی‌های سبک مناسب است، اما ساختار دقیق را تضمین نمی‌کند.

json_schema

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "درخواست پشتیبانی را به داده ساختاریافته تبدیل کن."
    },
    {
      "role": "user",
      "content": "کاربر می‌گوید پاسخ‌ها کند شده‌اند و این برای صفحه پرداخت فوری است."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "strict": True,
      "schema": {
        "type": "object",
        "required": [
          "summary",
          "priority",
          "labels"
        ],
        "additionalProperties": False,
        "properties": {
          "summary": {
            "type": "string"
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "درخواست پشتیبانی را به داده ساختاریافته تبدیل کن."
    },
    {
      "role": "user",
      "content": "کاربر می‌گوید پاسخ‌ها کند شده‌اند و این برای صفحه پرداخت فوری است."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "strict": true,
      "schema": {
        "type": "object",
        "required": [
          "summary",
          "priority",
          "labels"
        ],
        "additionalProperties": false,
        "properties": {
          "summary": {
            "type": "string"
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "درخواست پشتیبانی را به داده ساختاریافته تبدیل کن."
    },
    {
      "role": "user",
      "content": "کاربر می‌گوید پاسخ‌ها کند شده‌اند و این برای صفحه پرداخت فوری است."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "strict": true,
      "schema": {
        "type": "object",
        "required": [
          "summary",
          "priority",
          "labels"
        ],
        "additionalProperties": false,
        "properties": {
          "summary": {
            "type": "string"
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.chat.completions.create(
    "model": "openai:default:gpt-4o-mini",
    messages=[
        {
          "role": "system",
          "content": "درخواست پشتیبانی را به داده ساختاریافته تبدیل کن."
        },
        {
          "role": "user",
          "content": "کاربر می‌گوید پاسخ‌ها کند شده‌اند و این برای صفحه پرداخت فوری است."
        }
      ],
    response_format={
        "type": "json_schema",
        "json_schema": {
          "name": "support_ticket",
          "strict": True,
          "schema": {
            "type": "object",
            "required": [
              "summary",
              "priority",
              "labels"
            ],
            "additionalProperties": False,
            "properties": {
              "summary": {
                "type": "string"
              },
              "priority": {
                "type": "string",
                "enum": [
                  "low",
                  "medium",
                  "high"
                ]
              },
              "labels": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.chat.completions.create({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "درخواست پشتیبانی را به داده ساختاریافته تبدیل کن."
    },
    {
      "role": "user",
      "content": "کاربر می‌گوید پاسخ‌ها کند شده‌اند و این برای صفحه پرداخت فوری است."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "strict": true,
      "schema": {
        "type": "object",
        "required": [
          "summary",
          "priority",
          "labels"
        ],
        "additionalProperties": false,
        "properties": {
          "summary": {
            "type": "string"
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
});

console.log(response);

strict: True به مدل می‌گوید به schema نزدیک‌تر بماند. در عوض، schema شما هم باید دقیق و قابل اجرا باشد.

طراحی schema خوب

• فیلدهای واقعاً لازم را در required بگذارید.
• برای مقدارهای محدود از enum استفاده کنید.
• additionalProperties: False را وقتی فعال کنید که فیلد اضافه برای شما خطاست.
• schema را کوچک نگه دارید؛ schema بزرگ و مبهم کیفیت خروجی را پایین می‌آورد.
• نام فیلدها را همان نام‌هایی بگذارید که اپلیکیشن شما مصرف می‌کند.

آیا اعتبارسنجی نهایی هنوز لازم است؟

بله. خروجی ساختاریافته ریسک را کم می‌کند، اما جای اعتبارسنجی اپلیکیشن را نمی‌گیرد. همیشه:

• JSON را parse کنید.
• schema یا مدل typed خودتان را validate کنید.
• منطق محصول را جداگانه بررسی کنید.
• خطاهای parsing را قابل مشاهده و قابل بازیابی طراحی کنید.

مدل را کمک‌کننده ساختار بدانید، نه منبع نهایی اعتماد.

ترکیب با ابزارها

اگر ابزارها هم فعال‌اند، ممکن است مدل ابتدا tool_calls برگرداند و پاسخ نهایی در نوبت بعدی ساخته شود. در این حالت:

• schema را برای پاسخ نهایی طراحی کنید.
• پیام assistant حاوی tool_calls را کامل در تاریخچه نگه دارید.
• نتیجه ابزار را با role: "tool" برگردانید.
• سپس پاسخ نهایی را طبق schema دریافت کنید.

ترکیب با حافظه نهان

خود response_format لزوماً مانع استفاده از حافظه نهان نیست، اما هر پارامتر روی کلید و رفتار حافظه نهان اثر می‌گذارد. سناریوی متنی ساده را جدا از سناریوی همراه ابزار یا ورودی چندرسانه‌ای آزمایش کنید.

اشتباه‌های رایج

• فقط نوشتن «JSON بده» بدون response_format.
• طراحی schema بسیار باز که عملاً هیچ چیزی را کنترل نمی‌کند.
• طراحی schema بسیار سخت بدون فکر به داده‌های ناقص.
• حذف اعتبارسنجی نهایی در سرویس خودتان.
• استفاده از خروجی خام مدل در مسیرهای حساس محصول.

جمع‌بندی

خروجی ساختاریافته یکی از بهترین راه‌ها برای تبدیل پاسخ مدل به داده قابل استفاده در محصول است. برای نمونه‌های سبک از json_object شروع کنید، اما برای جریان‌های مهم و قابل اتکا، json_schema را با اعتبارسنجی سمت اپلیکیشن همراه کنید.