فایل‌های ورودی پشتیبانی‌شده و الزامات

هنگام فراخوانی Gemini API از برنامه‌تان بااستفاده از کیت توسعه نرم‌افزار Firebase AI Logic، می‌توانید از مدل Gemini بخواهید براساس ورودی چندحالته، مانند تصاویر، ویدیو، و صدا، و اسناد (مانند PDF)، نوشتار تولید کند.

باید از انواع فایل پشتیبانی‌شده استفاده کنید، نوع MIME پشتیبانی‌شده‌ای را مشخص کنید، و مطمئن شوید که فایل‌ها و درخواست‌های چندحالتی شما الزامات را برآورده می‌کنند و از روال‌های مطلوب پیروی می‌کنند.

این صفحه مختص استفاده از GenerativeModel است و موارد زیر را شرح می‌دهد:

گزینه‌های ارائه فایل در درخواست‌های چندحالتی

ارائه‌دهنده Gemini API خود را انتخاب کنید تا محتوای مختص ارائه‌دهنده را در این صفحه مشاهده کنید

در هر درخواست چندحالتی، همیشه باید موارد زیر را ارائه دهید:

اندازه و تعداد فایل‌هایی که می‌توانید در درخواست ارائه دهید به نوع فایل ورودی، نحوه ارائه فایل، و مدل استفاده‌شده بستگی دارد (برای جزئیات، بخش مربوط به هر نوع فایل ورودی را در این صفحه ببینید).

گزینه ۱: ارائه فایل به‌عنوان داده درون‌خطی

به موارد زیر درباره فایل‌های ارائه‌شده به‌عنوان داده‌های درون‌خطی توجه کنید:

  • فقط فایل‌های کوچک را می‌توان به‌عنوان داده‌های درون‌خطی ارسال کرد زیرا محدودیت اندازه کل درخواست ۲۰ مگابایت است.

  • فایل درحین انتقال به base64 کدبندی می‌شود (که اندازه فایل را افزایش می‌دهد).

برای مشاهده مثالی که نحوه گنجاندن فایل به‌عنوان داده درون‌خطی را نشان می‌دهد، به تولید نوشتار از ورودی نوشتار و فایل (چندحالتی) مراجعه کنید. توجه داشته باشید که کیت‌های توسعه نرم‌افزار برای پلاتفرم‌های Android و Apple می‌توانند تصاویر درون‌خطی را در درخواست‌ها بدون نیاز به مشخص کردن نوع MIME مدیریت کنند. بیشتر بدانید

گزینه ۲: ارائه فایل بااستفاده از نشانی وب

در اینجا انواع قابل‌قبول نشانی‌های وب هنگام استفاده از Agent Platform Gemini API (formerly Vertex AI) آورده شده است:

  • Cloud Storage سطل:

    توجه داشته باشید که اگر سطل در پروژه دیگری غیراز پروژه‌ای است که با Firebase AI Logic استفاده می‌کنید، از قالب https://storage.googleapis.com/BUCKET_NAME/PATH/TO/FILE برای نشانی وب استفاده کنید.

  • نشانی‌های وب مرورگر/HTTP: نشانی وب فایل باید به‌صورت عمومی قابل‌خواندن باشد. نمونه‌ها شامل نشانی‌های وب از سایت‌های میزبان رسانه، نشانی‌های وب که رسانه را مستقیماً نشان می‌دهند (نه صفحه وبی که میزبان رسانه است)، یا منتشرشده فایل Google Drive یا Google Workspace.

  • نشانی وب ویدیو YouTube: ویدیو YouTube باید عمومی یا فهرست‌نشده باشد.

درباره الزامات نشانی‌های وب در سند Google Cloud بیشتر بدانید.


تصاویر: الزامات، روال‌های مطلوب، و محدودیت‌ها

تصاویر: الزامات

در این بخش، با انواع MIME پشتیبانی‌شده و محدودیت‌های هر درخواست برای تصاویر آشنا شوید.

انواع MIME پشتیبانی‌شده

مدل‌های چندحالتی Gemini از انواع MIME تصویر زیر پشتیبانی می‌کنند:

  • PNG - image/png
  • JPEG - image/jpeg
  • WebP - image/webp

محدودیت‌های هر درخواست

محدودیت خاصی برای تعداد پیکسل‌های تصویر وجود ندارد. بااین‌حال، تصاویر بزرگ‌تر کوچک می‌شوند و حاشیه به آن‌ها اضافه می‌شود تا با حداکثر وضوح ۳۰۷۲ × ۳۰۷۲ مطابقت داشته باشند و درعین‌حال نسبت ابعادی اصلی آن‌ها حفظ شود.

حداکثر تعداد فایل در هر درخواست: ۳٬۰۰۰ فایل تصویری

تصاویر: نشانه‌گذاری

