تحليل الفيديوهات المعمارية باستخدام Gemini API: دليل خطوة بخطوة

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

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

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

المتطلبات واختيار الملف

يتطلب سير العمل إمكانية الوصول إلى Gemini API ووسيلة لرفع الفيديو. تستخدم الأمثلة الرسمية Python وJavaScript وJava وGo وREST؛ أما الخطوات أدناه فلا تعتمد على لغة برمجة محددة. يستخدم مثال REST مفتاحًا باسم GEMINI_API_KEY. ولا توضح وثائق الفيديو المستخدمة هنا تفاصيل شروط الحساب أو الوصول إلى API.

يُذكر اسم النموذج gemini-3.8-flash في مثال طلب API. وهذا هو اسم النموذج المستخدم في مثال فهم الفيديو. أما إنشاء الفيديو فله دليل منفصل: تذكر Google Gemini Omni Flash لإنشاء الفيديو عمومًا وتحريره مع الكلام، وVeo 3.1 لاحتياجات مثل تمديد المشهد أو التحكم في الإطار الأخير. لا تخلطوا بين هذين الاستخدامين.

قبل إرسال الملف، تحقّقوا من حجمه وما إذا كنتم ستعيدون استخدامه:

• توصي Google باستخدام Files API للفيديوهات التي يزيد حجمها على 100 MB أو للفيديوهات الطويلة والملفات التي سيُعاد استخدامها. ويعرض الجدول في الوثيقة الحد الأعلى لـ Files API على أنه 2 GB للاستخدام المجاني و20 GB للاستخدام المدفوع.

• يحدد خيار Cloud Storage Registration حدًا قدره 2 GB لكل ملف، وتشير الوثيقة إلى عدم وجود حد إضافي للتخزين.

• طريقة رابط YouTube مخصصة لفيديوهات YouTube المتاحة للعامة.

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

سير عمل التحليل خطوة بخطوة

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

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

3. أرسلوا الطلب مع محتوى الفيديو. يتضمن الطلب إدخال الفيديو وطلب التحليل كإدخال نصي. في مثال Python، يُرفع الملف عبر Files API؛ أما مثال المحتوى الأصغر فيرسل بايتات الفيديو بصيغة مضمّنة. أيًا كانت طريقة التكامل المختارة، يجب تمرير نوع MIME ومرجع الملف بصورة صحيحة.

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

Bu mimari iç mekân videosunu sahne sırasına göre özetle. Görüntüde açıkça görülen mekânları, malzeme izlenimlerini ve kamera hareketlerini ayrı maddeler hâlinde belirt. Görüntüde olmayan bilgileri tahmin etme; belirsiz noktaları açıkça işaretle.

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

Videoda girişten ana yaşam alanına geçişin görüldüğü bölümü bul. İlgili zaman damgasını belirt ve o anda kadrajda görünen mekânsal ilişkileri kısaca açıkla. Bölüm net değilse bunu söyle; zaman veya plan bilgisi uydurma.

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

Bu şantiye videosunda tamamlanmış görünen imalatları ve hâlen devam ettiği açıkça anlaşılan işleri ayır. Her bulguyu videoda görülen sahneyle ilişkilendir; yapısal güvenlik, ölçü veya mevzuat uygunluğu hakkında çıkarım yapma.

يطلب هذا المثال تصنيفًا يساعد على تنظيم السجل البصري، لكنه لا ينتج اعتمادًا على السلامة أو المطابقة. قارنوا الإجابات بسجلات فريق الموقع.

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

أخطاء شائعة

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

طلب التحليل قبل اكتمال المعالجة: ينتظر مثال Files API إلى أن تصبح حالة الملف ACTIVE بعد رفعه. استخدام مرجع الملف قبل التحقق من حالة المعالجة لا يتوافق مع سير العمل الوارد في المثال.

الخلط بين تحليل الفيديو وإنشائه: لتحليل تسجيل موجود، استخدموا دليل فهم الفيديو. أما إنشاء الفيديو وتحريره، فتصف الوثيقة Gemini Omni Flash وVeo 3.1 بأنهما مساران منفصلان.

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

أثر ذلك في سير عمل العمارة والتصميم الداخلي

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

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

ابدؤوا بملخص عام لتسجيل قصير ومعبّر، ثم ضيّقوا نطاق المخرجات بأسئلة تركز على مشهد أو طابع زمني. وإذا كنتم سترسلون طلبات متعددة للفيديو نفسه، فضعوا توصية Google باستخدام Files API في الحسبان. وإذا كنتم تحتاجون أيضًا إلى إنشاء الفيديو عبر API، فراجعوا وثائق Gemini Omni Flash وVeo 3.1 بشكل منفصل عن سير عمل فهم الفيديو.

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

أُعدّ هذا الدليل باللغة التركية بالاستناد إلى المعلومات الواردة في وثائق Google لفهم الفيديو وإنشائه باستخدام Gemini API. والمصدران مرخصان بموجب CC BY 4.0.