JSON چیست؟ کاربرد JSON در هوش مصنوعی و ایجنت‌ها

وقتی از یک مدل زبانی می‌خواهید «اطلاعات این فاکتور را استخراج کن»، جواب آزاد و روان برای یک آدم خوب است، اما برای برنامه‌ای که باید قیمت را در دیتابیس ذخیره کند بی‌فایده است. برنامه به داده‌ای نیاز دارد که بشود مستقیم خواند. برای همین JSON به قالب مشترک بین مدل‌های هوش مصنوعی و نرم‌افزارها تبدیل شده است. در این مقاله توضیح می‌دهیم JSON چیست، در دنیای هوش مصنوعی دقیقاً چه کارهایی انجام می‌دهد و چطور از خطاهایی که خروجی مدل‌ها در آن پیش می‌آید جلوگیری کنید.

فهرست مطالب

JSON چیست؟
چرا JSON زبان مشترک شد؟
کاربرد اول: خروجی ساختاریافته مدل
کاربرد دوم: Function Calling و Tool Use
کاربرد سوم: ایجنت‌ها و پروتکل MCP
کاربرد چهارم: داده آموزشی و تنظیمات
کاربرد پنجم: JSON-LD و دیده‌شدن در جستجو
خطاهای رایج در JSON خروجی مدل‌ها
امنیت: خروجی مدل را قابل اعتماد فرض نکنید
سؤالات متداول

JSON چیست؟

JSON مخفف JavaScript Object Notation است؛ قالبی متنی برای نوشتن داده‌های ساختاریافته که هم برای انسان خواندنی است و هم برای ماشین. نامش از جاوااسکریپت آمده، اما به هیچ زبان برنامه‌نویسی خاصی وابسته نیست. PHP، پایتون، جاوا و تقریباً هر زبان دیگری می‌تواند آن را بخواند و بنویسد. قواعد آن در استانداردهایی مثل RFC 8259 و ECMA-404 مشخص شده است.

یک نمونه ساده از اطلاعات یک سفارش:

{
  "order_id": 1042,
  "customer": "علی رضایی",
  "paid": true,
  "items": [
    { "name": "هاست وردپرس", "price": 450000 },
    { "name": "دامنه", "price": 120000 }
  ],
  "coupon": null
}

JSON شش نوع داده دارد:

نوع	مثال	توضیح
رشته (string)	`"سلام"`	متن، همیشه داخل گیومه دوتایی
عدد (number)	`1042`	صحیح یا اعشاری، بدون گیومه
بولی (boolean)	`true`	فقط true یا false با حروف کوچک
تهی (null)	`null`	نبود مقدار
شیء (object)	`{ "a": 1 }`	مجموعه‌ای از جفت‌های «کلید: مقدار»
آرایه (array)	`[1, 2, 3]`	فهرست مرتب از مقدارها

چند قاعده هست که بیشترین خطا را می‌سازد: کلیدها باید حتماً داخل گیومه دوتایی باشند، گیومه تکی مجاز نیست، بعد از آخرین عضو یک شیء یا آرایه نباید ویرگول بگذارید و کامنت در JSON استاندارد وجود ندارد. همین چهار قاعده در بخش خطاهای رایج دوباره سراغ‌مان می‌آید.

چرا JSON زبان مشترک شد؟

JSON ساده است، حجم کمی دارد و هر زبان برنامه‌نویسی ابزار آماده‌ای برای کار با آن دارد. به همین دلیل بیشتر APIهای وب با آن کار می‌کنند. اگر سایت وردپرسی دارید، با JSON سروکار داشته‌اید حتی اگر نمی‌دانستید: REST API وردپرس پاسخ‌هایش را به‌صورت JSON برمی‌گرداند و تابع wp_json_encode() برای ساختن آن در هسته وردپرس هست. در PHP هم توابع json_encode() و json_decode() کار تبدیل را انجام می‌دهند.

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

کاربرد اول: خروجی ساختاریافته مدل

مشکل متن آزاد این است که هر بار یک‌جور نوشته می‌شود. اگر از مدل بخواهید اطلاعات یک ایمیل مشتری را استخراج کند، یک بار «نام: علی» می‌نویسد و بار دیگر «مشتری آقای علی هستند». کد شما نمی‌تواند روی چنین چیزی حساب کند. راه‌حل این است که قالب جواب را مشخص کنید:

{
  "customer_name": "علی",
  "request_type": "refund",
  "urgent": true
}

دو سطح از این کار وجود دارد. در سطح اول فقط در پرامپت از مدل می‌خواهید جواب را JSON بدهد. این روش بیشتر وقت‌ها کار می‌کند، اما تضمینی ندارد. در سطح دوم، API خود مدل جواب را به یک JSON Schema محدود می‌کند. JSON Schema توصیفی از شکل داده است: کدام کلیدها لازم‌اند، هر کدام چه نوعی دارند و چه مقادیری مجازند. برخی سرویس‌دهنده‌ها، از جمله OpenAI، حالت «Structured Outputs» دارند که مدل را به پیروی از اسکیمای شما وادار می‌کند. نام پارامترها و جزئیات هر API با هم فرق دارد و مدام تغییر می‌کند، پس قبل از کدنویسی مستندات رسمی همان سرویس را ببینید.

