Gemini 2.5 모델 지원 종료 에 따른 마이그레이션 가이드

Gemini Enterprise Agent platform에서 Gemini 2.5 model의 마이그레이션

 

Gemini Enterprise Agent platform에서 Gemini 2.5 model의 마이그레이션

 

 

얼마전 구글의 최신 모델인 Gemini 4 Argon이 출시되었습니다. 하지만 지난 2025년 6월 17일에 정식출시한 Gemini 2.5 모델은 Pro 및 Flash 모델에서 모두 추론(Thinking) 기능을 제공하여 현재까지 고객사에서 다양한 애플리케이션에서 해당 모델을 사용하고 있습니다.

Gemini Enterprise Agent Platform에서는 Gemini 2.5 모델에 대해 2026년 10월 20일부로 서비스 종료를 예고하고 있기 때문에 지원 중단에 따른 서비스 장애를 예방하고자 대체 모델과 안전하게 마이그레이션 할 수 있는 체크리스트 및 예시를 바탕으로 고객사에서 참고하실 내용을 전달하고자 합니다.

 

Gemini 2.5 모델 지원 종료 및 대체 모델

모델 ID(Model ID)	출시일	종료일	대체 모델 ID
gemini-2.5-pro	2025년 6월 17일	2026년 10월 20일	gemini-3.8-flash gemini-3.5-flash
gemini-2.5-flash	2025년 6월 17일	2026년 10월 20일	gemini-3.8-flash gemini-3.5-flash-lite gemini-3.1-flash-lite
gemini-2.5-flash-lite	2025년 7월 22일	2026년 10월 20일	gemini-3.8-flash gemini-3.1-flash-lite Gemma 4

 

 

Python code 기반의 마이그레이션 예시

Gemini 2.5 Flash(gemini-2.5-flash) 모델은 Gemini 모델 중 유일하게 서울 리전(asia-northeast3)에 엔드포인트(endpoint)를 제공하는 모델로 다음 Python 코드는 서울 리전의 엔드포인트를 사용하고 답변 결과에 창의적인 결과물을 얻기 위해 temperature 및 top_p 값 설정과 Google 검색을 구성해 프롬프트에 답변 결과를 출력하는 예시입니다.

from inspect import cleandoc

from IPython.display import display, Markdown

from google import genai

from google.genai import types

PROJECT = !gcloud config get–value project

PROJECT_ID = PROJECT[0]

LOCATION = “asia-northeast3”

client = genai.Client(

    vertexai=True,

    project=PROJECT_ID,

    location=LOCATION

)

model = “gemini-2.5-flash”

google_search_tool = types.Tool(google_search=types.GoogleSearch())

creative_gen_config = types.GenerateContentConfig(

    temperature=1,

    top_p=0.8,

    tools=[google_search_tool],

)

prompt = “대한민국에서 노벨문학상 수상자는?”

response = client.models.generate_content(

    model=model,

    contents=prompt,

    config=creative_gen_config,

)

display(Markdown(response.text))

if response.candidates and response.candidates[0].grounding_metadata:

    metadata = response.candidates[0].grounding_metadata

if metadata.web_search_queries:

print(“\n🔍 [실행된 검색 쿼리]”)

for query in metadata.web_search_queries:

print(f”- {query}“)

if metadata.grounding_chunks:

print(“\n🔗 [참조된 출처(Sources)]”)

for chunk in metadata.grounding_chunks:

if chunk.web:

print(f”- {chunk.web.title}: {chunk.web.uri}“)

Gemini 2.5 Flash를 사용한 Python 코드

 

Gemini 3.8 Flash 모델 사용시 Python 수정 요소

1) Model ID 변경

Gemini 2.5 Flash를 명명한 Model ID를 마이그레이션 하고자 하는 대상 모델의 Model ID로 변경합니다.

## As-Is

model = “gemini-2.5-flash”

—————————————————————————————-

## To-Be : Gemini 3.8 Flash 모델로 변경

