إنشاء مخرجات JSON منظّمة من النصوص المعمارية باستخدام Gemini API

ما الذي ستتعلمه في هذا الدليل؟

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

سنتناول هنا ثلاث نقاط معًا: تحديد الحقول المطلوبة، وشرح المهمة والقيود بتعليمات واضحة، ثم إضافة المخطط المناسب إلى طلب API. أُعدّت الأمثلة لسير العمل المعماري؛ ولا ترد التعليمات أدناه بالنص نفسه في المصادر، بل هي أمثلة أصلية أُعدّت وفق الأساليب الموثقة.

المتطلبات والنطاق

تشير وثائق Google إلى دعم JSON Schema في REST API للمخرجات المنظّمة. أما في Google GenAI SDK، فتُعرض Pydantic في Python وZod في JavaScript كخيارين لتعريف المخطط. تتضمن المصادر أمثلة على Java وGo وغيرها أيضًا؛ لكننا نستخدم في هذا الدليل مسودة JSON Schema يسهل نقلها بدلًا من عرض الشيفرة.

تذكر أمثلة الوثائق ضرورة تثبيت Zod لاستخدامه مع JavaScript؛ لكنها لا توضح إصدار SDK أو متطلبات الحساب أو معلومات الأسعار. لذلك، تحقّق من المتطلبات الحالية للـ SDK والنموذج الذي ستستخدمه في وثائق Gemini API ذات الصلة قبل بدء المشروع. تذكر مقدمة الوثائق أن Gemini 4 Argon متاح، في حين يظهر اسم النموذج gemini-3.8-flash في مثال الشيفرة. لا تفترض أن اسم النموذج الوارد في المثال هو الأحدث أو الأنسب لكل استخدام.

1. حدّد الحقول المطلوب استخراجها

قبل إعداد المخطط، قرّر البيانات التي تريد استخراجها من النص ونوع كل حقل. تستهدف المسودة أدناه، مثلًا، استخراج اسم المكان والمادة المذكورة ووصف الوظيفة من موجز تصميم داخلي. وتتوافق البنى الأساسية في JSON Schema، مثل object وproperties وstring وrequired، مع الأمثلة الواردة في المصادر.

{
  "type": "object",
  "properties": {
    "mekan_adi": { "type": "string" },
    "malzeme": { "type": "string" },
    "islev": { "type": "string" }
  },
  "required": ["mekan_adi", "malzeme", "islev"]
}

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

2. اكتب المهمة والمدخلات بوضوح

تشرح التعليمات الجيدة العمل المطلوب تنفيذه والنص المراد معالجته وشكل الاستجابة بطريقة مفهومة. ويوصي دليل Google لتصميم التعليمات باستخدام توجيهات واضحة ومحددة، وبيان القيود وتوقعات التنسيق عند الحاجة. يمكنك تعديل المثال التالي ليناسب حقول الموجز التي تستخدمها.

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

الموجز: توجد في منطقة القراءة الواقعة في الطابق الأرضي أسطح مكسوة بالبلوط وطاولات للعمل المشترك.

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

3. ضيّق نطاق القيود بحسب متطلبات المشروع

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

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

الوصف: ستُستخدم أرضية تيرازو وسطح جدار من الجص المطلي في بهو المدخل.

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

4. وضّح التنسيق بمثال للإجابة

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

صنّف ملاحظة المساحة الجديدة باستخدام الحقول الواردة في المثال أدناه.

ملاحظة مثال: «سطح المطبخ من مركّب الكوارتز، وواجهات الخزائن مطلية بطلاء لاكيه مطفي».
مخرج المثال: {"mekan": "المطبخ", "malzemeler": ["مركّب الكوارتز", "لاكيه مطفي"]}

ملاحظة جديدة: «توجد في غرفة الدراسة أرضية باركيه خشبي وطلاء فوق اللياسة».
أجب بالتنسيق نفسه فقط.

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

أخطاء شائعة

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

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

الاستخدام في سير العمل المعماري والتصوّر البصري

قد يكون هذا النهج مفيدًا للمكاتب المعمارية ومصممي الديكور الداخلي والطلاب الذين يحتاجون إلى تصنيف عدد كبير من ملاحظات المشاريع ضمن الحقول نفسها. ويوفر استخراج أسماء المواد أو أنواع المساحات أو أوصاف الوظائف من أوصاف الغرف نقطة بداية منظّمة لسير العمل الذي ستُنقل فيه هذه البيانات إلى أداة أخرى. لا تصف المصادر تكاملًا مع برنامج محدد لـ BIM أو CAD أو التصوّر البصري؛ لذلك ينبغي تقييم الاتصال والتوافق على نحو مستقل.

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

الخطوات التالية

ابدأ باختيار حالة استخدام واحدة، مثل استخراج المواد من ملاحظة مساحة. حدّد الحقول وأعدّ المخطط، ثم جرّبه باستخدام تعليمات واضحة. قارن النتائج بالنص المصدر، ولاحظ الأخطاء المتكررة، وأضف أمثلة إلى التعليمات عند الحاجة الفعلية فقط. إذا كنت تستخدم Python في التطبيق، فقيّم خيار تعريف المخطط باستخدام Pydantic؛ وإذا كنت تستخدم JavaScript، فقيّم Zod. كما أن استخدام REST API مدعوم في الوثائق.

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

المصدر والترخيص

أُعدّ هذا الدليل بتكييف وثيقتَي Google «Structured outputs» و«Prompt design strategies» إلى التركية. وكلا المصدرين مرخّص بموجب CC BY 4.0.