ملفات الإدخال المتوافقة ومتطلبات واجهة برمجة التطبيقات Vertex AI Gemini API

عند طلب Vertex AI Gemini API من تطبيقك باستخدام حزمة تطوير البرامج (SDK) لVertex AI in Firebase، يمكنك توجيه نموذج Gemini لإنشاء نص استنادًا إلى إدخال متعدد الوسائط. يمكن أن تتضمّن الطلبات المتعدّدة الوسائط عدة وسائط (أو أنواع إدخال)، مثل النصوص والصور وملفات PDF والفيديوهات والمقاطع الصوتية.

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

توضّح هذه الصفحة ما يلي:

خيارات تقديم الملفات في طلبات الوسائط المتعددة

في كل طلب متعدد الوسائط، يجب دائمًا تقديم ما يلي:

يعتمد حجم الملفات التي يمكنك تقديمها في الطلب وعدد هذه الملفات على نوع ملف الإدخال وطريقة تقديم الملف والنموذج المستخدَم (للاطّلاع على التفاصيل، اطّلِع على قسم كل نوع من أنواع ملفات الإدخال في هذه الصفحة).

الخيار 1: تقديم الملف باستخدام عنوان URL أو عنوان موارد موحّد

في ما يلي الأنواع المقبولة لعناوين URL أو عناوين URI:

  • Cloud Storage for Firebase عنوان URL للحزمة: يجب أن يكون عنوان URL للملف متاحًا للجميع أو يجب أن يكون لدى المستخدم الذي سجّل الدخول أو العميل إذن وصول كافٍ إلى الملف. اطّلِع على مزيد من المعلومات عن Cloud Storage for Firebase المزايا، متطلبات عناوين URL، و عيّنات الرموز البرمجية.

  • Google Cloud Storage عنوان URL للحزمة: يجب أن يكون عنوان URL للملف متاحًا للجميع.

  • عناوين URL للمتصفّح أو HTTP: يجب أن يكون عنوان URL للملف قابلاً للقراءة للجميع. تشمل الأمثلة عناوين URL من المواقع الإلكترونية التي تستضيف الوسائط، أو عناوين URL التي تعرض الوسائط مباشرةً (وليس صفحة ويب تستضيف الوسائط)، أو ملف منشور على Google Drive أو Google Workspace.

  • عنوان URL لفيديو على YouTube: يجب أن يكون الفيديو على YouTube علنيًا أو غير مُدرَج.

اطّلِع على مزيد من المعلومات حول متطلبات عناوين URL وعناوين URI في مستندات Google Cloud.

الخيار 2: تقديم الملف كبيانات مضمّنة

يُرجى مراعاة ما يلي بشأن الملفات المقدَّمة كبيانات مضمّنة:

  • يمكن إرسال الملفات الصغيرة فقط كبيانات مضمّنة لأنّ الحد الأقصى لحجم الطلب هو 20 ميغابايت.

  • يتم ترميز الملف بترميز base64 أثناء نقله (ما يؤدي إلى زيادة حجم الملف).

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


الصور: المتطلبات وأفضل الممارسات والقيود

الصور: المتطلبات

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

أنواع MIME المتوافقة

تتوافق نماذج Gemini المتعدّدة الوسائط مع أنواع MIME التالية للصور:

نوع MIME للصورة Gemini 1.5 Flash Gemini 1.5 Pro Gemini 1.0 Pro Vision
‫PNG‏ - image/png
‫JPEG - image/jpeg
‫WebP ‏- image/webp

الحدود القصوى المسموح بها لكل طلب

ما مِن حدّ أقصى محدّد لعدد البكسل في الصورة. ومع ذلك، يتم تصغير الصور الأكبر حجمًا وإضافة حواف إليها لتتلاءم مع الحد الأقصى للدقة البالغ 3072 × 3072 مع الحفاظ على نسبة العرض إلى الارتفاع الأصلية.

