Gemini 3.6 Flash 마이그레이션: 5가지 API 변경과 1가지 조용한 실패

핵심 요약 gemini-3.6-flash 또는 gemini-3.5-flash-lite로 마이그레이션하면 요청 변경이 다섯 가지 생깁니다. 그중 넷은 HTTP 400을 반환하므로 바로 알아차립니다. 나머지 하나는 그렇지 않습니다. temperature, top_p, top_k는 이제 받아들여진 뒤 무시됩니다. 파이프라인이 안정적인 출력을 위해 temperature=0에 의존하고 있었다면, 믿고 있던 그 보장이 사라진 뒤에도 계속 200 OK를 반환합니다. 이것부터 먼저 고치고, 그다음에 시끄러운 넷을 고치십시오.

Last verified: 2026-07-21

설정 파일에서 모델 ID 하나만 바꾸고 나머지는 그대로 동작하리라 기대한다면, 배포하기 전에 첫 번째 섹션을 읽으십시오.

다섯 가지 변경, '언제 알아차리는가' 순으로

이 다섯 중 넷은 스스로 신호를 보냅니다. 통합 테스트가 잡아내고, 오류 추적기가 알림을 보내며, 오후 한나절이면 고칩니다. 프로덕션까지 흘러들어가는 것은 첫 번째입니다.

위험한 하나: temperature, top_p, top_k는 이제 무시됩니다

어떤 파이프라인이 오류 없이 망가지는가

조용한 no-op은 그 파라미터에 의존하고 있던 경우에만 위험합니다. 흔한 구성이 네 가지 있었습니다:

• 결정성(determinism) 파이프라인. 반복 호출 결과를 서로 일치시키려고 temperature=0을 설정하는 모든 것: 모델 출력으로 만든 캐시 키, 중복 제거 패스, 결과를 하류 상태 머신에 넣는 분류 작업. 이 설정은 이제 무력해졌으므로, 그것이 사 주던 출력 안정성은 더 이상 사지지 않습니다.
• golden file / 스냅샷 테스트. temperature=0을 고정해 두고 모델 출력을 저장된 기대 문자열과 diff하는 테스트 스위트. 모델을 바꾼 뒤 이들은 흔들리기 시작하는데, 그 흔들림이 설정 문제가 아니라 모델 품질 저하처럼 보여서 엉뚱한 방향으로 디버깅하게 만듭니다.
• 낮은 온도로 지탱하던 구조화 출력. 구조화 출력을 도입하지 않고 대신 temperature를 0 근처로, top_p를 좁게 유지해 모델이 파싱 가능한 JSON을 안정적으로 뱉게 하던 팀. 이제 두 손잡이가 동시에 무력해집니다.
• 경로별로 튜닝한 설정. '창의성' 슬라이더를 노출하거나, '요약'은 한 온도로 '브레인스토밍'은 다른 온도로 라우팅하는 제품. 슬라이더는 UI에서 여전히 움직입니다. 하지만 모델에서는 아무것도 움직이지 못합니다.

이들 중 무엇도 스택 트레이스를 만들지 않습니다. 대신 스스로 건강하다고 보고하는 시스템에서, 당신이 검증했던 것과 미묘하게 다른 출력을 만들어냅니다.

게이트웨이도 경고하지 않습니다

이 지점에서 신중한 팀조차 걸려 넘어집니다. 모델 게이트웨이는 각 모델이 어떤 파라미터를 지원하는지 설명하는 기계 판독 가능한 메타데이터를 게시하고, 상위 도구는 그 메타데이터를 읽어 무엇을 보낼지 결정합니다.

무엇이 temperature를 대체하는가

Google이 밝힌 대체는 또 다른 파라미터가 아닙니다. system instruction입니다. 원하는 동작을 샘플링 상수가 아니라 모델이 읽는 규칙으로 적으십시오.

이는 의도를 표현하는 방식의 실질적 변화이므로, 삭제가 아니라 '번역'을 하십시오:

배포 전에 모든 호출 지점을 찾는 법

설정 계층을 믿지 말고 코드베이스에서 파라미터 이름을 직접 검색하십시오. 이 값들은 보통 여러 곳에서 서로 다른 사람이 서로 다른 시점에 설정해 두기 때문입니다:

# Gemini 네이티브 및 OpenAI 호환 표기법, 그리고 이들을 담는 설정 객체
grep -rn "temperature\|top_p\|topP\|top_k\|topK\|candidate_count\|candidateCount" \
  --include="*.py" --include="*.ts" --include="*.js" --include="*.go" --include="*.java" .

