درخواست با فایل های رسانه ای

مشاهده در ai.google.dev

در Google Colab اجرا شود

مشاهده منبع در GitHub

Gemini API از درخواست با داده های متنی، تصویری و صوتی پشتیبانی می کند که به عنوان درخواست چندوجهی نیز شناخته می شود. می‌توانید متن، تصویر و صدا را در درخواست‌های خود قرار دهید. برای تصاویر کوچک، می توانید مدل Gemini را مستقیماً به یک فایل محلی هنگام ارائه درخواست اشاره کنید. برای تصاویر بزرگ‌تر، ویدیوها (توالی فریم‌های تصویر) و صدا، فایل‌ها را با File API آپلود کنید قبل از اینکه آنها را در دستورات قرار دهید.

File API به شما امکان می دهد تا حداکثر 20 گیگابایت فایل را در هر پروژه ذخیره کنید و حجم هر فایل از 2 گیگابایت بیشتر نباشد. فایل ها به مدت 48 ساعت ذخیره می شوند و می توان با کلید API خود برای تولید در آن بازه زمانی به آنها دسترسی داشت. در تمام مناطقی که Gemini API در دسترس است، بدون هزینه در دسترس است.

برای اطلاعات در مورد فرمت های فایل معتبر (انواع MIME) و مدل های پشتیبانی شده، به فرمت های فایل پشتیبانی شده مراجعه کنید.

این راهنما نحوه استفاده از File API برای آپلود یک فایل رسانه و گنجاندن آن در یک تماس GenerateContent به Gemini API را نشان می دهد. برای اطلاعات بیشتر به نمونه کدها مراجعه کنید.

برپایی

قبل از استفاده از File API، باید بسته Gemini API SDK را نصب کرده و یک کلید API را پیکربندی کنید. این بخش نحوه تکمیل این مراحل راه اندازی را شرح می دهد.

Python SDK را نصب کنید و بسته ها را وارد کنید

Python SDK برای Gemini API در بسته google-generativeai موجود است. وابستگی را با استفاده از pip نصب کنید.

pip install -q -U google-generativeai

بسته های لازم را وارد کنید.

import google.generativeai as genai
from IPython.display import Markdown

کلید API خود را تنظیم کنید

File API از کلیدهای API برای احراز هویت و دسترسی استفاده می کند. فایل های آپلود شده با پروژه مرتبط با کلید API مرتبط هستند. برخلاف سایر API های Gemini که از کلیدهای API استفاده می کنند، کلید API شما همچنین به داده هایی که در File API آپلود کرده اید دسترسی می دهد، بنابراین در ایمن نگه داشتن کلید API خود دقت بیشتری داشته باشید. برای اطلاعات بیشتر در مورد ایمن نگه داشتن کلیدهای خود، به بهترین شیوه ها برای استفاده از کلیدهای API مراجعه کنید.

کلید API خود را در یک Colab Secret به نام GOOGLE_API_KEY ذخیره کنید. اگر از قبل کلید API ندارید یا با Colab Secrets آشنا نیستید، به شروع سریع احراز هویت مراجعه کنید.

from google.colab import userdata
GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')

genai.configure(api_key=GOOGLE_API_KEY)

یک فایل را در File API آپلود کنید

File API به شما امکان می دهد انواع MIME چندوجهی، از جمله تصاویر و فرمت های صوتی را آپلود کنید. File API ورودی هایی را کنترل می کند که می توانند برای تولید محتوا با model.generateContent یا model.streamGenerateContent استفاده شوند.

File API فایل های کمتر از 2 گیگابایت را می پذیرد و می تواند تا 20 گیگابایت فایل را در هر پروژه ذخیره کند. فایل ها 2 روز دوام می آورند و از API قابل دانلود نیستند.

ابتدا یک نمونه تصویر را برای آپلود در API آماده خواهید کرد.

برای آپلود فایل خود، به بخش پیوست مراجعه کنید.

curl -o image.jpg https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg

در مرحله بعد، آن فایل را در File API آپلود خواهید کرد.

sample_file = genai.upload_file(path="image.jpg",
                            display_name="Sample drawing")

print(f"Uploaded file '{sample_file.display_name}' as: {sample_file.uri}")

Uploaded file 'Sample drawing' as: https://generativelanguage.googleapis.com/v1beta/files/ui00j5zfuqe0

response نشان می دهد که File API display_name مشخص شده را برای فایل آپلود شده و یک uri برای ارجاع فایل در تماس های Gemini API ذخیره کرده است. از response برای ردیابی نحوه نگاشت فایل های آپلود شده به URI استفاده کنید.

بسته به موارد استفاده شما، می توانید URI ها را در ساختارهایی مانند dict یا پایگاه داده ذخیره کنید.

دریافت فایل

پس از آپلود فایل، می‌توانید با تماس با files.get تأیید کنید که API با موفقیت فایل‌ها را دریافت کرده است.

این به شما امکان می دهد فراداده فایلی را که در File API آپلود شده است و با پروژه Cloud مرتبط است که کلید API شما به آن تعلق دارد، دریافت کنید. فقط name (و با بسط، uri ) منحصر به فرد است. فقط در صورتی از displayName برای شناسایی فایل ها استفاده کنید که خودتان منحصر به فرد بودن را مدیریت کنید.