في ما يلي الحد الأقصى لعدد ملفات الصور المسموح به في طلب فوري:

  • Gemini 1.0 Pro Vision: 16 صورة
  • Gemini 1.5 Flash و Gemini 1.5 Pro: 3,000 صورة

الصور: إنشاء الرموز المميّزة

في ما يلي كيفية احتساب الرموز المميّزة للصور:

  • Gemini 1.0 Pro Vision: تُحتسب كل صورة لـ 258 رمزًا مميّزًا.
  • Gemini 1.5 Flash و Gemini 1.5 Pro:
    • إذا كانت كلتا سمتَي الصورة أقل من أو تساوي 384 بكسل، يتم استخدام 258 رمزًا.
    • إذا كان أحد أبعاد الصورة أكبر من 384 بكسل، تتم قتصاص الصورة إلى مربّعات. يكون حجم كل مربّع افتراضيًا هو أصغر سمة (العرض أو الارتفاع) مقسومة على 1.5. إذا لزم الأمر، تتم تعديل كل مربّع بحيث لا يكون أصغر من 256 بكسل ولا أكبر من 768 بكسل. ويتم بعد ذلك تغيير حجم كل مربّع إلى 768×768 ويستخدم 258 رمزًا مميزًا.

الصور: أفضل الممارسات

عند استخدام الصور، اتّبِع أفضل الممارسات والمعلومات التالية للحصول على أفضل النتائج:

  • إذا كنت تريد رصد نص في صورة، استخدِم طلبات تتضمّن صورة واحدة لمحاولة الحصول على نتائج أفضل من الطلبات التي تتضمّن صورًا متعددة.
  • إذا كان طلبك يحتوي على صورة واحدة، ضَع الصورة قبل طلب نص الطلب في طلبك.
  • إذا كان الطلب يحتوي على صور متعددة، وأردت الإشارة إليها في وقت لاحق من الطلب أو أن يشير إليها النموذج في ردّه، قد يكون من المفيد منح كل صورة فهرسًا قبلها. استخدِم a b c أو image 1 image 2 image 3 للفهرس. في ما يلي مثال على استخدام الصور المفهرَسة في طلب: 
    image 1 
image 2 
image 3 

Write a blogpost about my day using image 1 and image 2. Then, give me ideas
for tomorrow based on image 3.
  • استخدِم صورًا بدرجة دقة أعلى، لأنّها تحقّق نتائج أفضل.
  • أدرِج بعض الأمثلة في الطلب.
  • يجب تدوير الصور إلى الاتجاه الصحيح قبل إضافتها إلى الطلب.
  • تجنَّب استخدام الصور المموّهة.

الصور: القيود

على الرغم من أنّ نماذج Gemini المتعددة الوسائط فعّالة في العديد من حالات استخدام الوسائط المتعددة، من المهم فهم القيود المفروضة على النماذج:

  • الإشراف على المحتوى: يرفض العارضون تقديم إجابات حول الصور التي تنتهك سياسات السلامة.
  • الاستدلال المكاني: لا تُحدِّد النماذج بدقة مكان النصوص أو الأجسام في الصور. وقد لا تعرض سوى الأعداد التقريبية للعناصر.
  • الاستخدامات الطبية: لا تكون النماذج مناسبة لتفسير الصور الطبية (مثل الأشعة السينية والتصوير المقطعي) أو تقديم advice طبي.
  • التعرّف على الأشخاص: لا يُقصد استخدام النماذج لتحديد هوية الأشخاص العاديين في الصور.
  • الدقة: قد تُحلِّم النماذج أو تخطئ عند تفسير الصور المنخفضة الجودة أو المُدارَة أو ذات الدقة المنخفضة جدًا. قد تُظهر النماذج أيضًا هلوسات عند تفسير نص مكتوب بخط اليد في مستندات الصور.


الفيديو: المتطلبات وأفضل الممارسات والقيود

الفيديو: المتطلبات

