المخرجات المنظمة: JSON موثوق من النماذج اللغوية

المخرجات المنظمة (structured output) إجابة بشكل حددته مسبقًا: كائن JSON بمفاتيح مسمّاة، أو جدول بأعمدة ثابتة، أو قالب بالعناوين نفسها في كل مرة. تحتاجها كلما قرأ برنامج الإجابة، وتفيد عندما يقرؤها شخص أيضًا، لأن كل إجابة تبدو عندئذ متشابهة ويسهل تصفحها أو مقارنتها.

الحيلة أن تصف الشكل بدقة تامة حتى لا يبقى للنموذج شيء يختاره. كلمة "JSON" وحدها ليست وصفًا. المثال التالي يستخرج تفاصيل من بلاغ عن خطأ. قارن طلب "التفاصيل الأساسية" بطلب يحدد المخطط صراحة.

نص حرJSON مع مخطط

EditCopy

استخرج التفاصيل الأساسية من بلاغ الخطأ هذا: "منذ تحديث الأمس والتطبيق ينهار عندما أضغط تصدير في مشروع فيه أكثر من 50 صورة. المشاريع الأصغر تُصدَّر بلا مشكلة. أستخدم Android 14، وإصدار التطبيق 3.2.0. هذا يعطّل تسليم عملي للعميل."

Try it

Example replyReplies vary between models and runs.

إليك التفاصيل الأساسية من بلاغ الخطأ:

• المشكلة: التطبيق ينهار عند تصدير المشاريع
• المسبّب: الضغط على تصدير في مشاريع فيها أكثر من 50 صورة
• البداية: بعد آخر تحديث
• المنصة: Android 14
• إصدار التطبيق: 3.2.0
• الأثر: مرتفع، لأنه يعطّل تسليمًا لعميل

يبدو أن المشاريع الأصغر تُصدَّر دون مشكلات.

إجابة النص الحر دقيقة وسهلة القراءة، لكن لن يستخدم تشغيلان التسميات نفسها، والخطورة جملة لا قيمة، والبرنامج سيضطر إلى تخمين أين يبدأ كل حقل. أما إجابة JSON فيمكن أن تدخل مباشرة إلى أداة تتبّع الأخطاء. لاحظ أن الرد ما زال داخل كتلة كود: تطبيقات المحادثة تضع JSON عادةً بهذه الطريقة، وهذا مهم عندما تحلّله في الكود.

كيف تطلب JSON

طلب JSON الجيد يجيب عن كل سؤال كان النموذج سيجيب عنه نيابة عنك:

• كل مفتاح بتهجئته الدقيقة. اكتب أسماء المفاتيح بين علامتي تنصيص كما يجب أن تظهر. قل "بهذه المفاتيح بالضبط" حتى لا يضيف النموذج مفاتيح أخرى.
• نوع كل قيمة. نص، أو رقم، أو قيمة منطقية، أو مصفوفة نصوص، أو كائن متداخل.
• القيم المسموحة لأي حقل له مجموعة ثابتة، مثل الخطورة أو الفئة. من دون القائمة، تحصل على "High" و"high" و"severe" و"P1" عبر أربعة تشغيلات.
• ماذا يفعل عندما يفتقد المُدخل قيمة. إذا لم تقل "null إذا لم يُذكر"، يميل النموذج إلى ملء الفجوة بتخمين معقول، ورقم إصدار مُخمَّن يبدو تمامًا مثل رقم حقيقي.
• لا شيء حوله. عبارة "أرجِع JSON فقط، دون أي نص قبله أو بعده" تزيل جملة الافتتاح الودية.

عندما يكون الشكل متداخلًا أو غير مألوف، فعرض كائن مثال كامل يعمل أفضل من وصفه. هذا هو الموجّه بالأمثلة مطبّقًا على الصيغة. اجعل قيم المثال مختلفة بوضوح عن المُدخل الحقيقي حتى لا ينسخها النموذج.

موجّه استخراج قابل لإعادة الاستخدام

يحتوي هذا المثال على الطلب نفسه مقسّمًا إلى أجزاء. أوقف جزء الصيغة وسيظل النموذج يُرجع JSON، لأن القيود تطلبه، لكنه يختار أسماء مفاتيحه الخاصة، مثل title بدلًا من job_title، فينكسر الكود الذي يتوقع مفاتيحك. جزء القيود هو ما يمنعه من إكمال رقم هاتف مكتوب نصفه أو استنتاج اسم الشركة من نطاق البريد. الصق توقيعًا حقيقيًا في حقل المُدخل لتختبره.

استخراج بيانات التواصل بصيغة JSON

EditCopy

Fill inالتوقيع

PartsTaskFormatConstraintsInput

Task

استخرج بيانات التواصل من توقيع البريد التالي.

Format

أرجِع كائن JSON بهذه المفاتيح بالضبط: { "name": "string", "job_title": "string or null", "company": "string or null", "email": "string or null", "phone": "string or null" }

Constraints

استخدم null لأي قيمة غير موجودة في النص. لا تخمّن ولا تكمل القيم الناقصة. أرجِع JSON فقط.

Input

بريا نائر | رئيسة قسم البيانات، Northwind Labs | priya.nair@northwind.example

Try it

Example replyReplies vary between models and runs.