# 이들을 감싸는 래퍼
grep -rn "generation_config\|generationConfig\|GenerateContentConfig\|thinking_budget\|thinkingBudget" .

시끄럽게 실패하는 넷

이들은 더 간단합니다. API가 알려 주기 때문입니다. 테스트 스위트가 드러내는 순서대로 고치면 됩니다.

thinking_budget과 thinking_level은 동시에 존재할 수 없습니다

값을 고를 때 알아 둘 만한 기본값이 두 가지 있습니다. 두 모델 사이에서 다르기 때문입니다:

• gemini-3.6-flash의 기본값은 medium입니다.
• gemini-3.5-flash-lite의 기본값은 minimal이며, 처리량에 맞춰 튜닝되어 있습니다.

더 이상 모델 턴을 프리필할 수 없습니다

모든 FunctionResponse에는 call_id와 name이 필요합니다

candidate_count는 사라졌습니다

전과 후: 깔끔하게 마이그레이션되는 요청

아래는 폐기된 필드를 모두 담은 Gemini 네이티브 호출과, 이 이동에서 살아남는 버전입니다.

# 이전: 2.5 세대 모델에서는 동작하지만, 3.6 Flash에서는 깨지거나 조용히 오작동한다
config = {
    "temperature": 0,          # 이제 무시됨, 오류 없음
    "top_p": 0.95,             # 이제 무시됨, 오류 없음
    "top_k": 40,               # 이제 무시됨, 오류 없음
    "candidate_count": 1,      # Gemini 3.x에서 미지원
    "thinking_budget": 8192,   # thinking_level과 함께 오면 400
}

# 이후: 의도를 샘플링 상수에서 지시문으로 옮김
config = {
    "system_instruction": (
        "최대 세 문장으로 답하세요. 평이한 서술문을 쓰세요. "
        "서두를 붙이거나, 질문을 되풀이하거나, 후속 제안을 하지 마세요. "
        "답이 불확실하면 한 문장으로 그렇다고 말하세요."
    ),
    "thinking_level": "medium",
}

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["EVOLINK_API_KEY"],
    base_url="https://api.evolink.ai/v1"
)

response = client.chat.completions.create(
    model="gemini-3.6-flash",
    messages=[
        {"role": "system", "content": "최대 세 문장으로 답하세요. 서두 없이."},
        {"role": "user", "content": "이 장애 보고서를 요약하세요."}
    ]
    # temperature, top_p 없음: 넣어도 받아들여진 뒤 하류에서 무시됨
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env["EVOLINK_API_KEY"],
  baseURL: "https://api.evolink.ai/v1",
});

const response = await client.chat.completions.create({
  model: "gemini-3.6-flash",
  messages: [
    { role: "system", content: "최대 세 문장으로 답하세요. 서두 없이." },
    { role: "user", content: "이 장애 보고서를 요약하세요." },
  ],
  // temperature, top_p 없음
});

console.log(response.choices[0].message.content);

조용한 실패를 잡아내는 마이그레이션 순서

순서가 중요합니다. 시끄러운 오류는 쉽고 조용한 것은 그렇지 않기 때문입니다. 이 순서로 진행하십시오:

1. 먼저 인벤토리. 위 grep을 돌려 샘플링 파라미터가 설정된 모든 곳을 설정 저장소와 대시보드까지 포함해 나열하십시오. 각각이 어떤 동작을 보호하고 있었는지 적어 두십시오.
2. 삭제만 하지 말고 의도를 번역. 발견한 모든 temperature에 대해 그것이 무엇을 위한 것이었는지 정한 뒤, 그에 상응하는 system instruction을 작성하십시오. 번역 없이 삭제하는 것이 곧 품질 저하를 출시하는 방법입니다.
3. 400들을 고친다. thinking_budget을 thinking_level로 교체하고, candidate_count를 제거하고, 프리필된 모델 턴을 제거하고, 모든 FunctionResponse에 call_id와 name을 추가하십시오.
4. 의도적으로 thinking 레벨을 선택, 특히 Flash-Lite에서 그렇습니다. minimal 기본값은 자율 다단계 작업에 부적합합니다. 이는 마이그레이션에서 가장 큰 비용 레버이기도 합니다: 우리 작업 세트에서 3.6 Flash를 minimal로 돌렸을 때 같은 모델을 기본 medium으로 돌릴 때보다 패스당 73.6% 저렴했고, medium에서는 thinking 토큰이 청구 출력의 85%를 차지했습니다. 시험해야 할 것은 절감이 실제인지가 아니라, 당신의 워크로드가 그 하락을 견디는지입니다.
5. 무엇이든 비교하기 전에 스냅샷 테스트를 새 모델 기준으로 다시 잡으십시오. 옛 golden file은 더 이상 적용되지 않는 파라미터 아래에서 생성되었으므로, 유효한 기준점이 아닙니다.
6. 같은 작업 세트에서 두 모델 모두에 평가를 돌리고, 통과율만이 아니라 출력 분포를 비교하십시오. 조용한 동작 변화는 오답으로 드러나기 전에 형식·길이·장황함의 드리프트로 먼저 드러납니다.
7. 실제 트래픽으로 카나리하며 하류 파서를 주시하십시오. API 오류율만 보지 마십시오. 무언가 조용히 깨진다면, 그것은 호출 자체가 아니라 모델 출력을 소비하는 코드에서 깨집니다.