في هذا القسم، يمكنك الاطّلاع على أنواع MIME المتوافقة والقيود المفروضة لكل طلب بشأن الفيديو.

أنواع MIME المتوافقة

تتوافق نماذج Gemini المتعدّدة الوسائط مع أنواع MIME التالية للفيديو:

نوع MIME للفيديو Gemini 1.5 Flash Gemini 1.5 Pro Gemini 1.0 Pro Vision
‫FLV - video/x-flv
‫MOV - video/quicktime
‫MPEG - video/mpeg
‫MPEGPS - video/mpegps
الأميال لكل غالون: video/mpg
‫MP4 - video/mp4
‫WEBM - video/webm
‫WMV - video/wmv
3GPP - video/3gpp

الحدود القصوى المسموح بها لكل طلب

في ما يلي الحد الأقصى لعدد ملفات الفيديو المسموح به في طلب فوري:

  • Gemini 1.0 Pro Vision: ملف فيديو واحد
  • ‫Gemini 1.5 Flash و Gemini 1.5 Pro: 10 ملفات فيديو

فيديو: إنشاء الرموز المميّزة

في ما يلي كيفية احتساب الرموز المميّزة للفيديو:

  • جميع نماذج Gemini المتعددة الوسائط: يتم أخذ عيّنات من الفيديوهات بمعدل لقطة واحدة في الثانية. يضمّ كل لقطة فيديو 258 رمزًا.
  • ‫Gemini 1.5 Flash و Gemini 1.5 Pro: يتم ترميز المقطع الصوتي باستخدام لقطات الفيديو. يتم أيضًا تقسيم المقطع الصوتي إلى مجموعات مدتها ثانية واحدة تضم كلّ منها 32 رمزًا مميزًا. يتم تداخل رمزَي الإطار الفيديو والصوت مع الطوابع الزمنية الخاصة بهما. يتم تمثيل الطابعات الزمنية على شكل 7 علامات.

فيديو: أفضل الممارسات

عند استخدام الفيديو، اتّبِع أفضل الممارسات والمعلومات التالية للحصول على أفضل النتائج:

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

  • يُرجى مراعاة ما يلي إذا كنت تستخدم إصدار Gemini 1.0 Pro Vision:

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

فيديو: القيود

على الرغم من أنّ نماذج Gemini المتعددة الوسائط فعّالة في العديد من حالات استخدام الوسائط المتعددة، من المهم فهم القيود المفروضة على النماذج:

  • الإشراف على المحتوى: يرفض العارضون تقديم إجابات على الفيديوهات التي تنتهك سياسات السلامة لدينا.
  • التعرّف على الأصوات غير الكلامية: قد تخطئ الطُرز التي تتيح استخدام الصوت في التعرّف على الأصوات غير الكلامية.
  • الحركة السريعة: قد ترتكب النماذج أخطاء عند محاولة فهم الحركة السريعة في الفيديو بسبب معدّل أخذ العينات الثابت الذي يبلغ لقطة واحدة في الثانية.
  • علامات الترقيم في النص المنسوخ: (في حال استخدام Gemini 1.5 Flash) قد تعرِض النماذج نصوصًا منسوخة لا تتضمّن علامات ترقيم.


الصوت: المتطلبات والقيود

الصوت: المتطلبات

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

أنواع MIME المتوافقة

تتوافق نماذج Gemini المتعدّدة الوسائط مع أنواع MIME التالية للصوت:

نوع MIME للصوت Gemini 1.5 Flash Gemini 1.5 Pro
‫AAC - audio/aac
FLAC - audio/flac
‫MP3 - audio/mp3
MPA - audio/m4a
‫MPEG - audio/mpeg
‫MPGA - audio/mpga
‫MP4 - audio/mp4
OPUS - audio/opus
PCM - audio/pcm
‫WAV - audio/wav
‫WEBM - audio/webm

الحدود القصوى المسموح بها لكل طلب

يمكنك تضمين ملف صوتي واحد كحد أقصى في طلب طلب.

