הנחיות עם קובצי מדיה

Python Node.js Go

להצגה ב-ai.google.dev

הפעלה ב-Google Colab

הצגת המקור ב-GitHub

ב-Gemini API יש תמיכה בהנחיות באמצעות נתונים של טקסט, תמונה, אודיו ווידאו, שנקראים גם הנחיות ריבוי מודלים, כלומר אפשר לכלול את סוגי קובצי המדיה האלה בהנחיות. בקבצים קטנים, אפשר להפנות את המודל של Gemini ישירות לקובץ מקומי כשמזינים הנחיה. מעלים קבצים גדולים יותר באמצעות File API לפני שכוללים אותם בהודעות.

באמצעות File API אפשר לאחסן עד 20GB של קבצים לכל פרויקט, והגודל של כל קובץ לא חורג מ-2GB. הקבצים מאוחסנים למשך 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" הוא (c) זכויות יוצרים 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}")
   

אימות מצב ההעלאה של קובץ הסרטון

מוודאים שה-API העלה את קובץ הסרטון בהצלחה. לשם כך, מפעילים את השיטה files.get דרך ה-SDK.

קובצי וידאו כוללים שדה 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)

הצגת המטא-נתונים של קובץ הסרטון

אפשר לקבל את המטא-נתונים של קובץ הסרטון שהועלה בכל שלב באמצעות קריאה ל-method 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 - תמונה/webp
  • HEIC - תמונה/heic
  • HEIF – תמונה/heif
• עד 3,600 תמונות במודלים של Gemini 1.5.
• אין מגבלות ספציפיות על מספר הפיקסלים בתמונה. עם זאת, תמונות גדולות יותר מוקטנות כדי להתאים לרזולוציה מקסימלית של 3,072x3,072 תוך שמירה על יחס הגובה-רוחב המקורי.

פורמטים של אודיו

במודלים של Gemini 1.5, אתם יכולים להשתמש בנתוני אודיו ליצירת הנחיות. כשמשתמשים באודיו להנחיות, הם כפופים למגבלות ולדרישות הבאות:

• נתוני האודיו נתמכים בסוגי ה-MIME הנפוצים הבאים:
  • WAV – אודיו/WAV
  • MP3 - אודיו/mp3
  • AIFF - אודיו/aiff
  • AAC – אודיו/aac
  • OGG Vorbis – אודיו/ogg
  • FLAC – אודיו/flac
• האורך המקסימלי הנתמך של נתוני אודיו בהנחיה יחידה הוא 9.5 שעות.
• קובצי האודיו נדגמים מחדש ברזולוציית נתונים של 16 Kbps, ומספר ערוצי אודיו משולבים בערוץ אחד.
• אין מגבלה ספציפית על מספר קובצי האודיו בהנחיה אחת, אבל האורך הכולל של כל קובצי האודיו בהנחיה אחת לא יכול לחרוג מ-9.5 שעות.

פורמטים של סרטונים

במודלים של Gemini 1.5, אתם יכולים להשתמש בנתונים של סרטונים כדי ליצור הנחיות.

• נתוני וידאו נתמכים בסוגי ה-MIME הנפוצים הבאים של וידאו:

  • video/mp4
  • וידאו/mpeg
  • וידאו/mov
  • וידאו/avi
  • video/x-flv
  • וידאו/mpg
  • וידאו/אינטרנט
  • סרטון/wmv
  • וידאו/3gpp

• שירות File API דוגם סרטונים לתמונות בקצב של פריים אחד לשנייה (FPS), ועשוי להשתנות כדי לספק את איכות ההסקה הטובה ביותר. תמונות בודדות משתמשות ב-258 אסימונים ללא קשר לרזולוציה ולאיכות.

פורמטים של טקסט פשוט

ה-File API תומך בהעלאה של קובצי טקסט פשוט עם סוגי ה-MIME הבאים:

• טקסט/פשוט
• text/html
• text/css
• text/javascript
• application/x-javascript
• טקסט/x-typescript
• application/x-typescript
• טקסט/csv
• טקסט/סימון
• טקסט/x-python
• application/x-python-code
• application/json
• text/xml
• אפליקציה/rtf
• טקסט/rtf

כשמדובר בקובצי טקסט פשוט שסוג MIME לא מופיע ברשימה, אתם יכולים לנסות לציין באופן ידני את אחד מסוגי ה-MIME שלמעלה.

נספח: העלאת קבצים ל-Colab

ה-notebook הזה משתמש ב-File API עם קבצים שהורדו מהאינטרנט. אם מריצים את הקוד ב-Colab ורוצים להשתמש בקבצים משלך, צריך קודם להעלות אותם למכונה של Colab.

קודם לוחצים על קבצים בסרגל הצד השמאלי ואז לוחצים על הלחצן העלאה:

לאחר מכן מעלים את הקובץ ל-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}")