file = genai.get_file(name=sample_file.name)
print(f"Retrieved file '{file.display_name}' as: {sample_file.uri}")

تولید محتوا

پس از آپلود فایل، می‌توانید درخواست‌های GenerateContent را که به File API URI ارجاع می‌دهند، ارسال کنید. در این مثال، شما درخواستی ایجاد می کنید که با یک متن شروع می شود و پس از آن تصویر آپلود شده است.

# Set the model to Gemini 1.5 Pro.
model = genai.GenerativeModel(model_name="models/gemini-1.5-pro-latest")

response = model.generate_content(["Describe the image with a creative description.", sample_file])

Markdown(">" + response.text)

فایلهاروحذف کن

فایل ها پس از 2 روز به طور خودکار حذف می شوند. همچنین می توانید با استفاده از files.delete() آنها را به صورت دستی حذف کنید.

genai.delete_file(sample_file.name)
print(f'Deleted {sample_file.display_name}.')

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

مدل‌های Gemini از درخواست با چندین فرمت فایل پشتیبانی می‌کنند. این بخش ملاحظات استفاده از فرمت های رسانه ای عمومی را برای درخواست، به ویژه فایل های تصویری، صوتی و تصویری توضیح می دهد. همانطور که در جدول زیر نشان داده شده است، می توانید از فایل های رسانه ای برای درخواست فقط با نسخه های مدل خاص استفاده کنید.

فرمت های تصویر

می‌توانید از داده‌های تصویر برای درخواست با مدل‌های gemini-pro-vision و gemini-1.5-pro استفاده کنید. هنگامی که از تصاویر برای درخواست استفاده می کنید، آنها مشمول محدودیت ها و الزامات زیر هستند:

• تصاویر باید در یکی از انواع داده های تصویری MIME زیر باشند:
  • PNG - تصویر/png
  • JPEG - تصویر/jpeg
  • WEBP - تصویر/وب
  • HEIC - تصویر/هیک
  • HEIF - تصویر / heif
• حداکثر 16 تصویر جداگانه برای gemini-pro-vision و 3600 تصویر برای gemini-1.5-pro
• هیچ محدودیت خاصی برای تعداد پیکسل های یک تصویر وجود ندارد. با این حال، تصاویر بزرگ‌تر برای داشتن حداکثر وضوح 3072 در 3072 در حالی که نسبت تصویر اصلی خود را حفظ می‌کنند، کوچک می‌شوند.

فرمت های صوتی

با مدل gemini-1.5-pro می توانید از داده های صوتی برای درخواست استفاده کنید. هنگامی که از صدا برای درخواست استفاده می کنید، آنها مشمول محدودیت ها و الزامات زیر هستند:

• داده های صوتی در انواع فرمت های صوتی رایج MIME زیر پشتیبانی می شوند:
  • WAV - صدا / موج
  • MP3 - صوتی/mp3
  • AIFF - صوتی/aiff
  • AAC - صوتی/aac
  • OGG Vorbis - صدا/ogg
  • FLAC - صوتی/flac
• حداکثر طول پشتیبانی از داده های صوتی در یک فرمان 9.5 ساعت است.
• فایل های صوتی با وضوح داده 16 کیلوبیت در ثانیه نمونه برداری می شوند و چندین کانال صوتی در یک کانال واحد ترکیب می شوند.
• هیچ محدودیت خاصی برای تعداد فایل‌های صوتی در یک اعلان وجود ندارد، با این حال طول کل کل فایل‌های صوتی در یک فرمان نمی‌تواند از 9.5 ساعت تجاوز کند.

فرمت های ویدیویی

با مدل gemini-1.5-pro می توانید از داده های ویدئویی برای درخواست استفاده کنید. با این حال، فرمت‌های فایل ویدیویی به عنوان ورودی مستقیم توسط Gemini API پشتیبانی نمی‌شوند. می‌توانید از داده‌های ویدیویی به‌عنوان ورودی فوری با تقسیم کردن ویدیو به مجموعه‌ای از تصاویر قاب ثابت و یک فایل صوتی جداگانه استفاده کنید. این روش به شما امکان می دهد با انتخاب تعداد فریم در ثانیه در درخواست شما از فایل ویدیویی، میزان داده و سطح جزئیات ارائه شده توسط ویدیو را مدیریت کنید.

ضمیمه: بارگذاری فایل ها در Colab

این نوت بوک از File API با فایل هایی که از اینترنت دانلود شده اند استفاده می کند. اگر این را در Colab اجرا می کنید و می خواهید از فایل های خود استفاده کنید، ابتدا باید آنها را در نمونه colab آپلود کنید.

ابتدا روی Files در نوار کناری سمت چپ کلیک کنید، سپس روی دکمه آپلود کلیک کنید:

در مرحله بعد، آن فایل را در File API آپلود خواهید کرد. در فرم سلول کد زیر، نام فایلی را که آپلود کرده اید وارد کنید و نام نمایشی مناسبی برای فایل وارد کنید، سپس سلول را اجرا کنید.

my_filename = "gemini_logo.png" # @param {type:"string"}
my_file_display_name = "Gemini Logo" # @param {type:"string"}

my_file = genai.upload_file(path=my_filename,
                            display_name=my_file_display_name)
print(f"Uploaded file '{my_file.display_name}' as: {my_file.uri}")