Skip to main content

Google GenAI SDK: Python 튜토리얼과 함께하는 가이드

Google의 GenAI SDK는 최신 Gemini 모델을 사용해 텍스트, 이미지, 비디오 처리 등 고급 생성형 AI 기능을 애플리케이션에 매끄럽게 통합할 수 있도록, 개발자에게 통합되고 유연한 툴킷을 제공합니다. 이 글은 AI 번역본입니다. 오역이 있을 수 있으니 댓글로 알려 주세요.
Created on September 12|Last edited on September 12
Google의 GenAI SDK는 개발자가 자체 애플리케이션에 생성형 AI 기능을 더 쉽게 도입할 수 있도록 돕습니다. 웹, 모바일, 백엔드 어디를 대상으로 개발하든, 이 SDK를 통해 텍스트 생성, 요약, 이미지 이해 등 작업에 필요한 Google의 Gemini 모델에 직접 접근할 수 있습니다. 이제 외부 도구나 API에 의존하지 않고, 개발 환경 안에서 Google의 모델을 바로 활용할 수 있습니다.
이 글에서는 SDK 설정 방법, LLM으로 추론을 실행하는 방법, 그리고 개발과 운영 단계에서 W&B Weave를 사용해 모델 성능을 추적하는 방법을 다룹니다.


목차



Gemini API와 Google GenAI SDK 이해하기

새로운 Google GenAI SDK는 이전 버전에 비해 상당한 이점을 제공하며, 특히 Gemini Developer API와 Vertex AI 전반에서 매끄럽게 동작하는 통합 인터페이스를 제공한다는 점이 돋보입니다. 이러한 아키텍처적 개선으로 개발자는 Developer API로 애플리케이션을 프로토타이핑한 뒤, 대규모 코드 수정 없이 Vertex AI로 원활하게 마이그레이션할 수 있습니다. 이 SDK의 설계 철학은 개발자 생산성과 배포 유연성을 ���시하며, 서로 다른 Google AI 서비스를 전환할 때 대규모 코드 변경이 필요했던 이전 SDK의 공통적인 불편을 해소하는 데 초점을 맞추고 있습니다.
Vertex AI Gemini API와 Gemini Developer API 사이의 핵심 차이점을 보여 주는 유용한 표를 찾았습니다. 요약하면, Gemini AI는 단기 생산성과 빠른 프로토타이핑을 위한 것이고, Vertex AI는 프로덕션 등급의 엔터프라이즈 규모 AI 솔루션을 위해 설계되었습니다.

또한 GenAI SDK는 Python, Go, Node.js, Java를 포함한 여러 프로그래밍 언어를 지원하여, 개발 팀이 선호하는 기술 스택 내에서 작업할 수 있도록 보장합니다. 이러한 다중 언어 지원은 플랫폼 전반에서 일관된 API 패턴과 결합되어, Google의 AI 생태계 내 다양한 구성 요소 간을 오가며 작업하는 개발자의 학습 부담을 크게 줄여 줍니다. 아울러 이 SDK는 포괄적인 오류 처리, 스트리밍 기능, 견고한 인증 메커니즘 등 현대적 개발 모범 사례를 반영하여 기존 애플리케이션에 손쉽게 통합할 수 있도록 합니다.
현재 개발자에게는 Google GenAI SDK로 마이그레이션할 것을 권장합니다. 이는 Google의 AI 개발 도구가 나아가는 미래 방향을 대표하기 때문입니다. 이전 google-generativeai 해당 패키지는 여전히 동작하지만, 새로운 통합 SDK로 대체되고 있습니다 (google-genai)로, 향상된 기능, 더 나은 성능, 그리고 확장되는 Google의 AI 모델 생태계를 보다 폭넓게 지원합니다. 이러한 전환은 급변하는 생성형 AI 기술 환경에 신속히 적응할 수 있는 최첨단 도구를 개발자에게 제공하겠다는 Google의 의지를 반영합니다.