حتی با حالت ساختاریافته هم کار شما تمام نشده است. جواب را در کد خودتان اعتبارسنجی کنید (بخش امنیت را ببینید).

کاربرد دوم: Function Calling و Tool Use

مدل زبانی خودش نمی‌تواند موجودی انبار را بخواند یا ایمیل بفرستد. اما می‌تواند «درخواست کند» که برنامه شما این کار را بکند. این قابلیت اسمش Function Calling یا Tool Use است و کل مکالمه آن با JSON انجام می‌شود:

شما فهرستی از ابزارها را با توصیف و JSON Schema ورودی‌شان به مدل می‌دهید.
کاربر می‌پرسد: «سفارش ۱۰۴۲ کجاست؟»
مدل به‌جای جواب متنی، یک شیء JSON برمی‌گرداند که نام ابزار و آرگومان‌ها را دارد.
برنامه شما تابع واقعی را اجرا می‌کند و نتیجه را (باز هم به‌صورت JSON) به مدل می‌دهد.
مدل با توجه به نتیجه، جواب نهایی را به کاربر می‌نویسد.

تعریف یک ابزار، به‌شکل ساده‌شده، این‌طور است:

{
  "name": "get_order_status",
  "description": "وضعیت یک سفارش را با شماره سفارش برمی‌گرداند",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "integer" }
    },
    "required": ["order_id"]
  }
}

و درخواست مدل برای استفاده از آن چیزی شبیه این است:

{ "name": "get_order_status", "arguments": { "order_id": 1042 } }

نام فیلدها در هر سرویس‌دهنده کمی فرق دارد (مثلاً input_schema یا parameters)، اما منطق ثابت است: توصیف ابزار و آرگومان‌ها در قالب JSON Schema است و مدل فقط آرگومان‌ها را پر می‌کند. توصیف خوب اهمیت زیادی دارد، چون مدل از روی همین متن تصمیم می‌گیرد کدام ابزار را کی صدا بزند. اگر مقاله ایجنت هوش مصنوعی چیست را خوانده باشید، می‌دانید که ایجنت‌ها دقیقاً از همین چرخه استفاده می‌کنند.

کاربرد سوم: ایجنت‌ها و پروتکل MCP

وقتی ابزارهای زیادی داشته باشید، هر برنامه مجبور می‌شود برای هر ابزار کد اتصال جداگانه بنویسد. پروتکل MCP (Model Context Protocol) این اتصال را استاندارد کرده است. MCP بر پایه JSON-RPC 2.0 ساخته شده؛ یعنی همه پیام‌ها بین برنامه و سرور ابزار، شیءهای JSON با قالب مشخص‌اند. دو متد اصلی آن tools/list (فهرست ابزارهای موجود) و tools/call (اجرای یک ابزار) هستند. ورودی هر ابزار هم با JSON Schema توصیف می‌شود.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_order_status",
    "arguments": { "order_id": 1042 }
  }
}

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

کاربرد چهارم: داده آموزشی و تنظیمات

JSON فقط برای گفت‌وگوی لحظه‌ای نیست، پشت صحنه هم کاربرد دارد:

داده‌های Fine-tuning: فایل نمونه‌های آموزشی معمولاً به فرمت JSONL آماده می‌شود. JSONL یعنی در هر خط یک شیء JSON کامل. مثلاً فایل Fine-tuning در OpenAI این قالب را می‌خواهد. مزیتش این است که فایل‌های بزرگ را می‌شود خط‌به‌خط بدون بارگذاری کامل پردازش کرد.
تنظیمات مدل: مدل‌های متن‌باز در پلتفرم‌هایی مثل Hugging Face معمولاً یک فایل config.json دارند که معماری و تنظیمات مدل را توصیف می‌کند.
ارزیابی و لاگ: نتیجه تست‌ها و لاگ درخواست‌ها هم اغلب به‌صورت JSON ذخیره می‌شود تا بشود آن‌ها را جستجو و تحلیل کرد.

کاربرد پنجم: JSON-LD و دیده‌شدن در جستجو

یک کاربرد JSON که برای صاحب سایت مستقیم‌تر است، داده ساختاریافته به شکل JSON-LD است. گوگل JSON-LD را برای افزودن schema.org به صفحه توصیه می‌کند. در همین مقاله‌ها، بخش سؤالات متداول را با یک بلوک JSON-LD از نوع FAQPage هم به ماشین‌ها معرفی می‌کنیم:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "JSON چیست؟",
    "acceptedAnswer": { "@type": "Answer", "text": "قالبی متنی برای داده ساختاریافته." }
  }]
}

