Gemini API 모델 마이그레이션 — 반복되는 Deprecation 알림 대응

Google AI Studio에서 “Action Required: Migrate to Gemini 2.5 or Gemini 3 models”라는 메일이 반복적으로 왔다. Gemini API의 모델 버전 관리와 마이그레이션 전략을 정리한다.

Table of contents

상황

2026년 1월부터 3월까지 Gemini API 관련 알림이 5회 이상 도착했다:

01/22 — [Action Required] Migrate to Gemini 2.5 or Gemini 3 models
01/27 — [조치 필요] 2026년 3월 31일 전에 마이그레이션하세요
02/18 — [Reminder] Migrate to a newer Gemini model
02/25 — [알림] 2026년 6월 1일 전에 최신 모델로 마이그레이션하세요
03/18 — [Billing Update] Gemini API usage tier updates
03/19 — [Reminder] Migrate to Gemini 3.1 Flash

데드라인이 계속 바뀌는 것처럼 보이지만, 모델마다 별도의 EOL 일정이 있다.

Gemini 모델 버전 체계

Gemini 2.0 Flash    → Deprecated (마이그레이션 필요)
Gemini 2.5 Flash    → Stable
Gemini 2.5 Pro      → Stable
Gemini 3.0          → GA
Gemini 3.1 Flash    → Latest
Gemini 3.1 Pro      → Latest

Google은 구 모델의 API를 일정 기간 후 중단하므로, 최신 모델로 전환해야 한다.

마이그레이션 전략

1. 현재 사용 모델 확인

코드에서 모델 ID를 검색한다:

grep -r "gemini-" --include="*.py" --include="*.ts" --include="*.yaml" .

결과 예시:

model = "gemini-2.0-flash"  # ← 마이그레이션 대상
model = "gemini-3-flash"    # ← OK

2. 호환성 확인

모델 변경 시 확인할 항목:

3. 점진적 전환

한 번에 모든 호출을 바꾸지 말고 단계적으로 전환한다:

# LiteLLM Proxy를 사용하면 모델 라우팅으로 처리 가능
# config.yaml
model_list:
  - model_name: gemini-flash
    litellm_params:
      model: gemini/gemini-3.1-flash  # 새 모델
      api_key: os.environ/GEMINI_API_KEY
    model_info:
      description: "Primary flash model"

4. 빌링 티어 확인

Gemini API는 무료 티어와 유료 티어가 있다:

• 무료 티어: RPM/RPD 제한 있음, 프로덕션 비추천
• Pay-as-you-go: API 키에 빌링 계정 연결 필요

빌링 업데이트 메일이 오면 가격 변동을 확인한다.

자동화

모델 버전을 환경변수로 관리

import os

GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-flash")

모델 변경 시 코드 수정 없이 환경변수만 변경하면 된다.

헬스체크

모델 Deprecation을 미리 감지하려면:

# API 호출 시 response header의 deprecation 경고 확인
# 또는 주기적으로 models.list 호출
import google.generativeai as genai

for model in genai.list_models():
    if "deprecated" in model.name.lower():
        print(f"DEPRECATED: {model.name}")

정리

Gemini API 모델 마이그레이션 알림은 앞으로도 반복될 것이다. 모델 ID를 환경변수로 관리하고, LiteLLM 같은 프록시로 모델 라우팅을 추상화하면 마이그레이션 부담을 줄일 수 있다.