Gemini API 키 받기

Gemini API에 접근하려면 Google의 생성형 AI 서비스에 대한 기본 인증 수단인 Gemini API 키가 필요합니다. 이 키는 요청을 승인하는 데 필수이며, 텍스트 생성부터 고급 멀티모달 처리까지의 기능에 접근할 수 있게 해줍니다. 이 키는 다음을 통해 받을 수 있습니다 Google AI Studio Google 계정으로 로그인한 뒤 초기 비용 없이 API 키를 생성하면 됩니다.

Gemini API 키를 받았다면 GenAI Python SDK를 사용하기 전에 개발 환경에 해당 키를 설정하세요. 이 SDK는 키를 직접 전달하기, 환경 변수를 설정하기, 구성 파일을 사용하는 등 여러 가지 구성 방법을 지원합니다.

Google GenAI SDK 설치 및 사용

시스템에 Google GenAI SDK를 설치하려면 다음 명령을 실행하세요:
pip install google-genai
이 튜토리얼에서는 Weave도 사용합니다. 다음 명령으로 설치하세요:
pip install weave

Gemini Developer API 구성

이제 Gemini 모델과 상호작용하는 데 사용하는 기본 인터페이스인 클라이언트 객체를 생성하는 방법을 보여드리겠습니다. The genai.Client 이 객체는 구성에 따라 인증을 처리하고 Gemini API 또는 Vertex AI 백엔드와의 통신을 담당합니다. 이 객체를 생성하는 방법은 다음과 같습니다.

옵션 1: 코드에서 API 키를 직접 전달하기

from google import genai
client = genai.Client(api_key='YOUR_GEMINI_API_KEY')

옵션 2: 환경 변수 사용

애플리케이션을 실행하기 전에 터미널이나 명령 프롬프트에서 필요한 환경 변수를 설정할 수 있습니다.
export GOOGLE_API_KEY='your-api-key'
또는 Python 스크립트 시작 부분에서 프로그램적으로 환경 변수를 설정하세요:
import os
os.environ['GOOGLE_API_KEY'] = 'your-api-key'
from google import genai
client = genai.Client()

Vertex AI를 통한 Gemini API 구성

백엔드로 Vertex AI를 사용하려면 로컬 시스템에 gcloud CLI를 설정해야 합니다. 시작하는 방법은 다음과 같습니다:

1단계: Google Cloud 프로젝트 만들기

먼저 새 프로젝트를 만들고 Google Cloud 콘솔프로젝트 선택기 페이지로 이동하여 기존 프로젝트를 선택하거나 새 프로젝트를 만드세요. Vertex AI 서비스를 사용하려면 프로젝트에 결제가 활성화되어 있어야 합니다. 아직 프로젝트를 만들지 않았다면 Google Cloud 검색창에서 ‘create project’를 검색한 뒤, 처음 나타나는 결과를 클릭하면 프로젝트 생성 절차로 쉽게 이동할 수 있습니다.



2단계: Vertex AI API 활성화

다음으로 프로젝트에서 Vertex AI API를 활성화하세요. Google Cloud 콘솔의 검색창에 “Vertex AI”를 입력합니다. 검색 결과에서 Vertex AI를 선택하면 Vertex AI 대시보드로 이동합니다. “모든 권장 API 활성화” Vertex AI에 필요한 API를 활성화합니다. 이 과정은 완료까지 잠시 시간이 걸릴 수 있습니다.



3단계: Google Cloud CLI 설정

로컬 개발 환경에서 Google Cloud 서비스와 상호작용하려면 gcloud CLI를 설치해야 합니다. Google Cloud 문서에서 CLI를 다운로드하여 설치하세요. 설치가 완료되면 다음 명령으로 CLI를 초기화하세요 gcloud init 터미널에서 실행하세요. 이 명령은 프로젝트 선택과 설정 구성을 단계별로 안내합니다.
다음 명령을 실행하여 최신 도구와 기능을 사용하도록 CLI 구성 요소를 업데이트할 수 있습니다:
gcloud components update
gcloud components install beta