نحوه محاسبه کردن توکن‌ها برای تصاویر در اینجا آمده است:

  • اگر هر دو بعد تصویر کمتر از یا مساوی ۳۸۴ پیکسل باشد، ۲۵۸ نشانه استفاده می‌شود.
  • اگر یکی از ابعاد تصویر بزرگ‌تر از ۳۸۴ پیکسل باشد، تصویر به‌صورت کاشی برش داده می‌شود. اندازه هر کاشی به‌طور پیش‌فرض به کوچک‌ترین بُعد (عرض یا ارتفاع) تقسیم بر ۱٫۵ است. درصورت لزوم، هر کاشی به‌گونه‌ای تنظیم می‌شود که کوچک‌تر از ۲۵۶ پیکسل و بزرگ‌تر از ۷۶۸ پیکسل نباشد. سپس اندازه هر کاشی به ۷۶۸×۷۶۸ تغییر می‌کند و از ۲۵۸ نشانه استفاده می‌کند.

تصاویر: روال‌های مطلوب

هنگام استفاده از تصاویر، برای کسب بهترین نتایج، از روال‌های مطلوب و اطلاعات زیر استفاده کنید:

  • اگر می‌خواهید نوشتار را در تصویر تشخیص دهید، از پیام‌واره‌های دارای یک تصویر استفاده کنید تا نتایج بهتری نسبت‌به پیام‌واره‌های دارای چند تصویر دریافت کنید.
  • اگر پیام‌واره‌تان حاوی یک تصویر است، تصویر را قبل‌از پیام‌واره نوشتاری در درخواستتان قرار دهید.
  • اگر پیام‌واره شما حاوی چند تصویر است و می‌خواهید بعداً در پیام‌واره به آن‌ها ارجاع دهید یا می‌خواهید مدل در پاسخ خود به آن‌ها ارجاع دهد، بهتر است قبل‌از هر تصویر یک نمایه به آن اختصاص دهید. از 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 در بسیاری از موارد استفاده چندوجهی قدرتمند هستند، مهم است که محدودیت‌های این مدل‌ها را درک کنید:

  • تعدیل محتوا: مدل‌ها از ارائه پاسخ درباره تصاویری که خط‌مشی‌های ایمنی ما را نقض می‌کنند خودداری می‌کنند.
  • استدلال فضایی: مدل‌ها در مکان‌یابی نوشتار یا اشیا در تصاویر دقیق نیستند. ممکن است فقط تعداد تقریبی اشیاء را برگردانند.
  • استفاده‌های پزشکی: مدل‌ها برای تفسیر تصاویر پزشکی (برای مثال، عکس‌های اشعه ایکس و سی‌تی اسکن) یا ارائه مشاوره پزشکی مناسب نیستند.
  • تشخیص افراد: این مدل‌ها برای شناسایی افراد غیرمشهور در تصاویر طراحی نشده‌اند.
  • دقت: مدل‌ها ممکن است هنگام تفسیر تصاویر با کیفیت پایین، چرخیده، یا با وضوح بسیار پایین دچار کژپنداری شوند یا اشتباه کنند. همچنین ممکن است مدل‌ها هنگام تفسیر نوشتار دست‌نویس در اسناد تصویری دچار کژپنداری شوند.


ویدیو: الزامات، روال‌های مطلوب، و محدودیت‌ها

ویدیو: الزامات

در این بخش، با انواع MIME پشتیبانی‌شده و محدودیت‌های هر درخواست برای ویدیو آشنا شوید.

انواع MIME پشتیبانی‌شده

مدل‌های چندحالتی Gemini از انواع رسانه ویدیویی زیر پشتیبانی می‌کنند:

  • 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

محدودیت‌های هر درخواست

حداکثر تعداد فایل در هر درخواست: ۱۰ فایل ویدیویی

ویدیو: تبدیل به داده‌واحد

نحوه محاسبه کردن توکن‌ها برای ویدیو در اینجا آمده است:

  • قطعه صوتی با فریم‌های ویدیو کدگذاری شده است. قطعه صوتی نیز به بخش‌های ۱ ثانیه‌ای تقسیم می‌شود که هرکدام معادل ۳۲ نشانه است. نشان‌های فریم ویدیو و صدا با مُهرهای زمانشان درهم‌تنیده شده‌اند. مُهرهای زمان به‌صورت ۵ کد نشان داده می‌شوند.
  • برای ویدیوهایی که با نرخ ۱ فریم در ثانیه (fps) یا کمتر نمونه‌برداری می‌شوند، مُهرهای زمان برای ساعت اول ویدیو به‌صورت ۵ نشانه برای هر فریم ویدیو نمایش داده می‌شوند. مُهرهای زمان باقی‌مانده به‌صورت ۷ نشانه برای هر فریم ویدیو نمایش داده می‌شوند.
  • برای ویدیوهایی که با نرخ نمونه‌برداری بالاتر از ۱ فریم در ثانیه (fps) نمونه‌برداری شده‌اند، مُهرهای زمان برای ساعت اول ویدیو به‌صورت ۹ نشانه برای هر فریم ویدیو نمایش داده می‌شوند. مُهرهای زمان باقی‌مانده به‌صورت ۱۱ نشانه برای هر فریم ویدیو نمایش داده می‌شوند.

ویدیو: روال‌های مطلوب

