運用 Gemini API 探索視覺功能

在 ai.google.dev 上查看 試用 Colab 筆記本 在 GitHub 中查看筆記本

Gemini API 可處理圖片和影片，讓開發人員有更多精彩的用途。Gemini 的視覺功能包括：

  • 為圖片加上說明文字，並回答圖片相關問題
  • 轉錄和分析 PDF，包括長文件 (脈絡窗口最多可達 200 萬個符號)
  • 描述、區隔及擷取影片資訊，包括影像影格和音訊，長度最長 90 分鐘
  • 偵測圖片中的物件，並傳回物件的定界框座標

本教學課程將示範幾種可能的方式，透過圖片和影片輸入內容提示 Gemini API，並提供程式碼範例，以及使用多模態視覺功能提示最佳做法的概略說明。所有輸出內容皆為文字。

事前準備：設定專案和 API 金鑰

在呼叫 Gemini API 之前，您必須設定專案並設定 API 金鑰。

使用圖片提示

在本教學課程中，您將使用 File API 上傳圖片，或將圖片做為內嵌資料，並根據這些圖片產生內容。

技術詳細資料 (圖片)

Gemini 1.5 Pro 和 1.5 Flash 最多可支援 3,600 個圖片檔案。

圖片必須採用下列圖片資料 MIME 類型：

  • PNG - image/png
  • JPEG - image/jpeg
  • WEBP - image/webp
  • HEIC - image/heic
  • HEIF - image/heif

每張圖片相當於 258 個符記。

除了模型的內容視窗之外，圖片中的像素數量並無特定限制，較大的圖片會縮小至最大解析度 3072x3072，同時保留原始的顯示比例，而較小的圖片則會放大至 768x768 像素。除了頻寬，較小圖片的成本不會降低，較高解析度的圖片也不會提升效能。

為確保最佳成效：

  • 請先將圖片旋轉至正確方向，再上傳。
  • 請避免使用模糊的圖片。
  • 如果使用單張圖片，請將文字提示放在圖片後方。

圖片輸入

如果圖片酬載總大小小於 20 MB，建議您上傳 Base64 編碼的圖片，或直接上傳儲存在本機的圖片檔案。

Base64 編碼圖片

您可以將公開圖片網址編碼為 Base64 酬載，然後上傳。建議您使用 httpx 程式庫擷取圖片網址。以下程式碼範例說明如何執行這項操作：

import httpx
import os
import base64

model = genai.GenerativeModel(model_name = "gemini-1.5-pro")
image_path = "https://upload.wikimedia.org/wikipedia/commons/thumb/8/87/Palace_of_Westminster_from_the_dome_on_Methodist_Central_Hall.jpg/2560px-Palace_of_Westminster_from_the_dome_on_Methodist_Central_Hall.jpg"

image = httpx.get(image_path)

prompt = "Caption this image."
response = model.generate_content([{'mime_type':'image/jpeg', 'data': base64.b64encode(image.content).decode('utf-8')}, prompt])

print(response.text)

多張圖片

如要以 Base64 編碼格式提示多張圖片，請執行下列操作：

import httpx
import os
import base64

model = genai.GenerativeModel(model_name = "gemini-1.5-pro")
image_path_1 = "path/to/your/image1.jpeg"  # Replace with the actual path to your first image
image_path_2 = "path/to/your/image2.jpeg" # Replace with the actual path to your second image

image_1 = httpx.get(image_path_1)
image_2 = httpx.get(image_path_2)

prompt = "Generate a list of all the objects contained in both images."

response = model.generate_content([
{'mime_type':'image/jpeg', 'data': base64.b64encode(image_1.content).decode('utf-8')},
{'mime_type':'image/jpeg', 'data': base64.b64encode(image_2.content).decode('utf-8')}, prompt])

print(response.text)

上傳一或多個儲存在本機的圖片檔案

或者，您也可以上傳一或多個本機儲存的圖片檔案。

import PIL.Image
import os
import google.generativeai as genai

image_path_1 = "path/to/your/image1.jpeg"  # Replace with the actual path to your first image
image_path_2 = "path/to/your/image2.jpeg" # Replace with the actual path to your second image

sample_file_1 = PIL.Image.open(image_path_1)
sample_file_2 = PIL.Image.open(image_path_2)

#Choose a Gemini model.
model = genai.GenerativeModel(model_name="gemini-1.5-pro")

prompt = "Write an advertising jingle based on the items in both images."

response = model.generate_content([prompt, sample_file_1, sample_file_2])

print(response.text)

請注意，這些內嵌資料呼叫不包含透過 File API 提供的許多功能，例如取得檔案中繼資料、列出或刪除檔案。

大型圖片酬載

如果您要傳送的檔案和系統指示總大小超過 20 MB，請使用 File API 上傳這些檔案。

使用 File API 的 media.upload 方法，上傳任何大小的圖片。

上傳檔案後，您可以提出參照 File API URI 的 GenerateContent 要求。選取生成式模型，並提供文字提示和上傳的圖片。

import google.generativeai as genai

myfile = genai.upload_file(media / "Cajun_instruments.jpg")
print(f"{myfile=}")

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content(
    [myfile, "\n\n", "Can you tell me about the instruments in this photo?"]
)
print(f"{result.text=}")
files.py

OpenAI 相容性

您可以使用 OpenAI 程式庫存取 Gemini 的圖像理解功能。這樣一來，您就能透過更新三行程式碼並使用 Gemini API 金鑰，將 Gemini 整合至現有的 OpenAI 工作流程。請參閱圖像理解範例，瞭解如何傳送以 Base64 酬載編碼的圖片。

功能