4단계: IAM 역할 구성

관리자는 적절한 IAM 역할이 할당되었는지 확인해야 합니다. 이러한 역할에는 다음이 포함됩니다:
  • Vertex AI 사용자 또는 Vertex AI 관리자, 및
  • 서비스 계정 사용자
사용자의 구체적인 요구 사항과 Vertex AI 사용 목적에 따라 달라질 수 있지만, 이 튜토리얼에서는 Vertex AI 관리자와 서비스 계정 사용자 권한을 권장합니다.
이를 위해 Google Cloud 검색창에서 “IAM”을 검색하면, 다음을 수행할 수 있습니다

그다음 사용자 계정 옆에 있는 편집 버튼을 선택합니다. 버튼은 다음과 같은 모양입니다:

그리고 적절한 역할을 할당합니다:


Vertex AI로 클라이언트 생성하기

Vertex AI를 통해 Gemini에 액세스하는 경우, 다음 세 가지 환경 변수를 설정해야 합니다:
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='us-central1'
또는 클라이언트를 초기화하기 전에 Python에서 프로그래밍 방식으로 설정합니다:
import os
from google import genai

os.environ['GOOGLE_GENAI_USE_VERTEXAI'] = 'true'
os.environ['GOOGLE_CLOUD_PROJECT'] = 'your-project-id'
os.environ['GOOGLE_CLOUD_LOCATION'] = 'us-central1'

client = genai.Client()
이제 두 백엔드의 기본 설정을 마쳤으니, Gemini 모델로 추론을 실행할 수 있는 코드를 작성해 봅시다!

첫 번째 요청 보내기

환경과 클라이언트를 설정한 뒤에는 추론이라고 불리는 과정을 통해 Gemini에게 응답 생성을 요청할 수 있습니다. 이는 프롬프트를 모델에 보내고, 선택적으로 이미지를 함께 전달한 다음, 생성된 응답을 받는 방식으로 이루어집니다. Gemini는 텍스트 전용과 멀티모달 상호작용을 모두 지원하므로, 상세한 장면 설명과 같은 작업을 위해 이미지가 포함된 프롬프트도 처리할 수 있습니다.
추론을 실행할 수 있는 코드 예시는 다음과 같습니다:
import requests
from io import BytesIO
from typing import Optional, Union
from PIL import Image
from google import genai
from google.genai import types

import weave; weave.init("google_genai")

@weave.op
def gemini_infer(
prompt: str,
api_key: str,
image: Image = None,
model: str = "gemini-2.0-flash-001"
) -> str:
"""
Run Gemini inference with an optional PIL image.

:param prompt: The user prompt/question/command
:param api_key: Your Gemini API key
:param image: An optional PIL Image object
:param model: Model string (default: "gemini-2.0-flash-001")
:return: Model's text response
"""
client = genai.Client(api_key=api_key) # <-- Replace with your key
# Assemble contents
if image is not None:
# Save image to buffer as JPEG
buf = BytesIO()
image.save(buf, format="JPEG")
image_bytes = buf.getvalue()
contents = [
types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
prompt,
]
else:
contents = [prompt]
# Run inference
response = client.models.generate_content(
model=model,
contents=contents,
)
return response.text

# ---- Example usage ----

if __name__ == "__main__":
API_KEY = " " # <-- put your key here
# Download example image to PIL
img_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Fronalpstock_big.jpg/800px-Fronalpstock_big.jpg"
headers = {"User-Agent": "Mozilla/5.0 (compatible; GeminiScript/1.0)"}
response = requests.get(img_url, headers=headers)
response.raise_for_status()
pil_img = Image.open(BytesIO(response.content))

# With image
r1 = gemini_infer(
prompt="Describe this alpine scenery in detail.",
api_key=API_KEY,
image=pil_img,
)
print("\nGemini vision response:")
print(r1)