هنگام استفاده از ویدیو، از روال‌های مطلوب و اطلاعات زیر برای کسب بهترین نتایج استفاده کنید:

  • اگر پیام‌واره‌تان حاوی یک ویدیو است، ویدیو را قبل‌از پیام‌واره نوشتاری قرار دهید.
  • اگر به بومی‌سازی مُهر زمان در ویدیویی با صدا نیاز دارید، از مدل بخواهید مُهرهای زمانی تولید کند که از قالب شرح‌داده‌شده در «قالب مُهر زمان» پیروی کنند.

ویدیو: محدودیت‌ها

اگرچه مدل‌های چندوجهی Gemini در بسیاری از موارد استفاده چندوجهی قدرتمند هستند، مهم است که محدودیت‌های این مدل‌ها را درک کنید:

  • تعدیل محتوا: مدل‌ها از ارائه پاسخ درباره ویدیوهایی که خط‌مشی‌های ایمنی ما را نقض می‌کنند خودداری می‌کنند.
  • تشخیص صدای غیرگفتاری: مدل‌هایی که از صدا پشتیبانی می‌کنند ممکن است در تشخیص صداهای غیرگفتاری اشتباه کنند.


صدا: الزامات و محدودیت‌ها

صدا: الزامات

در این بخش، با انواع MIME پشتیبانی‌شده و محدودیت‌های هر درخواست برای صدا آشنا شوید.

انواع MIME پشتیبانی‌شده

مدل‌های چندحالتی Gemini از انواع MIME صوتی زیر پشتیبانی می‌کنند:

  • 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 پیکربندی کنید.


اسناد (مانند PDF): الزامات، روال‌های مطلوب، و محدودیت‌ها

اسناد: الزامات

در این بخش، با انواع MIME پشتیبانی‌شده و محدودیت‌های هر درخواست برای اسناد (مانند PDF) آشنا شوید.

انواع MIME پشتیبانی‌شده

مدل‌های چندحالتی Gemini از انواع MIME سند زیر پشتیبانی می‌کنند:

  • PDF - application/pdf
  • نوشتار - text/plain

محدودیت‌های هر درخواست

با فایل‌های PDF به‌عنوان تصویر رفتار می‌شود، بنابراین یک صفحه از فایل PDF به‌عنوان یک تصویر درنظر گرفته می‌شود. تعداد صفحه‌های مجاز در پیام‌واره به تعداد تصاویری که مدل‌های چندوجهی Gemini می‌توانند پشتیبانی کنند محدود است.

  • حداکثر تعداد فایل در هر درخواست: ۳٬۰۰۰ فایل
  • حداکثر تعداد صفحه در هر فایل: ۱۰۰۰ صفحه در هر فایل
  • حداکثر اندازه هر فایل: ۵۰ مگابایت برای هر فایل

اسناد: نشانه‌گذاری

نشانه‌گذاری PDF

فایل‌های PDF به‌عنوان تصویر درنظر گرفته می‌شوند، بنابراین هر صفحه از فایل PDF به‌همان روشی که تصویر نشان‌گذاری می‌شود، نشان‌گذاری می‌شود.

همچنین، هزینه فایل‌های PDF از قیمت‌گذاری تصویر Gemini پیروی می‌کند. برای مثال، اگر یک PDF دو صفحه‌ای را در یک فراخوانی API Gemini قرار دهید، هزینه ورودی پردازش دو تصویر را متحمل می‌شوید.

اسناد: روال‌های مطلوب

هنگام استفاده از فایل‌های PDF، برای کسب بهترین نتایج، از روال‌های مطلوب و اطلاعات زیر استفاده کنید:

  • اگر پیام‌واره‌تان حاوی یک PDF است، PDF را قبل‌از پیام‌واره نوشتاری در درخواستتان قرار دهید.
  • اگر سند طولانی دارید، برای پردازش آن، سند را به چند PDF تقسیم کنید.
  • از PDFهایی استفاده کنید که با نوشتار ارائه‌شده به‌صورت نوشتار ایجاد شده‌اند، نه با نوشتار موجود در تصاویر اسکن‌شده. این قالب تضمین می‌کند که نوشتار ماشین‌خوانا باشد تا ویرایش، جستجو، و دستکاری آن در مقایسه با فایل‌های PDF تصویری اسکن‌شده برای مدل آسان‌تر باشد. این روش هنگام کار با اسناد پرمتن مانند قراردادها، نتایج بهینه‌ای ارائه می‌دهد.

اسناد: محدودیت‌ها

اگرچه مدل‌های چندوجهی Gemini در بسیاری از موارد استفاده چندوجهی قدرتمند هستند، مهم است که محدودیت‌های این مدل‌ها را درک کنید:

  • استدلال فضایی: مدل‌ها در مکان‌یابی نوشتار یا اشیاء در فایل‌های PDF دقیق نیستند. ممکن است فقط تعداد تقریبی اشیاء را برگردانند.
  • دقت: مدل‌ها ممکن است هنگام تفسیر نوشتار دست‌نویس در اسناد PDF دچار کژپنداری شوند.