本節將概略說明 Gemini 模型的特定視覺功能，包括物件偵測和定界框座標。

取得物件的邊界框

經過訓練的 Gemini 模型會將定界框座標以 [0, 1] 範圍內的相對寬度或高度傳回。然後，這些值會以 1000 的比例縮放，並轉換為整數。實際上，座標代表圖片 1000 x 1000 像素版本上的邊界框。因此，您需要將這些座標轉換回原始圖片的尺寸，才能準確對應定界框。

# Choose a Gemini model.
model = genai.GenerativeModel(model_name="gemini-1.5-pro")

prompt = "Return a bounding box for each of the objects in this image in [ymin, xmin, ymax, xmax] format."
response = model.generate_content([sample_file_1, prompt])

print(response.text)

模型會以 [ymin, xmin, ymax, xmax] 格式傳回定界框座標。如要將這些標準化座標轉換為原始圖片的像素座標，請按照下列步驟操作：

  1. 將每個輸出座標除以 1000。
  2. 將 x 座標乘以原始圖片寬度。
  3. 將 y 座標乘以原始圖片高度。

如要進一步瞭解如何產生邊界框座標並在圖片上顯示，建議您參閱物件檢測食譜範例。

使用影片提示

在本教學課程中，您將使用 File API 上傳影片，並根據這些圖片產生內容。

技術詳細資料 (影片)

Gemini 1.5 Pro 和 Flash 最多可支援約一小時的影片資料。

影片必須採用下列任一影片格式 MIME 類型：

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

File API 服務會以每秒 1 格 (FPS) 的速度從影片中擷取圖像影格，並以 1 Kbps 的速度擷取單一頻道的音訊，每秒新增時間戳記。這些費率日後可能會因推論功能的改善而有所變動。

個別影格為 258 個符記，音訊則為每秒 32 個符記。使用中繼資料後，每秒影片會變成約 300 個符記，也就是說，100 萬個脈絡窗口最多可容納略低於一小時的影片。

如要詢問有關時間戳記位置的問題，請使用 MM:SS 格式，其中前兩位數字代表分鐘，後兩位數字代表秒數。

為確保最佳成效：

  • 每個提示使用一支影片。
  • 如果使用單一影片，請將文字提示放在影片後方。

使用 File API 上傳影片檔案

File API 可直接接受影片檔案格式。本範例使用 NASA 的短片「Jupiter's Great Red Spot Shrinks and Grows」。圖片來源：Goddard Space Flight Center (GSFC)/David Ladd (2018)。

「Jupiter's Great Red Spot Shrinks and Grows」屬於公有領域，且沒有可識別的人物。(NASA 圖片和媒體使用規範)

首先擷取短片：

wget https://storage.googleapis.com/generativeai-downloads/images/GreatRedSpot.mp4

使用 File API 上傳影片，並列印 URI。

# Upload the video and print a confirmation.
video_file_name = "GreatRedSpot.mp4"

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

驗證檔案上傳作業並檢查狀態

呼叫 files.get 方法，確認 API 已成功接收檔案。

import time

# Check whether the file is ready to be used.
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)

含有影片和文字的提示

上傳的影片處於 ACTIVE 狀態後，您可以發出 GenerateContent 要求，指定該影片的 File API URI。選取生成模型，並提供上傳的影片和文字提示。

# Create the prompt.
prompt = "Summarize this video. Then create a quiz with answer key based on the information in the video."

# Choose a Gemini model.
model = genai.GenerativeModel(model_name="gemini-1.5-pro")

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

# Print the response, rendering any Markdown
Markdown(response.text)

參考內容中的時間戳記

您可以使用 HH:MM:SS 格式的時間戳記，參照影片中的特定片段。

# Create the prompt.
prompt = "What are the examples given at 01:05 and 01:19 supposed to show us?"

# Choose a Gemini model.
model = genai.GenerativeModel(model_name="gemini-1.5-pro")

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

轉錄影片並提供視覺說明

Gemini 模型可同時處理音軌和影像影格，並為影片內容轉錄並提供視覺說明。針對視覺說明，模型會以每秒 1 格的速度取樣影片。這項取樣率可能會影響說明的細節程度，特別是針對視覺效果快速變化的影片。

# Create the prompt.
prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

# Choose a Gemini model.
model = genai.GenerativeModel(model_name="gemini-1.5-pro")

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

可列出檔案

您可以使用 files.list 列出所有使用 File API 上傳的檔案，以及這些檔案的 URI。

import google.generativeai as genai

print("My files:")
for f in genai.list_files():
    print("  ", f.name)
files.py

刪除檔案

使用 File API 上傳的檔案會在 2 天後自動刪除。您也可以使用 files.delete 手動刪除這些資料。

import google.generativeai as genai

myfile = genai.upload_file(media / "poem.txt")

myfile.delete()

try:
    # Error.
    model = genai.GenerativeModel("gemini-1.5-flash")
    result = model.generate_content([myfile, "Describe this file."])
except google.api_core.exceptions.PermissionDenied:
    pass
files.py

後續步驟

本指南說明如何使用 File API 上傳圖片和影片檔案，然後根據圖片和影片輸入內容產生文字輸出內容。如要進一步瞭解相關內容，請參閱下列資源：

  • 檔案提示策略：Gemini API 支援使用文字、圖片、音訊和影片資料提示，這也稱為多模態提示。
  • 系統指示：系統指示可讓您根據特定需求和用途，引導模型的行為。
  • 安全指南：生成式 AI 模型有時會產生非預期的輸出內容，例如不準確、偏頗或令人反感的輸出內容。後續處理和人工評估是限制這類輸出內容造成危害風險的必要措施。