# Text-only
r2 = gemini_infer(
prompt="Write a haiku about mountains.",
api_key=API_KEY
)
print("\nGemini text-only response:")
print(r2)

추론 환경을 갖추었다면, 다양한 프롬프트와 이미지를 손쉽게 실험해 볼 수 있습니다. 모델은 요청에 맞춘 응답을 반환하며, 창의적 작업과 분석적 작업 모두에서 Gemini의 유연성을 보여 줍니다. 이 과정이 프로젝트에 Gemini 기반 기능을 통합하는 핵심이 됩니다.
스크립트를 실행한 뒤 W&B Weave로 이동하면 모델의 모든 입력과 출력을 확인할 수 있습니다! 아래는 Weave 내부 화면 예시입니다:

Weave는 각 LLM 호출별 비용과 호출 지연 시간 같은 추가 정보도 보여 줍니다. LLM 애플리케이션을 구축한다면, 모델의 동작 데이터를 저장하는 일종의 “트레이싱” 프레임워크를 활용하는 것이 매우 중요합니다. 이렇게 하면 직관에만 의존하지 않고 실제 사용 패턴과 모델 출력 품질을 기반으로 데이터를 분석하고 시스템을 개선할 수 있습니다. 견고한 트레이싱 프레임워크를 도입하면 이상 동작을 보이는 프롬프트나 입력 데이터를 디버깅하기가 쉬워지고, 애플리케이션을 반복 개선하면서 성능 향상을 추적할 수 있으며, 사용자나 이해관계자에게 시스템 동작을 설명해야 할 때 투명성을 제공할 수 있습니다.

Veo 2로 동영상 생성하기

Gemini API를 사용하면 Veo 2에도 접근해 동영상을 생성할 수 있습니다! 아래 스크립트로 동영상을 생성하고 Weave에 기록할 수도 있습니다! 다음을 사용하면 됩니다 moviepy 해당 형식을 사용하면 동영상이 자동으로 Weave에 기록됩니다!
import time
import weave
import moviepy.editor as mpy
from google import genai
from google.genai import types


API_KEY = "your_api_key" # <-- your Gemini key
weave.init("gemini-genai")


@weave.op
def gemini_generate_video(prompt: str, api_key: str, fname: str = "video0.mp4") -> mpy.VideoFileClip:
client = genai.Client(api_key=api_key)
op = client.models.generate_videos(
model="veo-2.0-generate-001",
prompt=prompt,
config=types.GenerateVideosConfig(
person_generation="dont_allow",
aspect_ratio="16:9",
),
)
while not op.done:
time.sleep(10)
op = client.operations.get(op)

vid = op.response.generated_videos[0]
client.files.download(file=vid.video)
vid.video.save(fname)
return mpy.VideoFileClip(fname)

# --- Example usage ---

clip = gemini_generate_video("rotating red cube in front of stars", API_KEY)

프로세스는 API 키로 API에 연결한 뒤 Veo 모델의 generate_videos 메서드에 프롬프트를 보내는 것부터 시작합니다. API는 비동기 작업을 반환하며, 동영상이 준비될 때까지 이 작업의 상태를 주기적으로 폴링합니다. 완료되면 생성된 동영상을 다운로드해 로컬에 저장합니다(예: MP4 파일). Weave를 통합하면 각 동영상 생성 과정을 로깅하고 추적하여 관측성과 실험 관리를 수행할 수 있습니다. 만약 당신이 사용한다면 moviepy 해당 형식을 사용하면 동영상이 자동으로 Weave와 호환되어, 워크플로에서 곧바로 결과를 분석, 공유, 시각화하기가 쉬워집니다.
Weave 내부 화면은 다음과 같습니다:

Weave의 훌륭한 기능 중 하나는 API 키를 자동으로 마스킹해 준다는 점입니다. 따라서 Weave를 사용할 때 실수로 API 키가 유출될 걱정을 하지 않아도 됩니다.

