دليل تحويل الصور المعمارية إلى مخرجات JSON باستخدام Gemini API

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

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

تتناول وثائق Google الخاصة بـ Gemini API فهم الصور في سياقات مثل وصف الصور وتصنيفها والإجابة عن الأسئلة المتعلقة بها. ويمكن إرسال مدخلات الصور عبر URL أو البيانات المضمّنة أو Files API. يستخدم هذا المثال اسم النموذج gemini-3.8-flash الوارد ضمن أمثلة الوثائق.

المتطلبات

• عميل أو طلب REST يمكنه العمل مع Gemini API. توفر الوثائق أمثلة بلغة Python وJavaScript، إلى جانب أمثلة Java وGo.

• طريقة لإرسال الصورة إلى API: بيانات مضمّنة مشفّرة بترميز base64 للصور الصغيرة، وFiles API للملفات الكبيرة أو الصور التي ستُستخدم مجددًا.

• إذا كانت المخرجات مطلوبة بتنسيق JSON، فستحتاج إلى JSON Schema يحدد الحقول التي تتألف منها الإجابة. يمكن تعريف المخطط في Google GenAI SDKs باستخدام Pydantic في Python وZod في JavaScript.

• إذا كنت تستخدم REST، فستحتاج إلى مفتاح API في الطلب. لا يفترض هذا الدليل معلومات غير واردة في المصادر بشأن إنشاء الحسابات أو الرسوم أو حصص الاستخدام.

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

{
  "type": "object",
  "properties": {
    "gozlemler": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "unsur": { "type": "string" },
          "konum": { "type": "string" },
          "gorunur_ozellik": { "type": "string" }
        },
        "required": ["unsur", "konum", "gorunur_ozellik"]
      }
    }
  },
  "required": ["gozlemler"]
}

خطوات التنفيذ

1. حدّد الصورة والهدف

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

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

يوصي دليل Google لتصميم المطالبات بتحديد المهمة والقيود بوضوح، مع وصف تنسيق الإجابة المطلوبة. يطبّق المثال التالي هذا النهج على صورة داخلية:

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

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

3. أضف الصورة إلى طلب API

يمكنك ترميز صورة صغيرة بترميز base64 وإرسالها في حقل data. وتستخدم الوثائق في هذه الطريقة بيانات الصورة ونوع MIME إلى جانب المطالبة النصية. ويبلغ الحد الأقصى للحجم الإجمالي للطلب، عند استخدام بيانات الصورة المضمّنة مع نص المطالبة وتعليمات النظام، 20 MB. إذا كان من المحتمل تجاوز هذا الحد، فارفع الملف إلى Files API وأضف URI الناتج إلى الطلب.

توصي الوثائق باستخدام Files API للملفات الكبيرة أو عند استخدام الصورة نفسها في طلبات متعددة. أرسل المدخل النصي ومدخل الصورة معًا في الطلب، وحدد نوع MIME المناسب للصورة. ومن أنواع الصور المذكورة في الوثائق image/jpeg.

4. اضبط تنسيق إجابة JSON

في ميزة Structured outputs، اضبط تنسيق الإجابة على JSON وأرفق المخطط بالطلب. في مثال REST الوارد في الوثائق، تُضبط قيمة mime_type على application/json، ويوضع المخطط في الحقل schema. أما مثال Python فينشئ JSON Schema من نموذج Pydantic، ثم يتحقق من الإجابة باستخدام ذلك النموذج؛ ويستخدم مثال JavaScript مخطط Zod.

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

5. تحقّق من الإجابة واستخدمها

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

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

أخطاء شائعة

• طلب معلومات مؤكدة عن أمور غير ظاهرة في الصورة: قد تجعل المنظورية أو الدقة أو التأطير بعض التفاصيل غير واضحة. اطلب من النموذج الإشارة إلى عدم اليقين بدلًا من التخمين.

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

• إرسال ملف كبير ببيانات مضمّنة: يسري حد إجمالي لحجم الطلب يبلغ 20 MB عند تضمين بيانات الصورة. استخدم Files API للملفات الكبيرة.

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

• اعتبار المطالبة الأولى نسخة نهائية: حتى عندما تكون المهمة والقيود واضحة، من الضروري مراجعة المخرجات وتحسين المطالبة استنادًا إلى أمثلة حقيقية.

الأثر في سير عمل العمارة وarchviz

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

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

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

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

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

أُعدّ هذا المحتوى باللغة التركية بالاستناد إلى أدلة Google AI for Developers المسماة “Structured outputs” و“Image understanding” و“Prompt design strategies”. وتُتاح المصادر الثلاثة بموجب ترخيص CC BY 4.0.