Gemini API로 비전 기능 살펴보기

ai.google.dev에서 보기 Colab 노트북 사용해 보기 GitHub에서 노트북 보기

Gemini 모델은 이미지와 동영상을 처리할 수 있으므로 이전에는 도메인별 모델이 필요했던 많은 첨단 개발자 사용 사례를 지원할 수 있습니다. Gemini의 비전 기능에는 다음이 포함됩니다.

  • 이미지에 대한 자막 및 질문에 답변
  • 최대 2백만 개의 토큰을 포함하여 PDF를 텍스트로 변환하고 추론
  • 최대 90분 길이의 동영상을 설명, 세그먼트화, 정보 추출
  • 이미지에서 객체를 감지하고 객체의 경계 상자 좌표를 반환합니다.

Gemini는 처음부터 멀티모달 방식으로 빌드되었으며 Google은 계속해서 가능한 한계를 넓혀 나가고 있습니다.

이미지 입력

총 이미지 페이로드 크기가 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로 인코딩된 이미지

공개 이미지 URL을 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를 통해 사용할 수 있는 많은 기능이 포함되지 않습니다.

대용량 이미지 페이로드

전송하려는 파일과 시스템 안내의 조합이 20MB를 초과하는 경우 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

토큰

이미지의 토큰은 다음과 같이 계산됩니다.

  • Gemini 1.0 Pro Vision: 각 이미지는 258개의 토큰을 차지합니다.
  • Gemini 1.5 Flash 및 Gemini 1.5 Pro: 이미지의 크기가 둘 다 384픽셀 이하인 경우 258개의 토큰이 사용됩니다. 이미지의 한 변의 길이가 384픽셀보다 크면 이미지가 타일로 잘립니다. 기본적으로 각 타일 크기는 (너비 또는 높이 중에서) 가장 작은 치수를 1.5로 나눈 값으로 설정됩니다. 필요한 경우 각 타일은 256픽셀보다 작지 않고 768픽셀보다 크지 않도록 조정됩니다. 그런 다음 각 타일의 크기가 768x768로 조정되고 258개의 토큰이 사용됩니다.
  • Gemini 2.0 Flash: 두 측정기준이 모두 384픽셀 이하인 이미지 입력은 258개의 토큰으로 집계됩니다. 한쪽 또는 양쪽 크기가 더 큰 이미지는 필요에 따라 잘리고 크기가 조정되어 768x768픽셀의 타일로 변환되며, 각각 258개의 토큰으로 집계됩니다.

최상의 결과를 얻으려면

  • 업로드하기 전에 이미지를 올바른 방향으로 회전하세요.
  • 흐릿한 이미지는 사용하지 마세요.
  • 단일 이미지를 사용하는 경우 텍스트 프롬프트를 이미지 뒤에 배치합니다.

기능

이 섹션에서는 객체 감지 및 경계 상자 좌표를 비롯한 Gemini 모델의 특정 비전 기능을 간략히 설명합니다.

객체의 경계 상자 가져오기

Gemini 모델은 경계 상자 좌표를 [0, 1] 범위의 상대 너비 또는 높이로 반환하도록 학습됩니다. 그런 다음 이러한 값을 1,000으로 크기 조정하고 정수로 변환합니다. 사실상 좌표는 이미지의 1,000x1,000픽셀 버전에 있는 경계 상자를 나타냅니다. 따라서 경계 상자를 정확하게 매핑하려면 이러한 좌표를 원본 이미지의 크기로 다시 변환해야 합니다.

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] 형식의 경계 상자입니다. 왼쪽 상단이 원점입니다. x 및 y 축은 각각 가로 및 세로로 이동합니다. 좌표 값은 모든 이미지에 대해 0~1,000으로 정규화됩니다.
  • 시각화: AI 스튜디오 사용자에게는 UI 내에 표시된 경계 상자가 표시됩니다.

Python 개발자의 경우 2D 공간 이해 노트북 또는 실험용 3D 포인팅 노트북을 사용해 보세요.

좌표 정규화

모델은 [y_min, x_min, y_max, x_max] 형식의 경계 상자 좌표를 반환합니다. 이러한 정규화된 좌표를 원본 이미지의 픽셀 좌표로 변환하려면 다음 단계를 따르세요.

  1. 각 출력 좌표를 1,000으로 나눕니다.
  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개 토큰입니다. 메타데이터를 사용하면 동영상의 1초가 약 300개의 토큰이 되므로 100만 개의 컨텍스트 창에 1시간 미만의 동영상이 들어갈 수 있습니다.

타임스탬프가 지정된 위치에 관해 질문하려면 MM:SS 형식을 사용하세요. 여기서 처음 두 자리는 분을, 마지막 두 자리는 초를 나타냅니다.

최상의 결과를 얻는 방법

  • 프롬프트당 동영상을 하나만 사용합니다.
  • 동영상을 하나만 사용하는 경우 텍스트 프롬프트를 동영상 뒤에 배치합니다.

File API를 사용하여 동영상 파일 업로드

File API는 동영상 파일 형식을 직접 허용합니다. 이 예에서는 NASA의 짧은 영화 'Jupiter's Great Red Spot Shrinks and Grows'(목성의 대적점 수축 및 확장)를 사용합니다. 저작자: 고다드 우주 비행 센터 (GSFC)/데이비드 래드 (2018)

'Jupiter's Great Red Spot Shrinks and Grows'는 공개 도메인이며 식별 가능한 사람이 표시되지 않습니다. (NASA 이미지 및 미디어 사용 가이드라인)

먼저 Shorts 동영상을 가져옵니다.

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 상태가 되면 해당 동영상의 File API URI를 지정하는 GenerateContent 요청을 실행할 수 있습니다. 생성형 모델을 선택하고 업로드한 동영상과 텍스트 프롬프트를 제공합니다.

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 모델이 부정확하거나 편향되거나 불쾌감을 주는 출력과 같은 예상치 못한 출력을 생성하는 경우가 있습니다. 이러한 출력으로 인한 피해 위험을 제한하려면 후처리 및 사람의 평가가 필수적입니다.