Google의 마이그레이션 skill로 첫 패스를 돌려라

npx skills add google-gemini/gemini-skills --skill gemini-interactions-api --global

그다음, 코딩 에이전트에서 프로젝트를 가리키게 하십시오:

돌려 볼 가치가 있습니다. 기계적인 일을 처리합니다. 폐기된 필드 찾기, 요청 구성 재작성, 호출 지점 갱신인데, 위 3단계의 대부분을 포괄합니다.

은퇴 일정: 선택이 당신의 것이 아니게 되는 때

Computer Use: 공식 문서 넷, 답 둘

지금은 문서만으로 결론 낼 수 없는 능력 관련 질문이 하나 있습니다. 이 모델들이 Computer Use를 지원하는지가 Google 자신의 자료 전반에서 일관되지 않게 서술되어 있습니다:

• Gemini API 모델 문서는 3.6 Flash에 대해 Computer Use를 지원(preview)으로 표시하는 반면, 같은 모델의 엔터프라이즈 플랫폼 페이지는 미지원으로 표기합니다.
• 3.5 Flash-Lite의 경우, 모델 페이지들은 미지원이라 말하지만 출시 공지와 Gemini 3 개발자 가이드는 동작한다고 말합니다.

이번 주에 공급자를 다시 고르고 있다면 이것이 뜻하는 바

들어간 김에 확인할 만한 것이 두 가지 있습니다:

• 전환 기간에 옛 모델과 새 모델을 나란히 돌릴 수 있습니까? 위 6단계가 이를 요구합니다. 현재 구성 때문에 gemini-3.5-flash와 gemini-3.6-flash를 같은 작업 세트로 돌리는 일이 번거롭다면, 그 번거로움은 다음 마이그레이션에도 그대로 남습니다. 그리고 다음은 반드시 옵니다. Google은 이 규칙이 이후 출시되는 모든 모델에 적용된다고 밝혔습니다.
• 새 모델이 당신에게 호출 가능해지기까지 얼마나 걸립니까? gemini-3.6-flash는 출시 첫날 preview 접미사 없이 정식 출시(GA)에 도달했습니다. 모델이 출시되는 시점과 당신 코드가 그것을 호출할 수 있는 시점 사이의 간극은, 출시가 있을 때마다 당신이 치르는 비용입니다.

FAQ

출처

• Using the latest Gemini models (Google AI for Developers): 폐기된 샘플링 파라미터, thinking_level, candidate_count, 프리필 제한, FunctionResponse 요구사항, 마이그레이션 skill 명령
• Gemini deprecations (Google AI for Developers): 종료 날짜와 권장 대체 모델
• Gemini API models (Google AI for Developers): 모델 ID와 능력 지원 매트릭스
• Gemini 3 개발자 가이드 (Google AI for Developers): Gemini 3의 요청 동작과 능력
• Gemini 3.6 Flash (Gemini Enterprise Agent Platform) (Google Cloud): 엔터프라이즈 능력 목록과 페이지에 표시된 파라미터 기본값
• Introducing Gemini 3.6 Flash, 3.5 Flash-Lite, and 3.5 Flash Cyber (Google): 출시 공지와 출시 날짜
• google-gemini/gemini-skills (GitHub): 공식 마이그레이션 skill
• OpenRouter models 엔드포인트 (OpenRouter): 게이트웨이 메타데이터가 두 모델 모두에 대해 temperature, top_p, seed를 지원 파라미터로 나열, 2026-07-21 관측
• EvoLink 모델 카탈로그, Gemini 3.6 Flash 출시 추적기, Gemini 3.6 Flash 대 Gemini 3.5 Flash, Gemini 3.5 Flash 대 Gemini 3 Flash Preview 마이그레이션 가이드, Gemini 3 Pro 폐기 가이드, EvoLink API base URL