Gemini API용 Python Google GenAI SDK
Gemini API의 새로운 통합 google-genai SDK 참조 및 고급 설정 가이드
이 섹션은 새로운 SDK의 맥락을 설정하며, 사용자가 라이브러리 변경에 대해 가지는 주요 혼동을 다루고, 설치 및 두 가지 핵심 인증 방법을 포함한 시작을 위한 견고한 가이드를 제공합니다.
1.1. 새로운 표준: google-generativeai에서 google-genai로의 이전
Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»Google의 생성형 AI 모델 개발 생태계가 진화했습니다. google-genai 라이브러리는 이제 Gemini API 및 기타 Google 생성형 AI 모델과 상호작용하기 위한 공식적이고 통합된 Python SDK로, 2025년 5월에 일반 공급(GA)을 시작했으며, 이전 라이브러리인 google-generativeai을 대체합니다.
이전 라이브러리 google-generativeai는 Python Package Index(PyPI)에서 '비활성화됨'으로 표시되었으며, 폐지 경로를 따라가고 있습니다. 이 패키지의 지원, 포함된 중대한 오류 수정은 2025년 9월 말에 중단되며, 일부 자료에 따르면 2025년 8월 31일에 중단될 수 있습니다. 개발자에게는 가능한 한 빠르게 이전하여 원활한 전환을 보장할 것을 권장합니다.
이 변경은 단순한 이름 변경이 아니라 개발자 피드백에 기반한 전략적 통합입니다. 주요 목표는 Google 생성형 AI 모델(Gemini, Veo, Imagen 등) 전체 범위에 대한 접근을 간소화하고 개발자에게 더 명확하고 일관된 개발 경로를 제공하는 단일 SDK를 만드는 것이었습니다. google-genai 새 SDK의 설계에서 가장 중요한 결정 중 하나는 Gemini 개발자 API(접근이 용이한 서비스)와 기업 수준의 Vertex AI 플랫폼이라는 두 가지 별도 백엔드 서비스에 대한 단일 인터페이스 역할을 하는 것입니다.
이 통합 아키텍처는 개발자에게 스ム즈한 접근 경로를 제공합니다. 일반적으로 무료 레벨로 Gemini 개발자 API를 위한 API 키를 사용하여 빠르게 시작할 수 있습니다. 애플리케이션이 성장하고 Google Cloud의 더 높은 확장성, 거버넌스 및 기타 서비스 통합이 필요한 경우, 클라이언트 초기화에서 주로 변경되는 최소한의 코드 변경으로 Vertex AI 백엔드로 전환할 수 있습니다. google-genai SDK는 진입 장벽을 줄이고 Google Cloud에서의 운영을 위한 명확한 경로를 제공하는 다리 역할을 합니다. 따라서 이전 라이브러리 사용자는 최신 기능(예: Live API 및 Veo), 성능 향상 및 지속적인 지원에 액세스하기 위해 이전하는 것이 권장됩니다.
1.2. 설치 및 환경
Sección titulada «1.2. Instalación y Entorno»SDK를 설치하기 전에 Python 가상 환경을 설정하는 것이 권장됩니다. 이는 프로젝트의 종속성을 격리하여 다른 프로젝트나 시스템 패키지와의 충돌을 방지합니다.
venv를 사용하여 가상 환경을 생성하고 활성화하려면:
# En macOS/Linuxpython3 -m venv gemini-envsource gemini-env/bin/activate
# En Windowspy -m venv gemini-env.\gemini-env\Scripts\activate가상 환경이 활성화되면, pip를 사용하여 Google Gen AI SDK의 최신 버전을 설치할 수 있습니다. --upgrade 플래그를 사용하면 최신 버전을 확보할 수 있습니다.
pip install --upgrade google-genaiPython 버전 요구 사항을 고려하는 것이 필수적입니다. SDK google-genai는 Python 3.9 이상이 필요합니다. 호환되지 않는 버전을 사용하면 설치 또는 실행 중 예기치 않은 오류가 발생할 수 있습니다.
고성능 비동기 애플리케이션을 위한 SDK는 aiohttp를 HTTP 전송 백엔드로 사용할 수 있는 옵션을 제공합니다. 이는 기본값인 httpx 대신 사용할 수 있으며, 추가로 설치할 수 있습니다:
pip install google-genai[aiohttp]1.3. 인증: Gemini API의 키
Sección titulada «1.3. Autenticación: Su Clave para la API de Gemini»인증은 설정 단계에서 가장 중요한 단계이며, 사용하려는 백엔드 서비스에 따라 방법이 다릅니다. Gemini 개발자 API 또는 Vertex AI에서의 Gemini API를 사용하는 경우가 있습니다.
1.3.1. Gemini 개발자 API 경로 (프로토타입 및 무료 계층에 추천)
Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»이 방법은 Gemini로 작업을 시작하는 가장 빠른 방법입니다. Google AI Studio에서 무료로 얻을 수 있는 API 키가 필요합니다.
API 키를 얻는 과정은 다음과 같습니다:
- https://ai.google.dev/로 이동하여 Google 계정으로 로그인하세요.
- ‘API 키 얻기’(API 키 생성)를 클릭하세요.
- 새로운 또는 기존의 Google Cloud 프로젝트에서 API 키를 생성하십시오.
- API 키는 자동으로 생성됩니다.
API 키는 민감한 자격 증명이며 비밀번호와 같이 취급해야 합니다. 안전하게 저장해야 하며 클라이언트 측 코드에 노출하거나 공개 버전 관리 시스템에 커밋해서는 안 됩니다.
키를 사용하는 가장 안전하고 권장되는 방법은 환경 변수로 설정하는 것입니다. SDK는 GOOGLE_API_KEY 또는 GEMINI_API_KEY 환경 변수를 자동으로 감지하고 사용하도록 설계되었습니다. 두 가지 모두 설정된 경우 GOOGLE_API_KEY가 우선권을 갖습니다.
환경 변수를 설정하려면:
-
Linux/macOS (bash)에서:
Ventana de terminal export GOOGLE_API_KEY='SU_CLAVE_DE_API_AQUI'# Agregue esta línea a su archivo ~/.bashrc o ~/.zshrc para que sea permanente -
Windows에서: 시스템 설정의 '환경 변수' 그래픽 인터페이스를 사용하여 사용자 또는 시스템 변수를 추가하고
GOOGLE_API_KEY라는 이름을 사용자 또는 시스템 변수로 지정하세요.
1.3.2. Vertex AI 경로 (Google Cloud 통합용 권장 방법)
Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»Google Cloud의 기업 기능이 필요한 대규모 생산 애플리케이션의 경우 Vertex AI를 통해 Gemini API를 사용하는 것이 권장됩니다. 이 접근 방식은 요금이 활성화된 Google Cloud 프로젝트가 필요합니다.
초기 설정 단계에는 다음이 포함됩니다:
- Google Cloud 프로젝트를 선택하거나 생성하세요.
- 프로젝트에 요금이 활성화되어 있는지 확인하세요.
- 프로젝트에서 Vertex AI API (
aiplatform.googleapis.com)를 활성화하세요.
Vertex AI 인증은 두 가지 방법으로 수행할 수 있습니다:
-
앱 기본 인증 정보 (ADC) (생산 환경 권장): 대부분의 생산 환경 시나리오에 가장 선호되는 방법입니다. ADC는 환경에 따라 자동으로 인증 정보를 찾습니다. 로컬 개발 환경에서 이는 gcloud CLI 명령을 실행하여 구성할 수 있습니다:
Ventana de terminal gcloud auth application-default loginGoogle Cloud 환경에서 실행되는 경우 (예: Cloud Run, Google Kubernetes Engine, Cloud Functions), ADC는 해당 리소스에 연결된 서비스 계정을 자동으로 사용하여 키를 관리할 필요를 제거합니다.
-
Vertex용 API 키: Vertex AI 엔드포인트에 인증하는 데 API 키를 사용할 수 있지만, 개발자 API보다 프로세스가 더 복잡합니다. 서비스 계정의 API 키 생성을 활성화하기 위한 조직 수준의 권한이 필요하며, 적절한 역할(예:
Vertex AI User))을 가진 서비스 계정을 생성한 후 해당 서비스 계정에 제한된 API 키를 생성해야 합니다. 복잡성 때문에 이 방법은 일반적인 애플리케이션 개발보다는 특정 테스트 시나리오에서 주로 사용됩니다.
1.4. 클라이언트 초기화: 모델에 연결하기
Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»인증이 설정된 후 다음 단계는 genai.Client 개체를 인스턴스화하는 것입니다. 통합 SDK는 두 가지 백엔드 중 하나에 대해 단일 클라이언트를 제공하여 이를 간소화합니다.
다음은 클라이언트 초기화의 네 가지 주요 시나리오입니다.
-
시나리오 1: Gemini 개발자 API (명시적 키) 이 방법은 환경 변수를 설정하지 않고 빠른 노트북이나 스크립트에서 사용하기에 편리합니다. API 키는 직접 인수로 전달됩니다.
from google import genaiclient = genai.Client(api_key="SU_CLAVE_DE_API_AQUI") -
시나리오 2: Gemini 개발자 API (환경 변수) 이 방법은 코드에서 자격 증명을 분리하여 애플리케이션 코드에 더 깔끔하고 권장되는 접근 방식입니다. 클라이언트는 자동으로
GOOGLE_API_KEY환경 변수를 찾고 사용합니다.# Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configuradafrom google import genaiclient = genai.Client() -
시나리오 3: Vertex AI API (명시적 매개변수) Vertex AI에 연결하려면
vertexai을True로 설정하고 프로젝트 ID 및 위치를 제공합니다. 이 방법은 자동으로 애플리케이션 기본 인증 정보(ADC)를 사용하여 인증합니다.from google import genaiclient = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1") -
시나리오 4: Vertex AI API (환경 변수) Vertex AI의 대안으로 설정을 환경 변수에 외부화할 수 있습니다. 클라이언트는 이러한 변수를 감지하고 Vertex AI 백엔드를 사용하도록 구성합니다.
Ventana de terminal export GOOGLE_GENAI_USE_VERTEXAI=trueexport GOOGLE_CLOUD_PROJECT='su-id-de-proyecto-gcp'export GOOGLE_CLOUD_LOCATION='us-central1'# El cliente se configurará automáticamente para Vertex AIfrom google import genaiclient = genai.Client()
다음 표는 이 방법들을 간단히 요약합니다.
표 1: 클라이언트 초기화 참조
| 사용 사례 | 파이썬 코드 | 필요한 환경 변수 | 참고 사항 |
|---|---|---|---|
| 명시적인 키를 사용한 개발자 API | client = genai.Client(api_key="SU_CLAVE...") | 없음 | 노트북과 빠른 테스트에 유용합니다. 생산 코드에서는 피하십시오. |
| 환경 변수를 사용한 개발자 API | client = genai.Client() | GOOGLE_API_KEY 또는 GEMINI_API_KEY | 깨끗하고 안전한 애플리케이션 코드를 위한 선호하는 방법입니다. |
| 명시적 파라미터를 사용한 Vertex AI | client = genai.Client(vertexai=True, project="...", location="...") | 없음 (ADC 사용) | Vertex AI에 명시적으로 지정하는 방법. ADC 인증이 필요합니다 (gcloud auth...). |
| 환경 변수와 함께 Vertex AI | client = genai.Client() | GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION | 코드에 파라미터 없이 Vertex AI 클라이언트를 구성합니다. ADC 인증이 필요합니다. |
2부: 주요 기능: 텍스트 및 채팅
Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»이 부분은 가장 일반적인 사용 사례인 텍스트 생성 및 대화형 에이전트 구축에 몰입합니다. 관련된 주요 메서드와 객체를 자세히 설명합니다.
2.1. 내용 생성: 메서드 generate_content
Sección titulada «2.1. Generando Contenido: El Método generate_content»모든 단일 전환 생성 작업에 대한 주요 메서드는 client.models.generate_content()입니다. 이 다용도 메서드는 Gemini 모델과 상호작용하는 기초입니다.
기본 사용 사례는 contents와 같은 간단한 텍스트 문자열을 제공하고, gemini-2.5-flash와 같은 사용할 모델의 이름을 지정하는 것입니다.
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado como se describió anteriormenteresponse = client.models.generate_content( model="gemini-2.5-flash", contents="Explica brevemente por qué el cielo es azul.")
print(response.text)단순한 문자열을 전달하는 것은 편리하지만 SDK가 사용하는 데이터 구조를 이해하는 것이 필수적입니다. SDK 내부에서는 모든 입력이 types.Content 및 types.Part 객체로 구성된 표준화된 구조로 변환됩니다. 이 구조를 이해하는 것은 멀티모달 지시사항 및 함수 호출과 같은 SDK의 고급 기능을 활용하는 데 필수적입니다.
types.Content: 대화에서 단일 메시지 또는 라운드를 나타냅니다. 주요 속성 두 가지는role(일반적으로 'user' 입력 또는 'model' 출력)과parts목록입니다.types.Part:Content객체 내부의 데이터 조각을 나타냅니다. 일부는 텍스트, 이미지 데이터, 파일 참조, 함수 호출 등일 수 있습니다.
SDK는 contents 인수에 대한 여러 입력 유형을 지능적으로 처리하여 적절한 Content/Part 형식으로 변환합니다:
- 단일 문자열:
contents='¿Por qué el cielo es azul?'는 단일Part텍스트를 가진UserContent로 변환됩니다. - 문자열 목록:
contents=['Pregunta 1', 'Pregunta 2']는 두 개의 텍스트Part를 포함하는 단일UserContent로 변환됩니다. types.Part개체: 이미지 데이터를 지정하는 것과 같은 더 세부적인 제어가 가능합니다.- 완전히 형성된
types.Content개체: 메시지의 역할과 콘텐츠에 대한 최대 제어가 가능합니다.
생성된 응답에 액세스하려면 편의 메서드 response.text가 가장 간단한 방법입니다. 그러나 이 액세서는 단일 텍스트 부분으로 구성된 간단한 응답만 작동한다는 점을 기억하는 것이 중요합니다. 응답이 보안 필터에 의해 차단되었거나 여러 후보를 포함하거나 텍스트가 아닌 데이터 유형을 포함하는 경우 response.text에 액세스하면 오류가 발생합니다. 생산용으로 가장 견고하고 안전한 방법은 직접 후보 및 해당 부분에 액세스하는 것입니다:
try: # Método robusto para acceder al texto text_response = response.candidates.content.parts.text print(text_response)except (IndexError, AttributeError): # Manejar el caso en que no hay respuesta de texto válida print("No se pudo obtener una respuesta de texto válida.") # Se puede inspeccionar response.prompt_feedback para ver si fue bloqueado print(f"Razón del bloqueo del prompt: {response.prompt_feedback.block_reason}")2.2. 실시간 피드백을 위한 스트리밍 응답
Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»대화형 애플리케이션인 챗봇과 같은 경우, 모델의 응답 스트리밍은 사용자 경험을 극적으로 향상시킵니다. 전체 응답이 생성되는 것을 기다리는 대신, 텍스트 조각이 도착하는 대로 표시되어 즉각적인 피드백을 제공합니다.
이 기능은 generate_content_stream() 메서드를 통해 구현됩니다. 이 메서드는 모델이 생성하는 응답 조각을 순차적으로 생성하는 반복자를 반환합니다.
import google.genai as genai
# Asumiendo que 'client' ha sido inicializadoresponse_stream = client.models.generate_content_stream( model="gemini-2.0-flash", contents="Escribe un poema largo sobre el océano y sus misterios.")
print("Respuesta del modelo:")for chunk in response_stream: print(chunk.text, end="")print() # Para una nueva línea al final2.3. 대화형 AI 정복: 채팅 인터페이스
Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»SDK는 다중 라운드 대화를 관리하기 위한 두 가지 주요 메커니즘을 제공합니다. 하나는 대화 이력을 수동으로 관리하는 방법으로, 각 라운드를 나타내는 Content 객체 목록을 구성하고, 각 호출 시 generate_content()에 전달하는 방식입니다. 비록 유연하지만 이 방법은 복잡할 수 있습니다.
챗봇을 만들기 위한 권장되고 편리한 방법은 client.chats에서 제공하는 상태가 있는 채팅 인터페이스를 사용하는 것입니다. 이 고수준 개체는 이력을 관리하는 것을 추상화하여 애플리케이션 코드를 크게 단순화합니다. 이는 SDK에서 의도적으로 선택된 디자인 결정입니다: 챗팅과 같은 일반적인 사용 사례를 위해 상태가 있는 고수준 추상화(client.chats)를 제공함으로써, 상태가 없는 저수준 방법(generate_content)에 비해 개발을 훨씬 쉽게 합니다.
채팅 인터페이스를 사용하는 워크플로우는 다음과 같습니다:
- 채팅 세션 초기화: 새로운 대화를 시작하기 위해
client.chats.create()가 사용됩니다. 모델을 지정할 수 있으며, 선택적으로 대화를 구체화하기 위한 초기 이력을 제공할 수 있습니다. - 메시지 전송: 사용자의 다음 메시지를 전송하기 위해
chat.send_message()메서드가 사용됩니다. SDK는 상태를 자동으로 관리하며, 사용자 메시지와 모델의 이후 응답을 대화 이력에 자동으로 추가합니다. - 히스토리에 접근하기: 어떤 시점에서든 전체 대화 기록을
chat.get_history()를 사용하여 복구할 수 있습니다.
다음은 여러 단계에 걸친 대화 예시입니다:
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado# 1. Crear una nueva sesión de chatchat_session = client.chats.create( model="gemini-2.0-flash")
# 2. Enviar el primer mensajeprint("Usuario: Hola, ¿puedes ayudarme a planificar un viaje a la luna?")response = chat_session.send_message("Hola, ¿puedes ayudarme a planificar un viaje a la luna?")print(f"Modelo: {response.text}\n")
# 3. Enviar un segundo mensaje de seguimientoprint("Usuario: ¿Qué tres cosas debería empacar?")response = chat_session.send_message("¿Qué tres cosas debería empacar?")print(f"Modelo: {response.text}\n")
# 4. Mostrar el historial completo de la conversaciónprint("--- Historial de la Conversación ---")for message in chat_session.get_history(): # El rol y el texto están en message.role y message.parts.text role = "Usuario" if message.role == "user" else "Modelo" print(f"{role}: {message.parts.text}")모델의 동작을 조정하려면 generate_content 메서드는 config 매개변수를 받아들이며, 이는 types.GenerateContentConfig 객체를 받습니다. 이 객체는 개발자가 생성 과정의 여러 측면을 제어할 수 있도록 합니다.
가장 유용한 설정 중 하나는 system_instruction입니다. 시스템 명령문은 고수준 가이드를 제공하거나 모델에 지속적인 성격을 설정합니다. 예를 들어, 모델을 특정 인물로 행동하도록 지시하거나 응답 시 특정 규칙을 따르도록 할 수 있습니다.
from google.genai import types
# Asumiendo que 'client' ha sido inicializadoresponse = client.models.generate_content( model='gemini-2.0-flash', contents='¡Ah del barco! Cuéntame un chiste sobre un loro.', config=types.GenerateContentConfig( system_instruction='Hablas como un pirata malhumorado y conciso.' ))print(response.text)시스템 명령문 외에도 모델의 출력 창의성과 구조를 제어하기 위해 다른 여러 파라미터를 조정할 수 있습니다. 다음 표는 가장 중요한 파라미터를 설명합니다.
표 2: 생성 설정의 주요 파라미터
| 파라미터 | 설명 | 범위 | 출력에 미치는 영향 |
|---|---|---|---|
temperature | 토큰 선택의 무작위성을 제어합니다. | 0.0 - 1.0 | 더 낮은 값(예: 0.2)는 출력을 더 결정적이고 더 창의적이지 않게 만듭니다. 더 높은 값(예: 0.9)은 난수성과 창의성을 증가시킵니다. |
top_p | 핵 샘플링(Nucleus sampling). 누적 확률이 top_p보다 높은 가장 작은 토큰 집합을 고려합니다. | 0.0 - 1.0 | 0.95와 같은 값은 확률 질량의 상위 95%에 해당하는 토큰만 고려하게 됩니다. 매우 불확실한 토큰을 피하는 데 도움이 됩니다. |
top_k | 생성 단계마다 k개의 가장 가능성 있는 토큰만 고려합니다. | 정수 | top_k의 1는 탐욕적 디코딩(greedy decoding)입니다. 40와 같은 값은 40개의 가장 가능성 있는 토큰으로 선택을 제한합니다. |
candidate_count | 생성할 후보 응답의 수입니다. | 정수(예: 1-8) | 동일한 명령에 대해 여러 가능한 응답을 생성합니다. 사용자에게 옵션을 제공하는 데 유용합니다. |
max_output_tokens | 응답에서 생성할 수 있는 최대 토큰 수입니다. | 정수 | 출력 길이를 제한합니다. 비용과 지연 시간을 통제하는 데 필수적입니다. |
stop_sequences | 생성될 때 출력을 중지할 문자열 목록입니다. | 문자열 목록 | 특정 지점에서 생성을 중지하는 데 유용합니다. 예를 들어 문장 끝 표시자나 특정 형식에서 사용할 수 있습니다. |
seed | 생성에 사용할 난수 시드입니다. | 정수 | 시드를 제공하면 출력이 결정적이고 재현 가능해집니다(단, temperature가 0가 아닌 경우에 한합니다). |
제3부: 고급 상호작용: 멀티모달리티 및 함수 호출
Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»이 부분은 Gemini 모델이 어떻게 비텍스트 입력과 외부 도구에 연결하여 작동하는지를 설명함으로써 모델의 실제 능력을 보여줍니다.
3.1. 텍스트를 넘어서: 멀티모달 입력 이해하기
Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»Gemini 모델 패밀리의 주요 특징은 내재적인 멀티모달 기능입니다. 이는 텍스트, 이미지, 오디오, 비디오와 같은 다양한 데이터 유형(또는 '모달리티')을 단일 명령어에서 처리하고 추론할 수 있음을 의미합니다.
이 기능은 contents을 여러 Part 객체로 구성된 목록으로 구축함으로써 활성화되며, 각 Part는 다른 데이터 유형을 포함할 수 있습니다. 예를 들어, 하나의 요청에 이미지와 해당 이미지에 대한 텍스트 질문을 포함할 수 있습니다.
3.2. 이미지 처리 방법
Sección titulada «3.2. Trabajando con Imágenes»SDK는 이미지 데이터를 처리하기 위해 전략적으로 다른 두 가지 방법을 제공합니다. 선택은 파일 크기 및 재사용성과 같은 특정 사용 사례 요구사항에 따라 달라집니다.
이 두 가지 방법은 중복이 아닌, 운영 요구사항을 충족하기 위한 의도적인 설계입니다. 온라인 방법은 간단하고 개발 편의성을 위한 단일 분석에 적합합니다. 파일 API는 추가 로드 단계를 요구하지만, 파일 크기 처리, 효율성 및 확장성과 같은 생산 환경에서 필수적인 요소를 고려할 때 중요한 역할을 합니다.
방법 1: 이미지 데이터 온라인 전달 (Inline)
Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»이 방법은 이미지 파일 크기가 작을 때(요청 전체(명령어 및 바이트 포함)는 20MB 이하) 및 개발 간편성을 위해 적합합니다. 이미지 데이터는 직접 generate_content 호출에 전달됩니다.
-
로컬 파일에서: 이미지 파일은 이진 모드로 읽혀(
'rb')types.Part.from_bytes()에 전달되며, 올바른 MIME 유형을 지정해야 합니다.import google.genai as genaifrom google.genai import types# Asumiendo que 'client' ha sido inicializadowith open('imagen_scones.jpg', 'rb') as f:image_bytes = f.read()image_part = types.Part.from_bytes(data=image_bytes,mime_type='image/jpeg')prompt_part = "Describe lo que ves en esta imagen."# Combinar imagen y texto en una sola solicitudresponse = client.models.generate_content(model='gemini-2.5-flash', # O un modelo de visión como gemini-pro-visioncontents=[prompt_part, image_part])print(response.text) -
URL에서: 이미지의 바이트를 가져오기 위해
requests과 같은 라이브러리를 사용할 수 있으며, 이후 동일한 방식으로 전달할 수 있습니다.
방법 2: 파일 API (Files API)
Sección titulada «Método 2: La API de Archivos (Files API)»이 방법은 20MB 이상의 큰 이미지 파일이나 여러 인식 요청에서 동일한 파일을 재사용해야 하는 경우에 권장됩니다. 파일 API를 사용하면 각 호출 시 동일한 바이트를 다시 로드할 필요가 없습니다.
작업 흐름은 두 단계로 구성됩니다:
- 업로드:
client.files.upload()을 사용하여 파일을 구글 서버에 업로드합니다. 이 방법은 참조를 제공하는 파일 객체를 반환합니다. - 요청:
generate_content에 대한 호출의contents목록에 반환된 파일 객체를 직접 전달합니다. SDK가 로드된 파일의 참조를 해결합니다.
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar el archivo usando la API de Archivosprint("Cargando archivo...")sample_file = client.files.upload( file_path="imagen_grande.png", display_name="Mi Imagen de Muestra")print(f"Archivo cargado: {sample_file.uri}")
# 2. Usar el archivo cargado en una indicaciónprompt = "Analiza esta imagen y describe los objetos principales y su disposición espacial."response = client.models.generate_content( model='gemini-2.5-flash', contents=[prompt, sample_file] # Pasar el objeto de archivo directamente)
print(response.text)
# Opcional: Eliminar el archivo después de su usoclient.files.delete(name=sample_file.name)print(f"Archivo eliminado: {sample_file.name}")API를 통해 업로드된 파일은 48시간 동안 임시로 저장되며 자동으로 삭제됩니다. API는 이 파일들을 관리하기 위한 방법을 제공합니다, 예: get(), list() 및 delete().
3.3. 오디오 및 비디오와의 상호작용
Sección titulada «3.3. Interacción con Audio y Vídeo»이미지 처리 개념은 오디오 및 비디오와 같은 다른 모달리티로 직접 확장됩니다. 이러한 파일은 일반적으로 크기 때문에 파일 API가 주요 작업 방법입니다.
프로세스는 대규모 이미지와 동일합니다.
- 오디오(예: MP3, WAV) 또는 비디오(예: MP4) 파일을 업로드하려면
client.files.upload()를 사용하십시오. - 반환된 파일 객체를
generate_content에 대한 지시에 포함하십시오.
다음 예제는 오디오 파일을 업로드하고 모델에 이를 전사하도록 요청하는 방법을 보여줍니다.
import google.genai as genaiimport time
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar un archivo de audioprint("Cargando archivo de audio...")audio_file = client.files.upload( file_path="discurso_muestra.mp3", display_name="Discurso de Muestra")
# El procesamiento del archivo puede llevar tiempo, se espera a que esté ACTIVOwhile audio_file.state.name == "PROCESSING": print("Procesando archivo... esperando.") time.sleep(10) audio_file = client.files.get(name=audio_file.name)
if audio_file.state.name == "FAILED": raise ValueError(audio_file.state.name)
# 2. Usar el archivo de audio en una indicaciónprompt = "Transcribe el discurso en este archivo de audio."response = client.models.generate_content( model='gemini-2.5-flash', contents=[prompt, audio_file])print("\n--- Transcripción ---")print(response.text)3.4. 함수 호출: 모델의 능력 확장
Sección titulada «3.4. Llamada a Funciones: Ampliando las Capacidades del Modelo»함수 호출(도구 사용)은 모델이 외부 시스템과 상호작용할 수 있도록 하는 강력한 기술입니다. 모델이 내재적인 지식을 넘어 실시간 데이터를 API에서 얻거나 데이터베이스를 쿼리하거나 장치를 제어하는 등의 작업을 수행할 수 있도록 합니다.
일반적인 작업 흐름은 다음과 같습니다:
- 도구 정의: 모델이 호출할 수 있는 도구(파이썬 함수)의 집합을 정의합니다. 이 정의에는 함수 이름, 기능 설명 및 매개변수 스키마가 포함됩니다.
- 모델에 도구 전달: 정의된 도구 목록을
generate_content호출 시 모델에 전달합니다. - 모델이 호출 결정: 사용자 지시를 분석한 모델은 제공된 도구 중 하나가 도움이 될 수 있다고 판단하면, 텍스트 생성 대신
Part유형의 객체를 포함한 응답을 생성합니다. 이 객체는 호출할 함수 이름과 인수를 지정합니다. - 함수 실행: 애플리케이션 코드는 이
function_call를 감지하고, 제공된 인수와 함께 해당 파이썬 함수를 실행하여 결과를 얻습니다. - 결과를 모델에 반환:
generate_content에 대한 두 번째 호출을 수행하여 대화 기록과 실행 결과(types.Part.from_function_response()로 래핑된 상태)를 제공합니다. - 최종 응답: 모델은 함수 실행 결과를 사용하여 사용자에게 자연어로 된 최종 응답을 생성합니다.
연구 샘플은 엔드투엔드 함수 호출 코드 예제를 제공하지 않지만, Part 객체의 구조는 function_call 및 function_response에 대해 이 고급 패턴을 구현하는 기초가 됩니다.
제4부: 프로덕션 준비: 오류 처리, 보안 및 관리
Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»이 최종 부문은 견고하고 신뢰할 수 있으며 책임 있는 애플리케이션을 구축하는 데 필수적인 정보를 제공합니다.
4.1. 견고한 오류 처리
Sección titulada «4.1. Manejo Robusto de Errores»프로덕션 환경에서는 견고한 오류 처리가 필수적입니다. API 호출은 유효하지 않은 자격 증명, 네트워크 문제, 할당량 소진 또는 잘못된 형식의 입력으로 인해 실패할 수 있습니다.
SDK는 Python 표준 예외 시스템을 사용합니다. 대부분의 API 관련 오류는 try...except 블록을 사용하여 google.api_core.exceptions 모듈의 예외를 캡처하거나, 사용 가능한 경우 errors.APIError와 같은 더 구체적인 클래스를 사용하여 처리할 수 있습니다.
from google.api_core import exceptions as core_exceptionsimport google.genai as genai
# Asumiendo que 'client' ha sido inicializadotry: response = client.models.generate_content( model="nombre-de-modelo-invalido", contents="¿Cuál es tu nombre?" ) print(response.text)except core_exceptions.GoogleAPICallError as e: # 'e' es una superclase para muchos errores de API print(f"Ha ocurrido un error en la API: {e}") # En muchos casos, 'e' tendrá atributos como 'code' y 'message' # aunque esto puede variar. Se recomienda inspeccionar el objeto de excepción.
except core_exceptions.NotFound as e: # Un error más específico si se sabe qué buscar print(f"Error: Recurso no encontrado. ¿Es correcto el nombre del modelo? - {e.message}")
except core_exceptions.ResourceExhausted as e: # Específico para errores de cuota print(f"Error: Se ha excedido la cuota de la API. - {e.message}")예외를 캡처할 때, 예외 객체는 로깅 및 디버깅에 유용한 정보를 자주 포함합니다. 상태 코드와 설명 메시지와 같은 정보가 포함될 수 있습니다.
오류 메시지는 개발자에게 유용하지만, 악의적인 공격자에게 내부 구현 세부 사항을 노출시킬 수 있는 이중 칼날이 될 수 있습니다. 예를 들어, 보안 검증 오류 메시지 분석을 통해 내부 임계값 또는 방어 메커니즘을 알아낼 수 있으며, 이는 악의적인 행위자가 보호 기능을 회피하는 데 도움이 될 수 있습니다. 따라서 백엔드에서 오류를 철저히 로깅하는 것이 중요하지만, 최종 사용자에게 표시되는 정보는 주의 깊게 제어해야 합니다. 일반적으로 '요청을 처리하는 동안 오류가 발생했습니다'와 같은 일반적인 메시지를 표시하는 것이 더 안전합니다.
다음 표는 API에서 자주 발생하는 오류 코드와 해결 방법을 요약합니다.
표 3: API 일반 오류 코드 및 해결 방법
| HTTP 코드 | 상태 | 가능한 원인 | Python에서 추천된 작업 |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | 요청 본문이 잘못 구성되었습니다 (예: 잘못된 유형의 매개변수, 누락된 필수 필드). | PC_BLOCK_0의 매개변수와 PC_BLOCK_1의 형식이 올바른지 확인하십시오. 요청한 기능과 모델이 호환되는지 확인하십시오. |
| 403 | PERMISSION_DENIED | API 키가 잘못되었거나 필요한 권한이 없거나 제한된 리소스에 액세스하려고 합니다 (예: 조정된 모델). | API 키(또는 Vertex용 ADC 인증)가 올바르게 구성되어 있고 필요한 권한이 있는지 확인하십시오. |
| 429 | RESOURCE_EXHAUSTED | API 속도 제한을 초과했습니다 (분당 요청 수). | 재시도 로직에 지수 백오프(Exponential Backoff)를 구현하십시오. 필요할 경우 애플리케이션용 할당량 증가를 요청하십시오. |
| 500 | INTERNAL | Google 측에서 예기치 않은 오류가 발생했습니다. 때로는 매우 긴 입력 컨텍스트로 인해 발생할 수 있습니다. | 지시사항의 길이를 줄이십시오. 짧은 시간 후에 다시 시도하십시오. 문제가 지속되는 경우, 잠시 다른 모델로 전환하는 것을 고려하십시오. |
| 503 | UNAVAILABLE | 서비스가 일시적으로 과부하되었거나 사용할 수 없습니다. | 짧은 시간 후에 다시 시도하고, 지수 백오프 전략을 사용하십시오. 문제가 지속되면 문제를 보고하십시오. |
Gemini API는 잠재적으로 해로운 콘텐츠를 필터링하기 위한 내장된 보안 기능을 포함하고 있습니다. 이 기능들은 개발자가 더 안전하고 책임감 있는 애플리케이션을 구축하는 데 도움을 주도록 설계되었습니다.
API는 콘텐츠를 4가지 주요 손상 범주로 분류합니다:
- 모욕 (
HARM_CATEGORY_HARASSMENT) - 증오 유도 (
HARM_CATEGORY_HATE_SPEECH) - 성적 콘텐츠 (
HARM_CATEGORY_SEXUALLY_EXPLICIT) - 위험한 콘텐츠 (
HARM_CATEGORY_DANGEROUS_CONTENT)
각 범주에 대해 모델은 콘텐츠가 안전하지 않을 확률을 할당합니다. 기본적으로 API는 이 범주 중 하나에서 안전하지 않을 확률이 MEDIUM 또는 HIGH인 지시사항과 응답을 차단합니다.
개발자는 SafetySetting 개체 목록을 safety_settings 매개변수에 전달하여 이 기본 설정을 요청에 따라 재정의할 수 있습니다. 이는 각 범주에 대한 차단 임계값에 대한 세부 제어를 가능하게 합니다.
from google.genai import types
# Asumiendo que 'client' ha sido inicializado
# Ejemplo: Relajar el umbral para el acoso, pero mantener el predeterminado para otros.# ¡Use esta configuración con precaución y solo si es necesario para su caso de uso!safety_config =
try: response = client.models.generate_content( model='gemini-2.0-flash', contents="Escribe un diálogo entre dos personajes que están discutiendo acaloradamente.", safety_settings=safety_config ) print(response.text)except ValueError: # A menudo, una respuesta bloqueada puede generar un ValueError al intentar acceder a.text print("La respuesta fue bloqueada o está vacía.") # Inspeccionar la retroalimentación de seguridad para depurar print(f"Razón del bloqueo del prompt: {response.prompt_feedback.block_reason}") if response.candidates: print(f"Calificaciones de seguridad del candidato: {response.candidates.safety_ratings}")응답이 비어 있거나 오류가 발생하면 보안 피드백을 확인하는 것이 필수적입니다. 응답 개체는 prompt_feedback(입력 지시사항용) 및 candidates.safety_ratings(생성된 응답용)을 포함합니다. 이러한 속성은 콘텐츠가 차단되었는지 여부와 그 이유를 드러내며, 이는 디버깅에 필수적입니다.
다음 표는 다양한 차단 임계값의 의미를 설명합니다.
표 4: 보안 설정 임계값
| API 상수 | Google AI Studio 설정 | 설명 |
|---|---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED | 없음 | 임계값이 지정되지 않았으며, 모델의 기본 임계값이 사용됩니다. |
BLOCK_NONE | 블록 없음 (아무것도 차단하지 않음) | 안전하지 않은 콘텐츠일 확률에 관계없이 콘텐츠를 차단하지 마세요. 극도로 주의해서 사용해야 합니다. |
BLOCK_ONLY_HIGH | 블록 일부 (일부만 차단) | 안전하지 않은 콘텐츠일 확률이 HIGH일 때만 차단합니다. |
BLOCK_MEDIUM_AND_ABOVE | 블록 일부 (일부만 차단) | (대부분의 모델에 기본 설정) 위험한 콘텐츠 확률이 MEDIUM 또는 HIGH일 때 차단합니다. |
BLOCK_LOW_AND_ABOVE | 대부분 차단 (Bloquear la mayoría) | 위험한 콘텐츠 확률이 LOW, MEDIUM 또는 HIGH일 때 차단합니다. |
SDK는 사용 가능한 모델과 그 기능을 프로그래밍 방식으로 탐지할 수 있는 방법을 제공합니다. 이는 다양한 모델에 적응할 수 있는 애플리케이션을 구축하거나, 사용하기 전에 모델의 기능을 확인하는 데 유용합니다.
client.models.list() 메서드는 사용 가능한 모델에 대한 반복자를 반환합니다.
Python
import google.genai as genai
# Asumiendo que 'client' ha sido inicializadoprint("Modelos disponibles:")for model in client.models.list(): # El objeto 'model' contiene metadatos detallados print(f" - Nombre: {model.name}") print(f" - Nombre para mostrar: {model.display_name}") print(f" - Métodos soportados: {model.supported_generation_methods}") # Verificar si el modelo soporta chat (create_chat) if 'create_chat' in model.supported_generation_methods: print(" - ¡Este modelo soporta chat!") print("-" * 20)이 기능은 사용자가 조정한(파인튜닝된) 모델만 목록으로 표시하도록 설정 query_base=False을 목록 요청 설정에 설정하여 사용할 수 있습니다. 이는 애플리케이션이 동적으로 사용자 정의 모델을 탐지하고 사용할 수 있도록 합니다.
제5부: 환경 검증 및 기술 체크리스트
Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»통합된 SDK google-genai를 Portelcore 테넌트에 프로비저닝하는 것을 완료하기 위해 다음 기술적 이정표의 준수 여부를 검증합니다:
- 오래된 라이브러리
google-generativeai의 테넌트 스크립트를 새 표준google-genai으로 이전했습니다. ✓ - API 키는 텍스트 파일에 직접 작성하는 대신, 환경 변수
GOOGLE_API_KEY를 통해 전적으로 관리되거나 Google Cloud의 시크릿 관리자에 오브스큐레이트됩니다. ✓ - 강력한 예외 처리 제어(
google.api_core.exceptions)가 구현되어 429(자원 고갈) 상태 코드를 캡처하고 지수 백오프(Exponential Backoff) 정책을 사용합니다. ✓ - 온도 및 보안 임계값(
safety_settings)는 도메인 사용 사례에 따라 형식적으로 설정되었습니다. ✓

