قد يطلب تطبيق من نموذج لغوي استخراج اسم منتج وسعره وتاريخ فاتورته، ثم يفشل لأن الإجابة جاءت في فقرة بدل JSON صالح للقراءة الآلية. المخرجات المنظمة تعالج شكل البيانات ومطابقتها لمخطط محدد، لكنها لا تجعل كل قيمة مستخرجة صحيحة. هذا شرح للتحضير لعام 2027 وفق الخصائص الموثقة وقت الرصد في 27 أكتوبر 2026، وليس وعدًا بخواص مستقبلية.
ما المخرجات المنظمة في Claude API؟
تتيح JSON outputs تحديد مخطط JSON للرد عبر output_config.format. وتوجد خاصية strict: true لاستخدام الأدوات الصارم للتحقق من أسماء الأدوات ومدخلاتها. يمكن استخدام الخاصيتين منفصلتين أو معًا، لكنهما ليستا مجرد كتابة عبارة «أجب بصيغة JSON» في الرسالة.
حدد أسماء الحقول وأنواعها والحقول المطلوبة، ثم أرسل المخطط مع الطلب واقرأ النتيجة في التطبيق. كلما كان الشكل المتوقع واضحًا، قل احتياج البرنامج إلى تخمين مكان القيمة أو إزالة كلام زائد قبل تحليلها.
مثال عملي دون خلط الشكل بالحقيقة
في استخراج بيانات فاتورة، يمكنك طلب حقول اسم المورد وتاريخ الفاتورة والمبلغ وعملة المبلغ. المطابقة للمخطط تعني أن الحقول والأنواع تتبع الشكل المطلوب، لا أن النموذج قرأ كل رقم بلا خطأ أو أن الفاتورة أصلية.
راجع القيم المهمة مقابل المستند، وتحقق برمجيًا من الشروط الخاصة بتطبيقك، مثل العملة والنطاق المسموح للمبلغ واتساق المجاميع. وهذه مراجعة لمعنى البيانات، تختلف عن نجاح تحليل JSON وحده.
لماذا لا تنقل أي مخطط كما هو؟
يتبع المخطط JSON Schema مع قيود على الدعم. وبعض مساعدات SDK تحذف قيودًا غير مدعومة مثل minimum و maximum وحدود طول النص، وتنقلها إلى الوصف، وتضيف additionalProperties: false للأجسام.
لذلك افحص المخطط الذي ترسله مكتبة SDK فعليًا، ولا تفترض أن كل شرط كتبته في نموذج النوع أصبح قيدًا مفروضًا من واجهة البرمجة. وتختلف مساعدات اللغات في التحويل والتحقق؛ فالمخطط الخام والمخطط المحول ليسا بالضرورة الشيء نفسه.
التعامل مع الرد غير المكتمل أو الرفض
افحص stop_reason قبل اعتماد النتيجة. إذا بلغ الرد max_tokens فهو مقطوع وقد لا يطابق الشكل المتوقع. وإذا كانت النتيجة refusal فنجاح HTTP برمز 200 لا يعني وجود بيانات الأعمال التي طلبتها؛ عامل الحالة كمسار منفصل بدل إدخالها قسرًا إلى سجل فاتورة.
اختبر حالات مستند ناقص وقيمة غير موجودة ورد مقطوع، وحدد كيف يعرض التطبيق الخطأ أو يحيله للمراجعة. لا تملأ الحقول بقيم مخترعة لمجرد أن قاعدة البيانات تتطلب قيمة.
متى يكون الأسلوب مناسبًا؟
يفيد عندما سيستهلك برنامجٌ الردَ، مثل الاستخراج والتصنيف والتقارير المنظمة. أما إن كان الهدف نصًا يقرؤه إنسان فقط فقد تكفي تعليمات تنسيق واضحة. اختيار البنية يتبع استخدام النتيجة، مع إبقاء التحقق من الوقائع منفصلًا عن انتظام الشكل.
