Gemini API 활용 가이드

Gemini는 텍스트·이미지·오디오·비디오·문서를 함께 처리하는 멀티모달 모델입니다. API로 사용할 때의 실무 포인트를 정리합니다.

모델 선택 기준

계열	특징	주 사용처
Pro	최고 품질, 긴 컨텍스트, 복잡한 추론	에이전트 코어, 복잡한 분석
Flash	품질/속도/비용 균형	대부분의 프로덕션 워크로드
Flash-Lite	최저 비용, 대량 처리	분류, 추출, 대량 배치

정확한 모델 버전과 요금은 변동이 잦으므로 공식 모델 목록을 기준으로 확인하세요.

백엔드 선택: AI Studio vs Vertex AI

from google import genai

# AI Studio (API 키) - 프로토타이핑
client = genai.Client(api_key="...")

# Vertex AI (ADC/IAM) - 프로덕션
client = genai.Client(vertexai=True, project="my-project", location="global")

resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Cloud Run과 GKE의 차이를 세 줄로 요약해줘",
)
print(resp.text)

동일한 google-genai SDK로 두 백엔드를 모두 사용할 수 있습니다. 기업 환경에서는 IAM 통제와 감사로그가 가능한 Vertex AI 백엔드를 권장합니다.

프로덕션 팁

1. System Instruction 분리 — 페르소나/규칙은 system instruction에, 데이터는 user turn에
2. 구조화 출력 — response_schema(JSON Schema)로 파싱 안정성 확보
3. 컨텍스트 캐싱 — 반복 사용하는 긴 문서/프롬프트는 캐싱으로 토큰 비용 절감
4. 그라운딩 — 최신 정보가 필요하면 Google 검색 그라운딩, 사내 데이터는 RAG
5. 안전 설정 — safety settings를 워크로드 특성에 맞게 조정 (기본값이 과하게 차단하는 경우 검토)
6. 재시도/폴백 — 429(쿼터)/5xx 대비 지수 백오프, 상위→하위 모델 폴백 설계

비용 관리

• 입력/출력 토큰 단가가 다르며 출력이 더 비쌉니다 → max_output_tokens 제한
• 멀티모달 입력(이미지/비디오)은 토큰 환산 규칙 확인
• 배치 예측(Batch Prediction)은 온라인 대비 할인 제공

참고

• Gemini API 문서 (Vertex AI)
• google-genai SDK