探索 Gemini API 的视觉功能

在 ai.google.dev 上查看 试用 Colab 笔记本 在 GitHub 上查看笔记本

Gemini 模型能够处理图片和视频,从而支持许多先进的开发者用例,而这些用例在过去需要使用特定领域的模型。Gemini 的部分视觉功能包括:

  • 为图片添加文字说明并回答有关图片的问题
  • 转写和推理 PDF 文件(最多包含 200 万个令牌)
  • 对时长不超过 90 分钟的视频进行描述、细分和信息提取
  • 检测图片中的对象并返回其边界框坐标

Gemini 从一开始就是作为多模态模型来构建的,我们会不断突破可能的边界。

图片输入

对于小于 20MB 的总图片载荷大小,我们建议上传采用 Base64 编码的图片,或直接上传本地存储的图片文件。

使用本地图片

如果您使用的是 Python Imaging Library (Pillow ),也可以使用 PIL 图片对象。

from google import genai
from google.genai import types

import PIL.Image

image = PIL.Image.open('/path/to/image.png')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=["What is this image?", image])

print(response.text)

Base64 编码的图片

您可以将公开图片网址编码为 Base64 载荷,以便上传。以下代码示例展示了如何仅使用标准库工具执行此操作:

from google import genai
from google.genai import types

import requests

image_path = "https://goo.gle/instrument-img"
image = requests.get(image_path)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What is this image?",
              types.Part.from_bytes(image.content, "image/jpeg")])

print(response.text)

多张图片

如需使用多张图片提示,您可以在对 generate_content 的调用中提供多张图片。这些数据可以采用任何受支持的格式,包括 base64 或 PIL。

from google import genai
from google.genai import types

import pathlib
import PIL.Image

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_url_1 = "https://goo.gle/instrument-img" # Replace with the actual URL to your third image

pil_image = PIL.Image.open(image_path_1)

b64_image = types.Part.from_bytes(
    pathlib.Path(image_path_2).read_bytes(), "image/jpeg")

downloaded_image = requests.get(image_url_1)

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What do these images have in common?",
              pil_image, b64_image, downloaded_image])

print(response.text)

请注意,这些内嵌数据调用不包含通过 File API 提供的许多功能,例如获取文件元数据、列出删除文件

大型图片载荷

如果您打算发送的文件和系统说明的总大小超过 20 MB,请使用 File API 上传这些文件。

使用 File API 的 media.upload 方法上传任何大小的图片。

上传文件后,您可以发出引用 File API URI 的 GenerateContent 请求。选择生成式模型,并为其提供文本提示和上传的图片。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

img_path = "/path/to/Cajun_instruments.jpg"
file_ref = client.files.upload(path=img_path)
print(f'{file_ref=}')

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model="gemini-2.0-flash-exp",
    contents=["What can you tell me about these instruments?",
              file_ref])

print(response.text)

OpenAI 兼容性

您可以使用 OpenAI 库访问 Gemini 的图片理解功能。这样,您就可以通过更新三行代码并使用 Gemini API 密钥,将 Gemini 集成到现有的 OpenAI 工作流中。如需查看演示如何发送编码为 Base64 载荷的图片的代码,请参阅图片理解示例

使用图片提示

在本教程中,您将使用 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

令牌

以下是图片的 token 计算方式:

  • Gemini 1.0 Pro Vision:每张图片占 258 个词元。
  • Gemini 1.5 Flash 和 Gemini 1.5 Pro:如果图片的两个维度均小于或等于 384 像素,则使用 258 个 token。如果图片的某个维度大于 384 像素,则图片会被剪裁成图块。每个图块大小默认为最小维度(宽度或高度)除以 1.5。如有必要,系统会调整每个图块,使其不小于 256 像素且不大于 768 像素。随后系统会将每个图块的大小调整为 768x768,并使用 258 个 token。
  • Gemini 2.0 Flash:如果图片的两个维度均小于或等于 384 像素,则计为 258 个 token。如果图片的一维或二维尺寸较大,系统会根据需要剪裁和缩放图片,使其成为 768x768 像素的图块,每个图块计为 258 个令牌。

为了达到最佳效果

  • 请先将图片旋转到正确方向,然后再上传。
  • 避免使用模糊的图片。
  • 如果使用单张图片,请将文本提示放在图片后面。

功能

本部分概述了 Gemini 模型的具体视觉功能,包括物体检测和边界框坐标。

获取对象的边界框

Gemini 模型经过训练,可将边界框坐标作为介于 [0, 1] 范围内的相对宽度或高度返回。然后,这些值会乘以 1000 并转换为整数。实际上,这些坐标表示 1000 x 1000 像素版本的图片上的边界框。因此,您需要将这些坐标转换回原始图片的尺寸,以准确映射边界框。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

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

response = client.models.generate_content(
  model="gemini-1.5-pro",
  contents=[sample_file_1, prompt])

print(response.text)

您可以使用边界框在图片和视频中进行对象检测和定位。通过使用边界框准确识别和描绘对象,您可以解锁各种应用,并增强项目的智能化程度。