Gemini로 동영상 이해하기

여러 Gemini 모델은 동영상을 이해할 수도 있습니다! 아래 스크립트를 사용하면 Gemini로 추론을 실행하고, 앞서 생성한 동영상의 요약을 얻을 수 있습니다.
from moviepy.editor import VideoFileClip
from google import genai
from google.genai import types
import weave

weave.init("gemini-video-analysis")

API_KEY = "your_api_key" # <- Replace with your key

client = genai.Client(api_key=API_KEY)

# Only for videos of size <20Mb
video_file_name = "./video0.mp4"
video_bytes = open(video_file_name, 'rb').read()

@weave.op
def gemini_summarize_video(video_bytes: bytes, prompt: str, api_key: str):
client = genai.Client(api_key=api_key)
response = client.models.generate_content(
model='models/gemini-2.0-flash',
contents=types.Content(
parts=[
types.Part(
inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
),
types.Part(text=prompt)
]
)
)
return response.text

# Logging and inference via Weave
summary = gemini_summarize_video(video_bytes, "Please summarize the video in 3 sentences.", API_KEY)
print(summary)

짧은 코드 몇 줄이면 동영상을 바로 Gemini에 넣고 자연어로 똑똑한 요약을 받을 수 있습니다. 동영상과 프롬프트만 제공하면, 나머지는 Gemini가 처리합니다. 시각 정보를 분석하고 핵심 내용을 명확하고 간결한 문장으로 정제해 제공합니다.


Google GenAI API에서 “Thinking Mode” 사용하기

Google GenAI API에서 Gemini 2.5 Flash와 Gemini 2.5 Pro의 사고 기능도 사용할 수 있습니다. 접근 권한에 따라 Vertex AI와 일반 API 키 사용을 전환할 수 있으며, 스트리밍 응답 또는 일반(비스트리밍) 응답 중에서 선택할 수 있습니다. 코드는 다음과 같습니다:
import os
from google import genai
from google.genai import types
import weave

# --- CONFIG: Toggle here ---
USE_VERTEX = True # Set to False for Gemini consumer API
STREAMING = True # Set to False for normal responses

PROJECT = "your-google-cloud-project"
LOCATION = "us-central1"
API_KEY = "your-api-key" # Only used if USE_VERTEX=False


weave.init("gemini-genai")

# --- SETUP ENV VARIABLES ---
if USE_VERTEX:
os.environ["GOOGLE_CLOUD_PROJECT"] = PROJECT
os.environ["GOOGLE_CLOUD_LOCATION"] = LOCATION
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
else:
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "False"

# --- Initialize client ---
if USE_VERTEX:
client = genai.Client()
MODEL = "gemini-2.5-pro-preview-06-05"
else:
client = genai.Client(api_key=API_KEY)
MODEL = "gemini-2.5-pro-preview-06-05"


@weave.op
def run_gemini(
prompt,
streaming=STREAMING,
model=MODEL,
thinking_budget=1024,
include_thoughts=True
):
"""
Run a prompt through Gemini (Vertex or consumer API),
optionally using streaming, and configurable 'thinking_budget'
and 'include_thoughts'.

Returns (thoughts, answer) as strings.
"""
thoughts = ""
answer = ""
if streaming:
method = client.models.generate_content_stream
response = method(
model=model,
contents=prompt,
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
include_thoughts=include_thoughts,
thinking_budget=thinking_budget
)
)
)
for chunk in response:
for part in chunk.candidates[0].content.parts:
if not part.text:
continue
if part.thought:
if not thoughts:
print("Thoughts summary:")
print(part.text)
thoughts += part.text
else:
if not answer:
print("Answer:")
print(part.text)
answer += part.text
else:
method = client.models.generate_content
response = method(
model=model,
contents=prompt,
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
include_thoughts=include_thoughts,
thinking_budget=thinking_budget
)
)
)
for part in response.candidates[0].content.parts:
if not part.text:
continue
if part.thought:
if not thoughts:
print("Thoughts summary:")
print(part.text)
thoughts += part.text
else:
if not answer:
print("Answer:")
print(part.text)
answer += part.text
return thoughts, answer