الصوت: القيود

على الرغم من أنّ نماذج Gemini المتعددة الوسائط فعّالة في العديد من حالات استخدام الوسائط المتعددة، من المهم فهم القيود المفروضة على النماذج:

  • التعرّف على الأصوات غير الكلامية: قد تخطئ الطُرز التي تتيح استخدام الصوت في التعرّف على الأصوات غير الكلامية.
  • الطوابع الزمنية للمحتوى الصوتي فقط: لإنشاء طوابع زمنية دقيقة للملفات الصوتية فقط، يجب ضبط المَعلمة audio_timestamp في generation_config.
  • علامات الترقيم في النص المنسوخ: (في حال استخدام Gemini 1.5 Flash) قد تعرِض النماذج نصوصًا منسوخة لا تتضمّن علامات ترقيم.


المستندات (مثل ملفات PDF): المتطلبات وأفضل الممارسات والقيود

المستندات: المتطلبات

في هذا القسم، يمكنك الاطّلاع على أنواع MIME المتوافقة والقيود المفروضة لكل طلب بشأن المستندات (مثل ملفات PDF).

أنواع MIME المتوافقة

تتوافق نماذج Gemini المتعدّدة الوسائط مع أنواع MIME التالية للمستندات:

نوع MIME للمستند Gemini 1.5 Flash Gemini 1.5 Pro Gemini 1.0 Pro Vision
ملف PDF‏ - application/pdf
النص: text/plain

الحدود القصوى المسموح بها لكل طلب

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

  • Gemini 1.0 Pro Vision: 16 صفحة
  • Gemini 1.5 Pro و Gemini 1.5 Flash: 1,000 صفحة

المستندات: إنشاء الرموز المميّزة

إنشاء رموز مميّزة لملفات PDF

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

وتسري أيضًا أسعار صور Gemini على ملفات PDF. على سبيل المثال، إذا أدرجت ملف PDF مكوّنًا من صفحتَين في طلب Gemini API، ستسدد رسوم إدخال لمعالجة صورتَين.

إنشاء الرموز المميّزة للنص العادي

يتم تقسيم مستندات النصوص العادية إلى وحدات نصية. على سبيل المثال، إذا أدرجت مستندًا يحتوي على 100 كلمة مكتوبة بتنسيق نص عادي في طلب Gemini API، ستتحمل رسوم إدخال مقابل معالجة 100 كلمة.

المستندات: أفضل الممارسات

عند استخدام ملفات PDF، اتّبِع أفضل الممارسات والمعلومات التالية للحصول على أفضل النتائج:

  • إذا كان الطلب يحتوي على ملف PDF واحد، ضَع ملف PDF قبل الطلب النصي.
  • إذا كان لديك مستند طويل، ننصحك بتقسيمه إلى ملفات PDF متعددة لمعالجته.
  • استخدِم ملفات PDF التي تم إنشاؤها باستخدام نص معروض كنص بدلاً من استخدام النص في الصور الممسوحة ضوئيًا. يضمن هذا التنسيق إمكانية قراءة النص آليًا لكي يكون من السهل على النموذج تعديله والبحث فيه والتلاعب به مقارنةً بملف PDF المسجّل من صورة ممسوحة ضوئيًا. توفّر هذه الممارسة نتائج مثالية عند العمل مع المستندات التي تحتوي على الكثير من النصوص، مثل العقود.

المستندات: القيود

على الرغم من أنّ نماذج Gemini المتعددة الوسائط فعّالة في العديد من حالات استخدام الوسائط المتعددة، من المهم فهم القيود المفروضة على النماذج:

  • الاستدلال المكاني: لا تحدد النماذج بدقة مكان النص أو العناصر في ملفات PDF. وقد لا تعرض سوى الأعداد التقريبية للعناصر.
  • الدقة: قد تُظهر النماذج معلومات مضلِّلة عند تفسير النص المكتوب بخط اليد في ملفات PDF.