model = “gemini-3.8-flash”

 

2) 리전 엔드포인트 변경

Gemini 3.8 Flash는 단일 리전(예: asia-northeast3) 엔드포인트가 아닌 글로벌(global) 또는 멀티 리전(us, eu) 엔드포인트를 통해 제공됩니다.

비용 최적화를 위해 기본값인 global 사용이 권장되며, 멀티 리전(us/eu )은 10%의 요금 프리미엄이 발생합니다.

## As-Is

PROJECT = !gcloud config get–value project

PROJECT_ID = PROJECT[0]

LOCATION = “asia-northeast3”

—————————————————————————————-

## To-Be : Global endpoint로 변경

PROJECT = !gcloud config get–value project

PROJECT_ID = PROJECT[0]

LOCATION = “global”

 

3) 레거시 샘플링 파라미터 사용 변경

Gemini 3 계열 모델부터는 기존 샘플링 파라미터인 temperature, top_p, top_k의 사용이 중단되었습니다. 특히 top_p=0.8 와 같은 임의의 샘플링 값을 전달할 경우 API 검증 오류를 일으키거나 추론 과정에서 무한 루프 및 성능 저하를 유발할 수 있습니다.

Gemini 3.8 Flash에서는 추론(사고)의 수준을 조절하는 방법으로 thinking_level 을 사용하며, low , medium , high 의 세가지 단계를 설정할 수 있습니다.

## As-Is

google_search_tool = types.Tool(google_search=types.GoogleSearch())

creative_gen_config = types.GenerateContentConfig(

    temperature=1,

    top_p=0.8,

    tools=[google_search_tool],

)

—————————————————————————————-

## To-Be : 지원 중단된 temperature, top_p를 제거하고 thinking_config 적용

google_search_tool = types.Tool(google_search=types.GoogleSearch())

gen_config = types.GenerateContentConfig(

    thinking_config=types.ThinkingConfig(

        thinking_level=“medium” # “low”, “medium”(기본값), “high” 중 선택 가능

),

    tools=[google_search_tool],

)

 

Gemini 3.8 Flash로 마이그레이션한 최종 Python code

위 변경점들을 모두 반영하여 gemini-3.8-flash 모델에서 정상 작동하도록 수정한 코드입니다.

from inspect import cleandoc

from IPython.display import display, Markdown

from google import genai

from google.genai import types

PROJECT = !gcloud config get–value project

PROJECT_ID = PROJECT 0

# Gemini 3.8 Flash 지원을 위해 LOCATION을 “global”로 변경

LOCATION = “global”

client = genai.Client(

    vertexai=True,

    project=PROJECT_ID,

    location=LOCATION

)

# 모델 ID를 gemini-3.8-flash로 변경

model = “gemini-3.8-flash”

google_search_tool = types.Tool(google_search=types.GoogleSearch())

# 지원 중단된 temperature, top_p를 제거하고 thinking_config 적용

gen_config = types.GenerateContentConfig(

    thinking_config=types.ThinkingConfig(

        thinking_level=“medium” # “low”, “medium”(기본값), “high” 중 선택 가능

),

    tools=[google_search_tool],

)

prompt = “대한민국에서 노벨문학상 수상자는?”

response = client.models.generate_content(

    model=model,

    contents=prompt,

    config=gen_config,

)

display(Markdown(response.text))

if response.candidates and response.candidates 0 .grounding_metadata:

    metadata = response.candidates 0 .grounding_metadata

if metadata.web_search_queries:

print(“\n🔍 [실행된 검색 쿼리]”)

for query in metadata.web_search_queries:

print(f”- {query}“)

if metadata.grounding_chunks:

print(“\n🔗 [참조된 출처(Sources)]”)

for chunk in metadata.grounding_chunks:

if chunk.web:

print(f”- {chunk.web.title}: {chunk.web.uri}“)

모델을 Gemini 3.8 Flash로 변경한 Python 코드

