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

Python Node.js Go

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

در Google Colab اجرا کنید

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

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

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

File API ورودی هایی را کنترل می کند که می توانند برای تولید محتوا با model.generateContent یا model.streamGenerateContent استفاده شوند. برای اطلاعات در مورد فرمت های فایل معتبر (انواع MIME) و مدل های پشتیبانی شده، به فرمت های فایل پشتیبانی شده مراجعه کنید.

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

قبل از شروع: پروژه و کلید API خود را تنظیم کنید

قبل از فراخوانی Gemini API (یا File API آن)، باید پروژه خود را تنظیم کرده و کلید API خود را پیکربندی کنید.

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

genai.configure(api_key=GOOGLE_API_KEY)

تشویق با تصاویر

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

یک فایل تصویری آپلود کنید

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

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

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

2. آن فایل را با استفاده از media.upload آپلود کنید تا بتوانید با سایر تماس‌های 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}")
   

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

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

فراداده فایل تصویر را دریافت کنید

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

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

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

با استفاده از فایل تصویری آپلود شده محتوا تولید کنید

پس از آپلود تصویر، می‌توانید درخواست‌های GenerateContent را ارسال کنید که به uri در پاسخ اشاره می‌کند (از آپلود فایل یا دریافت مستقیم فراداده فایل).

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

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

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

Markdown(">" + response.text)

فایل تصویر را حذف کنید

پس از 48 ساعت فایل ها به طور خودکار حذف می شوند. همچنین می توانید با استفاده از files.delete از طریق SDK آنها را به صورت دستی حذف کنید.

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

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

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

یک فایل ویدیویی آپلود کنید

Gemini API فرمت های فایل های ویدئویی را مستقیما می پذیرد. در این نمونه از فیلم کوتاه "Big Buck Bunny" استفاده شده است.

"Big Buck Bunny" (ج) دارای حق چاپ 2008، Blender Foundation / www.bigbuckbunny.org است و تحت مجوز Creative Commons Attribution 3.0 مجوز دارد.

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

1. نمونه فایل ویدئویی را برای آپلود آماده کنید:

   wget https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4
   

2. آن فایل را با استفاده از media.upload آپلود کنید تا بتوانید با سایر تماس‌های API به آن دسترسی داشته باشید:

   video_file_name = "BigBuckBunny_320x180.mp4"
   
   print(f"Uploading file...")
   video_file = genai.upload_file(path=video_file_name)
   print(f"Completed upload: {video_file.uri}")
   

وضعیت آپلود فایل ویدیویی را تأیید کنید

با فراخوانی روش files.get از طریق SDK، بررسی کنید که API با موفقیت فایل ویدیویی را آپلود کرده است.

فایل‌های ویدیویی دارای یک فیلد State از File API هستند. هنگامی که یک ویدیو آپلود می شود، تا زمانی که برای استنباط آماده شود در حالت PROCESSING قرار می گیرد. فقط فایل های ACTIVE را می توان برای استنتاج مدل استفاده کرد.

import time

while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(10)
    video_file = genai.get_file(video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

فراداده فایل ویدیویی را دریافت کنید

با فراخوانی روش files.get از طریق SDK، می‌توانید فراداده فایل ویدیویی آپلود شده را در هر زمانی دریافت کنید.

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

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

با استفاده از فایل ویدئویی آپلود شده محتوا تولید کنید

پس از آپلود ویدیو، می‌توانید درخواست‌های GenerateContent را ارسال کنید که به uri در پاسخ اشاره می‌کند (از آپلود فایل یا دریافت مستقیم فراداده فایل).

قبل از اجرای استنتاج روی ویدیو، مطمئن شوید که وضعیت آپلود فایل ویدیویی (بخش بالا) را تأیید کرده اید.

# Create the prompt.
prompt = "Describe this video."

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

# Make the LLM request.
print("Making LLM inference request...")
response = model.generate_content([video_file, prompt],
                                  request_options={"timeout": 600})
print(response.text)

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

فایل ها پس از 48 ساعت به طور خودکار حذف می شوند. همچنین می توانید با استفاده از files.delete از طریق SDK آنها را به صورت دستی حذف کنید.

genai.delete_file(file_response.name)
print(f'Deleted file {file_response.uri}')

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

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

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

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

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

فرمت های صوتی

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

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

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

می توانید از داده های ویدئویی برای درخواست با مدل های Gemini 1.5 استفاده کنید.

• داده های ویدئویی در انواع فرمت های ویدئویی رایج MIME زیر پشتیبانی می شوند:

  • ویدئو/mp4
  • ویدئو/MPEG
  • ویدئو/فیلم
  • ویدئو/آوی
  • ویدئو/x-flv
  • ویدئو/mpg
  • ویدئو/وب
  • ویدئو/wmv
  • ویدئو/3gpp

• سرویس File API ویدیوها را با سرعت 1 فریم در ثانیه (FPS) در تصاویر نمونه می‌کند و ممکن است برای ارائه بهترین کیفیت استنتاج تغییر کند. تصاویر جداگانه بدون در نظر گرفتن وضوح و کیفیت، 258 توکن را اشغال می کنند.

فرمت های متن ساده

File API از آپلود فایل های متنی ساده با انواع MIME زیر پشتیبانی می کند:

• متن/ساده
• متن/html
• متن/css
• متن/جاوا اسکریپت
• برنامه/x-javascript
• text/x-typescript
• برنامه/x-typescript
• text/csv
• متن / علامت گذاری
• متن/x-python
• برنامه/x-python-code
• application/json
• متن/xml
• برنامه/rtf
• متن/rtf

برای فایل‌های متنی ساده با نوع MIME که در لیست نیستند، می‌توانید یکی از انواع MIME بالا را به صورت دستی تعیین کنید.

ضمیمه: بارگذاری فایل ها در 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}")