主要优势

  • 简单:无论您是否具备计算机视觉专业知识,都可以轻松将对象检测功能集成到您的应用中。
  • 可自定义:根据自定义说明(例如“我想查看此图片中所有绿色对象的边界框”)生成边界框,而无需训练自定义模型。

技术详情

  • 输入:您的问题和相关图片或视频帧。
  • 输出[y_min, x_min, y_max, x_max] 格式的边界框。左上角是原点。xy 轴分别为水平轴和垂直轴。坐标值会归一化为 0-1000(每个图片)。
  • 可视化:AI Studio 用户会在界面中看到绘制的边界框。

对于 Python 开发者,请试用2D 空间理解笔记本实验性 3D 指向笔记本

归一化坐标

该模型会以 [y_min, x_min, y_max, x_max] 格式返回边界框坐标。如需将这些归一化坐标转换为原始图片的像素坐标,请按以下步骤操作:

  1. 将每个输出坐标除以 1000。
  2. 将 x 坐标乘以原始图片宽度。
  3. 将 y 坐标乘以原始图片高度。

如需探索有关生成边界框坐标并在图片上直观呈现这些坐标的更详细示例,我们建议您查看我们的对象检测食谱示例

使用视频提示

在本教程中,您将使用 File API 上传视频,并根据这些图片生成内容。

技术详情(视频)

Gemini 1.5 Pro 和 Flash 最多支持约 1 小时的视频数据。

视频必须是以下视频格式 MIME 类型之一:

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

File API 服务会以每秒 1 帧 (FPS) 的速度从视频中提取图片帧,并以 1Kbps 的速度提取单声道音频,每秒添加一次时间戳。这些费率未来可能会发生变化,以便改进推理功能。

单个帧为 258 个令牌,音频为每秒 32 个令牌。添加元数据后,每秒视频内容会变成大约 300 个令牌,这意味着 100 万个令牌的上下文窗口只能容纳略低于一小时的视频内容。

如需询问带时间戳的位置,请使用 MM:SS 格式,其中前两位数表示分钟,后两位数表示秒。

为了达到最佳效果,请注意以下事项:

  • 每个提示使用一个视频。
  • 如果使用单个视频,请将文本提示放在视频后面。

使用 File API 上传视频文件

File API 直接接受视频文件格式。此示例使用了 NASA 的短片 “Jupiter's Great Red Spot Shrinks and Grows”。图片来源:戈达德太空飞行中心 (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。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print("Uploading file...")
video_file = client.files.upload(path="GreatRedSpot.mp4")
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(1)
    video_file = client.files.get(name=video_file.name)

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

print('Done')

包含视频和文字的提示

上传的视频处于 ACTIVE 状态后,您可以发出 GenerateContent 请求来指定该视频的 File API URI。选择生成式模型,并为其提供上传的视频和文本提示。

from IPython.display import Markdown

# Pass the video file reference like any other media part.
response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[
        video_file,
        "Summarize this video. Then create a quiz with answer key "
        "based on the information in the video."])

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

提及内容中的时间戳

您可以使用采用 HH:MM:SS 格式的时间戳来引用视频中的特定时刻。

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

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

转写视频并提供视觉描述

Gemini 模型可以同时处理音轨和视频帧,从而为视频内容转写并提供视觉描述。对于视频描述,模型以 1 帧/秒 的速率对视频进行采样。此采样率可能会影响说明的详细程度,对于画面快速变化的视频尤其如此。

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

response = client.models.generate_content(
    model="gemini-1.5-pro",
    contents=[video_file, prompt])

print(response.text)

列出文件

您可以使用 files.list 列出使用 File API 上传的所有文件及其 URI。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

print('My files:')
for f in client.files.list():
  print(" ", f'{f.name}: {f.uri}')

删除文件

使用 File API 上传的文件会在 2 天后自动删除。您也可以使用 files.delete 手动删除它们。

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")

# Upload a file
poem_file = client.files.upload(path="poem.txt")

# Files will auto-delete after a period.
print(poem_file.expiration_time)

# Or they can be deleted explicitly.
dr = client.files.delete(name=poem_file.name)

try:
  client.models.generate_content(
      model="gemini-2.0-flash-exp",
      contents=['Finish this poem:', poem_file])
except genai.errors.ClientError as e:
  print(e.code)  # 403
  print(e.status)  # PERMISSION_DENIED
  print(e.message)  # You do not have permission to access the File .. or it may not exist.

后续步骤

本指南介绍了如何使用 File API 上传图片和视频文件,然后根据图片和视频输入生成文本输出。如需了解详情,请参阅以下资源:

  • 文件提示策略:Gemini API 支持使用文本、图片、音频和视频数据进行提示,也称为多模态提示。
  • 系统指令:借助系统指令,您可以根据自己的特定需求和使用情形来控制模型的行为。
  • 安全指南:生成式 AI 模型有时会生成意外的输出,例如不准确、有偏见或令人反感的输出。后处理和人工评估对于限制此类输出造成伤害的风险至关重要。