یک نکته صادقانه: گوگل نمایش ظاهر ویژه FAQ را از ۲۰۲۳ به سایت‌های دولتی و سلامت محدود کرده است و ما ادعا نمی‌کنیم مدل‌های هوش مصنوعی حتماً از این بلوک استفاده می‌کنند. اما داده ساختاریافته صفحه را برای ماشین‌ها روشن‌تر می‌کند. درباره حضور در پاسخ‌های هوش مصنوعی بیشتر در مقاله AEO چیست نوشته‌ایم.

خطاهای رایج در JSON خروجی مدل‌ها

حتی وقتی از مدل JSON می‌خواهید، گاهی خروجی قابل خواندن نیست. این موارد را بیشتر می‌بینید (فهرست زیر تجربه رایج توسعه‌دهنده‌هاست و قانون رسمی نیست):

مشکل	نمونه	راه‌حل
متن اضافه دور JSON	«این هم نتیجه:» قبل از آکولاد	حالت خروجی ساختاریافته یا استخراج بخش بین اولین و آخرین آکولاد
بلوک Markdown دور JSON	سه بک‌تیک و کلمه json	حذف حصار قبل از تحلیل
ویرگول انتهایی	`{ "a": 1, }`	اعتبارسنجی و تلاش دوباره
گیومه تکی	`{ 'a': 1 }`	اسکیمای سخت‌گیر یا تلاش دوباره
JSON ناقص	پاسخ وسط کار قطع شده	سقف توکن خروجی را بالا ببرید و پاسخ‌های کوتاه‌تر بخواهید
نوع اشتباه	`"price": "450000"` به‌جای عدد	تعریف `type` در اسکیما و بررسی نوع در کد

در کد، هیچ‌وقت مستقیم به خروجی اعتماد نکنید و تحلیل را در بلوک مدیریت خطا بگذارید. در PHP این‌طور:

try {
    $data = json_decode( $output, true, 512, JSON_THROW_ON_ERROR );
} catch ( JsonException $e ) {
    // پاسخ نامعتبر: لاگ بگیرید و یک بار دوباره درخواست بدهید
}

و در جاوااسکریپت:

try {
  const data = JSON.parse(output);
} catch (err) {
  // پاسخ نامعتبر: لاگ و تلاش دوباره
}

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

چند توصیه برای اسکیما و پرامپت

اسکیما را ساده و کم‌عمق نگه دارید. شیءهای تو در توی زیاد احتمال خطا را بالا می‌برند.
برای فیلدهایی که چند مقدار مشخص دارند از enum استفاده کنید، مثلاً "refund"، "support" یا "sales".
برای هر فیلد توضیح کوتاه بنویسید. مدل از توضیح فیلد برای پر کردن درست آن استفاده می‌کند.
فیلدهایی که ممکن است مقدار نداشته باشند را صریحاً nullپذیر تعریف کنید تا مدل به‌جای حدس زدن، null بدهد.
یک یا دو نمونه از خروجی درست در پرامپت بگذارید.

امنیت: خروجی مدل را قابل اعتماد فرض نکنید

JSON معتبر به معنای داده درست یا امن نیست. اگر مدل بر اساس متنی که کاربر یا یک وب‌سایت بیرونی فرستاده کار می‌کند، آن متن می‌تواند مدل را به تولید مقدارهای دلخواه هل بدهد (به این حمله prompt injection می‌گویند). پس خروجی مدل را مثل ورودی هر کاربر ناشناس رفتار کنید:

نوع و محدوده هر فیلد را در کد بررسی کنید، نه فقط در اسکیما.
مقدارها را قبل از ذخیره در دیتابیس با روش‌های امن (مثل prepared statement) وارد کنید و قبل از نمایش در صفحه escape کنید.
به ابزارهای حساس، مثل حذف داده یا پرداخت، فقط با تأیید انسانی دسترسی بدهید.
برای هر ابزار فقط حداقل دسترسی لازم را تعریف کنید.

سؤالات متداول

JSON چیست و برای چه کاری استفاده می‌شود؟

JSON یک قالب متنی برای ذخیره و تبادل داده‌های ساختاریافته است. APIها، تنظیمات برنامه‌ها و ارتباط مدل‌های هوش مصنوعی با نرم‌افزارها از آن استفاده می‌کنند.

چرا مدل‌های هوش مصنوعی خروجی JSON تولید می‌کنند؟

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

JSON Schema چیست؟

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

فرق JSON و JSONL چیست؟

JSON یک سند کامل است. JSONL فایلی است که در هر خط یک شیء JSON مستقل دارد و برای فایل‌های بزرگ داده، مثل داده‌های آموزشی، مناسب است.

چرا JSON خروجی مدل گاهی خطا می‌دهد؟

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

آیا باید JSON یاد بگیرم تا از هوش مصنوعی استفاده کنم؟

برای استفاده روزمره از چت‌بات‌ها لازم نیست. اما اگر می‌خواهید هوش مصنوعی را به سایت یا نرم‌افزار خودتان وصل کنید، خواندن و نوشتن JSON یکی از اولین مهارت‌های ضروری است.

از کجا شروع کنید؟

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

منابع: RFC 8259: استاندارد JSON · مشخصات رسمی MCP · JSON Schema · مستندات OpenAI: Structured Outputs