使用媒體檔案提示

Python Node.js Go

前往 ai.google.dev 查看

在 Google Colab 中執行

前往 GitHub 查看原始碼

Gemini API 支援透過文字、圖片、音訊和影片資料建立提示，這項功能也稱為「多模態」提示。也就是說，您可以在提示中加入這些類型的媒體檔案。若是小型檔案，可以在提供提示時 將 Gemini 模型直接指向本機檔案先使用 File API 上傳較大的檔案，再將檔案加入提示中。

File API 可讓您為每個專案儲存多達 20 GB 的檔案，且每個檔案的大小不超過 2GB。檔案會保留 48 小時，且可在這段時間內用 API 金鑰存取，但無法透過 API 下載。在可使用 Gemini API 的所有區域，皆可免費使用 Files API。

File API 會處理可用來產生 model.generateContent 或 model.streamGenerateContent 內容的輸入。如要瞭解有效的檔案格式 (MIME 類型) 和支援的模型，請參閱「支援的檔案格式」一節。

本指南將說明如何使用 File API 上傳媒體檔案，並在對 Gemini API 的 GenerateContent 呼叫中加入媒體檔案。詳情請參閱程式碼範例。

事前準備：設定專案和 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 或資料庫。

取得圖片檔的中繼資料

上傳檔案後，您可以透過 SDK 呼叫 files.get，驗證 API 是否成功儲存檔案並取得其中繼資料。

透過這個方法，您可以針對連結至 API 金鑰的 Google Cloud 專案，取得相關上傳檔案的中繼資料。只有 name (再加上 uri) 是唯一的。只有在您自行管理檔案時，才使用 display_name 來識別檔案。

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

使用上傳的圖片檔產生內容

上傳圖片後，您可以提出參照 uri 的 GenerateContent 要求 (透過上傳檔案或直接取得檔案中繼資料)。

在這個範例中，您要建立以文字開頭的提示，後面接已上傳檔案的 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 小時後自動刪除檔案。您也可以透過 SDK 使用 files.delete 手動刪除。

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，並已取得創用 CC 姓名標示 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}")
   

確認影片檔案的上傳狀態

透過 SDK 呼叫 files.get 方法，確認 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)

取得影片檔案的中繼資料

您隨時可以透過 SDK 呼叫 files.get 方法，取得已上傳影片檔案的中繼資料。

透過這個方法，您可以針對連結至 API 金鑰的 Google Cloud 專案，取得相關上傳檔案的中繼資料。只有 name (再加上 uri) 是唯一的。只有在您自行管理檔案時，才使用 display_name 來識別檔案。

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

使用上傳的影片檔案產生內容

上傳影片後，您可以提出參照 uri 的 GenerateContent 要求 (透過上傳檔案或直接取得檔案中繼資料)。

請務必先驗證影片檔案的上傳狀態 (上節說明)，再開始對影片進行推論。

# 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 小時後自動刪除檔案。您也可以透過 SDK 使用 files.delete 手動刪除。

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 - 圖片/堆積
  • HEIF - 圖片/heif
• Gemini 1.5 模型最多可以有 3600 張圖片。
• 圖片中的像素數量沒有特別限制，不過系統會將較大的圖片縮小，以符合 3072 x 3072 的最大解析度，同時保留圖片的原始長寬比。

音訊格式

您可以在 Gemini 1.5 模型下，使用音訊資料建立提示。您在提示中使用音訊時，必須遵守下列限制和規定：

• 下列常見的音訊格式 MIME 類型支援音訊資料：
  • WAV - 音訊/WAV
  • MP3 - 音訊/mp3
  • AIFF - 音訊/AI
  • AAC - 音訊/AAC
  • OGG Vorbis - 音訊/ogg
  • FLAC - 音訊/flac
• 單一提示支援的音訊資料長度上限為 9.5 小時。
• 音訊檔案會重新取樣為 16 Kbps 的資料解析度，並將多個音訊聲道合併為單一聲道。
• 單一提示中的音訊檔案數量並無特別限制；不過，單一提示中所有音訊檔案的總長度不能超過 9.5 小時。

影片格式

您可以使用影片資料，在 Gemini 1.5 模型生成提示。

• 下列常見的影片格式 MIME 類型支援影片資料：

  • 影片/mp4
  • 影片/mpeg
  • 影片/移動
  • 影片/avi
  • video/x-flv
  • 影片/mpg
  • 影片/Webm
  • 影片/每週
  • 影片/3gpp

• File API 服務是以每秒 1 個影格 (FPS) 的速度將影片取樣為圖片，為提供最佳推論品質，隨時可能變更。無論解析度和品質為何，個別映像檔都會包含 258 個符記。

純文字格式

File API 支援上傳下列 MIME 類型的純文字檔案：

• 文字/plain
• text/html
• text/css
• text/javascript
• application/x-javascript
• 文字/x-typescript
• 應用程式/x-typescript
• 文字/csv
• 文字/markdown
• 文字/x-python
• application/x-python-code
• application/json
• text/xml
• 應用程式/rtf
• 文字/rtf

針對清單未列出 MIME 類型的純文字檔案，您可以嘗試手動指定上述其中一種 MIME 類型。

附錄：將檔案上傳至 Colab

此筆記本使用 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}")