{
  "name": "بريا نائر",
  "job_title": "رئيسة قسم البيانات",
  "company": "Northwind Labs",
  "email": "priya.nair@northwind.example",
  "phone": null
}

الجداول والقوالب الثابتة

المخرجات المنظمة ليست للبرامج فقط. عندما تقرأ الإجابة بنفسك، يعطيك جدول markdown أو قالب ثابت الفائدة نفسها: تعرف أين ستكون كل معلومة قبل أن تنظر.

جدول

EditCopy

قارن بين القوائم (list) والصفوف (tuple) والمجموعات (set) في Python في جدول markdown بهذه الأعمدة: النوع، مرتّب، قابل للتعديل، يسمح بالتكرار، الاستخدام المعتاد. صف واحد لكل نوع. لا نص خارج الجدول.

Try it

Example replyReplies vary between models and runs.

النوع	مرتّب	قابل للتعديل	يسمح بالتكرار	الاستخدام المعتاد
list	نعم	نعم	نعم	تسلسل تضيف إليه أو تحذف منه أو ترتّبه
tuple	نعم	لا	نعم	مجموعة قيم ثابتة، مثل الإحداثيات
set	لا	نعم	لا	إزالة التكرار والفحص السريع للعضوية

القالب يعمل بالطريقة نفسها في النصوص الأطول: أعطِ العناوين بترتيبها وقل ماذا يوضع تحت كل منها. عبارة "أجب بثلاثة عناوين عريضة: السبب، الإصلاح، طريقة التحقق" تنتج العناوين الثلاثة نفسها في كل مرة، فتسهل مقارنة مجموعة من الإجابات.

JSON mode في واجهة API

في عدة واجهات API للنماذج إعداد يفرض JSON صحيحًا من حيث البنية. في مكتبة Python من OpenAI هو response_format. يتطلب JSON mode ظهور كلمة "JSON" في مكان ما من رسائلك، لذا يذكرها موجّه النظام التالي ويعدّد المفاتيح.

import json
from openai import OpenAI

client = OpenAI()
MODEL = "your-model-id"  # e.g. from your provider's model list

report_text = "Since yesterday's update the app crashes when I tap Export..."

response = client.chat.completions.create(
    model=MODEL,
    response_format={"type": "json_object"},
    messages=[
        {
            "role": "system",
            "content": (
                "Extract the bug report into JSON with the keys "
                "summary (string), severity (one of low, medium, high, critical) "
                "and steps_to_reproduce (array of strings)."
            ),
        },
        {"role": "user", "content": report_text},
    ],
)

data = json.loads(response.choices[0].message.content)

يضمن JSON mode أن النص قابل للتحليل (ما لم يُقطع الرد عند حد التوكنات)، لا أنه يطابق مخططك. قد يظل مفتاح ناقصًا أو تكون الخطورة "urgent". ويقبل عدة مزوّدين أيضًا JSON Schema كاملًا، إما صيغةً للمخرجات أو مخططًا لمُدخلات تعريف أداة (دالة)، وبعض هذه الأوضاع يقيّد الإجابة بالمخطط. تحقق من وثائق المزوّد لمعرفة المعامل الدقيق، لأن هذه الميزات تختلف بين الواجهات.

تحقق من النتيجة في الكود

تعامل مع JSON الذي يعطيه النموذج كما تتعامل مع أي مُدخل من خارج برنامجك: حلّله، ثم افحصه. التحليل يلتقط البنية المكسورة، والفحص يلتقط كائنًا صحيح البنية بمحتوى خاطئ.

ALLOWED_SEVERITIES = {"low", "medium", "high", "critical"}

def problems(data):
    if not isinstance(data, dict):
        return ["the answer must be a JSON object"]
    found = []
    if not isinstance(data.get("summary"), str):
        found.append("summary must be a string")
    if data.get("severity") not in ALLOWED_SEVERITIES:
        found.append("severity must be low, medium, high or critical")
    steps = data.get("steps_to_reproduce")
    if not isinstance(steps, list) or not all(isinstance(s, str) for s in steps):
        found.append("steps_to_reproduce must be an array of strings")
    return found

عندما يفشل الفحص، كثيرًا ما تصلحه إعادة محاولة واحدة: أرسل إلى النموذج مخرجاته مع قائمة المشكلات واطلب JSON مصحّحًا. ضع حدًا لعدد المحاولات، وسجّل الإخفاقات، لأن الحقل الذي يفشل كثيرًا علامة على أن الموجّه غير واضح. وفي المشاريع الأكبر تحل مكتبة تحقق مثل Pydantic أو أداة تحقق من JSON Schema محل الدالة المكتوبة يدويًا.

وعادتان أخريان تمنعان الأخطاء الصامتة. اضبط حد توكنات المخرجات بما يكفي لأكبر إجابة تتوقعها، لأن الكائن المقطوع لا يُحلَّل أبدًا. وعندما يكون المُدخل طويلًا أو قادمًا من المستخدمين، افصله عن تعليماتك باستخدام الفواصل أو وسوم XML حتى يقل احتمال قراءة نص بداخله على أنه تعليمة. وإذا كان على موجّه واحد أن يستدل وينتج JSON معًا، ففكّر في سلسلة الموجّهات: دع خطوة تفكر بنص حر، وخطوة ثانية تحوّل النتيجة إلى البنية.