위 코드의 프롬프트에 대한 답변으로 다음과 같은 결과를 출력할 수 있습니다.

대한민국 최초의 노벨문학상 수상자는 작가 한강(Han Kang)입니다.

• 수상 연도: 2024년

• 주요 의의: 대한민국 최초이자 아시아 여성 작가 최초의 노벨문학상 수상

• 선정 사유: 스웨덴 한림원은 “역사적 트라우마에 맞서고 인간 삶의 연약함을 드러낸 강렬한 시적 산문”을 수상 이유로 밝혔습니다.

• 대표 작품: 《채식주의자》, 《소년이 온다》, 《작별하지 않는다》, 《흰》 등

 

Gemini 3.8 Flash로 마이그레이션시 주요 체크리스트

사용 모델을 Gemini 3.8 Flash로 변경시 다음과 같은 주요 체크리스트를 확인하여 코드를 변경시 확인

• 대상 모델 ID : gemini-2.5-flash 에서 gemini-3.8-flash 로 변경
• Location 변경 : global 또는 us, eu
•  이상 사용되지 않는 thinking_budget 또는 temperature 필드 대신 thinking_level 사용
  • 기본값 MEDIUM(유효한 값: LOW, MEDIUM, HIGH)
    ※ MINIMAL은 Gemini 3.8 Flash 모델에서 지원하지 않음
• 다음의 지원되지 않는 파라미터들을 제거
  frequency_penalty, presence_penalty, candidate_count, temperature, top_p, top_k
• 멀티턴(multi-turn) 채팅 요청 기록에서 미리 채워진 모델 턴을 모두 제거
  엄격한 FunctionResponse 매칭(id 또는 call_id 및 name)을 보장하고, 도구 사용 전 지문(pre-tool instructions)을 \n\n 형식으로 지정

 

기타 고려사항

모델 마이그레이션시 코드를 변경하는 것과 별개로 다음과 같은 추가적인 사항을 고려하여야 합니다.

 

데이터 국외 이전 컴플라이언스 (asia-northeast3 to global 변경시)

global 엔드포인트는 전 세계 구글 데이터센터 중 가용 리소스로 트래픽을 동적 라우팅을 하며 이에 따라, 요청 데이터가 해외 리전에서 처리될 수 있으므로 개인정보보호법상 국외 이전 동의 여부 및 사내 데이터 보안 규정을 확인해야 합니다.

 

할당량(Quota) 확인

asia-northeast3에 승인되어 있던 분당 요청 수(RPM) 및 토큰 수(TPM) 할당량을 global 엔드포인트용 할당량으로 확인해야 합니다.

 

지연시간

네트워크 왕복 지연 시간(RTT)이 서울 단일 리전 호출시와 대비하여 수십~수백 밀리초 증가할 수 있습니다.

 

다가오는 2026년 10월 20일까지 Gemini 2.5 모델의 서비스 지원 종료에 대비하여, 본 게시물에 안내된 체크리스트와 예시 코드를 참고해 안전한 마이그레이션에 도움이 되셨으면 합니다.

또한 추가적인 고려사항도 사전에 꼼꼼히 점검하시어 예기치 않은 서비스 장애를 예방하시고, 새로운 대체 모델로의 성공적인 전환을 통해 앞으로도 중단 없이 안정적이고 강력한 Google Cloud의 Agent Platform의 AI 서비스를 경험해 보시기 바랍니다.

 

Gemini API (Google AI Studio)에서 Gemini 2.5 모델 사용시 유의사항

Google AI Studio를 사용하는 경우 특정 종료 날짜가 없으며, 별도 공지가 있을 때까지 계속 제공합니다.

※ Gemini API Docs : Gemini deprecations

 

7 참고 공식 문서

• Model versions and lifecycle : https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions
• Developer’s guide to Gemini 3.8 Flash : https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/guides/gemini-3-8-flash

 

자세한 내용이 궁금하시다면, 메가존소프트 문의포탈을 통해 궁금한 부분을 남겨주세요.