# -------- EXAMPLES ---------
if __name__ == "__main__":
# Algebra example
prompt1 = "Solve x^2 + 4x + 4 = 0"
print("\nAlgebra Example:")
run_gemini(
prompt1,
streaming=True,
thinking_budget=512, # You can override per-call
include_thoughts=True # You can override per-call
)

# Primes example, with less thinking budget and thoughts off
prompt2 = "What is the sum of the first 50 prime numbers?"
print("\nPrimes Example:")
run_gemini(
prompt2,
streaming=False,
thinking_budget=32,
include_thoughts=False
)

# Logic puzzle example -- use default thinking_budget/streaming
prompt3 = """
Alice, Bob, and Carol each live in a different house on the same street: red, green, and blue.
The person who lives in the red house owns a cat.
Bob does not live in the green house.
Carol owns a dog.
The green house is to the left of the red house.
Alice does not own a cat.
Who lives in each house, and what pet do they own?
"""
print("\nLogic Puzzle Example:")
run_gemini(
prompt3,
thinking_budget=1024,
include_thoughts=True
)
스크립트의 핵심은 run_gemini 함수로, 각 프롬프트를 모델이 어떻게 추론할지 직접 지정할 수 있습니다. 이를 조정하면 thinking_budget, Gemini가 문제를 얼마나 깊이 탐색할지 제어할 수 있으며, 모델의 내부 “사고 과정” 포함 여부를 전환해 단계별 설명을 볼지, 최종 답변만 받을지 선택할 수 있습니다.
스크립트를 사용하려면 수학 방정식, 논리 퍼즐, 일반 질문과 같은 프롬프트만 제공하면 됩니다. 필요에 맞게 추론 깊이와 사고 과정 표시 여부를 설정하세요. 예를 들어, 복잡한 문제를 Gemini가 해결하는 동안 상세한 중간 단계를 확인할 수 있으며, 스트리밍 모드에서는 이러한 사고 과정과 답변이 실시간으로 나타납니다. 이 스크립트는 모델의 추론 과정을 탐구하고 Gemini의 최종 답뿐만 아니라 그 답에 도달하는 방식까지 이해하고 싶은 모든 사용자에게 유용합니다.

결론

대규모 언어 모델과 생성형 AI의 급격한 발전은 개발자가 애플리케이션을 구축하는 방식을 근본적으로 바꾸고 있으며, Google의 GenAI SDK는 이 변화의 최전선에 서 있습니다. 텍스트·이미지 생성부터 비디오 이해에 이르기까지 최첨단 Gemini 모델에 대한 통합 접근을 제공함으로써, 이 SDK는 팀이 빠르게 프로토타입을 만들고 무리 없이 프로덕션으로 확장하도록 돕습니다. 세심한 설계로 실험과 배포의 간극을 메워, Gemini Developer API를 쓰든 Vertex AI를 쓰든 일관된 도구 세트로 작업할 수 있게 합니다.
이들 모델의 역량이 계속 확장됨에 따라 GenAI SDK와 같은 견고한 도구를 도입하는 것은 경쟁력을 유지하고 설득력 있는 지능형 사용자 경험을 만드는 데 필수적입니다. 워크플로를 최적화하든, 창의적인 애플리케이션을 구축하든, 고급 분석을 기존 제품에 통합하든, Google GenAI SDK는 최신 AI 발전을 코드베이스 안에서 직접 활용할 수 있게 해 주며, 미래의 과제에 대응할 유연성까지 갖춘 탄탄한 기반을 제공합니다.

이 글은 AI 번역본입니다. 오역이 있으면 댓글로 알려 주세요. 원문 보고서는 다음 링크에서 확인할 수 있습니다: 원문 보고서 보기